From dbd59a84dfabf34f6da81e4abb6724d36e97326a Mon Sep 17 00:00:00 2001 From: Nelson <1475262689@qq.com> Date: Mon, 6 Jul 2026 17:02:16 +0800 Subject: [PATCH] Document V2 plan in Chinese --- ai_knowledge_base_v2/README.md | 40 ++-- .../2026-07-06-development-process-plan.md | 208 ++++++++++++++++++ .../2026-07-06-initial-context.md | 56 ++--- .../development_records/README.md | 20 +- ai_knowledge_base_v2/extracted/README.md | 28 +-- .../reports/legacy_reuse_evaluation.md | 162 +++++++------- .../source_documents/README.md | 40 ++-- 7 files changed, 382 insertions(+), 172 deletions(-) create mode 100644 ai_knowledge_base_v2/development_records/2026-07-06-development-process-plan.md diff --git a/ai_knowledge_base_v2/README.md b/ai_knowledge_base_v2/README.md index 3004405..55e4f38 100644 --- a/ai_knowledge_base_v2/README.md +++ b/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/` 里的机器抽取文档可以保留原始语言或工程化表达，优先服务开发检索。 +- 旧代码只在领域边界匹配时复用，不把旧的“答疑资产审核模型”硬套到新的“知识库权限问答模型”上。 diff --git a/ai_knowledge_base_v2/development_records/2026-07-06-development-process-plan.md b/ai_knowledge_base_v2/development_records/2026-07-06-development-process-plan.md new file mode 100644 index 0000000..2cbc599 --- /dev/null +++ b/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. 输出后端接口优先级，先锁定用户端主链路接口：登录、会话、聊天、历史、停止生成。 + +这三件事完成后，再开始脚手架和代码开发，风险会低很多。 diff --git a/ai_knowledge_base_v2/development_records/2026-07-06-initial-context.md b/ai_knowledge_base_v2/development_records/2026-07-06-initial-context.md index b67f72b..3bd376e 100644 --- a/ai_knowledge_base_v2/development_records/2026-07-06-initial-context.md +++ b/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 是继续在当前仓库中新建应用目录，还是后续拆成独立仓库，需要在架构规划后确认。 diff --git a/ai_knowledge_base_v2/development_records/README.md b/ai_knowledge_base_v2/development_records/README.md index 6a9c5ce..e910490 100644 --- a/ai_knowledge_base_v2/development_records/README.md +++ b/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` 目录。旧目录属于上一阶段“答疑资产后台系统”。 diff --git a/ai_knowledge_base_v2/extracted/README.md b/ai_knowledge_base_v2/extracted/README.md index 6b7333b..0014b38 100644 --- a/ai_knowledge_base_v2/extracted/README.md +++ b/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 个工作表。 diff --git a/ai_knowledge_base_v2/reports/legacy_reuse_evaluation.md b/ai_knowledge_base_v2/reports/legacy_reuse_evaluation.md index e82fdbd..9dda9b7 100644 --- a/ai_knowledge_base_v2/reports/legacy_reuse_evaluation.md +++ b/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. 尽早验证飞书实时检索和模型流式调用，避免后期被关键外部接口卡住。 diff --git a/ai_knowledge_base_v2/source_documents/README.md b/ai_knowledge_base_v2/source_documents/README.md index fff0f00..76c06f0 100644 --- a/ai_knowledge_base_v2/source_documents/README.md +++ b/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/` 中记录替换关系和影响范围。