# V2 开发流程规划

日期：2026-07-06

## 目标

这份文档用于统一 AI 知识库系统 V2 的开发顺序、交付节奏和风险控制方式。它既给开发执行使用，也给项目沟通和阶段验收使用。

V2 的核心目标不是在旧“答疑资产后台”上继续补功能，而是基于新需求重新建立一套“企业飞书知识库 AI 问答系统”。

## 总体原则

1. **先定边界，再写代码**：先把 V2 的模块、数据模型、接口边界和一期范围确定下来。
2. **先主链路，再补管理能力**：优先跑通用户提问到 AI 回答的闭环，再逐步补后台配置和运营能力。
3. **先 mock，再接真实外部服务**：短信、飞书检索、大模型都先做可替换 mock，保证本地可测；再逐个替换为真实服务。
4. **知识库范围先行**：知识库开放状态是问答范围的底线，不能等后期再补。
5. **文档同步更新**：重要决策、接口变化、范围变化都写入 `development_records/`。
6. **每次代码和内容改动都提交并推送**：保持远端仓库可追踪。

## 阶段一：需求和架构收口

### 目标

把新需求从“文档集合”整理成可以执行的工程计划。

### 要做的事

1. 梳理 PRD、SRS、API、数据库、RAG、权限矩阵之间的一致性。
2. 确认一期必须做、一期不做、后续扩展三类范围。
3. 明确 V2 是否在当前仓库中新建应用目录，还是拆独立仓库。
4. 确认数据库选型：按文档使用 MySQL 8.x，还是记录原因后沿用 PostgreSQL。
5. 输出 V2 模块划分、目录结构和接口分层方案。

### 交付物

- V2 架构设计记录
- 一期范围清单
- 待确认问题清单
- 数据库和部署选型决策记录

## 阶段二：后端基础工程和数据模型

### 目标

建立 V2 后端的骨架，先把核心领域模型和基础接口跑起来。

### 要做的事

1. 新建 V2 后端目录。
2. 建立配置、日志、数据库连接、异常响应、统一返回结构。
3. 建立核心数据表模型：
   - 用户：`sys_user`
   - 管理员：`sys_admin`
   - 角色：`sys_role`
   - 知识库：`sys_knowledge`
   - 知识库：`sys_knowledge`，其中开放状态决定一期用户可访问范围
   - 聊天会话：`sys_chat_session`
   - 聊天消息：`sys_chat_message`
   - Prompt：`sys_prompt`
   - 模型配置：`sys_model`
   - 系统配置：`sys_system_config`
   - AI 请求日志：`sys_ai_request_log`
   - 操作日志：`sys_operation_log`
4. 建立 mock 短信验证码和 Token 登录能力。
5. 建立管理员登录基础能力。

### 验收标准

- 后端可以本地启动。
- 数据库表可以初始化。
- 用户 mock 登录可以拿到 Token。
- 管理员可以登录后台接口。
- 基础接口有统一错误码和响应结构。

## 阶段三：用户端 H5 主链路

### 目标

优先让用户端“能用”：登录、创建会话、发送问题、看到 AI 回答、查看历史。

### 要做的事

1. 新建或调整 H5 用户端入口。
2. 实现手机号验证码登录页面，先接 mock 短信。
3. 实现首页/会话列表/新建会话。
4. 实现聊天页面：
   - 文本输入
   - Enter 发送
   - Shift+Enter 换行（Web）
   - 自动滚动
   - Markdown 渲染
   - 停止生成按钮
5. 实现 mock SSE 问答接口，先不依赖真实飞书和模型。
6. 实现聊天历史读取和会话标题修改。

### 验收标准

- 手机端优先体验可用。
- 用户可以完成从登录到提问再到查看回答的闭环。
- 即使外部飞书和模型未接入，mock 模式也能完整演示流程。

## 阶段四：RAG 和外部服务接入

### 目标

把 mock 问答替换为真实的开放知识库过滤、飞书实时检索、Prompt 组装和大模型流式输出。

### 要做的事

1. 实现开放知识库范围过滤。
2. 实现 FeishuKnowledgeService：
   - 根据 SpaceID/NodeID 检索知识库
   - 处理飞书异常和重试
   - 返回可追踪的知识片段
3. 实现 Prompt 组装：
   - 系统 Prompt
   - 用户问题
   - 已开放知识库片段
   - 上下文
4. 实现 ModelClient：
   - 从启用模型配置读取参数
   - 支持流式输出
   - 支持超时控制
5. 实现 AI 请求日志。
6. 实现无命中、飞书异常、模型异常的统一提示。

### 验收标准

- 用户只能检索已开放的知识库。
- 无命中时不编造答案。
- 飞书异常和模型异常有清晰提示并写日志。
- SSE 流式输出稳定。
- 停止生成可以中断请求，并保留已生成内容。

## 阶段五：管理后台

### 目标

补齐运营和配置能力，让系统可以由后台管理。

### 要做的事

1. 后台登录和基础布局。
2. 首页统计。
3. 用户管理：
   - 查询
   - 详情
   - 启用/禁用
   - 聊天次数配置
4. 管理员管理。
5. 知识库管理：
   - 新增
   - 编辑
   - 删除
   - 启用/禁用
6. Prompt 管理。
7. 模型管理。
8. 系统配置。
9. 聊天记录查询和详情。
10. 操作日志。

### 验收标准

- 后台可以完成一期文档要求的主要管理动作。
- 批量操作有二次确认和操作日志。
- 关键配置保存后能影响用户端问答行为。

## 阶段六：测试、验收和部署

### 目标

按测试用例和 UAT 文档进行收口，保证主流程、知识库开放范围和异常都可验收。

### 要做的事

1. 按 `08-测试用例` 执行功能测试。
2. 按 `09-UAT` 执行业务验收。
3. 重点测试：
   - 登录
   - 聊天
   - 多知识库开放范围
   - 知识库禁用
   - 无命中兜底
   - 飞书异常
   - 模型异常
   - 后台权限
4. 补充部署脚本和部署手册。
5. 明确备份、回滚、日志和配置检查清单。

### 验收标准

- 用户端主链路通过。
- 后台核心管理链路通过。
- 知识库开放范围过滤通过。
- 异常处理通过。
- 部署流程可复现。

## 建议的第一步

下一步建议先做 **阶段一：需求和架构收口**，具体从这三件事开始：

1. 输出 V2 一期范围清单，明确“必须做”和“暂不做”。
2. 输出 V2 技术架构草案，确定是否新建应用目录、数据库选型、后端/前端模块边界。
3. 输出后端接口优先级，先锁定用户端主链路接口：登录、会话、聊天、历史、停止生成。

这三件事完成后，再开始脚手架和代码开发，风险会低很多。
