Document V2 plan in Chinese

ai_knowledge_base_v2/README.md

@@ -1,29 +1,29 @@
-# AI Knowledge Base V2 Workspace
+# AI 知识库系统 V2 工作区
 
-This folder is the new workspace for the changed requirement: **AI 企业知识库问答系统**.
+这个目录用于承载新需求版本：**AI 企业知识库问答系统**。
 
-It is intentionally separated from the existing `hy_qa_asset_backend/docs` folder because the old implementation was an MVP for "大本营答疑资产后台系统", while the new requirement is a broader AI knowledge base product with login, permission control, chat sessions, admin management, Feishu real-time retrieval, and RAG.
+它和旧的 `hy_qa_asset_backend/docs` 目录刻意分开。旧项目的目标是“答疑资产后台系统”，核心是把大本营答疑内容清洗、审核、沉淀成可调用问答；新需求的目标是“企业飞书知识库 AI 问答系统”，核心是登录、权限、知识库、聊天会话、实时飞书检索和 RAG 问答。
 
-## Directory Layout
+## 目录说明
 
-- `source_documents/`: original PRD, SRS, API, database, RAG, prototype, plan, test, UAT, deployment, data dictionary, and permission matrix files.
-- `extracted/`: machine-extracted Markdown versions of the source documents for search and review.
-- `development_records/`: new project development notes, decisions, scope records, and future implementation logs.
-- `reports/`: assessment and design reports for this new version.
+- `source_documents/`：保存原始需求资料，包括 PRD、SRS、API、数据库、RAG、后台原型、实施计划、测试、验收、部署、字段字典、权限矩阵。
+- `extracted/`：从原始 Word/Excel 中抽取出的 Markdown，主要用于开发检索和上下文阅读。
+- `development_records/`：保存新项目开发过程记录、范围决策、架构决策、实施计划和阶段性说明。
+- `reports/`：保存评估报告、方案报告和后续技术调研结论。
 
-## Current Goal
+## 当前目标
 
-Build a new version based on the uploaded AI knowledge base requirement package:
+按照已上传的 AI 知识库系统需求包，重新规划和开发一版新系统：
 
-- User side: phone/SMS login, AI chat, sessions, history, streaming response, stop generation, Markdown rendering, and knowledge permission filtering.
-- Admin side: admin login, user management, admin management, knowledge base management, Prompt management, model management, chat records, dashboard, system config, and operation logs.
-- AI/RAG: Feishu knowledge base as the only knowledge source in phase one, real-time retrieval per question, permission-based knowledge filtering, Prompt assembly, model invocation, SSE streaming, and AI request logging.
-- Phase-one exclusions: file upload, OCR, image understanding, web search, local vector database sync, payment, course system, automatic authorization, multi-tenant, multi-Prompt, regenerate answer, and edit message.
+- 用户端：手机号验证码登录、AI 聊天、多会话、历史聊天、流式回答、停止生成、Markdown 渲染、知识库权限过滤。
+- 管理后台：管理员登录、用户管理、管理员管理、知识库管理、Prompt 管理、模型管理、聊天记录、数据统计、系统配置、操作日志。
+- AI/RAG：一期以飞书知识库作为唯一知识来源；每次提问实时检索；按用户权限过滤知识库；组装 Prompt；调用大模型；通过 SSE 流式输出；记录 AI 请求日志。
+- 一期不做：文件上传、图片理解、OCR、联网搜索、向量数据库同步、支付系统、课程系统、自动授权、多租户、多 Prompt、重新生成、编辑消息。
 
-## Working Principles
+## 工作原则
 
-- Keep this version additive and isolated until the architecture decision is confirmed.
-- Do not put new planning records into the old `hy_qa_asset_backend/docs` directory.
-- Treat the uploaded documents as the source of truth for V2.
-- Record major implementation decisions in `development_records/` before or alongside code changes.
-- Reuse old code only where the domain boundary still matches; do not force old "QA asset review" models into the new "AI knowledge base chat" model.
+- V2 先作为独立工作区推进，避免和旧项目文档混在一起。
+- 上传的原始文档是 V2 的需求依据。
+- 给用户、团队、交接和评审看的文档统一使用中文。
+- `extracted/` 里的机器抽取文档可以保留原始语言或工程化表达，优先服务开发检索。
+- 旧代码只在领域边界匹配时复用，不把旧的“答疑资产审核模型”硬套到新的“知识库权限问答模型”上。

ai_knowledge_base_v2/development_records/2026-07-06-development-process-plan.md

@@ -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. 输出后端接口优先级，先锁定用户端主链路接口：登录、会话、聊天、历史、停止生成。
+
+这三件事完成后，再开始脚手架和代码开发，风险会低很多。

ai_knowledge_base_v2/development_records/2026-07-06-initial-context.md

@@ -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 是继续在当前仓库中新建应用目录，还是后续拆成独立仓库，需要在架构规划后确认。

ai_knowledge_base_v2/development_records/README.md

@@ -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` 目录。旧目录属于上一阶段“答疑资产后台系统”。

ai_knowledge_base_v2/extracted/README.md

@@ -1,16 +1,16 @@
-# Extracted Source Index
+# 抽取文档索引
 
-This folder contains machine-extracted Markdown/text from the original requirement files.
+这个目录保存从原始 Word/Excel 需求资料中机器抽取出的 Markdown 文档，主要用于开发检索、上下文阅读和后续方案分析。
 
-- `02-AI知识库系统系统功能规格说明书_SRS_V10.md` from `02-AI知识库系统系统功能规格说明书（SRS）V1.0.docx`: 664 paragraphs, 13 tables
-- `03-AI知识库系统数据库设计文档.md` from `03-AI知识库系统数据库设计文档.docx`: 283 paragraphs, 18 tables
-- `04-AI知识库系统_API接口设计文档.md` from `04-AI知识库系统_API接口设计文档.docx`: 279 paragraphs, 1 tables
-- `05-AI知识库系统_AI-RAG技术方案设计_V10_1.md` from `05-AI知识库系统_AI-RAG技术方案设计_V1.0 (1).docx`: 154 paragraphs, 10 tables
-- `06-AI知识库系统后台页面原型说明书_V10_1.md` from `06-AI知识库系统后台页面原型说明书_V1.0 (1).docx`: 181 paragraphs, 19 tables
-- `07-AI知识库系统研发实施计划_V10.md` from `07-AI知识库系统研发实施计划_V1.0.docx`: 269 paragraphs, 9 tables
-- `08-AI知识库系统测试用例_Test_Cases_V10.md` from `08-AI知识库系统测试用例_Test_Cases_V1.0.docx`: 160 paragraphs, 29 tables
-- `09-AI知识库系统项目验收标准_UAT_V10.md` from `09-AI知识库系统项目验收标准（UAT）V1.0.docx`: 87 paragraphs, 36 tables
-- `10-AI知识库系统部署运维手册_V10.md` from `10-AI知识库系统部署运维手册_V1.0.docx`: 153 paragraphs, 11 tables
-- `12-AI知识库系统权限矩阵_Permission_Matrix_V10_1.md` from `12-AI知识库系统权限矩阵（Permission Matrix）V1.0 (1).docx`: 64 paragraphs, 22 tables
-- `AI_Knowledge_Base_PRD_V10.md` from `AI_Knowledge_Base_PRD_V1.0.docx`: 523 paragraphs, 10 tables
-- `11-AI知识库系统字段字典_Data_Dictionary_V10.md` from `11-AI知识库系统字段字典_Data_Dictionary_V1.0.xlsx`: 15 worksheets
+- `02-AI知识库系统系统功能规格说明书_SRS_V10.md`：来自 `02-AI知识库系统系统功能规格说明书（SRS）V1.0.docx`，664 个段落，13 张表。
+- `03-AI知识库系统数据库设计文档.md`：来自 `03-AI知识库系统数据库设计文档.docx`，283 个段落，18 张表。
+- `04-AI知识库系统_API接口设计文档.md`：来自 `04-AI知识库系统_API接口设计文档.docx`，279 个段落，1 张表。
+- `05-AI知识库系统_AI-RAG技术方案设计_V10_1.md`：来自 `05-AI知识库系统_AI-RAG技术方案设计_V1.0 (1).docx`，154 个段落，10 张表。
+- `06-AI知识库系统后台页面原型说明书_V10_1.md`：来自 `06-AI知识库系统后台页面原型说明书_V1.0 (1).docx`，181 个段落，19 张表。
+- `07-AI知识库系统研发实施计划_V10.md`：来自 `07-AI知识库系统研发实施计划_V1.0.docx`，269 个段落，9 张表。
+- `08-AI知识库系统测试用例_Test_Cases_V10.md`：来自 `08-AI知识库系统测试用例_Test_Cases_V1.0.docx`，160 个段落，29 张表。
+- `09-AI知识库系统项目验收标准_UAT_V10.md`：来自 `09-AI知识库系统项目验收标准（UAT）V1.0.docx`，87 个段落，36 张表。
+- `10-AI知识库系统部署运维手册_V10.md`：来自 `10-AI知识库系统部署运维手册_V1.0.docx`，153 个段落，11 张表。
+- `12-AI知识库系统权限矩阵_Permission_Matrix_V10_1.md`：来自 `12-AI知识库系统权限矩阵（Permission Matrix）V1.0 (1).docx`，64 个段落，22 张表。
+- `AI_Knowledge_Base_PRD_V10.md`：来自 `AI_Knowledge_Base_PRD_V1.0.docx`，523 个段落，10 张表。
+- `11-AI知识库系统字段字典_Data_Dictionary_V10.md`：来自 `11-AI知识库系统字段字典_Data_Dictionary_V1.0.xlsx`，15 个工作表。

ai_knowledge_base_v2/reports/legacy_reuse_evaluation.md

@@ -1,48 +1,48 @@
-# Legacy Reuse Evaluation
+# 旧代码复用评估报告
 
-Date: 2026-07-06
+日期：2026-07-06
 
-## Conclusion
+## 结论
 
-The existing project can provide useful engineering references, but it should not be directly extended as-is for the new requirement.
+现有项目可以提供一些工程实现参考，但不建议直接在旧代码上硬改成新系统。
 
-The old project is a **大本营答疑资产后台系统 MVP**. Its core flow is:
+旧项目是 **大本营答疑资产后台系统 MVP**，核心流程是：
 
-`Feishu session/transcript -> AI cleaning -> raw QA -> manual review -> standard QA -> manually marked callable QA`
+`飞书场次/转写稿 -> AI 清洗 -> 原始问答 -> 人工审核 -> 标准问答 -> 人工标记可调用`
 
-The new project is an **AI 企业知识库问答系统**. Its core flow is:
+新项目是 **AI 企业知识库问答系统**，核心流程是：
 
-`User login -> authorized knowledge bases -> real-time Feishu retrieval -> Prompt assembly -> model streaming answer -> chat/history/log persistence`
+`用户登录 -> 获取授权知识库 -> 实时检索飞书知识库 -> 组装 Prompt -> 大模型流式回答 -> 保存聊天、引用和日志`
 
-These two systems both touch "QA" and "Feishu", but their domain models, permissions, APIs, database tables, and user workflows are different. For long-term maintainability, V2 should use a new domain model and only reuse selected implementation patterns or small infrastructure pieces.
+两个系统都涉及“问答”和“飞书”，但领域模型、权限逻辑、接口、数据库表和用户流程都不一样。为了后期维护和交接，V2 应该重新建立自己的领域模型，只选择性复用旧项目里的工程模式、小工具或局部服务代码。
 
-## New Requirement Snapshot
+## 新需求概要
 
-Source documents define the V2 target as:
+根据这次上传的需求资料，V2 的目标包括：
 
-- Feishu knowledge base is the only phase-one knowledge source.
-- Phase one does not build an independent local knowledge base, does not manually sync content, and does not maintain a vector database sync.
-- User login uses phone number + SMS verification code.
-- Admin login uses username + password.
-- AI chat supports sessions, history, streaming output, stop generation, Markdown rendering, auto title, and daily chat quota.
-- AI can only answer from the user's authorized knowledge bases and retrieved snippets.
-- No-hit answer must be: `当前知识库中未检索到相关内容，请联系管理员补充相关知识。`
-- Feishu/model failures need unified fallback messages and logs.
-- Admin backend includes dashboard, user management, admin management, knowledge base management, Prompt management, model management, chat records, system config, and operation logs.
-- Core database tables include `sys_user`, `sys_admin`, `sys_role`, `sys_knowledge`, `sys_user_kb`, `sys_chat_session`, `sys_chat_message`, `sys_prompt`, `sys_model`, `sys_system_config`, `sys_ai_request_log`, and `sys_operation_log`.
+- 飞书知识库是一阶段唯一知识来源。
+- 一期不建立独立本地知识库，不做人工同步，不做向量数据库同步。
+- 用户端使用手机号 + 短信验证码登录。
+- 管理后台使用用户名 + 密码登录。
+- AI 聊天支持多会话、历史聊天、流式输出、停止生成、Markdown 渲染、自动标题和每日聊天额度。
+- AI 只能基于用户有权限访问的知识库和检索片段回答。
+- 没有命中知识时，统一回答：`当前知识库中未检索到相关内容，请联系管理员补充相关知识。`
+- 飞书或模型异常时，需要统一提示并记录日志。
+- 后台包含首页统计、用户管理、管理员管理、知识库管理、Prompt 管理、模型管理、聊天记录、系统配置和操作日志。
+- 核心表包括 `sys_user`、`sys_admin`、`sys_role`、`sys_knowledge`、`sys_user_kb`、`sys_chat_session`、`sys_chat_message`、`sys_prompt`、`sys_model`、`sys_system_config`、`sys_ai_request_log`、`sys_operation_log`。
 
-## Existing Code Overview
+## 旧项目现状
 
-The old project currently uses:
+旧项目当前技术栈：
 
-- Backend: FastAPI, SQLAlchemy, Pydantic, APScheduler, HTTPX.
-- Frontend: Next.js, React, TypeScript, TailwindCSS.
-- Database: PostgreSQL preferred, SQLite fallback.
-- AI: OpenAI-compatible chat completions with mock fallback.
-- Feishu: Bitable/document adapter with mock fallback.
-- Existing H5 page: mobile-first chat surface connected to `/api/standard-qa/callable`.
+- 后端：FastAPI、SQLAlchemy、Pydantic、APScheduler、HTTPX。
+- 前端：Next.js、React、TypeScript、TailwindCSS。
+- 数据库：优先 PostgreSQL，未配置时使用 SQLite。
+- AI：OpenAI 兼容 Chat Completions，支持 mock。
+- 飞书：已有多维表格和文档读取适配器，支持 mock。
+- H5：已有手机优先的聊天界面，但目前连接的是 `/api/standard-qa/callable`。
 
-The old database model centers on:
+旧项目核心数据模型：
 
 - `users`
 - `feishu_sessions`
@@ -52,46 +52,46 @@ The old database model centers on:
 - `audit_logs`
 - `system_settings`
 
-## Reuse Assessment
+## 可复用性评估
 
-| Area | Reuse Level | Recommendation |
+| 模块 | 复用等级 | 建议 |
 | --- | --- | --- |
-| FastAPI application skeleton | High | Reuse routing style, settings pattern, CORS setup, dependency injection, and service layering ideas. |
-| SQLAlchemy/Pydantic conventions | Medium | Reuse coding style, but rebuild models for `sys_*` tables required by V2. |
-| Next.js/Tailwind frontend setup | Medium | Reuse project setup and visual implementation experience; rebuild pages around V2 user/admin flows. |
-| H5 chat UI interaction | Medium | Reuse mobile-first interaction ideas such as compact header, chat bubbles, input ergonomics, and local loading states. Replace old callable-QA matching with real `/chat/completions` SSE. |
-| Feishu service adapter | Medium | Reuse token acquisition, HTTP wrapper, document text extraction ideas, and mock-mode pattern. V2 still needs a new Feishu knowledge retrieval service matching SpaceID/NodeID and real-time search. |
-| AI API wrapper | Medium | Reuse OpenAI-compatible request pattern. V2 needs streaming, cancellation, Prompt assembly, token logging, and model config from database. |
-| Operation/task logs | Low to Medium | Reuse audit/logging ideas. V2 needs `sys_operation_log` and `sys_ai_request_log`, not old QA audit semantics. |
-| Scheduler/task runner | Low | V2 phase one says no manual sync or vector DB sync, so scheduled QA processing is not core. Keep only if later needed for maintenance jobs. |
-| Old QA review domain | Low | Do not reuse as V2 core. Raw/standard QA review, risk/desensitization, and callable status are old-domain concepts. |
-| Existing `/standard-qa/callable` H5 API | Low | Replace with V2 chat/session/history APIs. It can stay as old system behavior but should not drive V2. |
-| Docker Compose | Medium | Reuse containerization pattern, but V2 should switch DB target to MySQL 8.x per documents or explicitly record a deviation if PostgreSQL remains. |
+| FastAPI 应用骨架 | 高 | 可参考路由拆分、配置读取、CORS、依赖注入和 service 分层方式。 |
+| SQLAlchemy / Pydantic 写法 | 中 | 可参考编码风格，但模型需要按 V2 的 `sys_*` 表重建。 |
+| Next.js / Tailwind 前端工程 | 中 | 可参考工程搭建方式和页面实现经验，但页面要按 V2 用户端和后台流程重建。 |
+| H5 聊天交互 | 中 | 可复用手机优先、聊天气泡、输入框、加载状态等交互思路；需要替换为真实会话接口和 SSE 流式问答。 |
+| 飞书服务适配 | 中 | 可参考 token 获取、HTTP 封装、文档文本提取和 mock 模式；V2 仍需新增基于 SpaceID/NodeID 的实时知识库检索服务。 |
+| AI 调用封装 | 中 | 可参考 OpenAI 兼容请求方式；V2 需要新增流式输出、停止生成、Prompt 组装、Token 记录和从数据库读取模型配置。 |
+| 日志/审计思路 | 低到中 | 可参考日志意识；V2 需要实现 `sys_operation_log` 和 `sys_ai_request_log`，不能直接沿用旧审核日志语义。 |
+| 定时任务 | 低 | V2 一期不做同步任务和向量库同步，定时任务不是核心。后续如有维护任务再引入。 |
+| 旧问答审核领域 | 低 | 不建议作为 V2 核心。原始问答、标准问答、风险、脱敏、可调用状态属于旧系统领域。 |
+| `/standard-qa/callable` 接口 | 低 | V2 应替换为聊天、会话、历史和 SSE 接口。这个接口可以作为旧系统能力保留，但不应驱动 V2。 |
+| Docker Compose | 中 | 可复用容器化思路，但 V2 文档指定 MySQL 8.x。如果继续用 PostgreSQL，需要单独记录偏离原因。 |
 
-## Gap Analysis
+## 缺口分析
 
-Must build or redesign for V2:
+V2 必须新建或重构的能力：
 
-- User SMS login, token/session invalidation, account expiry, and daily quota.
-- Admin username/password login and role/permission control.
-- Knowledge base management using `SpaceID` and `NodeID`.
-- User-to-knowledge permission table with effective/expired dates.
-- Chat session and message persistence.
-- SSE streaming endpoint `POST /chat/completions`.
-- Stop-generation endpoint `POST /chat/stop`.
-- Prompt management and active Prompt loading.
-- Model management with API URL/API key/model settings.
-- System config for login expiry, daily chat count, AI timeout, Feishu retries, context length, source display, and disabled web search.
-- Real-time Feishu retrieval with permission filtering.
-- AI request log with prompt, retrieval knowledge IDs, token usage, latency, status, and error.
-- Admin chat query/detail/export APIs.
-- UAT/test coverage around permission isolation and no-hallucination fallback.
+- 用户短信登录、Token、退出失效、账号有效期和每日额度。
+- 管理员用户名密码登录、角色和权限控制。
+- 知识库管理，字段包括知识库名称、SpaceID、NodeID、状态和备注。
+- 用户知识库授权关系，支持生效时间和到期时间。
+- 聊天会话和聊天消息持久化。
+- SSE 流式接口 `POST /chat/completions`。
+- 停止生成接口 `POST /chat/stop`。
+- Prompt 管理和当前 Prompt 加载。
+- 模型管理，包括 API URL、API Key、模型名称、温度、最大 Token 和超时。
+- 系统配置，包括登录有效期、每日聊天次数、AI 超时、飞书重试次数、上下文长度、是否展示引用来源、是否允许联网。
+- 按权限过滤后的飞书实时检索。
+- AI 请求日志，记录 Prompt、检索知识库、Token、耗时、状态和错误信息。
+- 后台聊天记录查询、详情和导出。
+- 围绕权限隔离、无命中兜底、不编造答案的测试和验收。
 
-## Recommended Technical Direction
+## 推荐技术方向
 
-1. Keep `ai_knowledge_base_v2/` as the new context and planning workspace.
-2. Create a new V2 application folder after architecture confirmation, rather than mutating old V1 files in place.
-3. Keep backend modular from day one:
+1. 继续把 `ai_knowledge_base_v2/` 作为新需求上下文和规划工作区。
+2. 架构确认后，新建 V2 应用目录，而不是直接大面积修改旧 V1 文件。
+3. 后端从第一天开始按模块拆分：
    - `auth`
    - `users`
    - `admins`
@@ -102,7 +102,7 @@ Must build or redesign for V2:
    - `models`
    - `config`
    - `logs`
-4. Keep services separated:
+4. service 层保持边界清楚：
    - `SmsCodeService`
    - `TokenService`
    - `FeishuKnowledgeService`
@@ -110,24 +110,24 @@ Must build or redesign for V2:
    - `ModelClient`
    - `ChatService`
    - `AuditLogService`
-5. Make mock providers explicit for local development:
-   - mock SMS code
-   - mock model response
-   - mock Feishu retrieval
-6. Do not store production model API keys in plain text unless a security decision is documented. Prefer environment secret references or encrypted storage.
+5. 本地开发阶段需要明确 mock provider：
+   - mock 短信验证码
+   - mock 大模型回答
+   - mock 飞书知识库检索
+6. 生产环境的模型 API Key 不建议明文存储。需要优先考虑环境变量引用、密文存储或其他安全方案，并形成决策记录。
 
-## Risk Notes
+## 风险提示
 
-- The new documents specify MySQL 8.x, while the existing project uses PostgreSQL/SQLite. This is a deployment and migration decision, not a small code change.
-- The documents say "Feishu updates immediately effective" and "real-time retrieval"; this depends on actual Feishu APIs and tenant permissions. A technical spike should validate retrieval behavior early.
-- Streaming and stop-generation affect backend request lifecycle, frontend rendering, and persistence semantics. This should be implemented as a first-class chat capability, not as an afterthought.
-- Permissions are central to the product. Every chat retrieval path must filter knowledge bases before retrieval and log what was used.
+- 新文档指定 MySQL 8.x，而旧项目使用 PostgreSQL/SQLite。这不是一个小改动，需要作为架构和部署决策处理。
+- 文档要求“飞书更新后立即生效”和“每次提问实时检索”，这强依赖飞书实际 API 能力和租户权限，必须尽早做技术验证。
+- 流式输出和停止生成会影响后端请求生命周期、前端渲染和消息落库语义，应作为核心能力设计。
+- 权限是产品底线。每一次聊天检索都必须先过滤用户知识库权限，并记录实际使用的知识库和片段。
 
-## Immediate Next Steps
+## 下一步建议
 
-1. Confirm whether V2 should be implemented in this repository under a new app folder, or whether this repository should become the V2 repository.
-2. Draft V2 architecture and module plan in `development_records/`.
-3. Scaffold V2 backend with the `sys_*` domain model and auth boundary.
-4. Scaffold V2 H5/user frontend around the documented chat APIs and SSE.
-5. Add admin frontend pages according to the prototype document.
-6. Keep old V1 code untouched until a deliberate migration or replacement decision is made.
+1. 确认 V2 是放在当前仓库的新应用目录，还是后续拆成独立仓库。
+2. 先写 V2 架构和开发流程计划。
+3. 搭建 V2 后端基础工程和 `sys_*` 领域模型。
+4. 搭建 V2 用户端 H5，先跑通登录 mock、会话、SSE mock 问答。
+5. 搭建后台基础框架和用户/知识库/Prompt/模型管理页面。
+6. 尽早验证飞书实时检索和模型流式调用，避免后期被关键外部接口卡住。

ai_knowledge_base_v2/source_documents/README.md

@@ -1,26 +1,26 @@
-# Source Documents
+# 原始需求资料
 
-This folder stores the original requirement package for AI Knowledge Base V2.
+这个目录保存 AI 知识库系统 V2 的原始需求资料。
 
-## Archived Files
+## 已归档文件
 
-| File | Role |
+| 文件 | 作用 |
 | --- | --- |
-| `AI_Knowledge_Base_PRD_V1.0.docx` | Product requirement source of truth. |
-| `02-AI知识库系统系统功能规格说明书（SRS）V1.0.docx` | Detailed software requirement specification. |
-| `03-AI知识库系统数据库设计文档.docx` | Database design reference. |
-| `04-AI知识库系统_API接口设计文档.docx` | Frontend/backend API contract reference. |
-| `05-AI知识库系统_AI-RAG技术方案设计_V1.0 (1).docx` | AI/RAG architecture and runtime flow reference. |
-| `06-AI知识库系统后台页面原型说明书_V1.0 (1).docx` | Admin UI structure and page prototype reference. |
-| `07-AI知识库系统研发实施计划_V1.0.docx` | Development plan and milestone reference. |
-| `08-AI知识库系统测试用例_Test_Cases_V1.0.docx` | Functional, permission, AI, security, and UAT test reference. |
-| `09-AI知识库系统项目验收标准（UAT）V1.0.docx` | Acceptance criteria reference. |
-| `10-AI知识库系统部署运维手册_V1.0.docx` | Deployment and operations reference. |
-| `11-AI知识库系统字段字典_Data_Dictionary_V1.0.xlsx` | Field dictionary and database naming reference. |
-| `12-AI知识库系统权限矩阵（Permission Matrix）V1.0 (1).docx` | Role and permission matrix reference. |
+| `AI_Knowledge_Base_PRD_V1.0.docx` | 产品需求说明书，作为产品目标和范围依据。 |
+| `02-AI知识库系统系统功能规格说明书（SRS）V1.0.docx` | 软件功能规格说明书，作为页面、字段、接口行为、权限、异常和验收依据。 |
+| `03-AI知识库系统数据库设计文档.docx` | 数据库设计依据。 |
+| `04-AI知识库系统_API接口设计文档.docx` | 前后端接口联调依据。 |
+| `05-AI知识库系统_AI-RAG技术方案设计_V1.0 (1).docx` | AI/RAG 架构和业务流程依据。 |
+| `06-AI知识库系统后台页面原型说明书_V1.0 (1).docx` | 后台页面结构和原型依据。 |
+| `07-AI知识库系统研发实施计划_V1.0.docx` | 研发排期、里程碑和交付计划依据。 |
+| `08-AI知识库系统测试用例_Test_Cases_V1.0.docx` | 功能、权限、AI、安全和 UAT 测试依据。 |
+| `09-AI知识库系统项目验收标准（UAT）V1.0.docx` | 项目验收标准依据。 |
+| `10-AI知识库系统部署运维手册_V1.0.docx` | 部署和运维依据。 |
+| `11-AI知识库系统字段字典_Data_Dictionary_V1.0.xlsx` | 字段、表结构和命名规范依据。 |
+| `12-AI知识库系统权限矩阵（Permission Matrix）V1.0 (1).docx` | 角色权限矩阵依据。 |
 
-## Notes
+## 使用约定
 
-- Keep these files unchanged as original source artifacts.
-- Use `../extracted/` for searchable Markdown copies.
-- If a newer version of a document is added later, keep both versions and record the supersession in `../development_records/`.
+- 原始文件保持不改动，作为需求溯源材料。
+- 需要搜索和引用时，优先查看 `../extracted/` 中的 Markdown 抽取版本。
+- 后续如果新增更高版本文档，保留旧版本，并在 `../development_records/` 中记录替换关系和影响范围。