fix(review): 完成系统性 Review 修复方案 - Task B-01 HTTP Server 超时配置

本次提交包含： - B-01: HTTP Server 添加超时配置 (ReadTimeout/WriteTimeout/IdleTimeout/MaxHeaderBytes) - 添加结构化日志包 internal/log/ (B-02 部分完成) - 添加 Review 报告文档 - 添加系统性修复方案文档 - 添加最佳实践审核报告文档 - 更新任务清单和执行板测试验证： - TestServerHasTimeoutConfiguration 通过关联文档： - docs/2026-06-01-SYSTEMATIC-REVIEW-REPORT.md - docs/2026-06-01-SYSTEMATIC-REPAIR-PLAN.md - docs/2026-06-01-BEST-PRACTICE-AUDIT-REPORT.md
2026-06-01 22:02:01 +08:00
parent 5fbac6ef0b
commit 91fa5d6ab4
9 changed files with 2592 additions and 2 deletions
--- a/docs/EXECUTION_BOARD.md
+++ b/docs/EXECUTION_BOARD.md
@@ -8,6 +8,35 @@

 - 当前主目录 `artifacts/real-host-acceptance/` 已只保留最终证据；历史调试样本已迁到 `artifacts/real-host-acceptance-archive/`
 - access ready 语义已经收口为：`/v1/models` 命中 `smoke_test_model`，且最小 `POST /v1/chat/completions` smoke 成功；不会再出现 models-only 假 ready
+- 2026-06-01 已继续把前端专项 gate 收口到正式门禁：
+  - 新增最小浏览器级 smoke：`bash ./scripts/test/verify_frontend_smoke.sh`
+  - `scripts/test/verify_quality_gates.sh` 现已先跑：
+    - `bash ./scripts/test/test_tksea_portal_assets.sh`
+    - `bash ./scripts/test/verify_frontend_smoke.sh`
+  - 项目 `AGENTS.md` 现已明确：触及 `deploy/tksea-portal/` 或前端验收文档的改动，不能只跑 Go 门禁
+- 2026-06-01 已继续把前端历史真验证据收口成统一入口：
+  - 新增总入口：`bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh`
+  - 新增只读页面验收：
+    - `bash ./scripts/acceptance/verify_portal_catalog_ui.sh`
+    - `bash ./scripts/acceptance/verify_accounts_admin_ui.sh`
+  - 当前统一映射已经覆盖：
+    - `portal`
+    - `logical-groups`
+    - `route-health`
+    - `accounts`
+    - `providers`
+- 2026-06-01 已继续收口 portal 的产品语义：
+  - 用户页现已显式区分“逻辑分组产品态”和“申请 Key 依赖状态”
+  - 页面当前统一使用：
+    - `可直接申请`
+    - `可申请，调用前需确认状态`
+    - `待补开通`
+    - `待人工整理`
+    - `仅目录可见`
+  - `兼容宿主线路 / allowed_groups / group_id` 已从普通用户主文案退到后端发放实现细节
+- 2026-06-01 已把 `PRD` 与当前前端交付范围口径对齐：
+  - `PRD` 中“暂不做 Web 控制台”保留其历史语义
+  - 但 `deploy/tksea-portal/` 下的 portal/admin 静态页已经被明确声明为 deployment-facing 配套交付物，不再允许出现“PRD 说没做，执行板说已完成”的冲突读法
 - 2026-06-01 已继续收掉 `subscription_ready` 的最后一个真实闭环缺口：
  - 根因不是 provider、不是前端，也不是宿主随机波动，而是 CRM 旧实现会在 subscription closure 里把目标用户替换成 synthetic managed user，再用 managed key 做 probe
  - 这样会出现“closure 返回 `subscription_ready`，但目标用户自己的 `GET /api/v1/subscriptions/active` 仍为空，`/v1/models` 仍然 `403 INSUFFICIENT_BALANCE`”的假阳性
@@ -46,6 +75,219 @@
 - `self_service` 主链路已通过 latest-head 标准 fresh-host 复验：
  - `artifacts/real-host-acceptance/20260521_210403/05-import.json`
  - `artifacts/real-host-acceptance/20260521_210403/07-access-status.json`
+
+## 2026-06-01 前端记录模板
+
+从 2026-06-01 起，`EXECUTION_BOARD.md` 中所有前端条目统一按以下字段记录：
+
+- 页面：
+  - 当前页面或入口 URL / 路径
+- 动作：
+  - 这次变更或验收覆盖的页面内显式动作
+- 接口：
+  - 页面直接依赖的关键 API；只写当前动作真正消费的接口
+- 最近真实回读：
+  - 最新脚本、页面回读、API 回读或 artifact 证据
+- 测试垃圾：
+  - 是否留下临时 `logical_group / route / user / draft / batch` 等测试资源
+- 当前结论：
+  - 统一使用 `已闭环 / 部分闭环 / 兼容入口 / 历史已闭环` 这组口径
+
+历史长段仍保留为证据仓；若要快速判断前端现状，优先读下面这份统一索引。
+
+## 2026-06-01 前端页面统一索引
+
+### `/portal/`
+
+- 页面：
+  - `https://sub.tksea.top/portal/`
+- 动作：
+  - 逻辑分组目录
+  - 权限/订阅/历史 key 投影
+  - 使用建议与模型说明
+- 接口：
+  - `GET /api/portal/logical-groups`
+  - `GET /api/portal/logical-groups/{group_id}`
+  - `GET /api/portal/logical-groups/{group_id}/models`
+  - `GET /api/portal/auth/me`
+  - `GET /api/portal/groups/available`
+  - `GET /api/portal/subscriptions`
+  - `GET /api/portal/keys`
+- 最近真实回读：
+  - 前端统一入口：`bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh`
+  - 页面只读验收：`bash ./scripts/acceptance/verify_portal_catalog_ui.sh`
+  - 浏览器 smoke：`bash ./scripts/test/verify_frontend_smoke.sh`
+  - 历史产品化真验见：
+    - `P4-T2 portal logical group catalog frontend`
+    - `P4-T3 portal logical entitlement projection`
+    - `P4-T4 portal logical group usage guidance`
+- 测试垃圾：
+  - portal 相关真验条目均要求删除临时 `logical_group / route / model / user / key / subscription`
+- 当前结论：
+  - `历史已闭环`
+
+### `/portal/admin/logical-groups.html`
+
+- 页面：
+  - `https://sub.tksea.top/portal/admin/logical-groups.html`
+- 动作：
+  - `logical_group` 创建 / 更新 / 删除
+  - `public_model` 新增 / 删除
+  - `route` 创建 / 更新 / 删除
+  - `route model` 新增 / 查看
+- 接口：
+  - `POST /api/admin/session/login`
+  - `POST /api/admin/session/logout`
+  - `GET /api/admin/session`
+  - `GET /api/logical-groups`
+  - `POST /api/logical-groups`
+  - `PUT /api/logical-groups/{group_id}`
+  - `DELETE /api/logical-groups/{group_id}`
+  - `POST /api/logical-groups/{group_id}/models`
+  - `DELETE /api/logical-groups/{group_id}/models/{public_model}`
+  - `POST /api/logical-groups/{group_id}/routes`
+  - `PUT /api/logical-groups/{group_id}/routes/{route_id}`
+  - `DELETE /api/logical-groups/{group_id}/routes/{route_id}`
+  - `POST /api/logical-groups/{group_id}/routes/{route_id}/models`
+- 最近真实回读：
+  - 控制面标准验收：`bash ./scripts/acceptance/verify_route_control_plane.sh`
+  - 前端统一入口：`bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh`
+  - 浏览器 smoke：`bash ./scripts/test/verify_frontend_smoke.sh`
+  - 历史真验主条目见：`P2-T1 管理页入口`
+- 测试垃圾：
+  - route/control-plane 真验要求删除临时 `logical_group / route / model`
+- 当前结论：
+  - `已闭环`
+
+### `/portal/admin/route-health.html`
+
+- 页面：
+  - `https://sub.tksea.top/portal/admin/route-health.html`
+- 动作：
+  - route 健康聚合查看
+  - `healthy / cooldown / failing / disabled` 四态过滤
+  - failover 与最近一次选路回读
+- 接口：
+  - `GET /api/routing/routes/health`
+  - `POST /api/routing/resolve`
+  - `GET /api/routing/logs/failovers`
+  - `GET /api/admin/session`
+  - `POST /api/admin/session/login`
+  - `POST /api/admin/session/logout`
+- 最近真实回读：
+  - 健康页验收：`bash ./scripts/acceptance/verify_route_health_ui.sh`
+  - 前端统一入口：`bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh`
+  - 浏览器 smoke：`bash ./scripts/test/verify_frontend_smoke.sh`
+  - 历史真验主条目见：`P2-T3 route 健康视图`
+- 测试垃圾：
+  - health/runtime 真验要求删除临时 `logical_group / route`
+- 当前结论：
+  - `已闭环`
+
+### `/portal/admin/accounts.html`
+
+- 页面：
+  - `https://sub.tksea.top/portal/admin/accounts.html`
+- 动作：
+  - `provider_accounts` 列表与过滤
+  - enable / disable / retire
+  - `binding_candidates` 查看
+  - route 显式绑定 / 清空绑定
+- 接口：
+  - `GET /api/provider-accounts`
+  - `POST /api/provider-accounts/{account_id}/enable`
+  - `POST /api/provider-accounts/{account_id}/disable`
+  - `POST /api/provider-accounts/{account_id}/retire`
+  - `GET /api/provider-accounts/{account_id}/binding-candidates`
+  - `POST /api/provider-accounts/{account_id}/binding`
+  - `GET /api/admin/session`
+  - `POST /api/admin/session/login`
+  - `POST /api/admin/session/logout`
+- 最近真实回读：
+  - 页面只读验收：`bash ./scripts/acceptance/verify_accounts_admin_ui.sh`
+  - 前端统一入口：`bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh`
+  - 浏览器 smoke：`bash ./scripts/test/verify_frontend_smoke.sh`
+  - 历史真验主条目见：
+    - `P3-T2 帐号资产页与归属展示`
+    - `P3-T3 帐号归属显式整理`
+- 测试垃圾：
+  - 绑定冲突真验要求删除临时 `logical_group / route`
+  - 现网样本状态在验收完成后需恢复
+- 当前结论：
+  - `已闭环`
+
+### `/portal/admin/providers.html`
+
+- 页面：
+  - `https://sub.tksea.top/portal/admin/providers.html`
+- 动作：
+  - pack / host / provider 目录加载
+  - `preview-import`
+  - `import`
+  - draft `save / update / delete / publish`
+- 接口：
+  - `GET /api/packs`
+  - `GET /api/hosts`
+  - `GET /api/packs/{pack_id}/providers`
+  - `POST /api/providers/{provider_id}/preview-import`
+  - `POST /api/providers/{provider_id}/import`
+  - `POST /api/provider-drafts`
+  - `PUT /api/provider-drafts/{draft_id}`
+  - `DELETE /api/provider-drafts/{draft_id}`
+  - `POST /api/provider-drafts/{draft_id}/publish`
+  - `GET /api/admin/session`
+  - `POST /api/admin/session/login`
+  - `POST /api/admin/session/logout`
+- 最近真实回读：
+  - 页面动作验收：`bash ./scripts/acceptance/verify_provider_admin_actions.sh`
+  - 前端统一入口：`bash ./scripts/acceptance/verify_frontend_acceptance_matrix.sh`
+  - 浏览器 smoke：`bash ./scripts/test/verify_frontend_smoke.sh`
+  - 本机真实页面级 artifact：`artifacts/provider-admin-matrix/1780278231_provider_admin_actions/99-summary.json`
+- 测试垃圾：
+  - 本机/远端 provider 验收需要显式清理临时 draft、provider、测试导入资源；发布验证若产生真实 git 提交，必须在记录里说明
+- 当前结论：
+  - `已闭环`
+
+### `/portal/admin-batch-import.html`
+
+- 页面：
+  - `https://sub.tksea.top/portal/admin-batch-import.html`
+- 动作：
+  - 创建 batch import run
+  - 刷新 run 摘要
+  - 过滤 item 列表并查看 `matched_account_state / account_resolution`
+- 接口：
+  - `POST /api/batch-import/runs`
+  - `GET /api/batch-import/runs/{run_id}`
+  - `GET /api/batch-import/runs/{run_id}/items`
+  - `GET /api/admin/session`
+  - `POST /api/admin/session/login`
+  - `POST /api/admin/session/logout`
+- 最近真实回读：
+  - 浏览器 smoke：`bash ./scripts/test/verify_frontend_smoke.sh`
+  - 资产回归：`bash ./scripts/test/test_tksea_portal_assets.sh`
+  - 当前更多证据仍来自执行板历史长段与 `admin-batch-import` 页面回读
+- 测试垃圾：
+  - 若创建真实 run，必须在条目里说明 run 是否仅为只读回查、是否清理相关临时输入样本
+- 当前结论：
+  - `部分闭环`
+
+### `/portal/admin/batch-import.html`
+
+- 页面：
+  - `https://sub.tksea.top/portal/admin/batch-import.html`
+- 动作：
+  - 跳转到 legacy `admin-batch-import.html`
+- 接口：
+  - 无独立业务接口；只承担兼容跳转
+- 最近真实回读：
+  - 资产回归：`bash ./scripts/test/test_tksea_portal_assets.sh`
+  - 浏览器 smoke：`bash ./scripts/test/verify_frontend_smoke.sh`
+- 测试垃圾：
+  - 无
+- 当前结论：
+  - `兼容入口`
+
 - 2026-05-27 已把公网用户入口从 `kimi-portal` 收口为通用多模型 portal：
  - 新正式地址：`https://sub.tksea.top/portal/`
  - 旧地址 `https://sub.tksea.top/kimi-portal/` 当前保留为 `302` 跳转，避免历史分享链接失效
@@ -2420,3 +2662,113 @@

 - `ProvidersRepo.Upsert / PacksRepo.Upsert` 已不再是这轮质量治理的主要薄点
 - 这一波按执行板列出的热点定点补测，到这里已经基本收口
+
+---
+
+## 2026-06-01 生产级修复任务
+
+### 系统性 Review 结论
+
+**Review 报告**: `docs/2026-06-01-SYSTEMATIC-REVIEW-REPORT.md`  
+**修复方案**: `docs/2026-06-01-SYSTEMATIC-REPAIR-PLAN.md`  
+**任务清单**: `TASKS.md`
+
+### 关键发现
+
+**综合评级**: B (有条件通过) → 目标 A (生产就绪)  
+**BLOCKER 问题**: 4 项（必须修复）  
+**HIGH 问题**: 5 项（建议修复）  
+**MEDIUM 问题**: 4 项（可选修复）
+
+### 修复任务追踪
+
+#### BLOCKER (P0)
+
+| 编号 | 任务 | 状态 | 负责人 | 预计工时 | PR |
+|------|------|------|--------|----------|-----|
+| B-01 | HTTP Server 添加超时配置 | 🔄 待开始 | - | 4h | - |
+| B-02 | 日志结构化改造 (slog) | 🔄 待开始 | - | 6h | - |
+| B-03 | 日志轮转配置 | 🔄 待开始 | - | 4h | - |
+| B-04 | CI/CD 工作流配置 | 🔄 待开始 | - | 4h | - |
+
+**BLOCKER 完成标准**:
+- [ ] HTTP Server 配置四项超时参数
+- [ ] 所有日志输出 JSON 格式
+- [ ] 日志轮转限制 100MB/3备份
+- [ ] GitHub Actions CI/CD 运行
+
+#### HIGH (P1)
+
+| 编号 | 任务 | 状态 | 负责人 | 预计工时 | PR |
+|------|------|------|--------|----------|-----|
+| H-01 | 补充 testutil 测试 | ⏳ 待排期 | - | 3h | - |
+| H-02 | 补充 migrations 测试 | ⏳ 待排期 | - | 4h | - |
+| H-03 | 日志 flush 错误监控 | ⏳ 待排期 | - | 3h | - |
+| H-04 | Prometheus 指标暴露 | ⏳ 待排期 | - | 6h | - |
+| H-05 | 移除 Dockerfile 默认值 | ⏳ 待排期 | - | 1h | - |
+
+#### MEDIUM (P2)
+
+| 编号 | 任务 | 状态 | 负责人 | 预计工时 | PR |
+|------|------|------|--------|----------|-----|
+| M-01 | 测试代码 panic 替换 | ⏳ 待排期 | - | 2h | - |
+| M-02 | 错误信息字符串匹配优化 | ⏳ 待排期 | - | 3h | - |
+| M-03 | 边界测试补充 | ⏳ 待排期 | - | 4h | - |
+| M-04 | 添加版本信息端点 | ⏳ 待排期 | - | 3h | - |
+
+### 执行计划
+
+**Week 1 (2026-06-01 ~ 06-07)**: BLOCKER 修复  
+**Week 2 (2026-06-08 ~ 06-14)**: HIGH 修复  
+**Week 3 (2026-06-15 ~ 06-21)**: MEDIUM 修复 + 全量验收
+
+### 生产就绪重新评估
+
+**目标日期**: 2026-06-21  
+**目标评级**: A (优秀，可直接上线)  
+**前提条件**: 所有 BLOCKER 修复 + HIGH 完成 80%
+
+
+---
+
+## 2026-06-01 最佳实践审核补充任务
+
+### 审核报告
+- **报告**: `docs/2026-06-01-BEST-PRACTICE-AUDIT-REPORT.md`
+- **结果**: 原始方案 100% 覆盖 Review 问题，但存在 9 项最佳实践差距
+- **建议**: 补充 4 项高优先级 + 5 项中优先级任务
+
+### 高优先级补充任务（必须完成）
+
+| 编号 | 任务 | 状态 | 工时 |
+|------|------|------|------|
+| H-1a | 日志敏感信息脱敏 | ⏳ 待排期 | 2h |
+| H-2a | CI/CD 安全扫描 | ⏳ 待排期 | 3h |
+| H-3a | Dockerfile 非 root 用户 | ⏳ 待排期 | 1h |
+| H-4a | 新建故障处理手册 | ⏳ 待排期 | 4h |
+
+### 中优先级补充任务（建议完成）
+
+| 编号 | 任务 | 状态 | 工时 |
+|------|------|------|------|
+| M-1a | 添加 ReadHeaderTimeout | ⏳ 待排期 | 1h |
+| M-2a | 添加 trace_id 支持 | ⏳ 待排期 | 3h |
+| M-3a | 添加模糊测试 | ⏳ 待排期 | 4h |
+| M-4a | 添加业务指标 | ⏳ 待排期 | 3h |
+| M-5a | API 限流实现 | ⏳ 待排期 | 4h |
+
+### 更新后计划
+
+**Phase 1 (Week 1)**: BLOCKER (4) + 高优先级补充 (4) = 8 项
+**Phase 2 (Week 2)**: HIGH (5) + 中优先级补充 (5) = 10 项
+**Phase 3 (Week 3)**: MEDIUM (4) + 验收测试 = 4 项
+
+**总计**: 22 项任务，预计 73h
+
+### 生产就绪目标
+
+**原始目标**: 综合评级 B → A
+**更新目标**: 综合评级 A + 符合行业最佳实践
+
+完成补充任务后，项目将完全符合生产级上线运营标准。
+