# V2 接口优先级规划

日期：2026-07-06

## 目的

这份文档用于确定接口开发顺序，避免一开始平均用力。优先级依据是：先跑通用户端主链路，再补后台配置和运营能力。

## P0：用户端主链路接口

P0 接口必须最先实现，即使先用 mock，也要尽快跑通端到端流程。

| 接口 | 用途 | 备注 |
| --- | --- | --- |
| `POST /auth/sms/send` | 发送短信验证码 | 开发阶段 mock；手机号必须存在于学员名单。 |
| `POST /auth/login` | 手机号验证码登录 | 不再自动创建用户，只允许已存在且启用的学员登录。 |
| `POST /auth/logout` | 退出登录 | Token 立即失效。 |
| `GET /user/profile` | 当前用户信息 | 返回额度、已用次数、账号信息。 |
| `POST /chat/session` | 创建会话 | 用户提问前可自动创建。 |
| `GET /chat/session/list` | 会话列表 | H5 首页/侧边历史使用。 |
| `GET /chat/history` | 聊天记录 | 参数 `sessionId`。 |
| `PUT /chat/session/title` | 修改会话标题 | 支持自动标题后手动修改。 |
| `DELETE /chat/session/{id}` | 删除会话 | 逻辑删除，仅用户侧隐藏。 |
| `POST /chat/completions` | AI 流式问答 | SSE，核心接口。 |
| `POST /chat/stop` | 停止生成 | 更新消息状态为 `STOPPED`。 |

## P1：RAG 和配置接口

P1 是真实问答质量和知识库范围控制的关键，建议在 P0 mock 主链路跑通后立即接入。

| 接口/能力 | 用途 | 备注 |
| --- | --- | --- |
| 开放知识库查询 | RAG 检索范围过滤 | 内部 service 可先不暴露接口；按最新口径读取全部已开放知识库。 |
| 飞书知识库实时检索 | 获取知识片段 | 内部 service，先做技术验证。 |
| Prompt 加载 | 获取当前系统 Prompt | 从 `sys_prompt` 读取。 |
| 启用模型加载 | 获取当前模型配置 | 从 `sys_model` 读取。 |
| AI 请求日志写入 | 追溯问答过程 | 每次 `/chat/completions` 必写。 |
| 系统配置读取 | 聊天额度、超时、重试、上下文长度 | 运行时配置。 |

## P2：后台基础管理接口

P2 用于让管理员能配置和运营系统。

| 接口 | 用途 |
| --- | --- |
| `POST /admin/login` | 管理员登录 |
| `GET /admin/dashboard` | 首页统计 |
| `GET /admin/user/list` | 用户列表 |
| `GET /admin/user/{id}` | 用户详情 |
| `POST /admin/user` | 手动新增学员 |
| `GET /admin/user/import/template` | 下载学员 Excel 导入模板 |
| `POST /admin/user/import/excel` | 上传 Excel 批量导入学员 |
| `POST /admin/user/import` | 批量导入学员，保留为兼容 JSON 接口 |
| `PUT /admin/user` | 修改用户 |
| `DELETE /admin/user/{id}` | 删除用户 |
| `POST /admin/user/chat-limit` | 批量修改聊天次数 |
| `POST /admin/user/enable` | 批量启用 |
| `POST /admin/user/disable` | 批量禁用 |
| `POST /admin/user/delete` | 批量删除 |
| `GET /admin/knowledge/list` | 知识库列表 |
| `POST /admin/knowledge` | 新增知识库 |
| `PUT /admin/knowledge` | 编辑知识库 |
| `DELETE /admin/knowledge/{id}` | 删除知识库 |

## P3：后台配置和审计接口

P3 用于完善后台能力和验收闭环。

| 接口 | 用途 |
| --- | --- |
| `GET /admin/prompt` | 获取 Prompt |
| `PUT /admin/prompt` | 保存 Prompt |
| `POST /admin/prompt/reset` | 恢复默认 Prompt |
| `GET /admin/model/list` | 模型列表 |
| `POST /admin/model` | 新增模型 |
| `POST /admin/model/enable` | 启用模型 |
| `DELETE /admin/model/{id}` | 删除模型 |
| `GET /admin/config` | 获取系统配置 |
| `PUT /admin/config` | 修改系统配置 |
| `GET /admin/log/list` | 操作日志查询 |
| `GET /admin/chat/list` | 聊天记录查询 |
| `GET /admin/chat/{id}` | 聊天详情 |
| `POST /admin/chat/export` | 聊天记录导出 |

## 接口统一规范

建议所有 JSON 接口统一返回：

```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

SSE 接口例外，使用 `text/event-stream`。

错误码建议先按这些大类实现：

| 错误码段 | 含义 |
| --- | --- |
| `10000` | 通用参数错误 |
| `20000` | 登录和 Token 错误 |
| `30000` | 账号状态和额度错误 |
| `40000` | 权限错误 |
| `50000` | 飞书、模型和外部服务错误 |

## 第一批开发建议

第一批接口建议只做：

1. `POST /auth/sms/send`
2. `POST /auth/login`
3. `GET /user/profile`
4. `POST /chat/session`
5. `GET /chat/session/list`
6. `GET /chat/history`
7. `POST /chat/completions`
8. `POST /chat/stop`

这 8 个接口可以支撑用户端 H5 的第一条完整主链路。
