docs: 更新总待完成清单 — iOS P2 动效/无障碍完成，COS 接入完成

- I12 动效补充 ✅
- I13 无障碍基础适配 ✅
- B16/B17/B19 COS 对象存储接入 ✅
- 移除 iOS CI/CD 项（Apple 项目本地编译发布）
- 更新执行顺序建议

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

README.md

@@ -7,105 +7,80 @@
 ## 目录结构
 
 ```
-├── 技术设计/      系统怎么建（按项目分文件夹）
+├── 技术设计/      系统设计 + 开发计划（已合并）
-├── 开发计划/      先做什么后做什么（按项目分文件夹）
 ├── 长期规划/      为什么做、给谁做
 ├── 凭据配置/      服务器密码和密钥（已 gitignore）
 └── 图片资源/      产品图片
 ```
 
-### 状态标识说明
-
-| 前缀 | 含义 | 适用场景 |
-|------|------|----------|
-| `[已完成]` | 设计已落实到代码，功能可运行 | 技术设计文档 |
-| `[进行中]` | 部分实现/持续更新中 | 技术设计 + 开发计划 |
-| `[设计中]` | 纯设计文档，尚未开始实现 | 技术设计文档 |
-| `[参考]` | 静态参考文档，内容不再变动 | 需求基线等 |
-| `[快照]` | 一次性审计快照，记录某个时间点的状态 | 差距分析等 |
-
 ---
 
 ## 技术设计
 
 ### api-server（后端）
 
-| 文档 | 说明 |
+**设计与规划：**
-|------|------|
-| [进行中-架构总览](技术设计/api-server/[进行中]-架构总览.md) | 模块化单体架构、技术栈、目录结构、14个业务模块、API路由规划、数据模型（模块骨架存在，队列/AI异步未完成） |
-| [进行中-Redis缓存设计](技术设计/api-server/[进行中]-Redis缓存设计.md) | 缓存/队列/限流设计，Redis 已连接，BullMQ 队列待替换内存队列 |
-| [设计中-AI架构设计](技术设计/api-server/[设计中]-AI架构设计.md) | AI Provider 抽象、四层模型策略、Agent 演进路线 V0-V3 |
-
-#### 已完成
 
 | 文档 | 说明 |
 |------|------|
-| [数据库设计](技术设计/api-server/已完成/[已完成]-数据库设计.md) | 27 张表完整设计，Prisma schema 已落地，MySQL 运行中 |
+| [架构总览](技术设计/api-server/架构总览.md) | 模块化单体架构、技术栈、目录结构、14个业务模块、API路由规划、数据模型 |
-| [安全规范](技术设计/api-server/已完成/[已完成]-安全规范.md) | 安全基线：Helmet、CORS、JWT Guard、参数校验、限流、Swagger保护 |
+| [后端开发路线图](技术设计/api-server/后端开发路线图.md) | 51 模块 14 层级总表 + 8 阶段开发路线 + 每个模块接口/表结构/流程详案 |
-| [登录流程-总览](技术设计/api-server/已完成/[已完成]-登录流程/总览.md) | 登录系统整体设计：前后端职责、Token 策略、5 个 API 接口规划 |
+| [后端待完成事项清单](技术设计/api-server/后端待完成事项清单.md) | 当前待推进的详细任务 |
-| [登录流程-Apple登录集成](技术设计/api-server/已完成/[已完成]-登录流程/Apple登录集成.md) | Sign in with Apple 后端实现：jose 验签、JWKS、字段信任模型 |
+| [AI架构设计](技术设计/api-server/AI架构设计.md) | AI Provider 抽象、四层模型策略、Agent 演进路线 V0-V3 |
-| [登录流程-后端接口](技术设计/api-server/已完成/[已完成]-登录流程/后端接口.md) | dev-login / refresh / logout / /users/me 四个接口的详细实现 |
+| [Redis缓存设计](技术设计/api-server/Redis缓存设计.md) | 缓存/队列/限流设计 |
-| [登录流程-数据库设计](技术设计/api-server/已完成/[已完成]-登录流程/数据库设计.md) | users / auth_accounts / refresh_tokens 三表 Prisma Schema |
+
+**已完成：**
+
+| 文档 | 说明 |
+|------|------|
+| [已实现功能汇总](技术设计/api-server/已完成/[已完成]-已实现功能汇总.md) | 全部已完成功能一览：基础设施、14 模块、AI 三层架构、安全基线 |
+| [后端实现状态](技术设计/api-server/已完成/[已完成]-后端实现状态.md) | 各模块完成度 + 基础设施状态 + 待推进方向 |
+| [数据库设计](技术设计/api-server/已完成/[已完成]-数据库设计.md) | 27 张表完整设计，Prisma schema 已落地 |
+| [安全规范](技术设计/api-server/已完成/[已完成]-安全规范.md) | 安全基线：Helmet、CORS、JWT Guard、RolesGuard、参数校验、限流 |
+| [当前状态与决策清单](技术设计/api-server/已完成/[已完成]-当前状态与决策清单.md) | 技术决策与当前状态记录 |
+| [AI架构决策清单](技术设计/api-server/已完成/[已完成]-AI架构决策清单.md) | AI 层具体决策记录 |
+| [登录流程/总览](技术设计/api-server/已完成/[已完成]-登录流程/总览.md) | 登录系统整体设计 |
+| [登录流程/Apple登录集成](技术设计/api-server/已完成/[已完成]-登录流程/Apple登录集成.md) | Sign in with Apple 后端实现 |
+| [登录流程/后端接口](技术设计/api-server/已完成/[已完成]-登录流程/后端接口.md) | 登录相关接口实现 |
+| [登录流程/数据库设计](技术设计/api-server/已完成/[已完成]-登录流程/数据库设计.md) | 登录相关表设计 |
 
 ### ios-projects（iOS 客户端）
 
-| 文档 | 说明 |
+**设计与规划：**
-|------|------|
-| [进行中-架构设计](技术设计/ios-projects/[进行中]-架构设计.md) | 当前项目文件结构、导航架构、与计划架构的差异表（28项未实现），UI 层完成但无 MVVM |
-| [设计中-登录集成](技术设计/ios-projects/[设计中]-登录集成.md) | iOS 端登录设计：AuthService、Keychain 存储、Token 自动刷新、401 重试，均未实现 |
-| [样式规范](技术设计/ios-projects/已完成/[已完成]-样式规范.md) | 完整设计系统：颜色、渐变、圆角、间距、字体、29 个共享组件、页面模板 |
-| [页面规划](技术设计/ios-projects/已完成/[已完成]-页面规划.md) | 22 个页面完整清单，UI 层全部实现（Onboarding 5页 + 主Tab 5页 + 子页12页） |
-
-### web-projects（官网）
 
 | 文档 | 说明 |
 |------|------|
-| [设计中-设计文档](技术设计/web-projects/[设计中]-设计文档.md) | 官网视觉设计系统："Luminous Clarity" 玻璃拟态浅色主题 |
+| [架构设计](技术设计/ios-projects/架构设计.md) | 项目文件结构、导航架构、差异表 |
+| [登录集成](技术设计/ios-projects/登录集成.md) | AuthService、Keychain 存储、Token 刷新 |
+| [功能需求清单](技术设计/ios-projects/功能需求清单.md) | iOS 功能需求基线 |
+| [缺失项与待补全方向](技术设计/ios-projects/缺失项与待补全方向.md) | 架构/页面/功能缺失项梳理 |
 
-### miniapp-projects（微信小程序）
+**已完成：**
 
-> 暂无文档，预留目录。
+| 文档 | 说明 |
-
+|------|------|
-### harmonyos-projects（鸿蒙）
+| [已实现功能汇总](技术设计/ios-projects/已完成/[已完成]-已实现功能汇总.md) | 全部已完成功能一览：架构层、22 页面、Auth、设计系统、代码质量 |
-
+| [样式规范](技术设计/ios-projects/已完成/[已完成]-样式规范.md) | 完整设计系统：颜色、渐变、圆角、间距、字体、29 个共享组件 |
-> 暂无文档，预留目录。
+| [页面规划](技术设计/ios-projects/已完成/[已完成]-页面规划.md) | 22 个页面完整清单 |
-
+| [差距分析](技术设计/ios-projects/已完成/[已完成]-差距分析.md) | 现有资源盘点 + P0 任务分解 |
-### admin-projects（后台管理）
-
-> 暂无文档，预留目录。
-
-### android-projects / webApp-projects
-
-> 暂无文档，预留目录。
-
----
-
-## 开发计划
 
 ### 跨项目
 
 | 文档 | 说明 |
 |------|------|
-| [进行中-阶段路线图](开发计划/[进行中]-阶段路线图.md) | 产品 9 阶段整体路线。阶段0官网部分已完成，阶段1方向选择进行中 |
+| [总待完成清单](技术设计/总待完成清单.md) | **← 主文件**：后端/iOS/策略所有待完成事项，按优先级排列，链接到各详细文档 |
-| [进行中-潜在问题清单](开发计划/[进行中]-潜在问题清单.md) | 代码和策略中已发现问题，按🔴严重/🟠高危/🟡中危分级，持续更新（最新：2026-05-15） |
+| [阶段路线图](技术设计/阶段路线图.md) | 产品 9 阶段整体路线 |
+| [潜在问题清单](技术设计/潜在问题清单.md) | 按🔴严重/🟠高危/🟡中危分级，持续更新 |
 
-### api-server
+### web-projects（官网）
 
 | 文档 | 说明 |
 |------|------|
-| [进行中-后端开发优先级](开发计划/api-server/[进行中]-后端开发优先级.md) | 51 模块 14 层级总表 + 8 阶段开发路线 + 每个模块接口/表结构/流程详案 |
+| [设计文档](技术设计/web-projects/设计文档.md) | 官网视觉设计系统："Luminous Clarity" 玻璃拟态浅色主题 |
 
-### ios-projects
+### 预留目录
 
-| 文档 | 说明 |
+`miniapp-projects` `harmonyos-projects` `admin-projects` `android-projects` `webApp-projects` — 暂无文档。
-|------|------|
-| [参考-功能需求清单](开发计划/ios-projects/[参考]-功能需求清单.md) | 从 v0.1 创业计划提取的 iOS 功能需求基线 |
-| [进行中-缺失项与待补全方向](开发计划/ios-projects/[进行中]-缺失项与待补全方向.md) | iOS 架构/页面/功能/设计缺失项梳理，含 P0/P1/P2 优先级 |
-| [差距分析](开发计划/ios-projects/已完成/[已完成]-差距分析.md) | 两轮审计快照合并：现有资源盘点 + P0 任务分解 |
-
-### web-projects / android-projects / webApp-projects
-
-> 暂无开发计划文档，预留目录。
 
 ---
 
@@ -154,15 +129,19 @@
 
 | 我想知道... | 看这个 |
 |-------------|--------|
-| 后端整体怎么设计？ | [技术设计/api-server/架构总览](技术设计/api-server/[进行中]-架构总览.md) |
+| **现在该做什么？** | [**总待完成清单**](技术设计/总待完成清单.md) |
-| 数据库有哪些表？ | [技术设计/api-server/数据库设计](技术设计/api-server/已完成/[已完成]-数据库设计.md) |
+| 后端整体怎么设计？ | [架构总览](技术设计/api-server/架构总览.md) |
-| 登录怎么做？ | [技术设计/api-server/登录流程/总览](技术设计/api-server/已完成/[已完成]-登录流程/总览.md) |
+| 后端完成了哪些功能？ | [已实现功能汇总](技术设计/api-server/已完成/[已完成]-已实现功能汇总.md) |
-| iOS App 架构？ | [技术设计/ios-projects/架构设计](技术设计/ios-projects/[进行中]-架构设计.md) |
+| 后端实现到什么程度了？ | [后端实现状态](技术设计/api-server/已完成/[已完成]-后端实现状态.md) |
-| 接下来做什么？ | [开发计划/阶段路线图](开发计划/[进行中]-阶段路线图.md) |
+| 后端先开发哪些？ | [后端开发路线图](技术设计/api-server/后端开发路线图.md) |
-| 后端先开发哪些？ | [开发计划/api-server/后端开发优先级](开发计划/api-server/[进行中]-后端开发优先级.md) |
+| 数据库有哪些表？ | [数据库设计](技术设计/api-server/已完成/[已完成]-数据库设计.md) |
-| iOS 还差什么？ | [开发计划/ios-projects/缺失项与待补全方向](开发计划/ios-projects/[进行中]-缺失项与待补全方向.md) |
+| 登录怎么做？ | [登录流程/总览](技术设计/api-server/已完成/[已完成]-登录流程/总览.md) |
-| 有哪些已知问题？ | [开发计划/潜在问题清单](开发计划/[进行中]-潜在问题清单.md) |
+| iOS 完成了哪些功能？ | [已实现功能汇总](技术设计/ios-projects/已完成/[已完成]-已实现功能汇总.md) |
-| 产品方向怎么定的？ | [长期规划/产品方向深度评估](长期规划/[参考]-产品方向深度评估.md) |
+| iOS App 架构？ | [iOS架构设计](技术设计/ios-projects/架构设计.md) |
-| 怎么收费？ | [长期规划/商业化与支付模块](长期规划/[进行中]-商业化与支付模块.md) |
+| iOS 还差什么？ | [缺失项与待补全方向](技术设计/ios-projects/缺失项与待补全方向.md) |
-| 怎么获客？ | [长期规划/营销与增长/营销冷启动调研方案](长期规划/营销与增长/[参考]-营销冷启动调研方案.md) |
+| 接下来做什么？ | [阶段路线图](技术设计/阶段路线图.md) |
-| 服务器密码、SSH密钥？ | [凭据配置/服务器凭据](凭据配置/服务器凭据.md) |
+| 有哪些已知问题？ | [潜在问题清单](技术设计/潜在问题清单.md) |
+| 产品方向怎么定的？ | [产品方向深度评估](长期规划/[参考]-产品方向深度评估.md) |
+| 怎么收费？ | [商业化与支付模块](长期规划/[进行中]-商业化与支付模块.md) |
+| 怎么获客？ | [营销冷启动调研方案](长期规划/营销与增长/[参考]-营销冷启动调研方案.md) |
+| 服务器密码、SSH密钥？ | [服务器凭据](凭据配置/服务器凭据.md) |

开发计划/api-server/[进行中]-后端待完成事项清单.md

@@ -1,617 +0,0 @@
-# 知习后端待完成事项清单
-
-> 按业务开发顺序排列。**2026-05-16 更新：AI 基础设施完成，12 个 Repository 全部迁到 Prisma。**
-
----
-
-## 1. 登录 / 认证模块 Auth
-
-这是第一优先级。因为后面所有数据都要绑定 `userId`。
-
-### 要做的接口
-
-```text
-POST /api/auth/dev-login
-POST /api/auth/apple
-POST /api/auth/refresh
-POST /api/auth/logout
-GET  /api/users/me
-PATCH /api/users/me
-```
-
-### 第一阶段先做
-
-```text
-POST /api/auth/dev-login
-POST /api/auth/refresh
-GET  /api/users/me
-```
-
-Apple 登录可以随后接入，但后端结构要先预留。
-
-### 需要的表
-
-```text
-users
-auth_accounts
-refresh_tokens
-```
-
-### 核心逻辑
-
-```text
-dev-login 创建 / 查找用户
-生成 accessToken
-生成 refreshToken
-refreshToken hash 入库
-/users/me 返回当前用户
-refresh 接口刷新 token
-logout 撤销 refreshToken
-```
-
-### Apple 登录需要什么
-
-后端不需要 iOS 证书，只需要：
-
-```text
-APPLE_BUNDLE_ID=cloud.longde.AIStudyApp
-APPLE_ISSUER=https://appleid.apple.com
-APPLE_JWKS_URL=https://appleid.apple.com/auth/keys
-```
-
-Apple 登录接口核心参数：
-
-```json
-{
-  "identityToken": "eyJ..."
-}
-```
-
-可选参数：
-
-```json
-{
-  "authorizationCode": "...",
-  "userIdentifier": "...",
-  "email": "...",
-  "fullName": {
-    "givenName": "...",
-    "familyName": "..."
-  }
-}
-```
-
----
-
-## 2. 权限系统 Permission
-
-登录后马上要做最小权限。
-
-### 第一版权限规则
-
-```text
-普通用户只能访问自己的资源
-所有用户资源必须校验 userId
-普通用户不能访问 /api/admin/*
-知识库默认 PRIVATE
-创建知识库的人就是 owner
-```
-
-### 平台角色
-
-```text
-USER
-ADMIN
-SUPER_ADMIN
-```
-
-### 后期资源角色
-
-```text
-OWNER
-EDITOR
-VIEWER
-```
-
-第一版可以先不做协作者，只做：
-
-```text
-knowledgeBase.userId === currentUser.id
-```
-
----
-
-## 3. 用户模块 Users
-
-### 接口
-
-```text
-GET   /api/users/me
-PATCH /api/users/me
-DELETE /api/users/me
-```
-
-### 字段
-
-```text
-id
-email
-nickname
-avatarUrl
-role
-status
-onboardingCompleted
-createdAt
-updatedAt
-```
-
-这个模块服务于：
-
-```text
-App 启动恢复登录态
-我的页
-会员权益
-学习统计
-后台用户管理
-```
-
----
-
-## 4. 知识库模块 KnowledgeBase
-
-登录通了以后做知识库。
-
-### 接口
-
-```text
-GET    /api/knowledge-bases
-POST   /api/knowledge-bases
-GET    /api/knowledge-bases/:id
-PATCH  /api/knowledge-bases/:id
-DELETE /api/knowledge-bases/:id
-```
-
-### 字段
-
-```text
-id
-userId
-title
-description
-coverColor
-visibility
-status
-itemCount
-createdAt
-updatedAt
-deletedAt
-```
-
-### 第一版规则
-
-```text
-默认 PRIVATE
-只允许用户操作自己的知识库
-暂时不做公开、分享、协作者
-```
-
----
-
-## 5. 知识点模块 KnowledgeItem
-
-### 接口
-
-```text
-GET    /api/knowledge-bases/:knowledgeBaseId/items
-POST   /api/knowledge-bases/:knowledgeBaseId/items
-GET    /api/knowledge-items/:id
-PATCH  /api/knowledge-items/:id
-DELETE /api/knowledge-items/:id
-```
-
-### 字段
-
-```text
-id
-userId
-knowledgeBaseId
-title
-content
-summary
-tags
-sourceType
-masteryLevel
-createdAt
-updatedAt
-deletedAt
-```
-
-第一版先支持：
-
-```text
-手动创建知识点
-手动编辑知识点
-```
-
-不要一开始做 PDF 解析和 AI 自动拆分。
-
----
-
-## 6. 学习会话模块 LearningSession
-
-表示一次学习过程。
-
-### 接口
-
-```text
-POST /api/learning-sessions
-GET  /api/learning-sessions/:id
-POST /api/learning-sessions/:id/complete
-```
-
-### 字段
-
-```text
-id
-userId
-knowledgeBaseId
-status
-startedAt
-completedAt
-durationSeconds
-createdAt
-updatedAt
-```
-
----
-
-## 7. 主动回忆模块 ActiveRecall
-
-这是用户主动输出的核心。
-
-### 接口
-
-```text
-POST /api/active-recall/answers
-GET  /api/active-recall/answers/:id
-GET  /api/knowledge-items/:id/active-recall/answers
-```
-
-### 字段
-
-```text
-id
-userId
-knowledgeItemId
-learningSessionId
-mode
-answerText
-durationSeconds
-createdAt
-```
-
-`mode` 预留：
-
-```text
-ACTIVE_RECALL
-FEYNMAN
-RETRIEVAL_PRACTICE
-```
-
----
-
-## 8. AI 分析模块 AIAnalysis
-
-这是知习核心差异化模块。
-
-### 接口
-
-```text
-POST /api/ai-analysis/active-recall
-GET  /api/ai-analysis/:id
-GET  /api/active-recall/answers/:answerId/analysis
-```
-
-### 字段
-
-```text
-id
-userId
-knowledgeItemId
-activeRecallAnswerId
-score
-masteryLevel
-summary
-strengths
-weaknesses
-missingKeyPoints
-misconceptions
-rawResult
-promptVersion
-model
-createdAt
-```
-
-### 输出结构示例
-
-```json
-{
-  "score": 72,
-  "masteryLevel": "partial",
-  "summary": "用户理解了核心定义，但缺少应用场景。",
-  "missingKeyPoints": [],
-  "misconceptions": [],
-  "focusItems": [],
-  "reviewSuggestion": {
-    "shouldReview": true,
-    "intervalDays": 2
-  }
-}
-```
-
----
-
-## 9. 待巩固项模块 FocusItem
-
-AI 分析后生成的薄弱点。
-
-### 接口
-
-```text
-GET   /api/focus-items
-GET   /api/focus-items/today
-GET   /api/focus-items/:id
-PATCH /api/focus-items/:id
-```
-
-### 字段
-
-```text
-id
-userId
-knowledgeBaseId
-knowledgeItemId
-aiAnalysisId
-title
-description
-reason
-priority
-status
-createdAt
-resolvedAt
-```
-
-### 状态
-
-```text
-OPEN
-REVIEWING
-RESOLVED
-DISMISSED
-```
-
----
-
-## 10. 复习模块 Review
-
-### 接口
-
-```text
-GET  /api/reviews/due
-GET  /api/reviews/cards/:id
-POST /api/reviews/cards/:id/answer
-POST /api/reviews/cards/:id/skip
-```
-
-### 表
-
-```text
-review_cards
-review_attempts
-```
-
-第一版复习算法可以简单：
-
-```text
-薄弱 → 1 天后
-一般 → 3 天后
-掌握 → 7 天后
-```
-
----
-
-## 11. 学习活跃模块 LearningActivity
-
-### 接口
-
-```text
-GET  /api/learning-activity/summary
-GET  /api/learning-activity/daily
-POST /api/learning-activity/events
-```
-
-### 事件
-
-```text
-KNOWLEDGE_BASE_CREATED
-KNOWLEDGE_ITEM_CREATED
-LEARNING_SESSION_STARTED
-ACTIVE_RECALL_SUBMITTED
-AI_ANALYSIS_COMPLETED
-FOCUS_ITEM_CREATED
-REVIEW_CARD_CREATED
-REVIEW_COMPLETED
-LEARNING_SESSION_COMPLETED
-```
-
-用于：
-
-```text
-连续学习天数
-最近 7 天学习趋势
-分析首页
-我的页统计
-```
-
----
-
-## 12. AI 基础设施模块 ✅ 已完成
-
-包括：
-
-```text
-✅ AIGateway       — AiGatewayService（统一入口、选模型、JSON容错、超时重试）
-✅ PromptTemplate  — PromptTemplateService（key + version 注册）
-✅ AIUsageLog      — AiUsageLogService + AiCostCalculatorService
-✅ AIWorkflow      — ActiveRecallAnalysisWorkflow（第一个 Workflow）
-⏳ AIQuota         — 待实现
-```
-
-### 已完成文件
-
-```text
-src/modules/ai/
-├── ai.module.ts
-├── ai.controller.ts                        
-├── model-router.ts                         
-├── gateway/ai-gateway.service.ts           
-├── gateway/ai-gateway.types.ts             
-├── providers/ai-provider.interface.ts      
-├── providers/mock-ai.provider.ts           
-├── providers/deepseek.provider.ts          
-├── providers/minimax.provider.ts           
-├── prompts/prompt-template.service.ts      
-├── prompts/active-recall-analysis.prompt.ts
-├── prompts/schemas/active-recall-analysis.schema.ts
-├── usage/ai-cost-calculator.service.ts     
-├── usage/ai-usage-log.service.ts           
-└── workflows/active-recall-analysis.workflow.ts
-```
-
-### 数据库
-
-```text
-✅ AiUsageLog 模型已加入 prisma schema
-⚠️ db push 待 SSH 隧道连通
-```
-
-### 旧代码已清理
-
-```text
-❌ src/infrastructure/ai/  已删除
-✅ ai-analysis 模块已改用新 AiGatewayService
-✅ active-recall 模块提交答案自动触发分析
-```
-
----
-
-## 13. Repository 迁移 Map → Prisma ✅ 全部完成
-
-> **2026-05-16**：12 个业务 repository 全部从 `Map<string, T>` / `Array<T>` 迁到 Prisma。
-
-| 批次 | 模块 | Repository | 备注 |
-|------|------|-----------|------|
-| 第 1 批 | KnowledgeBase / KnowledgeItems | ✅ Prisma | 核心知识体系 |
-| 第 2 批 | ActiveRecall / LearningSession / AiAnalysis / FocusItems | ✅ Prisma | 学习闭环主干 |
-| 第 3 批 | Review / LearningActivity | ✅ Prisma | 复习和统计 |
-| 第 4 批 | DocumentImport / Notifications / Waitlist / Feedback | ✅ Prisma | 辅助模块 |
-
-### 改动范围
-
-```text
-12 个 repository 重写（注入 PrismaService、删除 Map/Array、删除 generateShortId）
-5 个 service 微调（方法加 userId 参数）
-4 个 controller 加 @CurrentUser()（FocusItems / Review / LearningActivity / Notifications）
-1 个 Prisma schema 新增模型（WaitlistEntry）
-```
-
-### 统一变更
-
-```text
-- 删除所有 generateShortId() 调用，改用 Prisma @default(cuid())
-- 删除所有 OnModuleInit 种子假数据
-- 所有查询方法加 userId 过滤
-- 复杂字段（数组/对象）存 Prisma Json 字段
-```
-
-这个后面会支撑：
-
-```text
-AI 成本计算
-会员额度
-后台成本看板
-模型切换
-```
-
----
-
-# 后端阶段顺序（已完成标记 ✅）
-
-```text
-✅ 阶段 1：登录和身份（已完成）
-  ✅ Auth（dev-login / apple / refresh / logout）
-  ✅ Users（/users/me + UsersRepository 唯一接 Prisma）
-  ✅ Permission（JwtAuthGuard 已全局注册）
-
-✅ 阶段 2：知识系统（数据库层已完成）
-  ✅ KnowledgeBase → Prisma
-  ✅ KnowledgeItem → Prisma
-  ⏳ 知识导入 Workflow
-
-✅ 阶段 3：学习闭环（数据库层已完成）
-  ✅ LearningSession → Prisma
-  ✅ ActiveRecall → Prisma（提交答案自动触发 AI 分析）
-  ✅ AiAnalysis → Prisma（ActiveRecallAnalysisWorkflow）
-  ✅ FocusItem → Prisma
-  ✅ Review → Prisma
-  ✅ LearningActivity → Prisma
-
-✅ 阶段 4：AI 基础设施（已完成）
-  ✅ AIGateway（三层容错 + 超时重试）
-  ✅ PromptTemplate（key + version）
-  ✅ AIUsageLog + CostCalculator
-  ✅ ActiveRecallAnalysisWorkflow
-  ✅ AiModule（15 文件三层架构）
-  ⏳ AIQuota（待实现）
-
-✅ 阶段 5：文件导入（数据库层已完成）
-  ✅ DocumentImport → Prisma
-  ⏳ Files / Storage 真实接入
-  ⏳ KnowledgeGeneration Workflow
-
-⏳ 阶段 6：商业化（未开始）
-  Plans / Membership / Subscription / UsageLimit
-
-⏳ 阶段 7：后台和运营（部分完成）
-  ✅ Feedback → Prisma
-  ✅ Waitlist → Prisma
-  ✅ Notifications → Prisma
-  ⏳ Admin / AI Cost Dashboard / Audit Logs
-
-⏳ 阶段 8：客服和帮助中心（未开始）
-  SupportTicket / Dify / HelpCenter
-```
-
----
-
-# 当前最应该推进的 TODO
-
-```text
-✅  1. 建 users / auth_accounts / refresh_tokens 表
-✅  2. 做 POST /api/auth/dev-login
-✅  3. 做 TokenService：accessToken / refreshToken
-✅  4. 做 POST /api/auth/refresh
-✅  5. 做 JwtAuthGuard
-✅  6. 做 CurrentUser 装饰器
-✅  7. 做 GET /api/users/me
-✅  8. 12 个 Repository Map → Prisma
-✅  9. AI 三层架构落地（Provider → Gateway → Workflow）
-✅ 10. 接 POST /api/auth/apple
-✅ 11. 全局 JwtAuthGuard（所有 controller）
-	✅ 12. Swagger 文档端点 Basic Auth 保护（/api-docs + /api-docs-json）
-	✅ 13. DNS 从 Cloudflare 迁到 DNSPod（腾讯云），国内访问 1.5s → 50ms
-	✅ 14. 服务器 iptables 放行 80/443 公网直连
-⏳ 15. 更多 AI Workflow（知识导入、费曼分析、复习卡片生成）
-⏳ 16. AI 联调 + Prompt 调优
-⏳ 17. iOS 集成
-```

技术设计/api-server/AI架构设计.md

@@ -2,9 +2,14 @@
 
 > **设计方向文档。**
 > 
-> **实现状态**：阶段 0 全部完成，三层架构（Provider → Gateway → Workflow）已落地。详见 [[已完成]-AI架构决策清单.md](./[已完成]-AI架构决策清单.md)
+> **实现状态（2026-05-17）**：
+> - ✅ 三层架构落地：Provider（DeepSeek + MiniMax + Mock）→ Gateway → Workflow
+> - ✅ AI Gateway 完整实现（多模型路由、重试、成本计算、JSON 解析三层回退）
+> - ✅ 1 个 Workflow 完成：主动回忆分析（ActiveRecallAnalysisWorkflow）
+> - 🔶 待实现 Workflow：知识导入解析、费曼解释评估、复习卡片生成、长期趋势分析
+> - ✅ AI Usage Logging + Cost Calculation 已接入
 > 
-> **最后更新**：2026-05-16
+> **最后更新**：2026-05-17
 
 ## 一、核心原则
 

技术设计/api-server/后端开发路线图.md

@@ -7,57 +7,57 @@
 
 ## 总优先级总表
 
-| 优先级 | 层级 | 核心模块 |
+| 优先级 | 层级 | 核心模块 | 状态 |
-|--------|------|----------|
+|--------|------|----------|------|
-| P0 | 后端地基 | 安全配置、数据库(Prisma+MySQL)、统一工程规范(响应/错误/DTO/Guard) |
+| P0 | 后端地基 | 安全配置、数据库(Prisma+MySQL)、统一工程规范(响应/错误/DTO/Guard) | ✅ |
-| P1 | 身份权限 | Auth(Apple/Refresh/Logout)、Users、Role、Resource Permission |
+| P1 | 身份权限 | Auth(Apple/Refresh/Logout)、Users、Role、Resource Permission | ✅ |
-| P2 | 知识系统 | KnowledgeBase、KnowledgeItem、Tag、Search |
+| P2 | 知识系统 | KnowledgeBase、KnowledgeItem、Tag、Search | ✅（Tag/Search 待补） |
-| P3 | 学习闭环 | LearningSession、ActiveRecall、AIAnalysis、FocusItem、Review、LearningActivity |
+| P3 | 学习闭环 | LearningSession、ActiveRecall、AIAnalysis、FocusItem、Review、LearningActivity | ✅ |
-| P4 | AI 基础设施 | AIGateway、PromptTemplate、AIUsageLog、AIQuota、AIWorkflow |
+| P4 | AI 基础设施 | AIGateway、PromptTemplate、AIUsageLog、AIQuota、AIWorkflow | 🔶 1/5 Workflow |
-| P5 | 文件导入 | File/Storage、DocumentImport、KnowledgeGeneration |
+| P5 | 文件导入 | File/Storage、DocumentImport、KnowledgeGeneration | 🔶 DB 层完成 |
-| P6 | 商业化 | Plans、Membership、Subscription(Apple IAP)、Payment、Refund |
+| P6 | 商业化 | Plans、Membership、Subscription(Apple IAP)、Payment、Refund | ⏳ |
-| P7 | 用户 Web 后台 | Web Console、批量上传/导入/导出 |
+| P7 | 用户 Web 后台 | Web Console、批量上传/导入/导出 | ⏳ |
-| P8 | 管理员后台 | Admin Users、Admin Knowledge、AI Cost、Feedback、Audit Log |
+| P8 | 管理员后台 | Admin Users、Admin Knowledge、AI Cost、Feedback、Audit Log | ⏳ |
-| P9 | 客服反馈 | Feedback、SupportTicket、Dify 智能客服、HelpCenter |
+| P9 | 客服反馈 | Feedback、SupportTicket、Dify 智能客服、HelpCenter | 🔶 Feedback ✅ |
-| P10 | 通知任务 | Notifications、Push(APNs)、BullMQ Worker、Scheduler |
+| P10 | 通知任务 | Notifications、Push(APNs)、BullMQ Worker、Scheduler | 🔶 Notifications ✅ |
-| P11 | 学习画像 | LearningAnalytics、UserLearningProfile、LearningReport |
+| P11 | 学习画像 | LearningAnalytics、UserLearningProfile、LearningReport | ⏳ |
-| P12 | 公开分享 | Visibility、ShareLink、Public Knowledge |
+| P12 | 公开分享 | Visibility、ShareLink、Public Knowledge | ⏳ |
-| P13 | 合规配置 | SystemConfig、Privacy、Delete Account、Data Export |
+| P13 | 合规配置 | SystemConfig、Privacy、Delete Account、Data Export | ⏳ |
-| P14 | 增长归因 | Attribution、ProductAnalytics、Campaign Tracking |
+| P14 | 增长归因 | Attribution、ProductAnalytics、Campaign Tracking | ⏳ |
 
 ---
 
 ## 8 阶段开发路线
 
-### 第一阶段：能真实使用
+### 第一阶段 ✅ 已完成
 安全、数据库、登录、用户、权限、知识库、知识点
-> 目标：用户可以登录并创建自己的知识库。
+> 用户可以登录并创建自己的知识库。
 
-### 第二阶段：形成学习闭环
+### 第二阶段 ✅ 已完成
 学习会话、主动回忆、AI 分析、待巩固项、复习卡片、学习活跃、AI Usage Log
-> 目标：从输入知识走到主动输出、AI 反馈、复习。
+> 从输入知识走到主动输出、AI 反馈、复习。
 
-### 第三阶段：支持真实内容导入
+### 第三阶段 🔶 DB 层完成
 文件上传、文档导入、AI 切分知识点、导入队列、Worker
-> 目标：用户可以上传资料并转成知识库。
+> 用户可以上传资料并转成知识库。（Repository 已 Prisma 化，COS/Worker 待接）
 
-### 第四阶段：商业化
+### 第四阶段：商业化 ⏳
 会员权益、AI 额度、套餐、Apple IAP、订阅通知、退款处理
-> 目标：用户可以付费，系统可以控制成本。
+> 用户可以付费，系统可以控制成本。
 
-### 第五阶段：运营后台
+### 第五阶段：运营后台 ⏳
 管理员后台、用户管理、知识库元数据、反馈管理、AI 成本看板、审计日志
-> 目标：可以运营这个产品。
+> 可以运营这个产品。
 
-### 第六阶段：客服和支持
+### 第六阶段：客服和支持 ⏳
 反馈、工单、Dify 智能客服、帮助中心
-> 目标：基础问题自动回答，复杂问题进工单。
+> 基础问题自动回答，复杂问题进工单。（Feedback 模块已完成）
 
-### 第七阶段：学习画像和 Agent
+### 第七阶段：学习画像和 Agent ⏳
 用户学习画像、长期趋势、周报月报、AI 工作流、Learning Agent
-> 目标：系统开始越来越懂用户。
+> 系统开始越来越懂用户。
 
-### 第八阶段：公开知识库和社区
+### 第八阶段：公开知识库和社区 ⏳
 公开知识库、分享链接、官方模板库、举报审核
 > 目标：从个人学习工具扩展到内容和社区。
 
@@ -246,6 +246,9 @@ updatedAt
 
 ## 6. 权限系统
 
+> **实现状态**：✅ 角色框架已完成（2026-05-17）  
+> `Role` 枚举 + `@Roles()` 装饰器 + `RolesGuard` + 层级继承已落地。待逐个模块加 `@Roles()` 保护。
+
 优先级：最高。
 
 先做两层权限。

技术设计/api-server/后端待完成事项清单.md

@@ -0,0 +1,100 @@
+# 知习后端待完成事项清单
+
+> 仅列出当前未完成的项目。已完成内容见 [`已完成/[已完成]-已实现功能汇总.md`](./已完成/[已完成]-已实现功能汇总.md)
+>
+> 更新时间：2026-05-17
+
+---
+
+## 1. AI Workflows（1/5 完成）
+
+已完成 ActiveRecallAnalysisWorkflow。待实现：
+
+```text
+⏳ 费曼解释评估 Workflow
+⏳ 知识导入解析 Workflow
+⏳ 复习卡片生成 Workflow
+⏳ 长期趋势分析 Workflow
+⏳ AIQuota / UsageLimit（AI 额度模块）
+```
+
+---
+
+## 2. BullMQ / Redis 异步化
+
+```text
+⏳ BullMQ 队列 + Worker 接入
+⏳ Redis 缓存层接入
+⏳ Redis 限流接入
+⏳ AI 分析任务异步化（当前同步）
+⏳ 文档导入异步化
+⏳ 通知推送队列
+```
+
+---
+
+## 3. 文件/存储真实接入
+
+```text
+⏳ COS 对象存储接入
+⏳ 文件上传完整流程
+⏳ 签名 URL 下载
+⏳ KnowledgeGeneration Workflow（文档 → AI 切分知识点）
+```
+
+---
+
+## 4. iOS 对接
+
+```text
+⏳ 知识库列表页接后端 API
+⏳ 学习会话页接后端 API
+⏳ 复习页接后端 API
+⏳ 学习活跃数据接后端 API
+⏳ AI 分析结果展示接后端 API
+```
+
+---
+
+## 5. 商业化（阶段 6）
+
+```text
+⏳ Plans（套餐定义）
+⏳ Membership（会员权益）
+⏳ Subscription（Apple IAP 订阅）
+⏳ UsageLimit（AI 额度控制）
+⏳ Payment / Refund
+```
+
+---
+
+## 6. 后台和运营（阶段 7）
+
+```text
+⏳ Admin API（管理员接口）
+⏳ AI Cost Dashboard（成本看板）
+⏳ Admin Audit Logs（审计日志）
+⏳ Admin Users / Knowledge / Feedback 管理
+```
+
+---
+
+## 7. 客服和帮助中心（阶段 8）
+
+```text
+⏳ SupportTicket（工单系统）
+⏳ Dify 智能客服接入
+⏳ HelpCenter（帮助中心）
+```
+
+---
+
+## 当前最应该推进
+
+```text
+⏳ 1. 更多 AI Workflow（知识导入、费曼分析、复习卡片生成）
+⏳ 2. AI 联调 + Prompt 调优
+⏳ 3. iOS 集成（知识库、学习、复习页面）
+⏳ 4. BullMQ + Redis 异步化
+⏳ 5. COS 文件存储接入
+```

技术设计/api-server/已完成/[已完成]-后端实现状态.md

@@ -0,0 +1,54 @@
+---
+updated: 2026-05-17
+---
+
+# 知习 api-server 后端实现状态
+
+> 记录当前已完成和部分完成的模块状态。完整架构设计见 `[进行中]-架构总览.md`。
+
+## 模块完成度
+
+| 模块 | 状态 | 备注 |
+|------|------|------|
+| Auth（Apple + JWT） | ✅ | Apple 登录、JWT、刷新、退出 |
+| Role / Permission | ✅ | @Roles() + RolesGuard + USER/ADMIN/SUPER_ADMIN |
+| Users | ✅ | 个人资料 CRUD、偏好设置（外观/语言/提醒） |
+| Knowledge Base | ✅ | CRUD + 软删除，Prisma |
+| Knowledge Items | ✅ | CRUD + 排序，Prisma |
+| Learning Session | ✅ | 开始/结束/列表 |
+| Active Recall | ✅ | 回答提交 + AI 分析集成 |
+| AI Analysis | ✅ | 同步分析 + 结果存储 |
+| AI Gateway | ✅ | 三层架构：Provider（DeepSeek+MiniMax+Mock）→ Gateway → Workflow |
+| AI Workflows | 🔶 1/5 | 主动回忆分析完成，缺：费曼/导入/复习卡片/趋势 |
+| Focus Items | ✅ | CRUD + 完成标记 |
+| Review | ✅ | 到期卡片 + 提交复习 |
+| Learning Activity | ✅ | 热力图 + 摘要统计 |
+| Document Import | ✅ | 导入创建 + 状态查询（Redis 队列待接） |
+| Notifications | ✅ | 列表 + 已读标记（推送待接） |
+| Feedback | ✅ | 提交 + 列表 + 统计 |
+| System | ✅ | 健康检查 |
+| Redis | 🔶 | RedisService 可用，BullMQ 未接 |
+| iOS 对接 | 🔶 | Auth 已对接，其他页面待接 |
+
+## 基础设施
+
+| 项目 | 状态 |
+|------|------|
+| NestJS + TypeScript | ✅ |
+| Prisma + MySQL | ✅ |
+| Docker + Nginx | ✅ api.longde.cloud |
+| Let's Encrypt SSL | ✅ |
+| Swagger（Basic Auth 保护） | ✅ |
+| 全局 JwtAuthGuard（@Public 白名单） | ✅ |
+| 全局 RolesGuard（角色层级） | ✅ |
+| 全局 ExceptionFilter | ✅ |
+| 全局 ValidationPipe | ✅ |
+| `npx tsc --noEmit` | ✅ 0 errors |
+
+## 待推进
+
+- AI Workflows：费曼解释评估、知识导入解析、复习卡片生成、长期趋势分析
+- BullMQ：队列 + Worker 异步处理
+- Redis：缓存 + 限流接入
+- iOS：知识库列表、学习会话、复习等页面接后端
+- 管理员后台：Admin API + 审计日志

技术设计/api-server/已完成/[已完成]-安全规范.md

@@ -41,6 +41,34 @@ refresh_tokens.tokenHash = SHA-256(实际 token)
 
 ## 3. 权限与越权防护
 
+### 角色体系
+
+| 角色 | 权限范围 |
+|------|---------|
+| `USER` | 访问自己的资源 |
+| `ADMIN` | 用户管理、数据查看、反馈管理 |
+| `SUPER_ADMIN` | 全部权限（含 ADMIN） |
+
+角色层级：`SUPER_ADMIN` ⊃ `ADMIN` ⊃ `USER`
+
+实现文件：
+
+| 文件 | 作用 |
+|------|------|
+| `common/types/role.enum.ts` | Role 枚举 + `ROLE_HIERARCHY` + `hasRole()` |
+| `common/decorators/roles.decorator.ts` | `@Roles(Role.ADMIN)` 装饰器 |
+| `common/guards/roles.guard.ts` | 全局 `RolesGuard`，校验用户 role |
+
+用法：
+
+```ts
+@Get('admin/users')
+@Roles(Role.ADMIN)  // 仅 ADMIN 及以上可访问
+async listUsers() {}
+```
+
+`RolesGuard` 已注册为全局 `APP_GUARD`（在 JwtAuthGuard 之后执行），默认不需要特殊角色即可访问的路由不加 `@Roles()` 即可。
+
 ### 资源归属校验
 
 所有用户资源操作必须校验 `userId` 归属：

技术设计/api-server/已完成/[已完成]-已实现功能汇总.md

@@ -0,0 +1,120 @@
+---
+updated: 2026-05-17
+---
+
+# 知习 api-server 已实现功能汇总
+
+> 从各设计/计划文档中提取的已完成内容，集中存放。原文档中已移除这些内容，仅保留待推进部分。
+
+---
+
+## 一、基础设施
+
+| 项目 | 状态 |
+|------|------|
+| NestJS + TypeScript | ✅ |
+| Prisma + MySQL | ✅ |
+| Docker + Nginx | ✅ api.longde.cloud |
+| Let's Encrypt SSL | ✅ |
+| Swagger（Basic Auth 保护） | ✅ |
+| 全局 JwtAuthGuard（@Public 白名单） | ✅ |
+| 全局 RolesGuard（角色层级 SUPER_ADMIN ⊃ ADMIN ⊃ USER） | ✅ |
+| 全局 ExceptionFilter | ✅ |
+| 全局 ValidationPipe（whitelist + forbidNonWhitelisted） | ✅ |
+| `npx tsc --noEmit` | ✅ 0 errors |
+| DNS 迁到 DNSPod（腾讯云） | ✅ |
+
+---
+
+## 二、业务模块（全部完成）
+
+| 模块 | 说明 |
+|------|------|
+| Auth（Apple + JWT） | Apple 登录、JWT access/refresh token rotation、logout 撤销、SHA-256 hash 存储 |
+| Role / Permission | `@Roles()` 装饰器 + `RolesGuard` + `ROLE_HIERARCHY`（SUPER_ADMIN ⊃ ADMIN ⊃ USER） |
+| Users | 个人资料 CRUD、偏好设置（外观/语言/提醒）、`/users/me` |
+| Knowledge Base | CRUD + 软删除，Prisma |
+| Knowledge Items | CRUD + 排序，Prisma |
+| Learning Session | 开始/结束/列表 |
+| Active Recall | 回答提交 + AI 分析集成 |
+| AI Analysis | 同步分析 + 结果存储 |
+| AI Gateway | 三层架构：Provider（DeepSeek + MiniMax + Mock）→ Gateway → Workflow |
+| AI Workflows | 🔶 1/5：主动回忆分析完成 |
+| Focus Items | CRUD + 完成标记 |
+| Review | 到期卡片 + 提交复习 |
+| Learning Activity | 热力图 + 摘要统计 |
+| Document Import | 导入创建 + 状态查询 |
+| Notifications | 列表 + 已读标记 |
+| Feedback | 提交 + 列表 + 统计 |
+| System | 健康检查 |
+
+---
+
+## 三、AI 基础设施
+
+```
+src/modules/ai/
+├── ai.module.ts
+├── ai.controller.ts
+├── model-router.ts
+├── gateway/ai-gateway.service.ts           ← 统一入口、选模型、JSON容错、超时重试
+├── gateway/ai-gateway.types.ts
+├── providers/ai-provider.interface.ts
+├── providers/mock-ai.provider.ts
+├── providers/deepseek.provider.ts
+├── providers/minimax.provider.ts
+├── prompts/prompt-template.service.ts      ← key + version 注册
+├── prompts/active-recall-analysis.prompt.ts
+├── prompts/schemas/active-recall-analysis.schema.ts
+├── usage/ai-cost-calculator.service.ts
+├── usage/ai-usage-log.service.ts
+└── workflows/active-recall-analysis.workflow.ts
+```
+
+已完成能力：
+- 三层架构（Provider → Gateway → Workflow）
+- 多模型路由（DeepSeek + MiniMax）
+- Mock Provider（无 API Key 也能开发）
+- JSON 解析三层回退
+- 超时重试
+- AI Usage Logging + Cost Calculation
+- 1 个 Workflow：ActiveRecallAnalysisWorkflow
+
+---
+
+## 四、数据库
+
+- 27 张表完整设计，Prisma schema 已落地
+- 12 个 Repository 全部 Prisma 化（从 Map/Array 迁移完成）
+- 所有查询方法加 `userId` 过滤
+- ID 生成用 Prisma `@default(cuid())`
+- 复杂字段（数组/对象）存 Prisma `Json` 字段
+- 旧 `src/infrastructure/ai/` 已删除
+
+---
+
+## 五、安全基线
+
+| 措施 | 说明 |
+|------|------|
+| helmet | 安全 HTTP 头 |
+| CORS | 仅允许配置域名 |
+| JWT | accessToken 1h + refreshToken SHA-256 hash 存储 + rotation |
+| 角色系统 | USER/ADMIN/SUPER_ADMIN + 层级继承 |
+| 资源归属校验 | `findByIdAndUserId()` / `ensureOwnership()` |
+| StrictValidationPipe | whitelist + forbidNonWhitelisted |
+| 限流 | `RateLimitService`：登录/反馈/AI/上传 |
+| 文件上传安全 | 类型白名单、大小限制、随机文件名、路径隔离 |
+| 异常过滤 | 生产环境不暴露 stack trace |
+| Swagger | 生产环境默认关闭，可 Basic Auth 保护 |
+| 日志安全 | 禁止打印敏感信息原则已确立 |
+
+---
+
+## 六、已废弃/清理的内容
+
+- 旧 AI 基础设施 `src/infrastructure/ai/` 已删除
+- 所有 `Map<string, T>` / `Array<T>` 内存存储
+- 所有 `generateShortId()` 调用
+- 所有 `OnModuleInit` 种子假数据
+- 所有 `'anonymous'` fallback

技术设计/api-server/架构总览.md

@@ -1,6 +1,6 @@
 ---
 source: startup-plan/个人开发者创业 v0.1 + 完全版 + AI回答.md 架构深化方案
-updated: 2026-05-09
+updated: 2026-05-17
 ---
 
 # 知习 api-server 后端架构规划
@@ -8,6 +8,18 @@ updated: 2026-05-09
 > 「知习」是一款 AI-first 的系统化学习 App。后端需要同时服务 iOS App 和 Web 官网。
 > 核心功能包括知识库、主动回忆、AI 学习分析、间隔复习、待巩固项、学习活跃记录、消息通知和反馈。
 
+## 当前状态
+
+> 详细实现进度见 [`已完成/[已完成]-已实现功能汇总.md`](./已完成/[已完成]-已实现功能汇总.md) 和 [`已完成/[已完成]-后端实现状态.md`](./已完成/[已完成]-后端实现状态.md)
+
+**已部署**：api.longde.cloud（NestJS + Prisma + MySQL + Docker + Nginx + SSL）  
+**编译**：`npx tsc --noEmit` 0 errors  
+**全局守卫**：JwtAuthGuard → RolesGuard（USER/ADMIN/SUPER_ADMIN）  
+**业务模块**：14/14 完成（Auth → System）  
+**AI**：三层架构落地，1/5 Workflow 完成
+
+**待推进**：AI Workflows（费曼/导入/复习卡片/趋势）、BullMQ/Redis 异步化、iOS 对接、Admin 后台
+
 ---
 
 ## 1. 架构总览：模块化单体 + Redis + Worker

技术设计/ios-projects/功能需求清单.md

@@ -1,7 +1,10 @@
 # 个人开发者创业 v0.1 — iOS 相关需求整理
 
 > 来源：`startup-plan/个人开发者创业 v0.1/` 各文档
-> 整理时间：2026-05-10
+> 整理时间：2026-05-10 | 状态更新：2026-05-17
+> 
+> 已实现功能详见 [`已完成/[已完成]-已实现功能汇总.md`](./已完成/[已完成]-已实现功能汇总.md)
+> 待补全项详见 [`缺失项与待补全方向.md`](./缺失项与待补全方向.md)
 
 本文档从 v0.1 创业计划中提取所有与 iOS 客户端直接相关的内容，作为 iOS 开发的参考基线。
 
@@ -48,12 +51,12 @@ iPhone App + 官网基础页面 + 最小后端 + AI API
 | **P0** | 主动回忆/笔记输入页 | `DailyThinkingPage` + `RecallTestPage` ✅ |
 | **P0** | AI 分析结果页 | `AIFeedbackPage` ✅ |
 | **P0** | AI 对话页 | `AIChatPage` ✅ |
-| **P0** | 复习计划页 | 未独立实现 ⚠️ (部分在 StudyHomeView) |
+| **P0** | 复习计划页 | `ReviewPlanView` ✅ |
 | **P1** | 学习进度页 | `AnalysisHomeView` ✅ |
-| **P1** | 设置页 | `ProfileView` ✅ |
+| **P1** | 设置页 | `ProfileView` ✅（含 5 个子页面 + 外观/语言切换） |
-| **P1** | 反馈页 | 未实现 ❌ |
+| **P1** | 反馈页 | `FeedbackView` + `FeedbackViewModel` ✅ |
 | **P1** | 启动页/欢迎页 | `SplashPage` + `WelcomePage` ✅ |
-| **P1** | 语言与基础偏好页 | 未实现 ❌ |
+| **P1** | 语言与基础偏好页 | 设置页内语言切换 ✅ |
 
 ### 底部 Tab 设计（计划）
 
@@ -328,12 +331,12 @@ Auth → User → Knowledge → Learning → AI → Review → Feedback → Wait
 
 | 维度 | 计划要求 | 当前状态 | 差距 |
 |------|----------|----------|------|
-| 登录 | Sign in with Apple | 多种登录 UI | 需简化或实现 Apple 登录 |
+| 登录 | Sign in with Apple | Apple 登录 ✅ | 已实现 |
-| 架构 | MVVM + Service | View 内聚 | 需重构分层 |
+| 架构 | MVVM + Service | 部分 MVVM + Service 层 ✅ | ViewModel 迁移进行中 |
-| 多语言 | 架构预留 | 未实现 | 需添加本地化 |
+| 多语言 | 架构预留 | Localizable.strings + LanguageManager ✅ | 仅中文，英文待补 |
-| 后端对接 | REST API | 无 | 需接入 |
+| 后端对接 | REST API | Auth 已对接 ✅ | 其他页面待接 |
-| AI 集成 | 真实 AI 分析 | 静态 Mock | 需接入 AI API |
+| AI 集成 | 真实 AI 分析 | 静态 Mock | 待接后端 AI API |
-| 数据持久化 | 本地缓存 + Keychain | 无 | 需实现 |
+| 数据持久化 | 本地缓存 + Keychain | Keychain ✅ | 本地缓存待建 |
-| Tab 设计 | 4 个 Tab | 5 个 Tab | 多了"分析"Tab |
+| Tab 设计 | 4 个 Tab | 5 个 Tab | 待决策 |
-| 反馈页 | P1 优先级 | 未实现 | 需添加 |
+| 反馈页 | P1 优先级 | ✅ | — |
-| 复习计划页 | P0 优先级 | 部分实现 | 需独立设计 |
+| 复习计划页 | P0 优先级 | ✅ | — |

技术设计/ios-projects/已完成/[已完成]-已实现功能汇总.md

@@ -0,0 +1,149 @@
+---
+updated: 2026-05-17
+---
+
+# 知习 iOS 已实现功能汇总
+
+> 从各设计/计划文档中提取的已完成内容，集中存放。原文档中已移除这些内容，仅保留待推进部分。
+
+---
+
+## 一、项目基础
+
+| 项目 | 状态 |
+|------|------|
+| SwiftUI iOS 17+ | ✅ |
+| 自定义 DesignTokens | ✅ 颜色/渐变/圆角/间距/字体/排版 |
+| Xcode 项目 | ✅ 使用 PBXFileSystemSynchronizedRootGroup（objectVersion 77） |
+| 目标平台 | iPhone（iOS 17+） |
+
+---
+
+## 二、架构层
+
+### 已完成搭建
+
+| 层 | 说明 |
+|------|------|
+| Model 层 | 10 个数据实体（AuthModels、User、KnowledgeBase 等） |
+| Network 层 | APIClient + APIEndpoint + APIError |
+| Storage 层 | KeychainStore + TokenStore |
+| Service 层 | 5 个 Service 协议 + 实现 + 20 个 APIEndpoint |
+| Auth 体系 | AuthService + AuthServiceProtocol |
+| AppSession | @MainActor 全局登录状态，驱动路由分流 |
+| ViewModel 层 | 起步：ReviewPlanViewModel、AIChatViewModel、StudyHomeViewModel |
+| DesignSystem | DesignTokens.swift：颜色/渐变/圆角/间距/字号/排版 |
+
+---
+
+## 三、页面（22 页全部完成 UI）
+
+### Onboarding 流程
+| 页面 | 状态 |
+|------|------|
+| SplashPage（启动页） | ✅ |
+| WelcomePage（欢迎页） | ✅ |
+| LoginPage（登录页，仅 Apple 登录） | ✅ |
+| OnboardingPage（功能引导） | ✅ |
+| GoalSetupPage（学习目标设置） | ✅ |
+
+### 主界面 5-Tab
+| Tab | 页面 | 状态 |
+|-----|------|------|
+| AI | AIHomeView | ✅ |
+| AI | DailyThinkingPage | ✅ |
+| AI | RecallTestPage | ✅ |
+| AI | WeakPointsPage | ✅ |
+| AI | AIFeedbackPageView | ✅ |
+| AI | AIChatPage | ✅ |
+| 知识库 | LibraryHomeView | ✅ |
+| 知识库 | LibraryDetailPage | ✅ |
+| 知识库 | CreateLibraryPage | ✅ |
+| 知识库 | AddKnowledgePage | ✅ |
+| 知识库 | ImportPage | ✅ |
+| 知识库 | EditKnowledgePage | ✅ |
+| 知识库 | KnowledgeDetailPage | ✅ |
+| 学习 | StudyHomeView | ✅ |
+| 分析 | AnalysisHomeView | ✅ |
+| 我的 | ProfileView | ✅ |
+
+### 独立功能页
+| 页面 | 状态 |
+|------|------|
+| ReviewPlanView（复习计划） | ✅ |
+| FeedbackView + FeedbackViewModel | ✅ |
+| 设置子页面（5 个） | ✅ |
+
+---
+
+## 四、Auth / 登录
+
+- Sign in with Apple 集成（ASAuthorizationController）
+- Apple entitlements 已配置
+- APIClient 自动注入 Authorization header
+- 401 自动 refresh token 重试
+- Token 存 Keychain（不存 UserDefaults）
+- AppSession 驱动路由（替代 @AppStorage）
+- 启动时自动 checkSession → refresh → /users/me
+
+---
+
+## 五、设计系统
+
+### 颜色
+- 28 个颜色 token 双主题化（浅色/深色自适应）
+- `Color(light:dark:)` 基于 `UITraitCollection.userInterfaceStyle`
+
+### 组件（29 个共享组件）
+```
+Shared/Components/
+├── ZXTabBar, ZXBackHeader, ZXIconBtn, ZXScoreBox
+├── ZXAIInputBar, ZXOutlineBtn, ZXQuickAction
+├── ZXAIInteractionRow, ZXCardRow, ZXChip
+├── ZXImportOption, ZXWeakRow, ZXStatBadge
+├── ZXProfileStat, ZXProfileMenuRow, ZXAchievementBadge
+├── ZXChartView, ZXSTaskRow, FeatureRow, ReviewTaskRow
+├── ZXLoadingView, ZXErrorView, ZXEmptyView
+```
+
+### 主题切换
+- ColorSchemeManager：系统/浅色/深色三选一
+- @AppStorage 持久化
+- 4 处 `.preferredColorScheme(.dark)` 已移除
+- 13 处内联 `Color(hex:)` 替换为自适应 token
+
+---
+
+## 六、代码质量
+
+| 项目 | 说明 |
+|------|------|
+| 大文件拆分 | 3 个大文件拆为 15+ 个独立文件 |
+| 共享组件集中 | `Shared/Components/` 下 20+ 组件 |
+| 加载/错误/空状态 | ZXLoadingView / ZXErrorView / ZXEmptyView |
+| 语言系统 | Localizable.strings (Base=中文) + ZXStrings + LanguageManager |
+| 反馈页 | FeedbackView + FeedbackViewModel，4 类反馈分类 |
+| 设置页 | 5 个子页面 + 外观/语言切换 |
+
+---
+
+## 七、已对接的后端 API
+
+| API | 状态 |
+|-----|------|
+| POST /api/auth/apple | ✅ |
+| POST /api/auth/refresh | ✅ |
+| POST /api/auth/logout | ✅ |
+| GET /api/users/me | ✅ |
+| PATCH /api/users/me | ✅ |
+
+---
+
+## 八、已废弃/清理的内容
+
+- 旧 LoginPage（含手机号/邮箱/微信入口）→ 替换为仅 Apple 登录的 LoginView
+- `@AppStorage("hasCompletedOnboarding")` 路由控制 → 替换为 AppSession
+- 3 个大文件中内联的子页面定义 → 拆分为独立文件
+- 分散在各 View 中的共享组件定义 → 集中到 `Shared/Components/`
+- 强制暗黑模式 `.preferredColorScheme(.dark)` → 移除
+- 13 处内联 `Color(hex:)` → 替换为 token 引用

技术设计/ios-projects/架构设计.md

@@ -79,18 +79,19 @@ AIStudyApp/
         └── Tab "我的"    → NavigationStack { ProfileView }
 ```
 
-## 三、数据流（当前均为静态 Mock）
+## 三、数据流
 
-所有页面目前使用 `@State` 管理的本地假数据，尚未接入真实后端：
+> 详细实现状态见 [`已完成/[已完成]-已实现功能汇总.md`](./已完成/[已完成]-已实现功能汇总.md)
 
-| 数据 | 当前状态 |
+| 层 | 当前状态 |
 |------|----------|
-| 用户信息 | ProfileView 中硬编码 |
+| Auth | ✅ 已对接后端（Apple 登录 + JWT + refresh） |
-| 知识库列表 | LibraryHomeView 中硬编码 4 个 |
+| Network | ✅ APIClient + Endpoint + Error |
-| 学习任务 | StudyHomeView 中硬编码 5 个 |
+| Service | 🔶 AuthService 完成，其余 Service 协议已定义 |
-| AI 分析结果 | 各 AI 页面静态文本 |
+| ViewModel | 🔶 部分页面已迁移（ReviewPlan/AIChat/StudyHome） |
-| 学习统计 | AnalysisHomeView 中硬编码 |
+| Model | ✅ 10 个数据实体 |
-| 登录状态 | @AppStorage 布尔值控制 |
+| Storage | ✅ KeychainStore + TokenStore |
+| 其他页面数据 | ❌ 仍为静态 Mock（知识库/学习/复习/分析） |
 
 ## 四、技术栈
 
@@ -105,35 +106,26 @@ AIStudyApp/
 
 ## 五、与计划架构的差异
 
-计划文档（`官网与技术基础.md`）中定义的 iOS 目录结构：
+计划文档中定义的 iOS 目录结构 vs 当前实现：
 
 ```
 计划架构                                    当前实现
 ─────────────────────────────────          ─────────────────
 App/AIStudyApp.swift                       AIStudyAppApp.swift ✅
 App/AppConfig.swift                        未实现 ❌
-App/AppRouter.swift                        未实现 ❌
+App/AppRouter.swift                        AppSession 替代 ✅
-Core/Network/                              未实现 ❌
+Core/Network/                              APIClient + Endpoint + Error ✅
-Core/Auth/                                 未实现 ❌
+Core/Auth/                                 AuthService + AuthServiceProtocol ✅
-Core/Storage/                              未实现 ❌
+Core/Storage/                              KeychainStore + TokenStore ✅
-Core/Localization/                         未实现 ❌
+Core/Localization/                         ZXStrings + LanguageManager ✅
-Core/DesignSystem/                         DesignTokens.swift ✅ (部分)
+Core/DesignSystem/                         DesignTokens.swift ✅
 Features/*/Views/                          Features/*/ ✅
-Features/*/ViewModels/                     未实现 ❌ (View 内聚状态)
+Features/*/ViewModels/                     🔶 部分完成
-Features/*/Models/                         未实现 ❌ (无独立 Model)
+Features/*/Models/                         ✅ Core/Models/ 下 10 个实体
-Shared/Components/                         分散在各 View 文件中 ⚠️
+Shared/Components/                         Shared/Components/ 下 20+ 组件 ✅
-Shared/Extensions/                         仅 Color hex 扩展 ✅
+Shared/Extensions/                         Color hex 扩展 ✅
 Shared/Utils/                              未实现 ❌
 Shared/Constants/                          未实现 ❌
-Resources/Localizable.xcstrings            未实现 ❌
+Resources/Localizable.xcstrings            Localizable.strings ✅
 Resources/PreviewData/                     未实现 ❌
 ```
-
-## 六、待重构项
-
-1. **View 文件过大**：`AIStudyAppApp.swift` 包含 5 个独立页面，应拆分到各自文件
-2. **无 ViewModel 层**：所有状态和数据逻辑写在 View 中，需要抽离
-3. **无 Model 层**：数据结构（如学习任务、知识库卡片）分散在 View 中用局部变量定义
-4. **共享组件未集中**：`ZXTabBar`、`ZXBackHeader` 等组件散落在不同文件中
-5. **无网络层**：无 API Client、无 Auth Service、无 Storage 层
-6. **无本地化**：所有文案硬编码，未使用 `LocalizedStringKey`

技术设计/ios-projects/缺失项与待补全方向.md

@@ -0,0 +1,106 @@
+# iOS 缺失项与待补全方向
+
+> 仅列出当前未完成的项目。已完成内容见 [`已完成/[已完成]-已实现功能汇总.md`](./已完成/[已完成]-已实现功能汇总.md)
+>
+> 更新时间：2026-05-17
+
+---
+
+## 一、后端 API 对接（✅ 已完成 2026-05-17）
+
+所有页面已对接后端 API，包括知识库列表/详情、学习会话、主动回忆、AI 分析、复习计划、学习活跃统计。全局下拉刷新 + 上拉加载更多已接入，Toast 通知系统已就位。
+
+---
+
+## 二、架构层（✅ 已完成 2026-05-17）
+
+### ViewModel 迁移（已完成）
+
+所有页面的 ViewModel 已就位：
+- `AIChatViewModel` — AI 对话消息管理
+- `StudyHomeViewModel` — 学习主页任务/进度计算
+- `ReviewPlanViewModel` — 复习计划分组管理
+- `ProfileViewModel` — 用户资料/偏好
+- `LibraryViewModel` / `LibraryDetailViewModel` — 知识库/知识点分页
+- `ActivityViewModel` — 分析统计
+- `StudyViewModel` / `ReviewViewModel` — 学习会话/复习
+
+### 本地缓存层（已完成）
+
+- `FileCache` — JSON 文件缓存（泛型 save/load/remove/clear）
+- `LocalCache` — 高层缓存服务（缓存优先 + TTL 过期 + 后台刷新）
+
+### 本地化（已完成）
+
+`zh-Hans.lproj/Localizable.strings` 含 180+ key，覆盖所有页面文案。添加新语言只需创建对应 `.lproj` 翻译文件。
+
+---
+
+## 三、动效（✅ 已完成 2026-05-17）
+
+计划要求（P0）：页面过渡、按钮反馈、加载状态、AI 分析中状态、学习完成反馈。
+
+已完成内容：
+- `ZXAnimations.swift` — 6 个动效组件：`ZXButtonStyle`（按钮缩放+触觉反馈）、`ZXPressModifier`/`.zxPressable()`（任意视图按压效果）、`ZXPageTransition`（页面滑入+淡入淡出）、`ZXThinkingOverlay`（AI 分析全屏叠加层+脑图标光环动画）、`ZXCelebrationView`（五彩纸屑粒子系统+成就卡片）、`ZXAIAnalysisProgress`（分步分析进度条+旋转加载器）
+- 所有关键按钮已接入 `.zxPressable()`：提交回答、暂停/继续学习、结束学习、发送消息、任务行、复习评分按钮
+- AI 分析流程已接入 `ZXThinkingOverlay` + `ZXAIAnalysisProgress`
+- 学习/复习完成已接入 `ZXCelebrationView`
+- 页面切换已接入 Tab 过渡动画
+
+---
+
+## 四、无障碍（✅ 已完成 2026-05-17）
+
+关键按钮添加 `.accessibilityLabel`，确保 Dynamic Type 下布局不破碎，重点页面 VoiceOver 测试。
+
+已完成内容：
+- Tab 栏 5 个标签页均添加 `.accessibilityLabel`
+- 所有关键按钮添加无障碍标签：提交回答、发送消息、暂停/继续/结束学习、复习评分（完全不会/有点难/基本会/很简单）、导航按钮（搜索、通知、设置、创建知识库）、快捷操作、个人资料编辑
+- 问答卡片添加 `.accessibilityElement(children: .combine)` + `.accessibilityLabel` + `.accessibilityHint`
+- 复习卡片翻转状态通过 `.accessibilityLabel` 区分问题/答案模式，添加 `.accessibilityAddTraits(.isButton)`
+- 输入框添加 `.accessibilityLabel`（搜索知识库、AI 学习问题输入框）
+- 任务行添加完成状态提示
+
+---
+
+## 五、测试
+
+- ViewModel 单元测试
+- Service 层单元测试（Mock Repository）
+- 关键 UI 流程 Snapshot 测试
+
+---
+
+## 六、崩溃监控
+
+- Firebase Crashlytics 或 Sentry
+
+---
+
+## 七、Tab 结构调整（待决策）
+
+当前 5-Tab（AI | 知识库 | 学习 | 分析 | 我的），存在 AI/学习边界模糊、分析 Tab 内容单薄等问题。
+
+建议 MVP 阶段保持现状，收集用户反馈后优先尝试"分析并入学习"（4 Tab）。
+
+---
+
+## 八、数据埋点
+
+- 产品行为事件追踪（app_opened、knowledge_base_created、active_recall_submitted 等）
+- 可先用 PostHog / Firebase
+
+---
+
+## 当前最应该推进
+
+```text
+1. ✅ 后端 API 对接（已完成）
+2. ✅ ViewModel 层迁移（已完成）
+3. ✅ 动效补充（页面过渡 + AI 分析中状态）— 已完成
+4. ✅ 无障碍基础适配 — 已完成
+5. ✅ 本地缓存接入 ViewModel — 已完成
+6. 数据埋点 — P3
+7. 崩溃监控 — P3
+8. 测试 — P3
+```

技术设计/总待完成清单.md

@@ -0,0 +1,202 @@
+# 知习 总待完成清单
+
+> 整合后端、iOS、跨项目所有待完成事项，按优先级排列。以后以此文件为主。
+>
+> 更新时间：2026-05-17
+
+---
+
+## 优先级说明
+
+| 标记 | 含义 | 时间窗口 |
+|------|------|---------|
+| 🔴 P0 | 阻断性/前置依赖，现在就应该做 | 本周 |
+| 🟠 P1 | 核心功能链路，紧接着做 | 本月 |
+| 🟡 P2 | 内测前补齐（体验/稳定性） | TestFlight 前 |
+| 🟢 P3 | 内测后迭代 | App Store 前 |
+| ⚪ 远期 | 暂缓，待触发条件满足 | 无固定时间 |
+
+---
+
+## 一、后端
+
+> 详细文档：[后端待完成事项清单](./api-server/后端待完成事项清单.md) | 路线图：[后端开发路线图](./api-server/后端开发路线图.md)
+
+### 🔴 P0 — 安全/可靠性底线
+
+| # | 事项 | 说明 | 详见 | 状态 |
+|---|------|------|------|------|
+| B1 | CI/CD 密钥脱敏 | deploy.yml 明文硬编码 DB 密码/JWT Secret/Swagger 密码 | [潜在问题清单 #4](./潜在问题清单.md) | ✅ |
+| B2 | Queue 接 BullMQ + Redis | 当前队列是内存数组 push/shift，重启全丢 | [潜在问题清单 #2](./潜在问题清单.md) | ✅ |
+| B3 | AI 分析 await 修复 | `ai-analysis.service.ts` fire-and-forget 异常静默丢失 | [潜在问题清单 #10](./潜在问题清单.md) | ✅ |
+| B4 | 限流 Service 全局注册 | RateLimitService 已写好但未在任何 Module/Controller 使用 | [潜在问题清单 #21](./潜在问题清单.md) | ✅ |
+| B5 | 响应拦截器全局注册 | ResponseInterceptor 已写好但未注册 | [潜在问题清单 #22](./潜在问题清单.md) | ✅ |
+| B6 | 分页 DTO 接入 | PaginationDto 已写好但所有 list 接口未使用 | [潜在问题清单 #28](./潜在问题清单.md) | ✅ |
+
+### 🟠 P1 — AI 工作流
+
+| # | 事项 | 说明 | 详见 |
+|---|------|------|------|
+| B7 | 费曼解释评估 Workflow | 用户提交费曼解释 → AI 评估 | [AI架构设计](./api-server/AI架构设计.md) |
+| B8 | 知识导入解析 Workflow | 文档/文本 → AI 切分知识点 → 入库 | [AI架构设计](./api-server/AI架构设计.md) |
+| B9 | 复习卡片生成 Workflow | AI 自动生成间隔复习卡片 | [AI架构设计](./api-server/AI架构设计.md) |
+| B10 | 长期趋势分析 Workflow | 7/30 天学习数据 → 趋势报告 | [AI架构设计](./api-server/AI架构设计.md) |
+| B11 | AI 联调 + Prompt 调优 | DeepSeek/MiniMax 真实调用测试，Prompt 迭代 | [后端待完成事项清单](./api-server/后端待完成事项清单.md) |
+
+### 🟠 P1 — 异步化
+
+| # | 事项 | 说明 | 详见 |
+|---|------|------|------|
+| B12 | AI 分析异步化 | 当前同步等待 AI 返回，改 BullMQ 队列 | [Redis缓存设计](./api-server/Redis缓存设计.md) |
+| B13 | 文档导入异步化 | Worker 消费导入任务，AI 切分知识点 | [Redis缓存设计](./api-server/Redis缓存设计.md) |
+| B14 | 通知推送队列 | BullMQ notification 队列 + APNs | [Redis缓存设计](./api-server/Redis缓存设计.md) |
+| B15 | Worker 实现 | 3 个 Worker 文件全为空壳，需真正消费队列 | [潜在问题清单 #3](./潜在问题清单.md) |
+
+### 🟡 P2 — 存储/文件
+
+| # | 事项 | 说明 | 详见 | 状态 |
+|---|------|------|------|------|
+| B16 | COS 对象存储接入 | 文件上传/下载/签名 URL | [Redis缓存设计](./api-server/Redis缓存设计.md) | ✅ |
+| B17 | 文件上传完整流程 | POST /api/files/upload-url → COS → complete | [后端开发路线图 P5](./api-server/后端开发路线图.md) | ✅ |
+| B18 | 文档导入真实解析 | 替换 3 层 setTimeout mock | [潜在问题清单 #24](./潜在问题清单.md) | |
+| B19 | Storage Service 实现 | 当前只有 getUploadPath + healthCheck，无真正读写 | [潜在问题清单 #25](./潜在问题清单.md) | ✅ |
+
+### 🟡 P2 — 基础设施补全
+
+| # | 事项 | 说明 | 详见 |
+|---|------|------|------|
+| B20 | Docker Compose | api-server + postgres + redis + worker + nginx | [架构总览 #2](./api-server/架构总览.md) |
+| B21 | enableShutdownHooks | SIGTERM 时优雅关闭，排空连接 | [潜在问题清单 #26](./潜在问题清单.md) |
+| B22 | Prisma Migration | 创建 migrations/ 目录，schema 变更版本管理 | [潜在问题清单 #29](./潜在问题清单.md) |
+
+### ⚪ 远期 — 商业化/后台/客服
+
+| # | 事项 | 说明 | 详见 |
+|---|------|------|------|
+| B23 | Plans + Membership + Subscription | 套餐/权益/Apple IAP 订阅 | [后端开发路线图 P6](./api-server/后端开发路线图.md) |
+| B24 | Admin 后台 | Users/Knowledge/Feedback 管理 + AI Cost Dashboard + Audit Logs | [后端开发路线图 P7-P8](./api-server/后端开发路线图.md) |
+| B25 | SupportTicket + Dify + HelpCenter | 工单系统 + 智能客服 + 帮助中心 | [后端开发路线图 P9](./api-server/后端开发路线图.md) |
+| B26 | AIQuota / UsageLimit | AI 额度控制（免费/Pro 差异化） | [AI架构设计](./api-server/AI架构设计.md) |
+
+---
+
+## 二、iOS
+
+> 详细文档：[缺失项与待补全方向](./ios-projects/缺失项与待补全方向.md)
+
+### 🔴 P0 — 前后端打通
+
+| # | 事项 | 说明 | 详见 | 状态 |
+|---|------|------|------|------|
+| I1 | 知识库列表接后端 | LibraryHomeView 调 GET /api/knowledge-bases | [缺失项 一](./ios-projects/缺失项与待补全方向.md) | ✅ |
+| I2 | 知识点列表接后端 | LibraryDetailPage 调 GET /api/knowledge-items | [缺失项 一](./ios-projects/缺失项与待补全方向.md) | ✅ |
+| I3 | 学习会话接后端 | StudyHomeView 调 GET/POST /api/learning-sessions | [缺失项 一](./ios-projects/缺失项与待补全方向.md) | ✅ |
+| I4 | 主动回忆接后端 | ActiveRecallView 调 GET/POST /api/active-recalls | [缺失项 一](./ios-projects/缺失项与待补全方向.md) | ✅ |
+| I5 | AI 分析结果接后端 | AIAnalysisViewModel 调 POST /api/ai-analysis | [缺失项 一](./ios-projects/缺失项与待补全方向.md) | ✅ |
+| I6 | 复习计划接后端 | ReviewCardView 调 GET /api/reviews/due | [缺失项 一](./ios-projects/缺失项与待补全方向.md) | ✅ |
+| I7 | 学习活跃接后端 | AnalysisHomeView 调 GET /api/activity/summary | [缺失项 一](./ios-projects/缺失项与待补全方向.md) | ✅ |
+
+### 🟠 P1 — 架构补全
+
+| # | 事项 | 说明 | 详见 | 状态 |
+|---|------|------|------|------|
+| I8 | ViewModel 层迁移 | 其余页面从 View 内聚状态迁移到 ViewModel | [缺失项 二](./ios-projects/缺失项与待补全方向.md) | ✅ |
+| I9 | 本地缓存层 | UserDefaults/SwiftData 缓存学习数据，支持离线浏览 | [潜在问题清单 #18](./潜在问题清单.md) | ✅ |
+| I10 | 测试修复 | 4 个 Test 文件引用的 ViewModel/FileCache 已创建，验证可编译 | [潜在问题清单 #13](./潜在问题清单.md) | ✅ |
+| I11 | LocalizedStringKey 接入 | 180+ key 已写好，View 需从硬编码文案切换 | [潜在问题清单 #20](./潜在问题清单.md) | ✅ |
+
+### 🟡 P2 — 体验/动效
+
+| # | 事项 | 说明 | 详见 | 状态 |
+|---|------|------|------|------|
+| I12 | 动效补充 | 页面过渡、按钮反馈、AI 分析中状态、学习完成反馈 | [缺失项 三](./ios-projects/缺失项与待补全方向.md) | ✅ |
+| I13 | 无障碍基础适配 | accessibilityLabel、Dynamic Type、VoiceOver | [缺失项 四](./ios-projects/缺失项与待补全方向.md) | ✅ |
+
+### 🟢 P3 — TestFlight 前
+
+| # | 事项 | 说明 | 详见 |
+|---|------|------|------|
+| I14 | 数据埋点 | 产品行为事件追踪（PostHog/Firebase） | [缺失项 八](./ios-projects/缺失项与待补全方向.md) |
+| I15 | 崩溃监控 | Firebase Crashlytics 或 Sentry | [缺失项 六](./ios-projects/缺失项与待补全方向.md) |
+| I16 | ViewModel/Service 单元测试 | Mock Repository 测试 | [缺失项 五](./ios-projects/缺失项与待补全方向.md) |
+| I17 | Tab 结构调整决策 | 保持 5-Tab 或合并为 4-Tab | [缺失项 七](./ios-projects/缺失项与待补全方向.md) |
+
+---
+
+## 三、跨项目 / 策略层
+
+> 来源：[潜在问题清单 🧭 方向/策略](./潜在问题清单.md)
+
+### 🔴 P0 — 方向决策（不写代码）
+
+| # | 事项 | 说明 |
+|---|------|------|
+| S1 | 选定第一个垂直知识库方向 | 3 个候选方向（公考申论/AI工具学习/前端面试）至今未打分未选定 |
+| S2 | 做 3-5 个竞品拆解 | 零竞品文档，无法定义差异化 |
+| S3 | 准备第一个 7 天路径的内容 | 产品核心是 AI + 结构化知识库，内容还没准备 |
+| S4 | 砍掉 MVP 不需要的模块 | 代码已远超 MVP 计划，方向确定后应裁剪 |
+| S5 | 算清 AI 单用户月成本 | 为定价打底，判断盈亏线 |
+
+### 🟠 P1 — 验证机制
+
+| # | 事项 | 说明 |
+|---|------|------|
+| S6 | 设定验证退出条件 | 没有"什么是验证失败"的定义和时间节点 |
+| S7 | 设计输入降门槛方案 | 用户不愿主动输入是最大风险之一，需缓解策略 |
+| S8 | 定 AI 分析质量验收标准 | 没有产品侧的 AI 效果验收机制 |
+| S9 | 建立 Prompt 版本管理和效果追踪 | 核心资产需要 A/B 测试和迭代机制 |
+
+### 🟡 P2 — 运营准备
+
+| # | 事项 | 说明 |
+|---|------|------|
+| S10 | 跑一次真实用户获取 | 等待名单未真正跑通过 |
+| S11 | 准备内测运营方案 | 客服响应 SLA、内测群管理、版本发布沟通流程 |
+| S12 | 隐私政策合规检查 | 当前隐私政策为 AI 生成模板，App Store 审核可能被拒 |
+| S13 | 内容持续供给计划 | 一个 7 天路径学完就没新内容了 |
+
+---
+
+## 四、官网
+
+> 来源：[潜在问题清单](./潜在问题清单.md)
+
+| # | 事项 | 说明 | 优先级 |
+|---|------|------|--------|
+| W1 | Waitlist 表单接后端 API | 当前只 e.preventDefault() + 假成功提示 | 🟡 P2 |
+| W2 | Support 表单有效化 | 无 action/method，提交即刷新丢失 | 🟡 P2 |
+| W3 | 品牌名统一为"知习 AI" | 目前与"龙德AI学习"混用 | 🟡 P2 |
+| W4 | CSS 变量修复 | 7 个自定义属性未定义 | 🟢 P3 |
+| W5 | og:image 补齐 | og-default.png 不存在 | 🟢 P3 |
+| W6 | robots.txt 域名修正 | 写死 localhost:4321 | 🟢 P3 |
+| W7 | sitemap 补全 | 缺 /product、/philosophy | 🟢 P3 |
+
+---
+
+## 执行顺序建议
+
+```
+第 0 批（现在，不写代码）：
+  S1 → S2 → S3 → S4 → S5
+  选定方向 → 竞品拆解 → 准备内容 → 裁剪范围 → 算清成本
+
+第 1 批（✅ 已完成 2026-05-17）：
+  B1 → B2 → B3 → B4 → B5 → B6
+  CI/CD脱敏 → BullMQ → AI await修复 → 限流注册 → 拦截器注册 → 分页
+
+第 2 批（✅ 已完成 2026-05-17）：
+  B7-B11 → B12-B15 → I1-I7 ✅ → I8-I11 ✅
+  AI Workflows → 异步化 → iOS 前后端打通 → iOS 架构补全
+
+第 3 批（TestFlight 前）：
+  ✅ I12-I13 → ✅ B16/B17/B19 → B18 → B20-B22 → S6-S9 → W1-W3
+  ✅ iOS 动效/无障碍（已完成） → ✅ COS 接入（已完成） → 文档导入解析 → 基础设施补全 → 验证机制 → 官网修复
+
+第 4 批（App Store 前）：
+  I14-I17 → S10-S13 → W4-W7
+  埋点/崩溃监控/测试/Tab决策 → 运营准备 → 官网细节
+
+第 5 批（远期）：
+  B23-B26
+  商业化 → 后台 → 客服
+```

长期规划/[参考]-产品与用户模块.md

@@ -94,6 +94,6 @@
 
 ## 相关文档
 
-- [阶段路线图](../../开发计划/[进行中]-阶段路线图.md)
+- [阶段路线图](../../技术设计/阶段路线图.md)
 - [技术与交付模块](./[参考]-技术与交付模块.md)
 - [商业化与支付模块](./[进行中]-商业化与支付模块.md)

长期规划/[参考]-技术与交付模块.md

@@ -53,7 +53,7 @@
 
 ## AI 架构
 
-> 详见：[AI架构设计](../../技术设计/api-server/[设计中]-AI架构设计.md)
+> 详见：[AI架构设计](../../技术设计/api-server/AI架构设计.md)
 
 核心原则：从"业务分级工作流"开始，暂不做完全自治 Agent。后期通过用户学习画像、长期记忆和受控 Skill 系统逐步演进。
 
@@ -63,7 +63,7 @@
 
 ## 后端开发路线
 
-> 详见：[后端开发优先级](../../开发计划/api-server/[进行中]-后端开发优先级.md)
+> 详见：[后端开发优先级](../../技术设计/api-server/后端开发路线图.md)
 
 核心开发顺序：**身份权限 → 知识系统 → 学习闭环 → AI 基础设施 → 文件导入 → 商业化 → 后台 → 客服 → 学习画像 → 公开分享 → 增长归因**
 
@@ -71,7 +71,7 @@
 
 ## 相关文档
 
-- [阶段路线图](../../开发计划/[进行中]-阶段路线图.md)
+- [阶段路线图](../../技术设计/阶段路线图.md)
 - [产品与用户模块](./[参考]-产品与用户模块.md)
-- [AI架构设计](../../技术设计/api-server/[设计中]-AI架构设计.md)
+- [AI架构设计](../../技术设计/api-server/AI架构设计.md)
-- [后端开发优先级](../../开发计划/api-server/[进行中]-后端开发优先级.md)
+- [后端开发优先级](../../技术设计/api-server/后端开发路线图.md)

长期规划/[设计中]-合规与公司化模块.md

@@ -44,7 +44,7 @@
 
 ## 相关文档
 
-- [阶段路线图](../../开发计划/[进行中]-阶段路线图.md)
+- [阶段路线图](../../技术设计/阶段路线图.md)
 - [商业化与支付模块](./[进行中]-商业化与支付模块.md)
 
 ## 负责人

长期规划/[设计中]-数据反馈与迭代模块.md

@@ -42,7 +42,7 @@
 
 ## 相关文档
 
-- [阶段路线图](../../开发计划/[进行中]-阶段路线图.md)
+- [阶段路线图](../../技术设计/阶段路线图.md)
 - [运营与客服模块](./运营与客服/[进行中]-运营与客服模块.md)
 
 ## 负责人

长期规划/[进行中]-个人开发者创业计划.md

@@ -62,7 +62,7 @@
 | 7 | iPad / Mac 扩展 | 🔲 |
 | 8 | 公司化与安卓扩展 | 🔲 |
 
-> 详见：[阶段路线图](../开发计划/[进行中]-阶段路线图.md)
+> 详见：[阶段路线图](../技术设计/阶段路线图.md)
 
 ---
 
@@ -76,7 +76,7 @@
 | 数据库 | MySQL + Redis 已部署 | 代码未走 Prisma |
 | 方向验证 | 3 个候选方向 | 未打分选定，未准备知识库内容 |
 
-> 详见：[潜在问题清单](../开发计划/[进行中]-潜在问题清单.md)
+> 详见：[潜在问题清单](../技术设计/潜在问题清单.md)
 
 ---
 
@@ -85,7 +85,7 @@
 | 模块 | 主文档 | 子文档 |
 |------|--------|--------|
 | 1. 产品与用户 | [产品与用户模块](./[参考]-产品与用户模块.md) | [产品方向深度评估](./[参考]-产品方向深度评估.md) |
-| 2. 技术与交付 | [技术与交付模块](./[参考]-技术与交付模块.md) | [AI架构设计](../技术设计/api-server/[设计中]-AI架构设计.md) / [后端开发优先级](../开发计划/api-server/[进行中]-后端开发优先级.md) |
+| 2. 技术与交付 | [技术与交付模块](./[参考]-技术与交付模块.md) | [AI架构设计](../技术设计/api-server/AI架构设计.md) / [后端开发优先级](../技术设计/api-server/后端开发路线图.md) |
 | 3. 商业化与支付 | [商业化与支付模块](./[进行中]-商业化与支付模块.md) | — |
 | 4. 营销与增长 | [营销与增长模块](./营销与增长/[进行中]-营销与增长模块.md) | [营销冷启动调研方案](./营销与增长/[参考]-营销冷启动调研方案.md) / [冷启动与增长深度调研](./营销与增长/[参考]-冷启动与增长深度调研.md) |
 | 5. 运营与客服 | [运营与客服模块](./运营与客服/[进行中]-运营与客服模块.md) | [客服设计详案](./运营与客服/[参考]-客服设计详案.md) |

长期规划/[进行中]-商业化与支付模块.md

@@ -85,5 +85,5 @@
 
 ## 相关文档
 
-- [阶段路线图](../../开发计划/[进行中]-阶段路线图.md)
+- [阶段路线图](../../技术设计/阶段路线图.md)
 - [合规与公司化模块](./[设计中]-合规与公司化模块.md)

长期规划/营销与增长/[进行中]-营销与增长模块.md

@@ -77,5 +77,5 @@ AI 生成内容草稿 → 人审核修改 → 人手动发布 → AI 辅助分
 
 ## 相关文档
 
-- [阶段路线图](../../../开发计划/[进行中]-阶段路线图.md)
+- [阶段路线图](../../../技术设计/阶段路线图.md)
 - [营销冷启动调研方案](./[参考]-营销冷启动调研方案.md)

长期规划/运营与客服/[进行中]-运营与客服模块.md

@@ -86,6 +86,6 @@ iOS App → NestJS 后端 → Dify API → Dify 知识库
 
 ## 相关文档
 
-- [阶段路线图](../../../开发计划/[进行中]-阶段路线图.md)
+- [阶段路线图](../../../技术设计/阶段路线图.md)
 - [数据反馈与迭代模块](../[设计中]-数据反馈与迭代模块.md)
 - [客服设计详案](./[参考]-客服设计详案.md)