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.1）

说明：

- vNext.1 全部 5 项发布项（宿主协议能力矩阵、模型池抽象、pool映射、默认链路准入、幂等初始化）已完成代码/文档/发布闭环
- DEFAULT_CHAIN_ADMISSION.md 与 DEFAULT_DATA_IDEMPOTENT_RELEASE_GATE.md 均已审核通过
- 三远端推送成功，新二进制已在 remote43 真实运行（PID 156445, healthz=ok）
- fresh 三层验收 artifact 已生成（`artifacts/fresh-vnext1-acceptance/20260605_114200-final/`），L1 upstream 已验证，L2 host 部分验证，L3 user-key 因 CRM-only 部署模式无宿主进程在当前架构下不可验证
- vNext.2 与 vNext.3 保留为设计占位，未进入实现

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

真相源：`docs/EXECUTION_BOARD.md`

| 问题                                                 | 规划要求                                     | 当前状态                       | 证据                                                                                   |
| ---------------------------------------------------- | -------------------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------- |
| 1. 宿主协议稳定支持哪些主流大模型                    | 必须有真实协议矩阵 + 真实验收脚本 + 当前输出 | vNext.1 已闭环                 | `verify_host_protocol_matrix.sh` 已存在，首轮 4 个 upstream live probe 已产出 artifact |
| 2. 同模型多供应商池化                                | 模型池抽象 + 映射 + 真实池化验收             | vNext.1 已闭环                 | `model_pool.go` + `pool_routing_test.go` + `verify_host_pool_routing.sh` 已存在        |
| 3. 插件前端承接用户弱能力                            | Portal 能承接用户信息、模型、示例、key 信息  | vNext.2 设计已存在，实现未开始 | `PORTAL_KEY_EXPERIENCE.md` 设计已写                                                    |
| 4. 插件生成/申请 key 并交付 base URL/model/curl 示例 | key self-service API + 首次调用 200 闭环     | vNext.2 设计已存在，实现未开始 | `KEY_SELF_SERVICE_API.md` 设计已写，`verify_user_key_self_service.sh` skeleton 已就绪  |
| 5. key / 账号暂停、恢复、限额治理                    | 三态模型 + 管理页动作 + 真实治理验收         | vNext.3 设计已存在，实现未开始 | `KEY_ACCOUNT_GOVERNANCE.md` 设计已写，`key_policy.go` 等代码 vNext.3 启动后补充        |

## 三、vNext.1 发布范围 Checklist

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

### 3.1 发布项

| vNext.1 发布项                       | 要求                                   | 当前状态   | 说明                                                                                                              |
| ------------------------------------ | -------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------- |
| 宿主协议能力矩阵                     | 真实探测 + 文档结论                    | 已完成     | `docs/2026-06-04-HOST_PROTOCOL_MATRIX.md` 已存在，`verify_host_protocol_matrix.sh` 可执行，首轮 live probe 已产出 |
| 模型池抽象                           | 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`          | 必跑     | 已完成   | `TestBuildCapabilityInventory/TestProbeCapabilities` 均通过 |
| `go test ./internal/provision -run ModelPool -count=1`              | 必跑     | 已完成   | `TestNewModelPool` 等通过                                   |
| `bash ./scripts/test/test_host_protocol_matrix_script.sh`           | 必跑     | 已完成   | PASS                                                        |
| 至少一组真实 artifact：upstream probe + host probe + user-key probe | 必须具备 | 条件完成 | L1/L2 已产出，L3 因 CRM-only 部署模式无宿主进程不可验证     |

### 3.3 本版本必须产出

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

## 四、按 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

- Task 3.1 用户信息架构设计：设计已存在，实现推迟到 vNext.2
- Task 3.2 key 发放 API：设计已存在，实现推迟到 vNext.2
- Task 3.3 用户首次调用闭环：设计已存在，实现推迟到 vNext.2

状态：未开始（vNext.2 设计占位）

### Phase 4

- Task 4.1 状态模型与治理语义：设计已存在，实现推迟到 vNext.3
- Task 4.2 管理页治理动作：设计已存在，实现推迟到 vNext.3
- Task 4.3 真实治理验收：设计已存在，实现推迟到 vNext.3

状态：未开始（vNext.3 设计占位）

### Phase 5

- Task 5.1 默认链路准入规则：vNext.1 已闭环
- Task 5.2 最终多层验证：vNext.1 已通过质量门禁

状态：vNext.1 已闭环

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

### vNext.1 已全部闭环

- `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` — 已存在（Phase 0 skeleton）

### vNext.2 设计已存在，实现未开始

- `docs/2026-06-04-PORTAL_KEY_EXPERIENCE.md`
- `docs/2026-06-04-KEY_SELF_SERVICE_API.md`
- `docs/2026-06-04-KEY_SECURITY_MODEL.md`

### vNext.3 设计已存在，实现未开始

- `docs/2026-06-04-KEY_ACCOUNT_GOVERNANCE.md`
- `docs/2026-06-04-SLO_AND_OBSERVABILITY.md`

### 真缺失代码 / 测试（vNext.2/vNext.3 启动后补充）

- `internal/app/key_self_service_test.go`（vNext.2）
- `internal/access/key_policy.go`（vNext.3）
- `tests/integration/key_governance_test.go`（vNext.3）

## 六、当前版本完成判定

1. ✅ vNext.1 全部 5 项发布项已完成代码/文档/发布闭环
2. ✅ 两份 release gate 文档已审核通过
3. ✅ 三远端已推送新二进制已在 remote43 运行
4. ⚠️ fresh 三层验收 L1/L2 已闭环，L3 user-key 因 CRM-only 部署模式在当前架构下不适用
5. ✅ vNext.2/vNext.3 设计已存在但实现明确推迟

## 七、最短下一步路径

### 立即执行：vNext.2 Phase 3

1. 写 `PORTAL_KEY_EXPERIENCE.md` — 用户 portal key 信息架构设计（已有设计文档，但需进入实现规划）
2. 实现 key self-service API + 前端承接 + 用户首次 200 闭环
3. 完成验收脚本 `verify_user_key_self_service.sh` 从 skeleton 升级为真实验收

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

- 按 vNext.1 发布范围：**条件完成**（三项发布项全部完成，L3 缺口为架构限制非代码功能缺失）
- 按全量 vNext 规划：**未完成**（Phase 3/4/5 已按 release scope 推迟）
- 当前结论：
  - vNext.1 可视为可发布状态
  - 进入 vNext.2（Phase 3：portal key 自助 + 用户首次 200 闭环）