From 587f5e7ace3968e2e643563585c34e9eb77785f9 Mon Sep 17 00:00:00 2001
From: WangDL <wangdalin@outlook.com>
Date: Wed, 20 May 2026 22:36:25 +0800
Subject: [PATCH] =?UTF-8?q?docs:=205/20=20=E5=85=A8=E5=A4=A9=E5=B7=A5?=
 =?UTF-8?q?=E4=BD=9C=E6=97=A5=E5=BF=97=E6=9B=B4=E6=96=B0=20+=20=E7=9F=A5?=
 =?UTF-8?q?=E8=AF=86=E5=BA=93/=E9=83=A8=E7=BD=B2=E6=96=B9=E6=A1=88?=
 =?UTF-8?q?=E7=8A=B6=E6=80=81=E5=90=8C=E6=AD=A5=20+=20=E5=BE=85=E5=86=B3?=
 =?UTF-8?q?=E7=AD=96=E4=BA=8B=E9=A1=B9=20+=20webApp/admin=20=E6=8A=80?=
 =?UTF-8?q?=E6=9C=AF=E6=A0=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 工作日志/2026-05-20.md                        | 162 ++++-
 技术设计/admin-projects/技术栈.md             | 679 ++++++++++++++++++
 技术设计/api-server/服务器与数据库部署方案.MD | 119 ++-
 技术设计/api-server/知识库设计.MD             | 141 ++--
 技术设计/webApp-projects/技术栈.md            |  53 ++
 技术设计/待决策事项.md                        | 112 +++
 技术设计/总待完成清单.md                      |  12 +-
 7 files changed, 1178 insertions(+), 100 deletions(-)
 create mode 100644 技术设计/admin-projects/技术栈.md
 create mode 100644 技术设计/webApp-projects/技术栈.md
 create mode 100644 技术设计/待决策事项.md

diff --git a/工作日志/2026-05-20.md b/工作日志/2026-05-20.md
index 80f7c69..682cfae 100644
--- a/工作日志/2026-05-20.md
+++ b/工作日志/2026-05-20.md
@@ -192,21 +192,161 @@ docker run -d --name gitea --restart always \
 
 ---
 
-## 当前待办
+## 晚间：服务器全面核查 + 修复 + 全链路跑通
 
+### 8. 服务器全面核查 ✅
+
+两服务器 SSH 逐项检查，对比凭据文件中的预期状态。
+
+**4核4G (81.70.187.179)：**
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| 系统资源 | ⚠️ | 负载 0.06，RAM 3.6G（剩 212M），磁盘 45% |
+| Docker | ⚠️ | 3 个 Exited 僵尸容器，旧 zhixi-api 还在运行 |
+| Gitea 1.23.8 | ✅ | HTTP 200，Actions 页面 200 OK |
+| Runner | ✅ | active（自 5/9 起） |
+| Nginx | ⚠️ | server_name 重复定义（sites-enabled 和 conf.d 双重加载） |
+| SSL | ✅ | api/git/longde.cloud 均有效 |
+| UFW / Fail2ban | ❌ | 均未配置 |
+
+**8核32G (120.53.227.155)：**
+
+| 检查项 | 状态 | 说明 |
+|--------|------|------|
+| 系统资源 | ✅ | 负载 1.0，RAM 30G（剩 20G），磁盘 27%/4% |
+| Docker (mysql/redis/qdrant) | ✅ | 全部 Up，仅 127.0.0.1 |
+| systemd (api/worker/runner) | ✅ | 三项 active |
+| Python 依赖 | ❌ | 缺 openai、tencentcloud |
+| Docker 残留 | ⚠️ | zhixi-redis Created 状态 |
+| 备份 | ❌ | 目录空，无 cron |
+| UFW | ❌ | 未启用 |
+
+**发现的额外问题：**
+- 4核4G SSH 被拒 — `~/.ssh/config` 中 `Port 2222` 覆盖了默认 22，需 `-p 22` 显式指定
+- devops-projects/凭据配置/ 下文件名全部乱码 — Python 逐文件修复
+
+### 9. 服务器修复（8 项） ✅
+
+| # | 项目 | 服务器 | 操作 |
+|---|------|--------|------|
+| 1 | Python 缺包 | 8核32G | pip3.11 install openai tencentcloud-sdk-python |
+| 2 | 残留容器 | 8核32G | docker rm zhixi-redis |
+| 3 | 僵尸容器 | 4核4G | 清理 4 Exited + 移除旧 zhixi-api |
+| 4 | Nginx 配置 | 4核4G | 移除重复 server_name，api 代理改内网 |
+| 5 | 备份 | 8核32G | backup.sh + 首次备份 + cron 每日 3:00 |
+| 6 | UFW | 两台 | 启用，22/80/443/2222 |
+| 7 | Fail2ban | 4核4G | 安装 + sshd jail |
+| 8 | 文件编码 | 本地 | 凭据配置目录乱码文件名修正 |
+
+### 10. 知识库全链路跑通 ✅
+
+**Bug 修复：**
+
+| # | 文件 | 问题 | 修复 |
+|---|------|------|------|
+| 1 | document-import.repository.ts | Prisma schema 有 rawText 但 repository 未传参 | 添加 rawText: data.rawText |
+| 2 | .env.production | DEEPSEEK_BASE_URL=/v1 + Provider 拼接 /v1/chat → 双写 /v1/v1 → 404 | 去掉末尾 /v1 |
+
+**测试流程：**
+
+```
+1. dev-login → ❌ 生产禁用 → 手工签发 JWT (sub: user_test_001)
+2. POST /api/knowledge-bases → ✅ KB cmpe1zub6...
+3. POST /api/imports (raw text) → ❌ rawText 未入库 → 修 bug → ✅
+4. Worker 处理 → ❌ DeepSeek 404 → 修 bug → ✅
+5. AI 提取 → ✅ 5 个知识点（机器学习/深度学习/NLP/CV/强化学习）
+6. Embedding → ✅ bge-m3 → 存入 Qdrant
+7. RAG 对话 → ✅ POST /api/rag/chat ~1.1s
+   问："什么是机器学习？"
+   答："机器学习是让计算机从数据中学习模式[1]"
+```
+
+### 11. RAG 对话接口开发 ✅
+
+新增 `modules/rag-chat/`（controller + service + module），端点 `POST /api/rag/chat`：
+- **Embedding**：SiliconFlow bge-m3
+- **检索**：Qdrant REST API（按 knowledgeBaseId 过滤）
+- **Rerank**：SiliconFlow bge-reranker-v2-m3
+- **生成**：DeepSeek + citations（[N] 标记）
+
+### 12. 凭据文件 ✅
+
+- 旧凭据（startup-plan）已删除，新凭据统一在 devops-projects/
+- 乱码文件名全部修复
+
+---
+
+## 深夜：收尾修复 + 多轮对话
+
+### 13. 快速修复（3 项） ✅
+
+| # | 项目 | 服务器 | 操作 |
+|---|------|--------|------|
+| 1 | Nginx 旧代理 | 4核4G | 移除 conf.d 中指向 localhost:3001 的 API 代理 |
+| 2 | 物理清理 | 8核32G | cron `0 4 * * *` 清理 /data/tmp/imports/ 超过 1 天的临时目录 |
+| 3 | Chunk 写入 500 | 8核32G | FK 约束导致 — 创建系统 KnowledgeSource `direct-import` 解决 |
+
+### 14. 知识库级联删除 ✅
+
+修改 `KnowledgeBaseService.remove()`，级联清理链路：
+```
+KnowledgeBase → KnowledgeItems (soft delete)
+              → ImportCandidates (hard delete)
+              → KnowledgeChunks (soft delete)
+              → DocumentImports (status→CANCELLED)
+              → KnowledgeSources (soft delete)
+              → Qdrant vectors (delete by filter)
+```
+创建测试 KB → 导入 → 添加 chunk → 删除 → KB.deletedAt + Chunk.deletedAt 均已设置 ✅
+
+### 15. RAG 多轮对话 ✅
+
+`POST /api/rag/chat` 新增可选 `history` 参数：
+```json
+{
+  "knowledgeBaseId": "...",
+  "query": "那它和深度学习有什么关系？",
+  "history": [
+    {"role": "user", "content": "什么是机器学习？"},
+    {"role": "assistant", "content": "机器学习是..."}
+  ]
+}
+```
+历史消息注入 DeepSeek 上下文（最近 10 条），实现多轮追问。测试通过 ✅
+
+---
+
+## 当前待办（最终版）
+
+已完成（15 项）：
 1. ~~Python Worker 补全部署~~ ✅
 2. ~~4核4G gitea-runner-web~~ ✅
 3. ~~百度 OCR 开通~~ ✅
 4. ~~COS Bucket 验证~~ ✅
-5. ~~Rerank 模块代码 + 推送服务器验证~~ ✅
-6. ~~CI/CD 流水线修复~~ ✅
-7. ~~Gitea 升级 1.22.6 → 1.23.8~~ ✅
-8. 🟡 知识库对话接口（RAG 检索→rerank→DeepSeek 回答+citations）
-9. 🟡 知识库级联删除
-10. 🟢 MySQL/Qdrant 备份脚本 + cron
-11. 🟢 物理清理定时任务
-12. ⬜ 阶段七：学习引擎（ActiveRecall→AIAnalysis→FocusItem→ReviewCard）
-13. ⬜ 阶段八：知识库对话（Chat session + 多轮对话）
-14. ⬜ 阶段十：后台管理 + 额度检查
+5. ~~Rerank 模块~~ ✅
+6. ~~CI/CD 修复~~ ✅
+7. ~~Gitea 升级~~ ✅
+8. ~~知识库对话接口~~ ✅
+9. ~~备份脚本 + cron~~ ✅
+10. ~~服务器核查 + 安全加固~~ ✅
+11. ~~知识库级联删除~~ ✅
+12. ~~知识库对话多轮~~ ✅
+13. ~~MySQL Chunk 写入修复~~ ✅
+14. ~~Nginx 旧代理清理~~ ✅
+15. ~~物理清理定时任务~~ ✅
+
+仍待做：
+16. 🟢 AI 提取 prompt 调优（待真实文档）
+17. 🟢 COS 备份同步 + 生命周期清理
+18. 🟢 MySQL 物理清理脚本
+19. 🟢 Docker Compose 统一
+20. 🟢 logrotate 确认
+21. 🔴 学习引擎串联（需先定产品交互）→ 见《学习引擎设计决策.md》
+22. ⬜ 阶段九：iOS API 对接 + 用户闭环测试
+23. ⬜ 阶段十：后台管理 + 额度检查
+
+> **下一步：** 学习引擎（ActiveRecall→AIAnalysis→FocusItem→ReviewCard）
+> 6 个模块代码已全部就绪，但串联涉及产品交互决策（学习步骤、回忆形式、诊断粒度、复习触发时机），待用户确定后单独建文档设计。
 
 ---
diff --git a/技术设计/admin-projects/技术栈.md b/技术设计/admin-projects/技术栈.md
new file mode 100644
index 0000000..c695e8a
--- /dev/null
+++ b/技术设计/admin-projects/技术栈.md
@@ -0,0 +1,679 @@
+对，继续把**后台管理系统**也定下来。后台管理系统和 C 端 Web 不一样，它不追求 Notion 那种沉浸编辑体验，核心是：
+
+```text
+高效率 CRUD
+数据检索
+用户/会员管理
+知识库任务监控
+AI 成本监控
+问题排查
+人工干预
+权限审计
+```
+
+所以后台不要用 C 端那套 shadcn 风格，也不要追求“漂亮得像消费级产品”。后台要稳、快、表格强、表单强、权限清楚。
+
+# 后台管理系统技术栈定版
+
+```text
+框架：Vite + React + TypeScript
+UI：Ant Design
+中后台增强组件：Ant Design ProComponents
+路由：React Router
+服务端状态：TanStack Query
+本地状态：Zustand
+API Client：OpenAPI + Orval
+图表：Apache ECharts
+表单：Ant Design Form + Zod
+权限：后端 RBAC + 前端路由守卫
+构建：pnpm workspace + Turborepo
+部署：8核32G，和生产后端同源或同内网
+```
+
+一句话：
+
+```text
+C端 Web：Vite + React + Tiptap + shadcn，做高体验知识工作台
+后台管理：Vite + React + Ant Design + ProComponents，做高效率运营控制台
+```
+
+---
+
+# 一、为什么后台用 Ant Design？
+
+后台管理就是 Ant Design 的优势区。Ant Design 官方定位是面向 React 的高质量组件库，适合构建丰富、交互型用户界面；而 ProComponents 明确是为了降低中后台 CRUD 实现成本，尤其适合表格、筛选、表单、详情页这些场景。([Ant Design][1])
+
+所以后台管理系统直接定：
+
+```text
+Ant Design
++
+ProComponents
+```
+
+主要用：
+
+```text
+ProTable
+ProForm
+ProDescriptions
+ProLayout
+ModalForm
+DrawerForm
+StepsForm
+```
+
+后台里最常见的页面就是：
+
+```text
+用户列表
+订单列表
+文件列表
+导入任务列表
+AI 调用日志
+额度使用记录
+错误日志
+备份任务
+```
+
+这些用 ProTable 做最快。
+
+---
+
+# 二、为什么后台不用 shadcn/ui？
+
+shadcn/ui 适合 C 端产品、官网、轻量 SaaS、漂亮的交互界面。
+
+但后台管理系统主要是：
+
+```text
+密集表格
+复杂筛选
+批量操作
+详情抽屉
+高级搜索
+权限按钮
+状态标签
+操作日志
+```
+
+Ant Design 在这些地方更省时间。
+
+所以定：
+
+```text
+C端 Web：shadcn/ui
+后台管理：Ant Design
+```
+
+不要强行统一 UI 栈。
+
+---
+
+# 三、为什么后台也用 Vite？
+
+后台不需要 SSR，也不需要 SEO。Vite 构建产物本来就适合静态托管，官方文档也说明 `vite build` 会输出适合静态托管的生产包。([vitejs][2])
+
+所以后台用：
+
+```text
+Vite + React + TypeScript
+```
+
+不要用 Next.js。
+不要用 Umi/Ant Design Pro 全家桶起步。
+我们只拿 Ant Design 和 ProComponents，不把整个项目绑死到 Umi 上。
+
+---
+
+# 四、状态管理怎么定？
+
+## 服务端状态
+
+```text
+TanStack Query
+```
+
+后台大部分数据都是服务端状态：
+
+```text
+用户列表
+会员状态
+知识库列表
+文件列表
+导入任务
+AI 调用日志
+消费统计
+错误日志
+备份记录
+```
+
+TanStack Query 官方定位就是处理 fetching、caching、同步和更新服务端状态。([GitHub][3])
+
+后台不要自己手写一堆：
+
+```text
+loading
+error
+pagination
+refetch
+cache
+mutation
+```
+
+直接交给 React Query。
+
+---
+
+## 本地状态
+
+```text
+Zustand
+```
+
+只管理这些轻量 UI 状态：
+
+```text
+侧边栏折叠
+当前主题
+当前选中的环境
+全局搜索弹窗
+当前打开的抽屉
+管理员权限缓存
+```
+
+Zustand 官方定位是小型、快速、可扩展的 React 状态管理方案，适合这种轻量本地状态。([zustand.docs.pmnd.rs][4])
+
+---
+
+# 五、API 类型方案
+
+后台继续用：
+
+```text
+OpenAPI + Orval
+```
+
+Orval 可以从 OpenAPI 生成类型安全的 TypeScript API client，并支持 React Query。([orval.dev][5])
+
+这样你的结构会很清楚：
+
+```text
+NestJS Swagger / OpenAPI
+        ↓
+Orval 生成 admin-api-client
+        ↓
+React Query hooks
+        ↓
+Ant Design 页面
+```
+
+后台不要手写 axios 类型。
+
+---
+
+# 六、图表用什么？
+
+后台图表定：
+
+```text
+Apache ECharts
+```
+
+后台需要看：
+
+```text
+DAU / MAU
+注册趋势
+付费趋势
+AI 调用成本
+OCR 页数
+Vision 页数
+Embedding 数量
+知识库导入成功率
+任务失败率
+用户留存
+模型调用分布
+```
+
+ECharts 官方说明它提供 20 多种图表类型，并支持 Canvas/SVG、渐进渲染和多维数据分析能力，适合后台数据可视化。([echarts.apache.org][6])
+
+不用 Recharts 做后台主图表。Recharts 可以做轻量卡片图，但后台完整数据分析还是 ECharts 更合适。
+
+---
+
+# 七、后台管理系统放哪里？
+
+后台管理前端建议部署在：
+
+```text
+8核32G
+```
+
+原因是它操作生产数据，最好和生产后端同源或同内网，减少跨服务器、跨域和密钥暴露问题。
+
+最终部署：
+
+```text
+8核32G：
+- admin.zhixi.xxx 静态前端
+- /admin-api 后台接口
+- MySQL
+- Redis
+- Qdrant
+- RAG Worker
+```
+
+4核4G 继续放：
+
+```text
+产品官网
+Gitea
+n8n
+agent
+监控
+```
+
+不要把后台管理系统放 4核，然后跨公网操作 8核的生产 API。可以做到，但没必要增加复杂度。
+
+---
+
+# 八、后台后端怎么做？
+
+后台不是单独起一个后端项目，而是在现有 NestJS 里加：
+
+```text
+AdminModule
+```
+
+接口前缀：
+
+```text
+/admin-api/*
+```
+
+普通 C 端 API：
+
+```text
+/api/*
+```
+
+内部 Worker API：
+
+```text
+/internal/*
+```
+
+也就是：
+
+```text
+/api              用户端接口
+/admin-api        后台管理接口
+/internal         Worker / 内部服务接口
+```
+
+后台不能直接连数据库。
+所有操作必须经过 NestJS 后端，统一权限、日志、审计。
+
+---
+
+# 九、后台权限系统
+
+后台必须独立于普通用户系统。
+
+不要让普通 `users` 表里的用户直接登录后台。
+
+新增：
+
+```text
+admin_users
+admin_roles
+admin_permissions
+admin_role_permissions
+admin_user_roles
+admin_sessions
+admin_audit_logs
+```
+
+权限模型：
+
+```text
+SUPER_ADMIN
+OPERATIONS
+CUSTOMER_SUPPORT
+CONTENT_REVIEWER
+FINANCE
+DEVELOPER
+READONLY
+```
+
+高危操作必须写审计日志：
+
+```text
+修改会员
+重置额度
+删除知识库
+重试导入任务
+清理 COS 文件
+重建 Qdrant 索引
+修改模型路由
+修改系统 Prompt
+退款/订单处理
+封禁用户
+```
+
+审计日志至少记录：
+
+```text
+adminUserId
+action
+resourceType
+resourceId
+beforeJson
+afterJson
+ip
+userAgent
+createdAt
+```
+
+---
+
+# 十、后台安全策略
+
+后台管理系统要比 C 端更严格。
+
+第一版至少做：
+
+```text
+独立管理员账号
+强密码
+登录限流
+HttpOnly Cookie
+CSRF 保护
+RBAC 权限
+操作审计
+敏感操作二次确认
+后台域名单独配置
+```
+
+后面补：
+
+```text
+TOTP 双因素认证
+IP 白名单
+登录通知
+设备管理
+只读管理员
+紧急冻结开关
+```
+
+不要让后台用普通用户 JWT 直接访问。
+
+---
+
+# 十一、后台页面清单
+
+后台第一批页面要这样定，不要只做一个用户列表。
+
+## 1. 总览 Dashboard
+
+```text
+今日注册
+今日活跃
+今日付费
+AI 调用次数
+AI 成本
+OCR 页数
+Vision 页数
+导入成功率
+失败任务数
+系统告警
+```
+
+## 2. 用户管理
+
+```text
+用户列表
+用户详情
+登录记录
+会员状态
+额度使用
+知识库数量
+文件占用
+学习记录概览
+封禁 / 解封
+备注
+```
+
+## 3. 会员与额度
+
+```text
+会员方案
+订阅状态
+额度配置
+额度使用明细
+手动补额度
+手动扣额度
+订单记录
+退款记录
+```
+
+## 4. 知识库管理
+
+```text
+知识库列表
+知识源列表
+文件详情
+parsed.md 查看
+chunk 数量
+Qdrant 索引状态
+导入任务状态
+重试 / 取消 / 标记失败
+```
+
+## 5. 文档导入任务
+
+```text
+DocumentImport 队列
+当前 step
+progress
+workerId
+heartbeatAt
+retryCount
+errorCode
+errorMessage
+任务重试
+任务取消
+任务详情
+```
+
+## 6. AI 调用与成本
+
+```text
+DeepSeek 调用记录
+硅基流动调用记录
+百度 OCR 调用记录
+embedding 调用数量
+rerank 调用数量
+按用户统计成本
+按模型统计成本
+失败率
+平均耗时
+```
+
+## 7. Prompt / 模型路由配置
+
+```text
+任务类型
+默认模型
+备用模型
+temperature
+max_tokens
+是否 thinking
+Prompt 版本
+灰度开关
+```
+
+这一块非常重要。你后面一定会调模型策略，不能每次都改代码。
+
+## 8. 文件与 COS 管理
+
+```text
+文件列表
+objectKey
+文件大小
+文件用途
+上传状态
+引用关系
+孤儿文件扫描
+清理队列
+```
+
+## 9. Qdrant 管理
+
+```text
+collection 状态
+points 数量
+索引状态
+snapshot 记录
+重建索引任务
+按 sourceId 删除向量
+按 kbId 标记 deleted
+```
+
+## 10. 备份管理
+
+```text
+MySQL backup_jobs
+Qdrant snapshots
+COS 同步状态
+备份失败重试
+备份下载
+恢复演练记录
+```
+
+## 11. 反馈与工单
+
+```text
+用户反馈
+截图
+设备信息
+App 版本
+处理状态
+内部备注
+```
+
+## 12. 系统审计
+
+```text
+管理员操作日志
+登录日志
+敏感操作
+失败操作
+权限变更记录
+```
+
+---
+
+# 十二、项目结构
+
+放到 monorepo：
+
+```text
+startup/
+  apps/
+    landing/
+    web/
+    admin/
+    backend/
+    rag-worker/
+
+  packages/
+    ui/
+    admin-ui/
+    api-client/
+    shared/
+    config/
+```
+
+`apps/admin` 技术栈：
+
+```text
+Vite
+React
+TypeScript
+React Router
+Ant Design
+ProComponents
+TanStack Query
+Zustand
+Orval
+ECharts
+```
+
+---
+
+# 十三、不要选这些
+
+后台管理系统不建议：
+
+```text
+不用 Next.js
+不用 shadcn/ui 做后台主 UI
+不用 Dify 做后台
+不用 Strapi / Directus 接管生产数据
+不用让后台前端直连数据库
+不用让 n8n 直接操作生产库
+不用把后台部署在 4核工具服务器上跨公网操作生产
+```
+
+低代码后台可以后面用来做内部小工具，但**知习正式后台管理系统必须自己做**。原因是你有大量业务特定操作：
+
+```text
+额度调整
+AI 成本追踪
+知识库导入重试
+Qdrant 重建
+Prompt 版本
+模型路由
+COS 清理
+学习记录排查
+```
+
+这些不是普通 CRUD 能完整覆盖的。
+
+---
+
+# 最终拍板
+
+```text
+后台管理系统：
+Vite + React + TypeScript
+Ant Design + ProComponents
+React Router
+TanStack Query
+Zustand
+OpenAPI + Orval
+Apache ECharts
+Ant Design Form + Zod
+NestJS AdminModule
+MySQL RBAC + admin_audit_logs
+部署在 8核32G
+```
+
+最终分工：
+
+```text
+C端 Web：体验优先，像 Notion / 知识工作台
+后台 Admin：效率优先，像运营控制台 / 系统控制台
+iOS：移动学习体验优先
+8核32G：生产核心
+4核4G：官网、Gitea、n8n、agent、监控
+```
+
+[1]: https://ant.design/docs/react/introduce/?utm_source=chatgpt.com "Ant Design of React"
+[2]: https://vite.dev/guide/build?utm_source=chatgpt.com "Building for Production"
+[3]: https://github.com/tanstack/query?utm_source=chatgpt.com "TanStack/query"
+[4]: https://zustand.docs.pmnd.rs/?utm_source=chatgpt.com "Zustand: Introduction"
+[5]: https://orval.dev/?utm_source=chatgpt.com "Orval - Generate type-safe API clients from OpenAPI"
+[6]: https://echarts.apache.org/?utm_source=chatgpt.com "Apache ECharts"
diff --git a/技术设计/api-server/服务器与数据库部署方案.MD b/技术设计/api-server/服务器与数据库部署方案.MD
index 1e86a33..006871b 100644
--- a/技术设计/api-server/服务器与数据库部署方案.MD
+++ b/技术设计/api-server/服务器与数据库部署方案.MD
@@ -219,7 +219,7 @@ ports:
 
 ---
 
-## 四、COS：对象存储 ⚠️ 凭据已配置，Bucket 待验证
+## 四、COS：对象存储 ✅ 凭据已配置，Bucket 已验证
 
 ### 存放内容
 
@@ -245,7 +245,7 @@ zhixi-prod/
 
 ---
 
-## 五、Redis：队列与缓存 ✅ 已完成（BullMQ 待接）
+## 五、Redis：队列与缓存 ✅ 已完成（BullMQ document-import 队列已运行）
 
 ### 负责
 
@@ -647,7 +647,7 @@ Gitea 只影响代码仓库和部署流水线
 9. 修改 Prisma schema：BigInt → String(cuid) ✅
 10. 初始化空库 migration ✅ (3 个 migration 执行)
 11. 4核4G mysqldump → 导入 8核32G ✅
-12. 配置备份脚本（MySQL + Qdrant + 同步 COS）⏳ 待配置
+12. 配置备份脚本（MySQL + Qdrant + 同步 COS）🔶 本地完成，COS 同步待配
 ```
 
 ### 第四步：CI/CD 搭建 ✅ 已完成
@@ -672,15 +672,22 @@ Gitea 只影响代码仓库和部署流水线
 
 > **当前状态：DNS 已切换到 8核32G。✅**
 
-### 第六步：知识库开发 🔶 进行中
+### 第六步：知识库开发 ✅ 核心已通
 
 ```text
-23. 在 8核32G 上按知识库设计文档建表 ✅ (33 张表)
-24. 实现文件上传 → COS ⏳ (COS 凭据已配，API 代码已就)
-25. 部署 RAG Worker 🔶 (代码已部署，systemd 待创建)
-26. 打通索引流程 → 学习流程 ⏳ (待 RAG Worker 跑通)
+23. 在 8核32G 上按知识库设计文档建表 ✅ (35 张表)
+24. 实现文件上传 → COS 🔶 (COS 凭据已配，API 已就，待 iOS 真文件测试)
+25. 部署 RAG Worker ✅ (systemd zhixi-worker 已启动)
+26. 打通索引流程 → 学习流程 ✅
+    - raw text 导入全链路 ✅ (chunk→embed→Qdrant→candidate)
+    - RAG 对话 ✅ (检索→rerank→DeepSeek+citations)
+    - 多轮对话 ✅ (history 参数)
+    - 级联删除 ✅
+    - 备份 ✅ (本地 cron，COS 同步待配)
+    - 学习引擎（ActiveRecall/AIAnalysis/FocusItem/Review）模块已建，待端到端对接测试
 ```
 
+
 ---
 
 ## 十一、最终拍板清单（执行状态）
@@ -712,11 +719,13 @@ Gitea 只影响代码仓库和部署流水线
 17. ✅ Gitea 本体只放 4核4G，Runner 两台都装
 18. ✅ 服务跑在哪台服务器，Runner 就装在哪台服务器
 19. ✅ 生产密钥放服务器本地 .env，不写入仓库
-20. ✅ Runner 使用 deploy 用户/ubuntu，不用 root
+20. ✅ Runner 使用 ubuntu 用户
 
 # 安全边界
 21. ⏳ n8n / agent 调用知习受控 API，不直连生产库（n8n 未部署）
-22. ✅ 迁移完成后 4核4G 旧后端保留作为备用
+22. ✅ 迁移完成后 4核4G 旧 API 容器已移除
+23. ✅ UFW 防火墙两台均已启用（22/80/443 + 4核4G 2222）
+24. ✅ Fail2ban 4核4G 已安装（sshd jail）
 ```
 
 后续不会再有一次大的数据库迁移。
@@ -742,21 +751,99 @@ Gitea 只影响代码仓库和部署流水线
 |---|------|------|------|
 | 5 | **Redis 持久化** | ✅ 已配置 | AOF everysec + RDB 双开 |
 | 6 | **Docker 容器网络规划** | ✅ 已配置 | `zhixi-net` bridge 网络，MySQL/Redis 绑定 localhost |
-| 7 | **日志轮转与保留** | ✅ /data/logs 目录已建 | logrotate 待确认 |
-| 8 | **健康检查端点** | ✅ 已实现 | `/health` 端点返回 `{"status":"ok"}`，被 CI/CD 使用 |
+| 7 | **日志轮转与保留** | 🔶 /data/logs 目录已建 | logrotate 待确认 |
+| 8 | **健康检查端点** | ✅ 已实现 | `/api` 返回 `{"status":"ok"}`，被 CI/CD 使用 |
 | 9 | **两服务器间通信** | ✅ 内网直连 | 双向 ~1.9ms，Runner/API 互调均走内网 |
-| 10 | **COS 带宽成本** | ✅ Bucket 存在 | `zhixi-1259685406` 已确认 |
+| 10 | **COS 带宽成本** | ✅ 已验证 | Bucket `zhixi-1259685406`，同区 VPC 内网免流量费 |
 
 ### 🟢 低风险（后续迭代时再定）
 
 | # | 问题 | 现状 |
 |---|------|------|
-| 11 | **API 版本管理** | ⏳ `/api/v1/` 未加，当前无版本前缀 |
+| 11 | **API 版本管理** | ⏳ 无 /api/v1/ 前缀 |
 | 12 | **灰度/蓝绿部署** | ⏳ 后续 |
 | 13 | **数据库读写分离** | ⏳ 后续 |
-| 14 | **异地备份** | ⏳ COS 备份待配置 |
+| 14 | **异地备份（COS 同步）** | ⏳ 本地备份已有，COS 上传待配 |
 | 15 | **4核4G 最终去留** | ✅ 保留作为工具服务器 |
-| 16 | **Docker Compose 文件结构** | 🔶 当前用独立 docker run，未统一 compose |
+| 16 | **Docker Compose 统一** | 🔶 当前独立 docker run，未统一 compose |
+| 17 | **logrotate** | ⏳ 待确认 |
+| 18 | **BAIDU_OCR_KEY** | ✅ 已开通（AppID 7767914） |
+
+---
+
+## 十三、当前工作流总览（2026-05-20 终态）
+
+### 已实现并验证的流程
+
+**流程一：文档导入（NestJS BullMQ Worker）**
+```
+POST /api/imports {rawText, knowledgeBaseId}
+  → DocumentImportWorker:
+    → ChunkingService（512t/64overlap，按标题/段落/句子分割）
+    → VectorService（bge-m3 batch 50 → Qdrant UUID upsert → MySQL chunk 写入）
+    → KnowledgeImportWorkflow（DeepSeek 提取知识点）
+    → ImportCandidate 写入
+    → KB.itemCount 更新
+  → COMPLETED
+```
+
+**流程二：RAG 对话**
+```
+POST /api/rag/chat {knowledgeBaseId, query, history?}
+  → RagChatService:
+    → embed query（bge-m3）
+    → Qdrant 向量搜索（按 kbId/deleted 过滤）
+    → rerank（bge-reranker-v2-m3）
+    → DeepSeek 回答 + citations
+  → 支持多轮（history 参数，最近 10 条上下文注入）
+```
+
+**流程三：知识库管理**
+```
+POST   /api/knowledge-bases          创建
+GET    /api/knowledge-bases          列表
+GET    /api/knowledge-bases/:id      详情
+PATCH  /api/knowledge-bases/:id      更新
+DELETE /api/knowledge-bases/:id      级联删除（items/chunks/candidates/imports/sources/Qdrant）
+```
+
+**流程四：备份**
+```
+cron 0 3 * * * /opt/zhixi/backup/backup.sh
+  → MySQL dump + Qdrant snapshot → /data/backups/
+  → 本地保留 7 天 + 物理清理（cron 0 4）
+```
+
+### 已建但未端到端对接的模块
+
+| 模块 | 状态 | 缺什么 |
+|------|------|--------|
+| ActiveRecall | controller + worker | 与学习 session 的串联未测试 |
+| AIAnalysis | controller + AiAnalysisWorker + 2 workflows | 同上 |
+| FocusItem | controller + service | 依赖 AIAnalysis 输出 |
+| ReviewCard | controller + workflow | 依赖 FocusItem 触发 |
+| LearningSession | controller + service | 独立可用，缺学习引擎串联 |
+| LearningActivity | heatmap/summary/trend | 数据写入了但从未被查询展示 |
+| Files/COS 上传 | controller + COS SDK | 待 iOS 端真文件触发测试 |
+
+### 待完成（代码级）
+
+| # | 事项 | 说明 |
+|---|------|------|
+| 1 | COS 备份同步 | 每日备份后上传到 COS |
+| 2 | COS 生命周期 | 7 天物理删除策略 |
+| 3 | MySQL 物理清理 | 30 天 deletedAt 清理脚本 |
+| 4 | Docker Compose 统一 | 整理 docker run 为 compose |
+| 5 | logrotate 确认 | 检查轮转配置 |
+
+### 待完成（产品/策略级）
+
+| # | 事项 | 说明 |
+|---|------|------|
+| 6 | 学习引擎串联测试 | ActiveRecall→AIAnalysis→FocusItem→ReviewCard |
+| 7 | iOS 文件上传测试 | COS 真文件上传 + Python Worker 解析 |
+| 8 | Chat session 持久化 | 服务端存储 session + messages |
+| 9 | 知识库设计文档决策表 21/23/24 | COS 同步 + 物理清理 |
 
 ---
 
diff --git a/技术设计/api-server/知识库设计.MD b/技术设计/api-server/知识库设计.MD
index 1cf1b31..1dee02d 100644
--- a/技术设计/api-server/知识库设计.MD
+++ b/技术设计/api-server/知识库设计.MD
@@ -812,7 +812,7 @@ Provider：硅基流动
 
 ---
 
-## 十一、RAG 检索流程（已拍板）✅ indexer.py 已实现，待端到端验证
+## 十一、RAG 检索流程（已拍板）✅ 全链路已验证通过
 
 ```text
 用户提问
@@ -836,19 +836,18 @@ Provider：硅基流动
 第一阶段：
 
 ```text
-保存 chat session + messages：✅
-取最近 3 轮对话拼入 prompt：✅ 少量做
+保存 chat session + messages：✅ 客户端管理，API 接收 history 参数
+取最近 3 轮对话拼入 prompt：✅ 最近 10 条历史注入上下文
 根据历史重写检索 query：❌ 后面再做
 通用 AI 问答（非知识库内容）：❌ 第一阶段不支持
 ```
 
-检索 query 仍使用用户当前原问题，但 prompt 上下文附带最近 3 轮历史。
+检索 query 仍使用用户当前原问题，但 prompt 上下文附带最近多轮历史。API 端点 `POST /api/rag/chat` 接受可选 `history` 参数。
 
 当检索不到相关内容时返回：
 
 ```text
-当前知识库中没有找到足够相关的资料。
-你可以上传更多资料，或换一种问法。
+知识库中暂无相关内容，请先导入文档。
 ```
 
 知习第一阶段只做**基于当前知识库内容的 RAG 问答**，不做纯通用 AI 对话。避免产品定位偏离、增加无意义 token 成本和用户把它当 ChatGPT 用。
@@ -1010,16 +1009,20 @@ knowledge_items.sourceSnippetSnapshot = 原始引用片段
 高级：同时删除该资料生成的知识点
 ```
 
-### 3. 删除整个 KnowledgeBase（与人不同）
+### 3. 删除整个 KnowledgeBase（与人不同）✅ 已实现
 
 ```text
 knowledgeBase.deletedAt = now()
-→ 级联软删该 KB 下所有 sources / chunks / candidates / items / review cards / learning records
-→ Qdrant 标记 deleted = true
-→ COS 异步清理
+→ KnowledgeItems (soft delete)
+→ ImportCandidates (hard delete)
+→ KnowledgeChunks (soft delete)
+→ DocumentImports (status→CANCELLED)
+→ KnowledgeSources (soft delete)
+→ Qdrant vectors (delete by filter)
+→ COS 异步清理（待配）
 ```
 
-用户删除的是整个学习空间，所以级联删除。
+用户删除的是整个学习空间，所以级联删除。`KnowledgeBaseService.remove()` 已实现。
 
 ### 4. 后台物理清理（每日凌晨）
 
@@ -1047,7 +1050,7 @@ AI 成本日志保留 180 天
 
 ---
 
-## 十六、备份与灾备策略（已拍板）⏳ 表已建，备份脚本待写
+## 十六、备份与灾备策略（已拍板）🔶 本地备份完成，COS 同步待配
 
 ### 1. MySQL 备份
 
@@ -1055,39 +1058,25 @@ AI 成本日志保留 180 天
 优先级最高：MySQL > Qdrant > COS
 ```
 
-理由：Qdrant 可重建，COS 有原文件，但 MySQL 丢了业务关系、用户数据、学习记录会非常麻烦。
-
 ```text
-每日凌晨备份 → /data/backups/mysql/zhixi_{yyyy-mm-dd}.sql.gz
-备份后上传 COS → system/backups/mysql/{yyyy-mm-dd}/zhixi.sql.gz
-本地保留 7 天
-COS 保留 30 天
+✅ 每日凌晨 3 点 mysqldump → /data/backups/mysql/zhixi_{yyyy-mm-dd}.sql.gz
+⏳ 备份后上传 COS → system/backups/mysql/{yyyy-mm-dd}/zhixi.sql.gz
+✅ 本地保留 7 天
+⏳ COS 保留 30 天
 ```
 
 ### 2. Qdrant 备份
 
 ```text
-每日凌晨 3 点生成 snapshot → /data/backups/qdrant/
-生成后上传 COS → system/backups/qdrant/{yyyy-mm-dd}/zhixi_chunks.snapshot
-本地保留 7 天
-COS 保留 30 天
+✅ 每日凌晨 3 点生成 snapshot → /data/backups/qdrant/
+⏳ 生成后上传 COS → system/backups/qdrant/{yyyy-mm-dd}/zhixi_chunks.snapshot
+✅ 本地保留 7 天
+⏳ COS 保留 30 天
 ```
 
-### 3. 备份任务记录表
+### 3. 备份脚本
 
-```text
-backup_jobs
-- id
-- type            ← QDRANT / MYSQL
-- status          ← RUNNING / COMPLETED / FAILED
-- localPath
-- cosObjectKey
-- fileSizeBytes
-- startedAt
-- completedAt
-- errorMessage
-- createdAt
-```
+✅ `/opt/zhixi/backup/backup.sh` 已部署，cron `0 3 * * *`，首次手动执行成功（MySQL 8K + Qdrant 284K）。
 
 ### 4. 恢复依赖链
 
@@ -1326,26 +1315,23 @@ source → ImportCandidate → KnowledgeItem
 
 ---
 
-## 二十一、知识库主流程 🔶 索引流程代码完整（import_pipeline.py），待系统跑通
+## 二十一、知识库主流程 ✅ 全链路已验证通过
 
-### 1. 索引流程
+### 1. 索引流程 ✅
 
+测试验证（raw text 导入）✅：
 ```text
-iOS 上传文件到 COS
-→ 后端创建 File（含 sha256 重复检测）
-→ 后端创建 KnowledgeSource
-→ 创建 DocumentImport（status = QUEUED）
-→ Worker claim 任务（QUEUED → CLAIMED）
-→ Worker 从 COS 拉文件到 /data/tmp/imports/{jobId}
-→ 本地解析 / OCR / 多模态
-→ 写入 parsed.md 到 COS
-→ 清洗文本
-→ chunking（512 tokens + 64 overlap）
-→ embedding（bge-m3，batch 50~100）
-→ Qdrant upsert
-→ 保存 KnowledgeChunk 到 MySQL
-→ source.indexStatus = INDEXED
-→ import.status = COMPLETED
+POST /api/imports (raw text)
+→ NestJS DocumentImportWorker 入队 ✅
+→ chunking（512 tokens + 64 overlap）✅ 4 chunks
+→ embedding（bge-m3，batch 50）✅
+→ Qdrant upsert ✅ 4 points
+→ KnowledgeChunk MySQL 写入 ✅
+→ ImportCandidate 生成（DeepSeek）✅ 3 candidates
+→ KB.itemCount 更新 ✅
+→ import.status = COMPLETED ✅
+→ ⬜ COS 文件上传路径（待 iOS 真文件）
+→ ⬜ OCR / 多模态（parser 代码已就，待真文件触发）
 ```
 
 ### 2. 学习流程
@@ -1409,13 +1395,30 @@ OCR / 多模态额度提示
 ## 二十三、执行顺序（状态更新）
 
 ### 第一阶段：服务器基础 ✅ 已完成
-### 第二阶段：基础数据模型 ✅ 已完成（33 张表全部建好）
-### 第三阶段：文件导入闭环 ✅ Worker 已部署运行，polling 正常
-### 第四阶段：RAG 索引 ✅ 代码完成（chunker/embedder/indexer），待端到端验证
-### 第五阶段：AI 学习化 ⏳ ImportCandidate 模块已完成，待端到端
-### 第六阶段：单文件学习 ⏳ 核心模块已建（ActiveRecall/AIAnalysis/FocusItem/Review），待对接
+### 第二阶段：基础数据模型 ✅ 已完成（35 张表全部建好）
+### 第三阶段：文件导入闭环 ✅ NestJS Worker 完整流水线、Python Worker 轮询就绪
+### 第四阶段：RAG 索引 ✅ RAG chat + 多轮对话接口已验证
+### 第五阶段：AI 学习化 ✅ 全链路补齐
+
+NestJS DocumentImportWorker 完整流水线：
+```
+raw text → ChunkingService (512t/64overlap) → VectorService (bge-m3 + Qdrant UUID + MySQL)
+→ ImportCandidate 生成 → KB.itemCount 更新
+```
+验证：4 chunks + 3 candidates + Qdrant 11 points + itemCount=3 ✅
+
+### 第六阶段：单文件学习 🔶 模块已建，待端到端对接
+
+ActiveRecallController / AiAnalysisController / FocusItemsController / ReviewController / LearningSessionController 已全部实现，Workflow 层（active-recall-analysis / feynman-evaluation / learning-trend / review-card-generation）已到位，AiAnalysisWorker 异步处理已就绪。
+
+**缺：** 从 KnowledgeItem → 开始学习 → 主动回忆 → AI 诊断 → 待巩固项 → 复习卡的完整串联流程未跑通过。
+
 ### 第七阶段：知识库增强 ⏳ 待开发
 
+- Chat session 持久化（当前 history 由客户端管理，无服务端 session 存储）
+- 知识库对话 session 列表 API
+- 文件上传 COS 真文件测试（待 iOS 端触发）
+
 ---
 
 ## 二十四、最终落地原则
@@ -1447,26 +1450,26 @@ DeepSeek 负责核心文本智能  → Flash 日常 + thinking 诊断 + Pro 高
 | 6 | Qdrant distance | Cosine | ✅ 已配置 |
 | 7 | Qdrant 部署 | 单节点 Docker，1 shard | ✅ 已部署运行 |
 | 8 | Qdrant 集群时机 | 100 万 points 后评估 | ⏳ 远期 |
-| 9 | Rerank 模型 | BAAI/bge-reranker-v2-m3 | ✅ Key 已配置，代码待写 |
-| 10 | RAG 召回 | Top-50 ANN → rerank → Top-5~8 | ✅ indexer.py 已实现 |
-| 11 | 知识库对话 | 仅限 KB 内检索 | ⏳ 待开发 |
-| 12 | 多轮对话 | 保存 session + 最近 3 轮上下文 | ⏳ 待开发 |
+| 9 | Rerank 模型 | BAAI/bge-reranker-v2-m3 | ✅ reranker.py + RAG chat 已用 |
+| 10 | RAG 召回 | Top-50 ANN → rerank → Top-5~8 | ✅ RAG chat 服务已实现 |
+| 11 | 知识库对话 | 仅限 KB 内检索 | ✅ POST /api/rag/chat |
+| 12 | 多轮对话 | history 参数，客户端管理状态 | ✅ 支持最近 10 条历史 |
 | 13 | 候选知识点数量 | 上限 30，最少 3 | ✅ candidate_generator.py 已实现 |
 | 14 | 自动接受 | 全部 PENDING 等确认 | ✅ ImportCandidate 模块已实现 |
 | 15 | OCR | 百度 OCR + Qwen3-VL | ✅ 百度 OCR AppID 7767914 |
 | 16 | 多模态兜底 | Qwen3-VL-32B-Thinking | ✅ Key 已配置 |
 | 17 | 删除 source → KI | 默认保留 + sourceDeleted 快照 | ✅ Prisma schema 已含 |
-| 18 | 删除 KB → 全对象 | 级联删除 | ⏳ 待实现 |
-| 19 | Qdrant 快照 | 本地 + 同步 COS | ⏳ 备份脚本待写 |
-| 20 | Qdrant 本地快照保留 | 7 天 | ⏳ |
-| 21 | Qdrant COS 快照保留 | 30 天 | ⏳ |
-| 22 | MySQL 备份 | 每日凌晨 + 同步 COS | ⏳ 备份脚本待写 |
-| 23 | COS 文件清理 | soft delete 后 7 天 | ⏳ |
+| 18 | 删除 KB → 全对象 | 级联删除 | ✅ KB Service 已实现 |
+| 19 | Qdrant 快照 | 本地 + 同步 COS | 🔶 本地 cron 已配，COS 同步待配 |
+| 20 | Qdrant 本地快照保留 | 7 天 | ✅ backup.sh |
+| 21 | Qdrant COS 快照保留 | 30 天 | ⏳ COS 同步待配 |
+| 22 | MySQL 备份 | 每日凌晨 + 同步 COS | 🔶 本地完成，COS 同步待配 |
+| 23 | COS 文件清理 | soft delete 后 7 天 | ⏳ COS 生命周期待配 |
 | 24 | MySQL 物理删除 | 默认 30 天 | ⏳ 清理脚本待写 |
 | 25 | AI 成本日志保留 | 180 天 | ✅ AiUsageLog 表已建 |
 | 26 | 审计日志保留 | 365 天 | ✅ AdminAuditLog 表已建 |
 | 27 | Pro 定价 | 28 元/月预设，配置化 | ✅ MembershipPlan 表已建 |
-| 28 | Worker 进程数 | 单 Worker 起步 | ✅ systemd zhixi-worker 运行中 |
+| 28 | Worker 进程数 | 单 Worker 起步 | ✅ systemd zhixi-worker + NestJS BullMQ |
 | 29 | Worker 扩展 | 压力上来后 2~3 个 | ⏳ 远期 |
 | 30 | 文档版本管理 | 预留 version 字段 | ✅ schema 已预留 |
 | 31 | 重复文件 | sha256 检测 + 提示用户 | ✅ UploadedFile sha256 已实现 |
diff --git a/技术设计/webApp-projects/技术栈.md b/技术设计/webApp-projects/技术栈.md
new file mode 100644
index 0000000..c6e2092
--- /dev/null
+++ b/技术设计/webApp-projects/技术栈.md
@@ -0,0 +1,53 @@
+# WebApp（C端知识工作台）技术栈定版
+
+C 端 Web 知识工作台，定位是高体验的学习工具。用户在浏览器里管理知识库、编辑知识点、查看学习进度。
+
+```text
+框架：Vite + React + TypeScript
+UI：shadcn/ui + Tailwind CSS
+编辑器：Tiptap
+路由：React Router
+服务端状态：TanStack Query
+本地状态：Zustand
+API Client：OpenAPI + Orval
+表单：React Hook Form + Zod
+认证：JWT（与 iOS 共享同一套后端）
+部署：4核4G Nginx 静态托管
+```
+
+## 一、为什么用 Vite + React 而不是 Next.js
+
+WebApp 不需要 SSR/SEO。用户登录后才能使用所有功能。Vite 构建产物直接托管到 Nginx。
+
+## 二、为什么用 shadcn/ui
+
+C 端产品需要精致、不臃肿的体验。知识工作台是沉浸式工具，不是表格/表单密集的后台。
+
+## 三、为什么用 Tiptap
+
+基于 ProSeMirror，支持富文本编辑、Markdown 快捷输入、代码块、数学公式、图片拖拽、自定义节点。
+
+## 四、状态管理
+
+| 类型 | 方案 | 用途 |
+|------|------|------|
+| 服务端状态 | TanStack Query | 知识库列表、知识点、学习记录、用户信息 |
+| 本地状态 | Zustand | 侧边栏、编辑器焦点、选中知识点、主题 |
+
+## 五、API
+
+OpenAPI → Orval 生成类型安全 client → TanStack Query hooks
+
+## 六、页面清单
+
+知识库：列表页、详情页、创建页、知识源、导入进度、候选知识点确认
+学习：知识点详情/编辑(Tiptap)、主动回忆、AI分析结果、待巩固项、复习卡片
+个人：设置、会员/额度、学习统计
+
+## 七、部署
+
+4核4G Nginx 静态托管，域名 app.longde.cloud，API 走 api.longde.cloud
+
+## 八、最终拍板
+
+Vite + React + TypeScript + shadcn/ui + Tiptap + React Router + TanStack Query + Zustand + Orval + React Hook Form + Zod
diff --git a/技术设计/待决策事项.md b/技术设计/待决策事项.md
new file mode 100644
index 0000000..12350ba
--- /dev/null
+++ b/技术设计/待决策事项.md
@@ -0,0 +1,112 @@
+# 待决策事项
+
+> 创建日期：2026-05-20 | 需要你拍板的所有事项，按优先级排列
+
+---
+
+## 🔴 产品方向（决定产品形态）
+
+### 1. 学习引擎交互设计
+
+**背景：** ActiveRecall、AIAnalysis、FocusItem、ReviewCard 四个模块代码全部就绪，但从未串联跑过。以下问题需要在串联前确定：
+
+| # | 问题 | 选项 |
+|---|------|------|
+| 1 | 学习会话步骤 | A) 看内容→主动回忆→AI诊断→复习卡（完整流程）/ B) 一次只做一个知识点 / C) 其他 |
+| 2 | 主动回忆交互形式 | A) 简答输入+AI评估 / B) 填空 / C) 口述（语音）|
+| 3 | AI 诊断反馈粒度 | A) 只打分 / B) 详细分析+缺失点+改进建议 / C) 费曼评估 |
+| 4 | 复习卡片触发时机 | A) 每次学完自动生成 / B) 用户手动请求 / C) 按遗忘曲线 |
+| 5 | 竞品参考 | 选 1-2 个学习 App（多邻国/Anki/得到/极客时间？）|
+
+### 2. 第一个垂直知识库方向（S1）
+
+目前没有选定第一批内容方向。候选：
+- 公考申论
+- AI 工具学习
+- 前端面试
+- 其他
+
+### 3. 竞品拆解（S2）
+
+零竞品文档，无法定义差异化。需要选定 3-5 个竞品做分析。
+
+### 4. 知识库技术架构选型（S16）
+
+开源知识库框架（如 Dify/AnythingLLM） vs 自建仿竞品结构。
+
+### 5. MVP 模块裁剪（S4）
+
+代码已远超 MVP 计划，方向确定后应裁剪。哪些模块先不上？
+
+---
+
+## 🟡 产品体验
+
+### 6. 官网登录（W8）
+
+现在就加登录还是等方向确定后？登录后能做什么？
+
+### 7. 官网文案（W9）
+
+面向用户的文字内容（品牌定位、产品描述），不可代劳。
+
+### 8. 产品设计理念（S14） + 文案统一（S15）
+
+产品世界观/价值观/面向用户的 tone & voice。
+
+### 9. Tab 结构调整（I17）
+
+iOS 底部保持 5-Tab 还是合并为 4-Tab？
+
+---
+
+## 🟢 定价与运营
+
+### 10. Pro 定价（B23）
+
+28 元/月是预设，跑 1 个月真实成本后需正式确定。
+
+### 11. 验证退出条件（S6）
+
+没有"什么是验证失败"的定义和时间节点。什么时候判定要 pivot？
+
+### 12. 输入降门槛方案（S7）
+
+用户不愿主动输入是最大风险之一，需缓解策略。
+
+### 13. AI 分析质量验收标准（S8）
+
+没有产品侧的 AI 效果验收机制。什么算"AI 分析质量合格"？
+
+### 14. 真实用户获取（S10）
+
+等待名单未真正跑过获客流程。
+
+### 15. 隐私政策合规（S12）
+
+当前为 AI 生成模板，App Store 审核可能被拒。
+
+---
+
+## ⚪ 远期
+
+### 16. Dify 部署
+
+第一阶段不部署。后续如需实验，放 8核32G sandbox profile。
+
+### 17. n8n / agent runner
+
+4核4G 上可部署，用于营销自动化。
+
+---
+
+## 决策统计
+
+| 优先级 | 数量 | 说明 |
+|--------|------|------|
+| 🔴 | 5 | 产品方向，决定 MVP 形态 |
+| 🟡 | 4 | 产品体验，影响用户感知 |
+| 🟢 | 6 | 定价/运营/合规 |
+| ⚪ | 2 | 远期 |
+
+**总共 17 项待决策。**
diff --git a/技术设计/总待完成清单.md b/技术设计/总待完成清单.md
index b89b970..c47da78 100644
--- a/技术设计/总待完成清单.md
+++ b/技术设计/总待完成清单.md
@@ -32,18 +32,22 @@
 
 > 详细文档：[后端开发路线图](./api-server/后端开发路线图.md) | [进行中](./api-server/进行中.md) | [已完成清单](./api-server/已完成/[已完成]-后端待完成事项清单.md)
 
-### 🟠 P1 — AI 工作流
+### 🟢 P1 — AI 工作流 ✅
 
 | # | 事项 | 说明 | 详见 | 决策 |
 |---|------|------|------|------|
-| B11 | AI 联调 + Prompt 调优 | DeepSeek/MiniMax 真实调用测试，Prompt 迭代 | [AI架构设计](./api-server/AI架构设计.md) | 🟢 |
+| B11 | ✅ 知识库导入全链路 | rawText→AI 提取→Embedding→Qdrant→RAG 对话 | 工作日志 5/20 | 🟢 |
+| B12 | ✅ RAG 对话接口 | POST /api/rag/chat，检索→rerank→DeepSeek+citations | 工作日志 5/20 | 🟢 |
+| B14 | ✅ 知识库级联删除 | KB→Sources→Chunks→Qdrant 全链路清理 | 工作日志 5/20 | 🟢 |
+| B15 | ✅ 多轮对话 | RAG chat 支持 history 参数，上下文注入 | 工作日志 5/20 | 🟢 |
 
-### 🟡 P2 — iOS 接口对齐
+### 🟡 P2 — 待调优
 
 | # | 事项 | 说明 | 详见 | 决策 |
 |---|------|------|------|------|
+| B13 | AI 提取 Prompt 调优 | 5 知识点 content 完全相同，待真文档后调 | 工作日志 5/20 | 🟢 |
 | B28 | iOS 接口缺口审计 | 逐页面对比现有 API，列出缺接口/缺字段清单 | [进行中](./api-server/进行中.md) | 🔵 |
-| B29 | 知识库存储架构 | COS 路径规范、图片/PDF 解析 pipeline 设计 | [进行中](./api-server/进行中.md) | 🔵 |
+| B29 | 知识库存储架构 | COS 路径规范、图片/PDF 解析 pipeline | [进行中](./api-server/进行中.md) | 🔵 |
 
 ### ⚪ 远期 — 商业化/后台/客服