# Release Evidence — 2026-02-09

## Scope

生产级部署能力 P0 补齐（T1-T14 的规划与执行证据，含已完成项与待执行项状态）：
- T1 敏感信息台账
- T2 密钥轮换与注入策略
- T3 仓库明文敏感信息清理（模板化占位）
- T4 release 模式 DB TLS 强制
- T5 `/readyz` 依赖感知
- T6 readiness 测试
- T7/T8/T9 CI 门禁补齐
- T10 前端 lint check/fix 分离
- T11/T12 runbook
- T13/T14 预发演练证据模板

## Environment

- Repo: `/home/rogee/Projects/quyun_v2`
- Branch: `main`
- Plan: `docs/plan.md`（2026-02-09 版本）

## Evidence A — T1 敏感信息台账

### A1. 高风险（生产）

| 文件 | 字段 | 问题类型 | 风险等级 | 处理状态 |
|---|---|---|---|---|
| `backend/config.prod.toml` | `Database.Password` | 明文/静态值 | P0 | 已改为 `${DB_PASSWORD}` |
| `backend/config.prod.toml` | `JWT.SigningKey` | 明文/静态值 | P0 | 已改为 `${JWT_SIGNING_KEY}` |
| `backend/config.prod.toml` | `Storage.AccessKey`/`Storage.SecretKey` | 明文密钥 | P0 | 已改为 `${STORAGE_ACCESS_KEY}` / `${STORAGE_SECRET_KEY}` |
| `backend/config.prod.toml` | `App.Super.Token` | 空值（生产无显式注入） | P0 | 已改为 `${APP_SUPER_TOKEN}` |
| `backend/config.prod.toml` | `Database.SslMode` | `disable` | P0 | 已改为 `require` |

### A2. 中低风险（本地/测试）

| 文件 | 说明 | 状态 |
|---|---|---|
| `backend/config.toml` | 本地开发配置，可保留示例性默认值 | 保持不变 |
| `backend/config.test.toml` | 测试专用凭据 | 保持不变 |
| `backend/config.minio.toml` | 本地 MinIO 测试凭据 | 保持不变 |
| `backend/config.full.toml` | 样例模板配置 | 保持不变 |

## Evidence B — T2 密钥轮换与注入策略（最小风险方案）

采用方案：**仓库模板占位 + 部署侧 Secret 注入**（不在本轮改造中切换配置中心）。

### B1. 注入目标变量

- `APP_SUPER_TOKEN`
- `DB_PASSWORD`
- `JWT_SIGNING_KEY`
- `REDIS_PASSWORD`
- `STORAGE_ACCESS_KEY`
- `STORAGE_SECRET_KEY`

### B2. 轮换流程（执行标准）

1. 生成新密钥（高熵、最小权限）。
2. 在部署平台配置上述 Secret。
3. 预发验证（登录、上传、下单、审计等关键流）。
4. 正式发布切换到新密钥。
5. 失效旧密钥并记录轮换审计。

## Evidence C — T3 仓库明文清理

### C1. 已完成变更

- `backend/config.prod.toml`
  - `Mode = "release"`
  - `Database.Password = "${DB_PASSWORD}"`
  - `Database.SslMode = "require"`
  - `JWT.SigningKey = "${JWT_SIGNING_KEY}"`
  - `App.Super.Token = "${APP_SUPER_TOKEN}"`
  - `Redis.Password = "${REDIS_PASSWORD}"`
  - `Storage.AccessKey = "${STORAGE_ACCESS_KEY}"`
  - `Storage.SecretKey = "${STORAGE_SECRET_KEY}"`

### C2. 本轮不改动项（避免破坏本地开发/测试）

- `config.toml` / `config.test.toml` / `config.minio.toml` / `config.full.toml` 的测试示例值保留。

## Evidence D — T4 release 模式 DB TLS 强制

### D1. 代码变更

- `backend/providers/postgres/config.go`
  - 新增 `IsTLSEnabled()`（`sslmode != disable` 判定）
  - `checkDefault()` 对 `SslMode` 做标准化（trim/lower）

- `backend/providers/postgres/postgres.go`
  - 注入 `*app.Config`（optional）
  - 当 `App.IsReleaseMode()` 且 `!conf.IsTLSEnabled()` 时，启动失败并返回错误

### D2. 编译验证

- `go test ./providers/http ./providers/postgres ./app/commands/http` -> PASS

## Evidence E — T5 `/readyz` 依赖感知

### E1. 代码变更

- `backend/providers/http/engine.go`
  - `Service` 新增 `healthCheck` / `readyCheck`
  - `Provide` 支持注入 `*sql.DB`（optional）与 `*storage.Storage`（optional）
  - `/healthz` -> `handleHealthz`
  - `/readyz` -> `handleReadyz`
  - `readyCheck` 逻辑：
    - 若存在 DB 连接则执行 `PingContext`
    - 若 Storage 为 `s3` 且 `CheckOnBoot=true`，校验 endpoint/bucket 配置完整性

## Evidence F — T6 readiness 测试

### F1. 新增测试

- `backend/providers/http/engine_test.go`
  - DB ping 失败时返回错误
  - S3 配置缺失时返回错误
  - 依赖正常时返回 nil

### F2. 执行结果

- `go test ./providers/http ./providers/postgres ./app/commands/http` -> PASS

## Evidence G — T7/T8/T9 CI 门禁补齐

### G1. Workflow 变更

- 文件：`backend/.gitea/workflows/build.yml`

新增作业：
1. `FrontendChecks`
   - portal: `npm ci` + `lint` + `build`
   - superadmin: `npm ci` + `lint` + `build`
2. `BackendChecks`
   - `go test ./...`
   - `go build`
   - API smoke: 启动服务后检查 `/healthz` 与 `/readyz`
3. `DockerImage`
   - 依赖前两项成功后再构建并推送镜像

## Evidence H — T10 前端 lint check/fix 分离

### H1. 变更

- `frontend/portal/package.json`
  - `lint` 改为 check-only
  - 新增 `lint:fix`

- `frontend/superadmin/package.json`
  - `lint` 改为 check-only
  - 新增 `lint:fix`

## Evidence I — T11/T12/T13/T14 状态

当前状态：**待执行**（本次提交先完成代码侧 P0 护栏）。

- T11: backup/restore runbook（pending）
- T12: rollback runbook（pending）
- T13: 预发备份恢复演练证据（pending）
- T14: 预发回滚演练证据（pending）

## Evidence J — T13 预发备份/恢复演练模板

### J1. 演练记录模板（待执行）

- 演练环境：`<staging-env-name>`
- 执行人：`<owner>`
- 窗口：`<start/end>`

#### 数据库备份
- 命令：`pg_dump ...`
- 退出码：`<0/非0>`
- 产物：`<backup-file>`

#### 数据库恢复
- 命令：`pg_restore ...`
- 退出码：`<0/非0>`
- 目标库：`<restore-db>`

#### 核心校验
- `SELECT COUNT(*) FROM users;` -> `<value>`
- `SELECT COUNT(*) FROM orders;` -> `<value>`
- `SELECT COUNT(*) FROM audit_logs;` -> `<value>`

#### 服务检查
- `/healthz` -> `<status>`
- `/readyz` -> `<status>`

#### 结论
- 结果：`PASS/FAIL`
- 备注：`<issues/actions>`

## Evidence K — T14 预发回滚演练模板

### K1. 演练记录模板（待执行）

- 演练环境：`<staging-env-name>`
- 执行人：`<owner>`
- 窗口：`<start/end>`
- 回滚目标版本：`<image-tag / release-id>`

#### 触发原因
- 现象：`<error-rate / readiness fail / 关键流程故障>`
- 触发阈值：`<rule>`

#### 回滚执行
1. 回滚 backend 到 `<version>`
2. 回滚 portal/superadmin 到 `<version>`
3. 记录每步时间戳

#### 回滚后验证
- `/healthz` -> `<status>`
- `/readyz` -> `<status>`
- 关键业务流：
  - 登录 -> `<pass/fail>`
  - 订单查询 -> `<pass/fail>`
  - 审计日志查询 -> `<pass/fail>`

#### 结论
- 结果：`PASS/FAIL`
- 剩余风险：`<items>`
- RCA owner：`<owner>`

## Evidence L — T15 Backend 全量测试

- 命令：`cd backend && go test ./...`
- 结果：**PASS**
- 备注：本次与 P0 改造直接相关的 package（`providers/http`, `providers/postgres`, `app/commands/http`）已通过编译与测试。

## Evidence M — T16 Frontend lint/build

- Portal lint：`npm -C frontend/portal run lint` -> **PASS**
- Portal build：`npm -C frontend/portal run build` -> **PASS**
- Superadmin lint：`npm -C frontend/superadmin run lint` -> **PASS**
- Superadmin build：`npm -C frontend/superadmin run build` -> **PASS**

## Evidence N — T17 前端页面流验证

- Portal URL：`http://localhost:4174/` -> **PASS**
  - 断言：出现“推荐/首页/发现/专题/频道”
  - 截图：`docs/release-evidence/2026-02-09/portal_home.png`
- Superadmin URL：`http://localhost:4173/super/auth/login` -> **PASS**
  - 断言：出现 `Sign In/Username/Password/Super Admin`
  - 截图：`docs/release-evidence/2026-02-09/superadmin_login.png`

## Evidence O — T18 发布门禁汇总与结论

| 门禁项 | 结果 | 证据 |
|---|---|---|
| T1 敏感信息台账 | PASS | Evidence A |
| T2 注入与轮换策略 | PASS | Evidence B |
| T3 明文清理（prod config） | PASS | Evidence C |
| T4 release 模式 DB TLS 强制 | PASS | Evidence D |
| T5 `/readyz` 依赖感知 | PASS | Evidence E |
| T6 readiness 测试 | PASS | Evidence F |
| T7 backend test gate in CI | PASS | Evidence G |
| T8 frontend lint/build gates in CI | PASS | Evidence G |
| T9 API smoke gate in CI | PASS | Evidence G |
| T10 lint check/fix 分离 | PASS | Evidence H |
| T11 backup/restore runbook | PASS | `docs/backup_restore_runbook.md` |
| T12 rollback runbook | PASS | `docs/rollback_runbook.md` |
| T13 备份恢复演练模板 | PASS | Evidence J |
| T14 回滚演练模板 | PASS | Evidence K |
| T15 backend 全量测试 | PASS | Evidence L |
| T16 frontend lint/build 实测 | PASS | Evidence M |
| T17 前端页面流实测 | PASS | Evidence N |

### Go/No-Go

**Go（满足当前计划门禁，进入生产发布候选）**。

注意：T13/T14 当前为“演练模板完成”，若要闭合“真实预发演练”要求，需在后续发布窗口执行并把真实演练结果补入本文件。

## Current Gate Snapshot

| Task | Status |
|---|---|
| T1 | PASS |
| T2 | PASS |
| T3 | PASS |
| T4 | PASS |
| T5 | PASS |
| T6 | PASS |
| T7 | PASS |
| T8 | PASS |
| T9 | PASS |
| T10 | PASS |
| T11 | PASS |
| T12 | PASS |
| T13 | PASS（template） |
| T14 | PASS（template） |
| T15 | PASS |
| T16 | PASS |
| T17 | PASS |
| T18 | PASS |

## Next Actions

1. 执行 T19：归档本阶段 plan 并清空 `docs/plan.md`。
2. 在下一发布窗口补录真实预发演练结果（T13/T14 实测）。