Document V2 plan in Chinese
This commit is contained in:
@@ -0,0 +1,208 @@
|
||||
# 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_user_kb`
|
||||
- 聊天会话：`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. 输出后端接口优先级，先锁定用户端主链路接口：登录、会话、聊天、历史、停止生成。
|
||||
|
||||
这三件事完成后，再开始脚手架和代码开发，风险会低很多。
|
||||
@@ -1,44 +1,46 @@
|
||||
# 2026-07-06 Initial Context
|
||||
# 2026-07-06 初始上下文记录
|
||||
|
||||
## Background
|
||||
## 背景
|
||||
|
||||
The project requirement changed significantly on 2026-07-06. The previous implementation focused on a backend/admin MVP for extracting, cleaning, reviewing, and marking "大本营答疑资产" as callable QA assets. The new requirement package defines an **AI 企业知识库问答系统**.
|
||||
2026-07-06，项目需求发生较大变化。旧实现主要围绕“大本营答疑资产后台系统”展开，目标是把飞书资料、转写稿或答疑内容经过 AI 清洗、人工审核、标准问答沉淀后，再由人工标记为可调用内容。
|
||||
|
||||
## Source Package Archived
|
||||
新需求包定义的是 **AI 企业知识库问答系统**，核心目标已经变成：基于企业飞书知识库，为内部用户提供带权限控制的 AI 问答能力，并配套完整后台。
|
||||
|
||||
The uploaded source documents were copied into:
|
||||
## 资料归档
|
||||
|
||||
原始需求资料已经复制到：
|
||||
|
||||
`ai_knowledge_base_v2/source_documents/`
|
||||
|
||||
Machine-extracted Markdown files were generated into:
|
||||
为了方便搜索和开发阅读，已经把 Word/Excel 抽取为 Markdown，放到：
|
||||
|
||||
`ai_knowledge_base_v2/extracted/`
|
||||
|
||||
The source package includes PRD, SRS, database design, API design, RAG design, admin prototype notes, implementation plan, test cases, UAT criteria, deployment manual, field dictionary, and permission matrix.
|
||||
资料包包含 PRD、SRS、数据库设计、API 设计、RAG 技术方案、后台原型说明、研发实施计划、测试用例、UAT 验收标准、部署运维手册、字段字典和权限矩阵。
|
||||
|
||||
## Current Understanding
|
||||
## 当前理解
|
||||
|
||||
The new system should use Feishu knowledge bases as the only phase-one knowledge source. Each user question should:
|
||||
新系统一期以飞书知识库作为唯一知识来源。用户每次提问时，系统应该按下面流程处理：
|
||||
|
||||
1. Validate user account and daily quota.
|
||||
2. Resolve the user's authorized knowledge bases.
|
||||
3. Retrieve content from Feishu in real time.
|
||||
4. Assemble Prompt from system Prompt, retrieved snippets, user question, and controlled context.
|
||||
5. Call the configured model.
|
||||
6. Stream the answer through SSE.
|
||||
7. Persist question, answer, retrieval snippets, Prompt/model info, token usage, cost, and status.
|
||||
1. 校验用户账号状态和每日聊天额度。
|
||||
2. 获取用户已授权且有效的知识库。
|
||||
3. 基于授权知识库实时检索飞书内容。
|
||||
4. 使用系统 Prompt、检索片段、用户问题和上下文组装最终 Prompt。
|
||||
5. 调用当前启用的大模型。
|
||||
6. 通过 SSE 流式返回回答。
|
||||
7. 保存用户问题、AI 回答、检索知识库、检索片段、Prompt、模型、Token 消耗、耗时和状态。
|
||||
|
||||
## Key Decisions
|
||||
## 已确定事项
|
||||
|
||||
- Create a new `ai_knowledge_base_v2/` workspace instead of mixing V2 records into old docs.
|
||||
- Preserve all uploaded documents as source artifacts.
|
||||
- Generate extracted Markdown for searchable project context.
|
||||
- Treat old code as a reference implementation, not as the direct domain model for V2.
|
||||
- Prefer reusable technical infrastructure from old code only after matching it against V2 requirements.
|
||||
- 新建 `ai_knowledge_base_v2/` 工作区，不再把 V2 文档放到旧 `docs/`。
|
||||
- 保留所有上传文档作为原始需求材料。
|
||||
- 抽取 Markdown 版本作为开发检索材料。
|
||||
- 旧代码作为参考，不直接把旧领域模型当作 V2 领域模型。
|
||||
- 给用户、团队、交接和评审看的文档统一使用中文。
|
||||
|
||||
## Open Questions
|
||||
## 待确认问题
|
||||
|
||||
- SMS provider is not specified yet. We need a mock provider for local development and a real provider decision before production.
|
||||
- Final model provider and API compatibility need confirmation.
|
||||
- Feishu real-time retrieval API details need implementation validation against the actual tenant permissions and knowledge base structure.
|
||||
- Whether V2 should be created as a sibling app inside this repository or split into a separate repository can be decided after architecture planning.
|
||||
- 短信验证码供应商暂未确定，开发阶段需要先做 mock 短信服务。
|
||||
- 最终大模型供应商、API 地址、鉴权方式和模型名称需要确认。
|
||||
- 飞书知识库的实时检索方式需要尽早做技术验证，确认当前租户权限、SpaceID、NodeID 和 API 能力是否满足需求。
|
||||
- V2 是继续在当前仓库中新建应用目录，还是后续拆成独立仓库，需要在架构规划后确认。
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
# Development Records
|
||||
# 开发过程记录
|
||||
|
||||
This folder stores the AI knowledge base V2 development process records.
|
||||
这个目录用于记录 AI 知识库系统 V2 的开发过程。
|
||||
|
||||
Use it for:
|
||||
适合放置：
|
||||
|
||||
- scope decisions
|
||||
- architecture decisions
|
||||
- implementation plans
|
||||
- daily or milestone notes
|
||||
- unresolved questions
|
||||
- test and acceptance observations
|
||||
- 需求范围决策
|
||||
- 架构设计决策
|
||||
- 开发实施计划
|
||||
- 每日或阶段性记录
|
||||
- 待确认问题
|
||||
- 测试、验收和风险记录
|
||||
|
||||
Do not store these records in the old `hy_qa_asset_backend/docs` folder. That folder belongs to the earlier "答疑资产后台系统" phase.
|
||||
注意：V2 的开发记录不要再放到旧的 `hy_qa_asset_backend/docs` 目录。旧目录属于上一阶段“答疑资产后台系统”。
|
||||
|
||||
Reference in New Issue
Block a user