sub2api-cn-relay-manager/docs/2026-06-05-VNEXT_COMPLETION_CHECKLIST.md

vNext 完成度 Checklist（2026-06-05）

目的：作为当前版本 goal 判断的真相源，避免再用局部 Task 完成替代版本完成。 依据文档：

• docs/2026-06-04-plugin-host-enhancement-TDD_PLAN.md
• docs/2026-06-04-plugin-host-enhancement-SPEC.md
• docs/2026-06-04-vnext-release-scope.md
• docs/EXECUTION_BOARD.md

一、先说结论

当前状态：完成（全量 vNext）

说明：

• vNext.1 已完成代码/文档/发布闭环。
• vNext.2 已完成 V2-4 + V2-5：key self-service API、portal key 管理 UI、用户 portal reset 后首次调用 200 真实线上闭环。
• vNext.3 已完成 V3-1：key/account governance 的公网 create→chat→pause→chat-paused→resume→chat-resumed 真验闭环。
• vNext.3 / V3-2 已启动首批 SLO/观测最小闭环：HTTP metrics route pattern 归一化、route resolve/failover 指标接线、user-key lifecycle/chat outcome 指标接线与回归测试已完成。
• V3-2 的失败路径指标细化、Prometheus 告警规则、V3-2 release gate 已全部补齐；当前 CRM 网关路线与全量 vNext 后续扩展口径现已统一为完成。

二、5 个核心问题 Checklist（全量 vNext 目标）

真相源：docs/EXECUTION_BOARD.md

问题	规划要求	当前状态	证据
1. 宿主协议稳定支持哪些主流大模型	必须有真实协议矩阵 + 真实验收脚本 + 当前输出	vNext.1 已闭环	verify_host_protocol_matrix.sh 与相关 artifact 已存在
2. 同模型多供应商池化	模型池抽象 + 映射 + 真实池化验收	vNext.1 已闭环	model_pool.go、pool 测试、真实验收脚本已存在
3. 插件前端承接用户弱能力	Portal 能承接用户信息、模型、示例、key 信息	V2-5 已完成	PORTAL_KEY_EXPERIENCE.md、deploy/tksea-portal/index.html、artifacts/portal-ui-v25/20260606_1009/99-summary.json
4. 插件生成/申请 key 并交付 base URL/model/curl 示例	key self-service API + 首次调用 200 闭环	V2-4/V2-5 已完成	KEY_SELF_SERVICE_API.md、verify_user_key_self_service.sh、artifacts/user-key-self-service/20260605_195408/99-summary.json、artifacts/portal-ui-v25/20260606_1009/99-summary.json
5. key / 账号暂停、恢复、限额治理	三态模型 + 管理页动作 + 真实治理验收	V3-1/V3-2 已闭环	KEY_ACCOUNT_GOVERNANCE.md、artifacts/v3-governance-live/20260608_102323/99-summary.json、internal/metrics/metrics.go、internal/app/public_chat_metrics_test.go、scripts/test/verify_vnext_slo_release_gate.sh

三、vNext.1 发布范围 Checklist

真相源：docs/2026-06-04-vnext-release-scope.md

3.1 发布项

vNext.1 发布项	要求	当前状态	说明
宿主协议能力矩阵	真实探测 + 文档结论	已完成	已有脚本 + live artifact
模型池抽象	ModelPool 抽象	已完成	已有实现 + 测试
pool 到 priority failover 运行面映射	runtime import / logical_group 映射	已完成	已接线并通过 provision 测试
默认链路准入规则	文档化硬规则	已审核通过	docs/2026-06-04-DEFAULT_CHAIN_ADMISSION.md
幂等默认数据/初始化脚本进入发布前置	runbook 或脚本说明	已审核通过	docs/2026-06-04-DEFAULT_DATA_IDEMPOTENT_RELEASE_GATE.md + scripts/setup_default_data.sh

3.2 本版本验收命令

验收项	规划要求	当前状态	证据
go test ./internal/host/sub2api -run Capability -count=1	必跑	已完成	已通过
go test ./internal/provision -run ModelPool -count=1	必跑	已完成	已通过
bash ./scripts/test/test_host_protocol_matrix_script.sh	必跑	已完成	PASS
至少一组真实 artifact：upstream probe + host probe + user-key probe	必须具备	已完成	fresh 验收 + 后续 V2-4 user-key artifact 已补齐

3.3 本版本必须产出

产物	规划要求	当前状态
docs/2026-06-04-vnext-release-scope.md	必须存在	已完成
docs/2026-06-04-HOST_PROTOCOL_MATRIX.md	必须存在	已完成
docs/2026-06-04-MODEL_POOL_DESIGN.md	必须存在	已完成
docs/2026-06-04-DEFAULT_CHAIN_ADMISSION.md	必须存在	已审核通过
幂等初始化/默认数据 runbook 或脚本说明	必须存在	已审核通过 + 配套脚本已实现

四、按 TDD Plan 分阶段状态

Phase 0 / 1 / 1.5

• 规格文档、capability inventory、host protocol matrix 基础骨架：已闭环
• release scope 已落地为实际执行边界

状态：vNext.1 已闭环

Phase 2

• Task 2.1 模型池抽象：完成
• Task 2.2 宿主池化映射编排：完成
• Task 2.3 真实池化路由验收：完成（脚本 + 集成测试）

状态：vNext.1 已闭环

Phase 3（vNext.2）

• Task 3.1 用户信息架构设计：设计已存在并已按设计接线到 portal
• Task 3.2 key 发放 API：已实现并上线验证
• Task 3.3 用户首次调用闭环：已完成真实 chat/completions=200
• Task 3.4 portal key 管理 UI：已完成真实登录、已有 Key、reset、新明文、curl 示例与首呼 200 闭环

状态：vNext.2 已闭环

Phase 4（vNext.3 / V3-1 + V3-2）

• Task 4.1 状态模型与治理语义：已实现并接线到 CRM 网关 POST /v1/chat/completions
• Task 4.2 管理页治理动作：已实现（pause / resume 同步宿主 managed user allowed_groups）
• Task 4.3 真实治理验收：已完成，见 artifacts/v3-governance-live/20260608_102323/99-summary.json
• Task 4.4 SLO / 观测闭环：已完成
  • internal/metrics/metrics.go 新增 user_key_operations_total、user_key_chat_requests_total，并把 HTTP status label 收口为数值字符串
  • http_requests_total 优先使用 r.Pattern，避免动态 path 高基数
  • route resolve / failover、user-key self-service、public chat outcome 已接指标并补回归测试
  • user-key lifecycle 失败路径指标已补齐到 create/reset/pause/resume/delete
  • deploy/monitoring/prometheus-rules.yml 已按当前指标口径重写
  • scripts/test/verify_vnext_slo_release_gate.sh 已落地并纳入总质量门

状态：V3-1 / V3-2 已闭环

Phase 5

• Task 5.1 默认链路准入规则：vNext.1 已闭环
• Task 5.2 多层验证：vNext.1 + V2-4 当前均已有真实 artifact

状态：完成（全量 vNext 已完成）

五、当前缺失文件 / 脚本 / 测试（按真实存在性校对）

已完成

• docs/2026-06-04-DEFAULT_CHAIN_ADMISSION.md — 已审核通过
• docs/2026-06-04-DEFAULT_DATA_IDEMPOTENT_RELEASE_GATE.md — 已审核通过
• scripts/acceptance/verify_host_pool_routing.sh — 已存在
• scripts/acceptance/verify_host_protocol_matrix.sh — 已存在
• scripts/acceptance/verify_user_key_self_service.sh — 已从 skeleton 升级为真实验收脚本
• internal/app/key_self_service_test.go — 已存在
• internal/app/user_key_operation_metrics_test.go — 已存在
• scripts/test/verify_vnext_slo_release_gate.sh — 已存在
• deploy/monitoring/prometheus-rules.yml — 已按 V3-2 指标口径重写

vNext.2 尚缺

• 无

V3-1 已闭环（2026-06-08）

• ✅ 三段式治理真验已完成：artifacts/v3-governance-live/20260608_102323/99-summary.json
• ✅ 真实公网 /v1/chat/completions 已切到 CRM 网关，paused key 现返回 403 key_paused
• ✅ 新 key 全链路真验通过：create 201 → chat-before 200 → pause 200 → chat-paused 403 → resume 200 → chat-resumed 200 → delete 200
• ✅ 治理验收脚本模板仍可复用：scripts/acceptance/verify_user_key_self_service.sh
• 备注：宿主 PUT /api/v1/admin/api-keys/{id} 仍不可用，但当前 V3-1 路线已通过 user-level allowed_groups + CRM 网关治理校验完成真实闭环。

六、当前版本完成判定

1. ✅ vNext.1 全部 5 项发布项已完成代码/文档/发布闭环
2. ✅ V2-4 已完成后端实现、线上部署、真实 user-key 首呼 200 验收
3. ✅ V2-5 已完成 portal 登录→已有 Key→reset 新明文→curl 示例更新→真实首呼 200 闭环
4. ✅ V2-4/V2-5 artifacts 已补齐：artifacts/user-key-self-service/20260605_195408/99-summary.json、artifacts/portal-ui-v25/20260606_1009/99-summary.json
5. ✅ V3-1 key/account governance：P0 根因与真实环境阻断均已收口；最新公网真验为 create 201 → chat 200 → pause 200 → chat-paused 403 → resume 200 → chat 200，见 artifacts/v3-governance-live/20260608_102323/99-summary.json。SLO/治理扩展项仍按后续范围推进，但不再阻塞 CRM 网关路线验收。

七、最短下一步路径

立即执行：收尾与同步

1. 运行完整质量门并确认 worktree clean
2. commit + push 本轮 V3-2 收尾变更
3. 更新任务真相源为 completed

八、当前判定（唯一有效口径）

• 按 vNext.1 发布范围：完成
• 按 vNext.2 当前执行项：完成（V2-4 + V2-5 已真实闭环）
• 按全量 vNext 规划：完成（V2-4 / V2-5 / V3-1 / V3-2 均已完成代码、门禁、文档与真实证据闭环）
• 当前结论：
  • 全量 vNext 后续扩展已完成
  • 当前仅剩本轮变更的 commit / push 收尾动作