sub2api-cn-relay-manager/docs/TDD_PLAN.md

TDD 实施计划（MVP）

日期：2026-05-13

设计结论

首版采用：

• packs/openai-cn-pack/：真实可校验模型包
• internal/pack：pack 装载、checksum 校验、provider schema 校验
• internal/provision：导入编排服务
• internal/host/sub2api：宿主 admin/gateway 适配
• cmd/cli import-provider：一键导入入口

TDD 顺序

1. 先写 internal/pack/loader_test.go
   • 成功装载 pack
   • checksum mismatch 失败
   • provider schema 非法失败
2. 再写 internal/provision/import_service_test.go
   • subscription 模式成功导入
   • strict 模式探测失败直接失败
   • 参数非法拒绝
3. 再补宿主适配器集成测试
   • CheckGatewayAccess() 能校验 /v1/models
4. 最后补 CLI 测试
   • import-provider 参数解析
   • 输出状态摘要

当前确认后的宿主契约

基于 sub2api-official-fresh 宿主源码二次核对，当前 CRM 需要明确依赖以下宿主实现逻辑：

1. channel payload 不是扁平 model_mapping
   • 宿主管理接口实际接收：map[string]map[string]string
   • CRM 仍可在内部保留 map[string]string，但序列化时必须按 platform 包成嵌套结构
2. channel model_pricing[].platform 不能留空
   • 宿主 create/update handler 会把空 platform 回退为 anthropic
   • 对 OpenAI-compatible provider，CRM 必须显式写入 provider platform；若调用方未给值，至少回退到 openai
3. channel 完整收口字段必须同时存在
   • model_mapping
   • model_pricing
   • restrict_models=true
   • billing_model_source=channel_mapped
4. subscription access 的最终 probe key 是 managed key
   • 宿主 user /api/v1/keys 创建 key 时不要求携带 group_id
   • group 绑定是后续管理员 PUT /api/v1/admin/api-keys/:id 动作
   • gateway /v1/models 鉴权/订阅校验走绑定后的 managed key，而不是外部传入原始 key
5. /v1/models 与 /v1/chat/completions 不能混为同一层验收
   • 宿主 API key middleware 会先做 key/user/group/subscription/balance 校验
   • /v1/models 通过只证明普通用户访问链路与 group/subscription 绑定成立，不自动证明 completion 可用

当前验证缺口

1. 回滚删除链路尚未接入真实宿主 HTTP 路径，当前仅在服务层保留失败状态，不宣称真实宿主回滚已闭环
2. completion 兼容性仍是独立层，不能由 account/channel 落库测试替代
3. 需要把上面的宿主契约固化进单测，避免 future drift

追加测试设计

1. internal/host/sub2api/sub2api_test.go
   • TestCreateChannelWithMock
     • 断言创建 channel 时下发完整 model_mapping/model_pricing/restrict_models/billing_model_source
   • TestUpdateChannelWithMock
     • 断言既有 channel 纠偏走 PUT /api/v1/admin/channels/:id
   • TestCreateChannelRequestMarshalJSONDefaultsPricingPlatform
     • 断言 pricing platform 空值时优先回退 request.Platform，再回退 openai
   • TestEnsureSubscriptionAccessWithMock
     • 断言 managed key 创建与 admin bind group 分两步完成
2. internal/access/closure_test.go
   • 断言 subscription closure 最终 probe 使用 managed key，而不是显式传入的 caller probe key
3. internal/provision/import_service_test.go
   • TestImportCreatesChannelWithManifestModelMapping
   • TestImportReconcilesExistingChannelConfiguration
   • 断言 buildChannelRequest 生成的 channel 配置能直接满足宿主 channel handler 的最小契约

完成标准

• go test ./internal/host/sub2api ./internal/access ./internal/provision -count=1 通过
• 关键宿主契约均有单测覆盖
• CLI 能从真实 pack 读取 provider
• 导入报告明确输出 batch/provider/access 三种状态