# sub2api-cn-relay-manager PRD（MVP）

日期：2026-05-13

## 目标

在**完全不修改 sub2api 官方系统代码**的前提下，交付一个可独立打包运行的外部伴生项目，使管理员能够通过一次导入动作，把国产模型 OpenAI 兼容中转能力安装到任意一套兼容的 sub2api 实例中。

## 硬约束

1. 不修改宿主源码
2. 不 fork 宿主并运行私有二进制
3. 不直接写宿主数据库
4. 不向宿主目录注入插件代码或补丁文件
5. 仅通过宿主现有 HTTP 管理 API 与标准 API 工作

## 首版验收

1. `model_pack` 可独立校验与装载
2. CLI 可直接读取 pack、选择 provider、导入多条 key
3. 导入流程能创建 group / channel / plan（subscription 模式）/ accounts
4. 至少一个 account 完成 `/test` 与 `/models` 验证
5. 至少一种普通用户访问路径被真实探测：`GET /v1/models`
6. 失败时明确区分：`succeeded / partially_succeeded / failed`

## 首版边界

### 做
- pack runtime
- provider schema 校验
- 多 key 去重与批量导入
- subscription/self-service 两种访问模式建模
- CLI 一键导入
- 基于 stub 的端到端测试

### 暂不做
- 通用型、需要单独前端工程维护的 Web 控制台
- 多宿主管理
- 自动代用户签发最终 API key
- 对账调度器完整实现
- 真实宿主删除/回滚链路

## 当前实现策略

首版先把“可独立打包 + 零侵入导入 + 用户访问验证”做成最小闭环；状态库、HTTP 控制面、对账调度在此基础上继续扩展。

## 2026-06-01 边界补充

上面的“暂不做 Web 控制台”仍然保留其历史语义：首版不以单独前端工程、完整产品化管理台作为 MVP 放行前提。

但当前仓库已经额外纳管了一组 deployment-facing 静态前端资产，作为控制面与公网 portal 的运维/验收配套，不应再被误读为“仓库没有前端”：

- `deploy/tksea-portal/index.html`
- `deploy/tksea-portal/admin/index.html`
- `deploy/tksea-portal/admin/logical-groups.html`
- `deploy/tksea-portal/admin/route-health.html`
- `deploy/tksea-portal/admin/accounts.html`
- `deploy/tksea-portal/admin/providers.html`
- `deploy/tksea-portal/admin-batch-import.html`
- `deploy/tksea-portal/admin/batch-import.html`

这些页面的角色是：

- 为已存在的控制面/宿主 API 提供静态浏览器入口
- 为 portal、provider 导入、logical group、route health、batch import 等链路提供可操作或可观测界面
- 作为部署与验收资产纳入仓库门禁

所以当前口径应统一为：

- `PRD` 首版主线仍然是“控制面 + pack + 零侵入导入闭环”
- 前端页面属于后续已落地的配套交付物，而不是 `PRD` 当天写作时承诺的 MVP 主目标