Plan V2 phase one architecture

2026-07-06 17:09:33 +08:00
parent dbd59a84df
commit b7dfa13872
7 changed files with 607 additions and 0 deletions
--- a/ai_knowledge_base_v2/development_records/2026-07-06-api-priority.md
+++ b/ai_knowledge_base_v2/development_records/2026-07-06-api-priority.md
@@ -0,0 +1,120 @@
+# 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` | 新增用户 |
+| `PUT /admin/user` | 修改用户 |
+| `DELETE /admin/user/{id}` | 删除用户 |
+| `POST /admin/user/kb` | 批量授权知识库 |
+| `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 的第一条完整主链路。
--- a/ai_knowledge_base_v2/development_records/2026-07-06-architecture-plan.md
+++ b/ai_knowledge_base_v2/development_records/2026-07-06-architecture-plan.md
@@ -0,0 +1,152 @@
+# V2 架构设计草案
+
+日期：2026-07-06
+
+## 架构目标
+
+V2 架构要解决四件事：
+
+1. 支持手机端优先的 AI 问答体验，并为后续微信小程序留出空间。
+2. 后端必须把权限、聊天、RAG、模型、日志拆清楚，避免后期维护困难。
+3. 外部依赖先 mock 后真实接入，保证本地可开发、可测试、可演示。
+4. 关键能力可追溯：用户问题、检索知识库、Prompt、模型、Token、耗时和错误都要记录。
+
+## 推荐仓库结构
+
+建议继续在当前仓库中推进 V2，但所有 V2 代码放在 `ai_knowledge_base_v2/` 下，和旧系统隔离。
+
+```text
+ai_knowledge_base_v2/
+  source_documents/          # 原始需求资料
+  extracted/                 # 机器抽取文档
+  development_records/       # 开发过程和决策记录
+  reports/                   # 评估和调研报告
+  apps/
+    backend/                 # V2 后端服务
+    user-client/             # 用户端 H5，后续可按小程序方向演进
+    admin-web/               # 管理后台
+  packages/
+    shared-types/            # 前后端共享类型，可后续再建
+```
+
+说明：
+
+- 先不删除旧系统，避免把两套不同领域模型混在一起。
+- V2 代码目录后续新增时，也要同步记录到 `development_records/`。
+- 如果未来决定拆独立仓库，再以当前目录为迁移源。
+
+## 技术选型建议
+
+### 后端
+
+建议：`FastAPI + SQLAlchemy + Alembic + MySQL 8.x + Redis`
+
+原因：
+
+- 旧项目已经使用 FastAPI、SQLAlchemy、Pydantic，有可复用经验。
+- 新数据库文档明确指定 MySQL 8.x，V2 应优先对齐。
+- Alembic 用于数据库迁移，避免手工建表不可追踪。
+- Redis 用于验证码、Token 黑名单、限流和可选的生成状态控制。
+
+### 用户端
+
+建议：优先评估 `uni-app + Vue 3` 作为用户端技术路线。
+
+原因：
+
+- 用户端主要场景是手机端。
+- 后续可能转微信小程序，uni-app 比 Next.js H5 更适合这一目标。
+- 交互和接口要按 H5/小程序都能承载的方式设计，避免依赖纯 Web 特性。
+
+阶段一先记录为“建议”，代码开工前需要最终确认。若为了复用旧 H5 代码选择 Next.js，也必须接受后续小程序迁移成本更高这一代价。
+
+### 管理后台
+
+建议：`Vue 3 + Vite + Element Plus` 或沿用当前 Next.js 后台经验二选一。
+
+优先建议 Vue 3 的原因：
+
+- 后台是典型表单、表格、筛选、弹窗、权限菜单场景。
+- Element Plus 生态适合快速搭后台。
+- 与用户端 uni-app/Vue 体系更接近，团队后续维护成本更低。
+
+### AI/RAG
+
+建议独立成后端 service，不单独拆微服务：
+
+- `FeishuKnowledgeService`
+- `RagService`
+- `PromptService`
+- `ModelClient`
+- `AiRequestLogService`
+
+一期先在单体后端内实现，后续并发或成本压力变大时再拆独立 AI 服务。
+
+## 后端模块边界
+
+| 模块 | 职责 |
+| --- | --- |
+| `auth` | 用户短信登录、管理员登录、Token 签发、退出失效。 |
+| `users` | 普通用户资料、状态、额度、有效期。 |
+| `admins` | 管理员账号、角色、后台权限。 |
+| `knowledge` | 飞书知识库配置、启用禁用、删除和用户授权。 |
+| `chat` | 会话、消息、标题、历史、停止生成。 |
+| `rag` | 权限过滤、飞书检索、Prompt 组装、冲突处理。 |
+| `models` | 模型配置、启用模型、模型调用客户端。 |
+| `prompts` | 系统 Prompt 查看、保存、恢复默认。 |
+| `config` | 系统配置读写和运行时配置加载。 |
+| `logs` | 操作日志、AI 请求日志、导出。 |
+| `dashboard` | 首页统计和知识库排行榜。 |
+
+## 核心调用链路
+
+```text
+用户发送问题
+  -> Token 校验
+  -> 账号状态/有效期校验
+  -> 每日额度校验
+  -> 获取用户授权知识库
+  -> 过滤禁用知识库和过期授权
+  -> 实时检索飞书知识库
+  -> 无命中则返回固定兜底
+  -> 组装 Prompt
+  -> 调用启用模型
+  -> SSE 流式输出
+  -> 保存用户消息、AI 消息、检索片段、AI 请求日志
+```
+
+## 数据库原则
+
+- 使用 MySQL 8.x、utf8mb4、InnoDB。
+- 表名按需求文档使用 `sys_*`。
+- 主键统一 `BIGINT AUTO_INCREMENT`。
+- 常规删除使用 `is_deleted` 逻辑删除。
+- 知识库删除按文档允许物理删除，但删除前必须二次确认、解除授权并写操作日志。
+- 生产环境密钥不建议明文保存；模型 API Key 需要在实现前做安全决策。
+
+## 外部服务接入策略
+
+| 外部服务 | 开发阶段 | 生产阶段 |
+| --- | --- | --- |
+| 短信验证码 | mock 固定验证码/控制台输出 | 接真实短信供应商 |
+| 飞书知识库 | mock 检索数据 + 技术验证脚本 | 实时检索 SpaceID/NodeID |
+| 大模型 | mock SSE + OpenAI 兼容流式调用 | 从后台启用模型配置读取 |
+| Redis | 可选本地容器 | 验证码、Token 黑名单、限流、停止生成状态 |
+
+## 风险和控制措施
+
+| 风险 | 控制措施 |
+| --- | --- |
+| 飞书实时检索 API 能力不确定 | 阶段二开始前做技术验证脚本，确认 SpaceID/NodeID、权限和返回结构。 |
+| H5 后续转小程序成本高 | 用户端优先采用适合小程序路线的技术栈，交互不依赖复杂 Web API。 |
+| 权限后补导致越权 | RAG 链路第一步就是权限过滤，接口测试必须覆盖越权场景。 |
+| 模型回答编造 | 无命中固定兜底，Prompt 明确限制，日志记录检索片段和 Prompt。 |
+| API Key 明文风险 | 开发前明确密钥存储策略，生产不在日志中输出密钥。 |
+| 单文件膨胀 | 按模块和 service 拆分，控制单文件职责。 |
+
+## 第一阶段暂定结论
+
+1. V2 先在当前仓库 `ai_knowledge_base_v2/` 下继续推进。
+2. 后端优先使用 FastAPI，数据库对齐文档使用 MySQL 8.x。
+3. 用户端优先评估 uni-app + Vue 3，管理后台优先评估 Vue 3 + Element Plus。
+4. 第一条代码主线从后端基础工程和用户端 mock 主链路开始，不先做完整后台。
--- a/ai_knowledge_base_v2/development_records/2026-07-06-open-questions.md
+++ b/ai_knowledge_base_v2/development_records/2026-07-06-open-questions.md
@@ -0,0 +1,46 @@
+# V2 待确认问题清单
+
+日期：2026-07-06
+
+## 目的
+
+这份文档记录阶段一暂时无法从现有资料中完全确定的问题。它不是阻塞开发的借口，而是为了把风险显性化：能先 mock 的先 mock，必须确认的在进入真实接入前确认。
+
+## 必须尽早确认
+
+| 编号 | 问题 | 影响 | 建议处理 |
+| --- | --- | --- | --- |
+| Q-001 | V2 是否长期放在当前仓库，还是后续拆独立仓库？ | 影响目录结构、CI/CD 和部署方式。 | 当前先在 `ai_knowledge_base_v2/` 下推进，后续如拆仓库再迁移。 |
+| Q-002 | 数据库是否严格使用 MySQL 8.x？ | 影响 ORM、迁移、Docker 和部署。 | 建议按文档使用 MySQL 8.x。 |
+| Q-003 | 用户端技术栈是否采用 uni-app + Vue 3？ | 影响 H5 和微信小程序迁移成本。 | 建议优先采用 uni-app；如选择 Next.js，需要接受后续小程序迁移成本。 |
+| Q-004 | 短信验证码供应商是谁？ | 影响登录真实接入、费用和安全策略。 | 开发阶段先 mock，生产前确认供应商。 |
+| Q-005 | 大模型供应商、API URL、模型名和鉴权方式是什么？ | 影响模型配置和流式输出兼容性。 | 先按 OpenAI 兼容接口设计，真实供应商确认后适配。 |
+| Q-006 | 飞书知识库实时检索 API 是否满足需求？ | 是 RAG 主链路最大外部风险。 | 阶段二前做技术验证脚本。 |
+
+## 需要产品确认
+
+| 编号 | 问题 | 影响 | 建议处理 |
+| --- | --- | --- | --- |
+| Q-101 | 普通用户的姓名是否必须填写？ | 首次手机号登录时可能没有姓名。 | 首次登录可默认使用手机号后四位或空姓名，后台再补。 |
+| Q-102 | 每日聊天次数是自然日重置还是 24 小时窗口？ | 影响额度计算。 | 建议按 Asia/Shanghai 自然日重置。 |
+| Q-103 | 删除会话是否允许用户恢复？ | 影响数据模型。 | 一期按逻辑删除、不提供恢复入口。 |
+| Q-104 | 引用来源默认是否展示？ | 影响用户端回答样式。 | 建议默认后台关闭，管理员可开启。 |
+| Q-105 | 知识冲突是否需要明显提示样式？ | 影响 H5 展示。 | 建议回答底部展示“存在不同知识库观点”的提示。 |
+
+## 需要技术验证
+
+| 编号 | 问题 | 影响 | 建议处理 |
+| --- | --- | --- | --- |
+| Q-201 | 飞书 SpaceID/NodeID 能否直接实时检索文本？ | 决定 FeishuKnowledgeService 实现方式。 | 做最小脚本验证。 |
+| Q-202 | 飞书接口响应是否包含来源标题/链接？ | 影响引用来源展示和日志。 | 验证返回结构。 |
+| Q-203 | 模型流式输出是否兼容标准 SSE？ | 影响前后端流式实现。 | 选定模型后测试。 |
+| Q-204 | 停止生成如何取消上游模型请求？ | 影响 `/chat/stop` 可靠性。 | 后端记录生成任务状态，优先实现软停止，再优化硬取消。 |
+| Q-205 | API Key 如何安全保存？ | 影响生产安全。 | 建议优先环境变量引用或加密存储。 |
+
+## 暂不阻塞开发的默认假设
+
+1. V2 暂时继续放在当前仓库的 `ai_knowledge_base_v2/` 下。
+2. 后端使用 FastAPI，数据库按文档使用 MySQL 8.x。
+3. 短信、飞书和大模型先做 mock provider。
+4. 用户端优先按手机端和小程序迁移友好的方式设计。
+5. 后台管理端优先保证功能完整和可维护，不追求复杂视觉效果。
--- a/ai_knowledge_base_v2/development_records/2026-07-06-phase1-execution-record.md
+++ b/ai_knowledge_base_v2/development_records/2026-07-06-phase1-execution-record.md
@@ -0,0 +1,56 @@
+# 阶段一执行记录：需求和架构收口
+
+日期：2026-07-06
+
+## 本阶段目标
+
+按照开发流程规划，阶段一的目标是把新需求从“文档集合”整理成可以指导开发的工程边界，包括：
+
+1. 一期范围和不做范围。
+2. V2 架构草案和模块边界。
+3. 接口开发优先级。
+4. 待确认问题清单。
+5. 技术选型和关键决策记录。
+
+## 已完成文档
+
+| 文档 | 作用 |
+| --- | --- |
+| `2026-07-06-phase1-scope.md` | 锁定一期必须做、明确不做、后续扩展和验收重点。 |
+| `2026-07-06-architecture-plan.md` | 说明 V2 推荐目录、技术栈、后端模块、核心链路和风险控制。 |
+| `2026-07-06-api-priority.md` | 按 P0/P1/P2/P3 规划接口开发顺序。 |
+| `2026-07-06-open-questions.md` | 记录必须确认、产品确认和技术验证问题。 |
+| `2026-07-06-tech-decisions.md` | 记录当前建议采纳或待确认的技术决策。 |
+
+## 阶段一暂定结论
+
+1. V2 先在当前仓库的 `ai_knowledge_base_v2/` 下独立推进。
+2. V2 后端建议使用 FastAPI + SQLAlchemy + Alembic。
+3. V2 数据库建议严格对齐文档，使用 MySQL 8.x。
+4. 用户端建议优先评估 uni-app + Vue 3，降低后续微信小程序迁移成本。
+5. 管理后台建议优先评估 Vue 3 + Element Plus。
+6. 短信、飞书、大模型先做 mock provider，再逐步替换真实服务。
+7. 开发顺序先跑通用户端主链路，再补后台完整管理能力。
+
+## 进入阶段二前要确认的事
+
+这些问题不一定全部阻塞代码开工，但越早确认越好：
+
+1. 是否接受 V2 继续放在当前仓库的 `ai_knowledge_base_v2/` 下。
+2. 是否确认 V2 使用 MySQL 8.x。
+3. 用户端是否采用 uni-app + Vue 3。
+4. 后台是否采用 Vue 3 + Element Plus。
+5. 飞书知识库实时检索 API 是否能满足需求，需要做技术验证。
+6. 生产短信和大模型供应商待定，当前先按 mock + OpenAI 兼容接口推进。
+
+## 建议下一步
+
+下一步进入阶段二：**后端基础工程和数据模型**。
+
+建议第一批开发任务：
+
+1. 在 `ai_knowledge_base_v2/apps/backend/` 新建 V2 后端工程。
+2. 建立 FastAPI、配置、日志、统一响应、异常处理和健康检查。
+3. 配置 MySQL 8.x 和 Alembic 迁移。
+4. 建立第一批核心表模型：用户、管理员、角色、知识库、用户知识库权限、会话、消息。
+5. 实现 mock 短信登录、Token 签发和当前用户接口。
--- a/ai_knowledge_base_v2/development_records/2026-07-06-phase1-scope.md
+++ b/ai_knowledge_base_v2/development_records/2026-07-06-phase1-scope.md
@@ -0,0 +1,105 @@
+# V2 一期范围清单
+
+日期：2026-07-06
+
+## 目的
+
+这份文档用于锁定 AI 知识库系统 V2 的一期开发边界。后续开发、测试、验收和排期都以这里的范围为准；如果范围变化，需要新增决策记录，不直接悄悄改代码。
+
+## 一期产品目标
+
+一期要交付的是一个“企业飞书知识库 AI 问答系统”的可用版本，核心价值是：
+
+1. 用户可以登录并向系统提问。
+2. 系统只基于用户有权限访问的飞书知识库回答。
+3. 管理员可以维护用户、知识库、Prompt、模型、系统配置和聊天记录。
+4. 每次 AI 调用都有日志可追溯，方便排查回答、权限和成本问题。
+
+## 一期必须包含
+
+### 用户端
+
+| 功能 | 一期要求 | 说明 |
+| --- | --- | --- |
+| 手机号验证码登录 | 必须 | 先接 mock 短信，后续替换真实短信供应商。 |
+| 自动创建普通用户 | 必须 | 首次手机号登录后自动创建用户，无需管理员审核。 |
+| Token 登录态 | 必须 | 支持登录有效期、退出后 Token 失效。 |
+| AI 聊天 | 必须 | 文本输入、发送、接收 AI 回复。 |
+| 多会话 | 必须 | 支持新建会话、切换会话、历史会话列表。 |
+| 历史聊天 | 必须 | 用户可以查看自己的历史聊天。 |
+| 会话标题 | 必须 | 支持自动生成和手动修改标题。 |
+| 流式回答 | 必须 | 使用 SSE 流式返回。 |
+| 停止生成 | 必须 | 停止当前模型请求，保留已生成内容。 |
+| Markdown 渲染 | 必须 | 支持标题、列表、代码块、表格等基础 Markdown。 |
+| 每日聊天次数限制 | 必须 | 默认次数来自系统配置，也支持用户维度覆盖。 |
+| 知识库权限控制 | 必须 | 只能检索用户有权限、未禁用、未过期的知识库。 |
+
+### 管理后台
+
+| 功能 | 一期要求 | 说明 |
+| --- | --- | --- |
+| 管理员登录 | 必须 | 用户名 + 密码。 |
+| Dashboard | 必须 | 展示用户、聊天、Token 等核心统计；AI 成功率/失败率一期不展示。 |
+| 用户管理 | 必须 | 查询、详情、启用/禁用、删除、授权知识库、设置额度和有效期。 |
+| 管理员管理 | 必须 | 仅超级管理员可维护管理员账号。 |
+| 知识库管理 | 必须 | 新增、编辑、删除、启用/禁用飞书知识库。 |
+| Prompt 管理 | 必须 | 查看、编辑、保存、恢复默认；保存后立即生效。 |
+| AI 模型管理 | 必须 | 新增、编辑、启用、删除模型；同一时间仅一个模型启用。 |
+| 聊天记录 | 必须 | 查询、详情、导出。 |
+| 系统配置 | 必须 | 登录有效期、每日聊天次数、AI 超时、飞书重试次数、上下文长度、是否展示引用来源。 |
+| 操作日志 | 必须 | 关键后台操作必须写日志；日志不允许删除。 |
+
+### AI/RAG 能力
+
+| 能力 | 一期要求 | 说明 |
+| --- | --- | --- |
+| 飞书知识库实时检索 | 必须 | 一期不做本地同步和向量库同步。 |
+| 多知识库权限过滤 | 必须 | 检索前先过滤用户授权知识库。 |
+| Prompt 组装 | 必须 | 系统 Prompt + 检索片段 + 历史上下文 + 当前问题。 |
+| 大模型调用 | 必须 | 从启用模型配置读取 API URL、Key、模型名和参数。 |
+| SSE 输出 | 必须 | 支持流式输出和结束标记。 |
+| 引用来源 | 必须 | 用户端是否展示由后台配置控制；后台始终记录完整引用。 |
+| 无命中兜底 | 必须 | 固定返回“当前知识库中未检索到相关内容，请联系管理员补充相关知识。” |
+| 知识冲突处理 | 必须 | 展示不同知识库观点，不由 AI 自行裁决。 |
+| AI 请求日志 | 必须 | 记录用户、会话、模型、Prompt、知识库、Token、耗时、状态和错误。 |
+
+## 一期明确不做
+
+| 功能 | 不做原因 |
+| --- | --- |
+| 文件上传 | 文档明确一期不做，避免知识来源变复杂。 |
+| 图片理解 | 不属于当前文本知识问答主链路。 |
+| OCR | 不属于一期能力。 |
+| 联网搜索 | 一期固定关闭，避免模型越过企业知识库回答。 |
+| 向量数据库同步 | 一期要求实时访问飞书，不做本地同步。 |
+| 支付系统 | 与当前企业内部知识问答无关。 |
+| 课程系统 | 与当前一期主链路无关。 |
+| 自动授权 | 用户知识库权限由后台管理。 |
+| 多租户 | 一期按单企业内部系统处理。 |
+| 多 Prompt | 一期只维护一个当前生效 Prompt。 |
+| 重新生成回答 | 文档明确不做。 |
+| 编辑历史消息 | 文档明确不做。 |
+
+## 后续扩展预留
+
+以下能力不进入一期开发，但架构上要避免封死：
+
+- 多模型切换策略
+- 向量数据库
+- 更多知识源
+- 文件上传
+- 多租户
+- 联网搜索
+- 更复杂的 Prompt 版本管理
+- 知识库同步/缓存
+- 企业微信、微信小程序或其他端
+
+## 一期验收重点
+
+1. 用户可以完成登录、提问、流式回答、停止生成、查看历史。
+2. AI 只使用用户有权限的知识库，权限过期、知识库禁用、未授权都不能参与检索。
+3. 无知识命中时不编造答案。
+4. 飞书异常、模型异常、AI 超时都有明确提示和日志。
+5. 后台可以维护用户、知识库、Prompt、模型、系统配置和聊天记录。
+6. 管理后台权限隔离生效：普通管理员不能维护管理员账号。
+7. 所有关键操作和 AI 请求都可追溯。
--- a/ai_knowledge_base_v2/development_records/2026-07-06-tech-decisions.md
+++ b/ai_knowledge_base_v2/development_records/2026-07-06-tech-decisions.md
@@ -0,0 +1,116 @@
+# V2 技术决策记录
+
+日期：2026-07-06
+
+## 记录方式
+
+状态说明：
+
+- `建议采纳`：当前建议按此执行，后续如修改需要新增决策记录。
+- `待确认`：先作为默认假设推进，但需要用户或技术验证确认。
+- `已确认`：已经明确执行。
+
+## D-001：V2 代码与文档放在独立目录
+
+状态：建议采纳
+
+决策：V2 继续在当前仓库推进，但所有 V2 文档和后续代码都放在 `ai_knowledge_base_v2/` 下。
+
+原因：
+
+- 避免和旧“答疑资产后台系统”混在一起。
+- 当前远端仓库已经打通提交和推送，便于持续追踪。
+- 后续如果需要拆仓库，可以从这个目录迁移。
+
+## D-002：数据库优先使用 MySQL 8.x
+
+状态：建议采纳
+
+决策：V2 数据库按需求文档使用 MySQL 8.x、utf8mb4、InnoDB。
+
+原因：
+
+- 数据库设计文档明确指定 MySQL 8.x。
+- 字段字典、表命名和部署文档都围绕该方向。
+- 旧项目的 PostgreSQL/SQLite 只能作为旧系统实现参考，不作为 V2 默认数据库。
+
+## D-003：后端优先使用 FastAPI
+
+状态：建议采纳
+
+决策：V2 后端优先使用 FastAPI + SQLAlchemy + Alembic。
+
+原因：
+
+- 旧项目已有 FastAPI 经验，可以复用工程实践。
+- FastAPI 适合快速实现 REST、SSE 和 OpenAI 兼容模型调用。
+- SQLAlchemy 可以兼容 MySQL，Alembic 能提供可追踪迁移。
+
+## D-004：用户端优先评估 uni-app + Vue 3
+
+状态：待确认
+
+决策：用户端建议优先使用 uni-app + Vue 3，而不是直接沿用旧 Next.js H5。
+
+原因：
+
+- 主要使用场景是手机端。
+- 用户之前提出后续可能封装成微信小程序。
+- uni-app 更适合 H5 与小程序双端路线。
+
+代价：
+
+- 旧 Next.js H5 代码只能复用交互经验，不能大面积复制。
+- 团队需要接受 Vue/uni-app 工程结构。
+
+## D-005：管理后台优先评估 Vue 3 + Element Plus
+
+状态：待确认
+
+决策：管理后台建议优先使用 Vue 3 + Vite + Element Plus。
+
+原因：
+
+- 后台是典型表格、表单、筛选、弹窗和权限菜单场景。
+- Element Plus 可以快速搭建可维护后台。
+- 与用户端 Vue 体系更一致。
+
+备选：
+
+- 如果团队强希望复用旧 Next.js 后台经验，可以继续用 Next.js，但要记录技术栈不统一的维护成本。
+
+## D-006：短信、飞书、大模型先 mock 后真实接入
+
+状态：建议采纳
+
+决策：外部服务必须先有 mock provider，保证本地开发和测试不被外部账号、权限、费用阻塞。
+
+原因：
+
+- 短信供应商未确认。
+- 飞书实时检索 API 需要技术验证。
+- 大模型供应商和模型参数未最终确认。
+
+## D-007：RAG 不单独拆微服务
+
+状态：建议采纳
+
+决策：一期 RAG 能力先作为后端内部 service 实现，不单独拆微服务。
+
+原因：
+
+- 一期重点是跑通业务闭环。
+- 单体更容易部署、调试和回滚。
+- 后续并发、成本、队列和模型调用压力变大后，再评估拆分。
+
+## D-008：生产密钥不直接明文展示
+
+状态：建议采纳
+
+决策：模型 API Key、飞书密钥、短信密钥等敏感信息不应在前端明文展示，也不应进入日志。
+
+建议实现：
+
+- 开发阶段可以用 `.env`。
+- 生产阶段优先使用环境变量引用或加密存储。
+- 后台模型配置页展示脱敏后的 Key。
--- a/ai_knowledge_base_v2/development_records/README.md
+++ b/ai_knowledge_base_v2/development_records/README.md
@@ -12,3 +12,15 @@
 - 测试、验收和风险记录

 注意：V2 的开发记录不要再放到旧的 `hy_qa_asset_backend/docs` 目录。旧目录属于上一阶段“答疑资产后台系统”。
+
+## 当前关键文档
+
+| 文档 | 说明 |
+| --- | --- |
+| `2026-07-06-development-process-plan.md` | V2 总体开发流程规划。 |
+| `2026-07-06-phase1-execution-record.md` | 阶段一执行记录和阶段二入口建议。 |
+| `2026-07-06-phase1-scope.md` | 一期范围清单。 |
+| `2026-07-06-architecture-plan.md` | 架构设计草案。 |
+| `2026-07-06-api-priority.md` | 接口优先级规划。 |
+| `2026-07-06-open-questions.md` | 待确认问题清单。 |
+| `2026-07-06-tech-decisions.md` | 技术决策记录。 |