From fe608da385ce6bfaa80c741397a0cc3ea4fd5cf3 Mon Sep 17 00:00:00 2001 From: WangDL Date: Sun, 17 May 2026 19:08:59 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=E6=8A=80=E6=9C=AF?= =?UTF-8?q?=E8=AE=BE=E8=AE=A1=E7=9B=AE=E5=BD=95=E7=BB=93=E6=9E=84=20+=20?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=E5=BE=85=E5=AE=8C=E6=88=90=E6=B8=85=E5=8D=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 文档从扁平结构迁移至分类目录 (api-server/ios-projects/web-projects/长期规划) - 更新总待完成清单 (B1-B6 全部完成, I1-I7 全部完成) - 新增后端实现状态、已实现功能汇总等已完成文档 - 新增 iOS 功能需求清单、架构设计、差距分析等文档 - 清理旧版未维护文档 Co-Authored-By: Claude Opus 4.7 --- README.md | 135 +-- 开发计划/admin-projects/.gitkeep | 0 开发计划/android-projects/.gitkeep | 0 .../api-server/[进行中]-后端待完成事项清单.md | 617 ---------- 开发计划/harmonyos-projects/.gitkeep | 0 .../ios-projects/[进行中]-缺失项与待补全方向.md | 1042 ----------------- 开发计划/miniapp-projects/.gitkeep | 0 开发计划/web-projects/.gitkeep | 0 开发计划/webApp-projects/.gitkeep | 0 .../{[设计中]-AI架构设计.md => AI架构设计.md} | 9 +- ...[进行中]-Redis缓存设计.md => Redis缓存设计.md} | 0 .../api-server/后端开发路线图.md | 67 +- 技术设计/api-server/后端待完成事项清单.md | 100 ++ .../api-server/已完成/[已完成]-后端实现状态.md | 54 + .../api-server/已完成/[已完成]-安全规范.md | 28 + .../api-server/已完成/[已完成]-已实现功能汇总.md | 120 ++ .../api-server/已完成/[已完成]-当前状态与决策清单.md | 0 .../{[进行中]-架构总览.md => 架构总览.md} | 14 +- .../ios-projects/功能需求清单.md | 31 +- .../ios-projects/已完成/[已完成]-差距分析.md | 0 .../已完成/[已完成]-已实现功能汇总.md | 149 +++ .../{[进行中]-架构设计.md => 架构设计.md} | 52 +- .../{[设计中]-登录集成.md => 登录集成.md} | 0 技术设计/ios-projects/缺失项与待补全方向.md | 87 ++ .../{[设计中]-设计文档.md => 设计文档.md} | 0 技术设计/总待完成清单.md | 203 ++++ .../潜在问题清单.md | 0 .../阶段路线图.md | 0 长期规划/[参考]-产品与用户模块.md | 2 +- 长期规划/[参考]-技术与交付模块.md | 10 +- 长期规划/[设计中]-合规与公司化模块.md | 2 +- 长期规划/[设计中]-数据反馈与迭代模块.md | 2 +- 长期规划/[进行中]-个人开发者创业计划.md | 6 +- 长期规划/[进行中]-商业化与支付模块.md | 2 +- .../营销与增长/[进行中]-营销与增长模块.md | 2 +- .../运营与客服/[进行中]-运营与客服模块.md | 2 +- 36 files changed, 906 insertions(+), 1830 deletions(-) delete mode 100644 开发计划/admin-projects/.gitkeep delete mode 100644 开发计划/android-projects/.gitkeep delete mode 100644 开发计划/api-server/[进行中]-后端待完成事项清单.md delete mode 100644 开发计划/harmonyos-projects/.gitkeep delete mode 100644 开发计划/ios-projects/[进行中]-缺失项与待补全方向.md delete mode 100644 开发计划/miniapp-projects/.gitkeep delete mode 100644 开发计划/web-projects/.gitkeep delete mode 100644 开发计划/webApp-projects/.gitkeep rename 技术设计/api-server/{[设计中]-AI架构设计.md => AI架构设计.md} (95%) rename 技术设计/api-server/{[进行中]-Redis缓存设计.md => Redis缓存设计.md} (100%) rename 开发计划/api-server/[进行中]-后端开发优先级.md => 技术设计/api-server/后端开发路线图.md (94%) create mode 100644 技术设计/api-server/后端待完成事项清单.md create mode 100644 技术设计/api-server/已完成/[已完成]-后端实现状态.md create mode 100644 技术设计/api-server/已完成/[已完成]-已实现功能汇总.md rename {开发计划 => 技术设计}/api-server/已完成/[已完成]-当前状态与决策清单.md (100%) rename 技术设计/api-server/{[进行中]-架构总览.md => 架构总览.md} (97%) rename 开发计划/ios-projects/[参考]-功能需求清单.md => 技术设计/ios-projects/功能需求清单.md (88%) rename {开发计划 => 技术设计}/ios-projects/已完成/[已完成]-差距分析.md (100%) create mode 100644 技术设计/ios-projects/已完成/[已完成]-已实现功能汇总.md rename 技术设计/ios-projects/{[进行中]-架构设计.md => 架构设计.md} (72%) rename 技术设计/ios-projects/{[设计中]-登录集成.md => 登录集成.md} (100%) create mode 100644 技术设计/ios-projects/缺失项与待补全方向.md rename 技术设计/web-projects/{[设计中]-设计文档.md => 设计文档.md} (100%) create mode 100644 技术设计/总待完成清单.md rename 开发计划/[进行中]-潜在问题清单.md => 技术设计/潜在问题清单.md (100%) rename 开发计划/[进行中]-阶段路线图.md => 技术设计/阶段路线图.md (100%) diff --git a/README.md b/README.md index 640940f..67ff6b3 100644 --- a/README.md +++ b/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) | 安全基线：Helmet、CORS、JWT Guard、参数校验、限流、Swagger保护 | -| [登录流程-总览](技术设计/api-server/已完成/[已完成]-登录流程/总览.md) | 登录系统整体设计：前后端职责、Token 策略、5 个 API 接口规划 | -| [登录流程-Apple登录集成](技术设计/api-server/已完成/[已完成]-登录流程/Apple登录集成.md) | Sign in with Apple 后端实现：jose 验签、JWKS、字段信任模型 | -| [登录流程-后端接口](技术设计/api-server/已完成/[已完成]-登录流程/后端接口.md) | dev-login / refresh / logout / /users/me 四个接口的详细实现 | -| [登录流程-数据库设计](技术设计/api-server/已完成/[已完成]-登录流程/数据库设计.md) | users / auth_accounts / refresh_tokens 三表 Prisma Schema | +| [架构总览](技术设计/api-server/架构总览.md) | 模块化单体架构、技术栈、目录结构、14个业务模块、API路由规划、数据模型 | +| [后端开发路线图](技术设计/api-server/后端开发路线图.md) | 51 模块 14 层级总表 + 8 阶段开发路线 + 每个模块接口/表结构/流程详案 | +| [后端待完成事项清单](技术设计/api-server/后端待完成事项清单.md) | 当前待推进的详细任务 | +| [AI架构设计](技术设计/api-server/AI架构设计.md) | AI Provider 抽象、四层模型策略、Agent 演进路线 V0-V3 | +| [Redis缓存设计](技术设计/api-server/Redis缓存设计.md) | 缓存/队列/限流设计 | + +**已完成：** + +| 文档 | 说明 | +|------|------| +| [已实现功能汇总](技术设计/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（鸿蒙） - -> 暂无文档，预留目录。 - -### admin-projects（后台管理） - -> 暂无文档，预留目录。 - -### android-projects / webApp-projects - -> 暂无文档，预留目录。 - ---- - -## 开发计划 +| 文档 | 说明 | +|------|------| +| [已实现功能汇总](技术设计/ios-projects/已完成/[已完成]-已实现功能汇总.md) | 全部已完成功能一览：架构层、22 页面、Auth、设计系统、代码质量 | +| [样式规范](技术设计/ios-projects/已完成/[已完成]-样式规范.md) | 完整设计系统：颜色、渐变、圆角、间距、字体、29 个共享组件 | +| [页面规划](技术设计/ios-projects/已完成/[已完成]-页面规划.md) | 22 个页面完整清单 | +| [差距分析](技术设计/ios-projects/已完成/[已完成]-差距分析.md) | 现有资源盘点 + P0 任务分解 | ### 跨项目 | 文档 | 说明 | |------|------| -| [进行中-阶段路线图](开发计划/[进行中]-阶段路线图.md) | 产品 9 阶段整体路线。阶段0官网部分已完成，阶段1方向选择进行中 | -| [进行中-潜在问题清单](开发计划/[进行中]-潜在问题清单.md) | 代码和策略中已发现问题，按🔴严重/🟠高危/🟡中危分级，持续更新（最新：2026-05-15） | +| [总待完成清单](技术设计/总待完成清单.md) | **← 主文件**：后端/iOS/策略所有待完成事项，按优先级排列，链接到各详细文档 | +| [阶段路线图](技术设计/阶段路线图.md) | 产品 9 阶段整体路线 | +| [潜在问题清单](技术设计/潜在问题清单.md) | 按🔴严重/🟠高危/🟡中危分级，持续更新 | -### api-server +### web-projects（官网） | 文档 | 说明 | |------|------| -| [进行中-后端开发优先级](开发计划/api-server/[进行中]-后端开发优先级.md) | 51 模块 14 层级总表 + 8 阶段开发路线 + 每个模块接口/表结构/流程详案 | +| [设计文档](技术设计/web-projects/设计文档.md) | 官网视觉设计系统："Luminous Clarity" 玻璃拟态浅色主题 | -### ios-projects +### 预留目录 -| 文档 | 说明 | -|------|------| -| [参考-功能需求清单](开发计划/ios-projects/[参考]-功能需求清单.md) | 从 v0.1 创业计划提取的 iOS 功能需求基线 | -| [进行中-缺失项与待补全方向](开发计划/ios-projects/[进行中]-缺失项与待补全方向.md) | iOS 架构/页面/功能/设计缺失项梳理，含 P0/P1/P2 优先级 | -| [差距分析](开发计划/ios-projects/已完成/[已完成]-差距分析.md) | 两轮审计快照合并：现有资源盘点 + P0 任务分解 | - -### web-projects / android-projects / webApp-projects - -> 暂无开发计划文档，预留目录。 +`miniapp-projects` `harmonyos-projects` `admin-projects` `android-projects` `webApp-projects` — 暂无文档。 --- @@ -154,15 +129,19 @@ | 我想知道... | 看这个 | |-------------|--------| -| 后端整体怎么设计？ | [技术设计/api-server/架构总览](技术设计/api-server/[进行中]-架构总览.md) | -| 数据库有哪些表？ | [技术设计/api-server/数据库设计](技术设计/api-server/已完成/[已完成]-数据库设计.md) | -| 登录怎么做？ | [技术设计/api-server/登录流程/总览](技术设计/api-server/已完成/[已完成]-登录流程/总览.md) | -| iOS App 架构？ | [技术设计/ios-projects/架构设计](技术设计/ios-projects/[进行中]-架构设计.md) | -| 接下来做什么？ | [开发计划/阶段路线图](开发计划/[进行中]-阶段路线图.md) | -| 后端先开发哪些？ | [开发计划/api-server/后端开发优先级](开发计划/api-server/[进行中]-后端开发优先级.md) | -| iOS 还差什么？ | [开发计划/ios-projects/缺失项与待补全方向](开发计划/ios-projects/[进行中]-缺失项与待补全方向.md) | -| 有哪些已知问题？ | [开发计划/潜在问题清单](开发计划/[进行中]-潜在问题清单.md) | -| 产品方向怎么定的？ | [长期规划/产品方向深度评估](长期规划/[参考]-产品方向深度评估.md) | -| 怎么收费？ | [长期规划/商业化与支付模块](长期规划/[进行中]-商业化与支付模块.md) | -| 怎么获客？ | [长期规划/营销与增长/营销冷启动调研方案](长期规划/营销与增长/[参考]-营销冷启动调研方案.md) | -| 服务器密码、SSH密钥？ | [凭据配置/服务器凭据](凭据配置/服务器凭据.md) | +| **现在该做什么？** | [**总待完成清单**](技术设计/总待完成清单.md) | +| 后端整体怎么设计？ | [架构总览](技术设计/api-server/架构总览.md) | +| 后端完成了哪些功能？ | [已实现功能汇总](技术设计/api-server/已完成/[已完成]-已实现功能汇总.md) | +| 后端实现到什么程度了？ | [后端实现状态](技术设计/api-server/已完成/[已完成]-后端实现状态.md) | +| 后端先开发哪些？ | [后端开发路线图](技术设计/api-server/后端开发路线图.md) | +| 数据库有哪些表？ | [数据库设计](技术设计/api-server/已完成/[已完成]-数据库设计.md) | +| 登录怎么做？ | [登录流程/总览](技术设计/api-server/已完成/[已完成]-登录流程/总览.md) | +| iOS 完成了哪些功能？ | [已实现功能汇总](技术设计/ios-projects/已完成/[已完成]-已实现功能汇总.md) | +| iOS App 架构？ | [iOS架构设计](技术设计/ios-projects/架构设计.md) | +| iOS 还差什么？ | [缺失项与待补全方向](技术设计/ios-projects/缺失项与待补全方向.md) | +| 接下来做什么？ | [阶段路线图](技术设计/阶段路线图.md) | +| 有哪些已知问题？ | [潜在问题清单](技术设计/潜在问题清单.md) | +| 产品方向怎么定的？ | [产品方向深度评估](长期规划/[参考]-产品方向深度评估.md) | +| 怎么收费？ | [商业化与支付模块](长期规划/[进行中]-商业化与支付模块.md) | +| 怎么获客？ | [营销冷启动调研方案](长期规划/营销与增长/[参考]-营销冷启动调研方案.md) | +| 服务器密码、SSH密钥？ | [服务器凭据](凭据配置/服务器凭据.md) | diff --git a/开发计划/admin-projects/.gitkeep b/开发计划/admin-projects/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/开发计划/android-projects/.gitkeep b/开发计划/android-projects/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/开发计划/api-server/[进行中]-后端待完成事项清单.md b/开发计划/api-server/[进行中]-后端待完成事项清单.md deleted file mode 100644 index f97c5e6..0000000 --- a/开发计划/api-server/[进行中]-后端待完成事项清单.md +++ /dev/null @@ -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` / `Array` 迁到 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 集成 -``` diff --git a/开发计划/harmonyos-projects/.gitkeep b/开发计划/harmonyos-projects/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/开发计划/ios-projects/[进行中]-缺失项与待补全方向.md b/开发计划/ios-projects/[进行中]-缺失项与待补全方向.md deleted file mode 100644 index 8d56c01..0000000 --- a/开发计划/ios-projects/[进行中]-缺失项与待补全方向.md +++ /dev/null @@ -1,1042 +0,0 @@ -# 缺失项与待补全方向 - -> 基于 v0.1 创业计划文档与当前 iOS 代码对比分析 -> 整理时间：2026-05-10 - -本文档系统性列出知习 iOS App 当前在架构、页面、功能、设计等方面的缺失项，并给出优先级建议。 - ---- - -## 一、架构层缺失 - -### 1.1 MVVM 分层 - -**现状**：全部代码写在 SwiftUI View 中，无任何 ViewModel/ObservableObject/@Published。grep 搜索 ViewModel、ObservableObject、@Published 均为零结果。 - -**缺失**： -- 无 ViewModel 层，业务逻辑、状态管理、数据转换全部堆在 View 里 -- 无 Model 层，数据结构通过 View 内的局部 struct 或硬编码数据隐式定义 -- 代码不可测试，无法单独验证业务逻辑 - -**计划要求**（`官网与技术基础.md` 第 5.3 节）： -``` -AIStudyApp/ -├── Features/ -│ ├── Onboarding/ -│ │ ├── Views/ ← 当前有，但无 ViewModel/Model 子目录 -│ │ ├── ViewModels/ ← 缺失 -│ │ └── Models/ ← 缺失 -``` - -### 1.2 Service 层 - -**现状**：无任何 Service 类，AI 分析、学习记录、用户管理等概念没有对应的服务抽象。 - -**缺失**： -| Service | 职责 | 设计文档 | -|---------|------|----------| -| AuthService | Apple 登录、Token 管理、会话维护 | `docs/AI对话.md`（详细设计） | -| LearningService | 学习记录 CRUD、进度追踪 | — | -| AIService | AI 分析请求代理、结果解析 | — | -| ReviewService | 复习任务生成、调度 | — | -| KnowledgeService | 知识库/路径/课程查询 | — | -| FeedbackService | 用户反馈提交 | — | - -**Auth 模块已有详细文件清单**（来自 `docs/AI对话.md`）： -``` -Features/Auth/Views/LoginView.swift -Features/Auth/ViewModels/LoginViewModel.swift - -Core/Services/AuthService.swift -Core/Services/AuthServiceProtocol.swift - -Core/Storage/KeychainStore.swift -Core/Storage/TokenStore.swift - -App/AppSession.swift - -Core/Models/AuthModels.swift -Core/Models/User.swift -``` - -### 1.3 Repository 层 - -**现状**：零数据持久化，所有"数据"均为 View 中硬编码的 mock。 - -**缺失**： -- 无数据访问抽象（未来可能切换 CoreData → API，需要 Repository 隔离） -- 无本地缓存层 -- 无网络数据源层 - -### 1.4 网络层 - -**现状**：无任何网络请求代码，无 APIClient，无 URLSession 调用。 - -**缺失**： -- APIClient（封装 URLSession，注入 baseURL、header、token） -- APIEndpoint（枚举化 API 路径，统一请求构建） -- APIError（统一错误模型和处理） -- 请求/响应拦截器（日志、token 刷新） -- Mock 层（本地开发和 UI 预览用） - -### 1.5 依赖注入 - -**现状**：无任何 DI 模式，Service 和 ViewModel 尚未创建，暂时不存在注入问题。但需要在架构搭建时建立模式。 - -**建议**：初期使用构造函数注入 + `@EnvironmentObject`，避免引入第三方 DI 框架。 - ---- - -## 二、核心能力缺失 - -### 2.1 Sign in with Apple（已有详细设计文档） - -**现状**：`LoginPage` 有 UI（手机号/邮箱/微信/Apple 入口），但 `AIStudyAppApp` 仅用 `@AppStorage("hasCompletedOnboarding")` 控制是否进入主界面，无实际认证。 - -**计划要求**：第一版登录方式仅为 Sign in with Apple（`Demo与MVP.md` 第 5.2 节）。 - -**详细设计方案**见 `docs/AI对话.md`，核心结论： - -**登录页只保留一个入口**： -``` -Sign in with Apple -``` - -**删除的入口**：手机号登录、邮箱登录、微信登录、验证码登录 - -**"跳过"按钮处理**： -```swift -#if DEBUG -Button("跳过，进入演示模式") { ... } -#endif -``` -正式环境不展示跳过入口，避免后续匿名用户迁移问题。 - -**登录流程设计**： -``` -App 启动 - ↓ -AppSession 检查 Keychain 是否有 refreshToken - ↓ -有 token → 调用 /auth/refresh 或 /users/me - ↓ -成功 → 进入主界面 -失败 → 清空 token，进入登录页 - ↓ -无 token → 进入登录页 - ↓ -用户点击 Sign in with Apple - ↓ -获取 identityToken / authorizationCode / userIdentifier - ↓ -POST /api/auth/apple - ↓ -后端返回 accessToken / refreshToken / user - ↓ -token 存入 Keychain（不要 UserDefaults） - ↓ -判断 user.onboardingCompleted - ↓ -未完成 → 引导/目标设置 -已完成 → 主界面 -``` - -**登录相关新增文件**： -``` -Features/Auth/Views/LoginView.swift # 仅 Apple 登录按钮 -Features/Auth/ViewModels/LoginViewModel.swift # @MainActor, @Published isLoading/errorMessage - -Core/Services/AuthService.swift -Core/Services/AuthServiceProtocol.swift - -Core/Storage/KeychainStore.swift -Core/Storage/TokenStore.swift - -App/AppSession.swift # 全局登录状态管理 - -Core/Models/AuthModels.swift # AppleLoginRequest, AuthResponse -Core/Models/User.swift -``` - -**API Contract（Auth）**： -```swift -// 请求 -struct AppleLoginRequest: Encodable { - let identityToken: String - let authorizationCode: String? - let userIdentifier: String - let fullName: AppleFullName? - let email: String? -} - -// 响应 -struct AuthResponse: Decodable { - let accessToken: String - let refreshToken: String - let expiresIn: Int - let user: User -} -``` - -**关键约束**： -- 不再用 `@AppStorage("hasCompletedOnboarding")` 单独决定是否进入主界面 -- 登录状态必须由 `AppSession` + Keychain token 决定 -- Token 不存 UserDefaults -- View 里不写网络请求，不直接处理 Apple 登录细节 - -### 2.2 后端 API 对接 - -**现状**：所有页面为静态 UI，无任何网络请求。 - -**计划定义的 P0 API**： -- `POST /ai/analyze-learning-input` — AI 分析用户学习输入 -- `POST /ai/chat` — AI 对话 -- 用户/知识库/学习记录/反馈 CRUD - -### 2.3 真实 AI 集成 - -**现状**：AI 相关页面全为静态文本。 - -**需对接**： -- 后端 AI Provider 抽象层（MiniMax/DeepSeek/OpenAI 等） -- 结构化 JSON 输出解析 -- AI 分析结果展示（掌握度评分、优缺点、建议） -- AI 对话流式响应 - -### 2.4 本地数据持久化 - -**现状**：零持久化实现。 - -**需实现**： -- UserDefaults / @AppStorage（简单偏好） -- Keychain（Token、敏感信息） -- 后续可考虑 CoreData 或 SwiftData（学习记录离线缓存） - -### 2.5 多语言本地化 - -**现状**：所有文案硬编码在 View 中，无 Localizable.xcstrings 文件。 - -**计划要求**（`Demo与MVP.md` 第 6 节）： -- 默认简体中文 -- 预留英文 -- App UI 文案使用本地化资源 - -**需实现**： -- 创建 `Localizable.xcstrings` -- 将所有硬编码文案迁移为 `LocalizedStringKey` -- 支持语言切换 - -### 2.6 错误/加载/空状态处理 - -**现状**：无任何错误处理、加载态、空状态 UI。 - -**至少需要**： -- 网络请求 loading 指示器 -- 网络错误提示和重试按钮 -- AI 分析中的等待状态 -- 列表空状态（如知识库为空时的引导） -- 登录失败错误提示 - ---- - -## 三、页面层面差距 - -### 3.1 与计划页面对比 - -| 计划页面 | 计划优先级 | 当前状态 | 说明 | -|----------|-----------|---------|------| -| 启动页/欢迎页 | P1 | ✅ 已实现 | SplashPage + WelcomePage | -| 登录页 | P0 | ✅ 已实现 | 新 LoginView 替换旧 LoginPage，仅 Apple 登录 | -| 语言与偏好页 | P1 | ❌ 未实现 | 无页面 | -| 学习方向选择页 | P0 | ⚠️ 部分实现 | GoalSetupPage 有目标选择，但非学习方向选择 | -| 学习路径页 | P0 | ✅ 已实现 | LibraryDetailPage | -| 今日学习任务页 | P0 | ✅ 已实现 | StudyHomeView | -| 内容阅读页 | P0 | ✅ 已实现 | KnowledgeDetailPage | -| 主动回忆/笔记输入页 | P0 | ✅ 已实现 | DailyThinkingPage + RecallTestPage | -| AI 分析结果页 | P0 | ✅ 已实现 | AIFeedbackPage | -| AI 对话页 | P0 | ✅ 已实现 | AIChatPage | -| 复习计划页 | P0 | ✅ 已实现 | ReviewPlanView，含今天/明天/本周分组 + 复习类型标签 | -| 学习进度页 | P1 | ✅ 已实现 | AnalysisHomeView | -| 设置页 | P1 | ⚠️ 部分实现 | ProfileView 有设置菜单，但功能入口为空 | -| 反馈页 | P1 | ✅ 已实现 | FeedbackView + FeedbackViewModel，分类选择 + 提交确认 | - -### 3.2 复习计划页（P0 ✅） - -**计划描述**：系统生成复习任务，用户查看待复习内容，按推荐时间安排学习。 - -**当前**：已实现 `Features/Review/ReviewPlanView.swift`，含今天/明天/本周三组、复习类型标签（间隔重复/费曼/回忆/薄弱）、完成勾选、播放按钮。数据层使用 `ReviewTask` Model + mock 数据。 - -**待对接**：接入 ReviewService 后端数据。 - -### 3.3 反馈页（P1 ✅） - -**计划描述**：App 内反馈入口，让内测用户提交问题和建议。 - -**当前**：已实现 `Features/Feedback/FeedbackView.swift` + `FeedbackViewModel.swift`，含 4 类反馈分类（Bug/功能建议/内容问题/其他）的图标选择器、文本描述输入、提交通知。入口位于 ProfileView 菜单末项。 - -**待对接**：接入后端 `/feedback` API（FeedbackService）。 - -### 3.4 等待名单入口 - -**计划**：官网 `/waitlist` 页面收集用户，App 内也需要引导用户加入等待名单/申请内测。 - -**需考虑**：是否在 App 内嵌等待名单入口（如 Welcome 页或设置页）。 - ---- - -## 四、设计与交互差距 - -### 4.1 Tab 结构调整 - -**计划设计**：4 个 Tab — 学习 | 知识库 | AI助手 | 我的 - -**当前实现**：5 个 Tab — AI | 知识库 | 学习 | 分析 | 我的 - -**差异分析**： -- 当前把"学习"和"分析"拆成了两个独立 Tab -- 计划把"AI助手"独立为一个 Tab，当前 AI 已是独立 Tab -- "分析"在计划中属于"学习"Tab 下的子页面，不需要顶层 Tab - -**建议**（两种方案）： -- **方案 A**：完全对齐计划 → 合并学习和分析为一个 Tab，保持 4 Tab -- **方案 B**：保留 5 Tab 结构 → 更新计划文档，论证"分析"独立为 Tab 的合理性（学习数据可视化、学习进度监控是独立价值） - -### 4.2 登录流程简化（已有详细设计） - -**计划要求**：仅 Sign in with Apple，不做手机号/邮箱/微信登录。 - -**当前 UI**：包含 4 种登录方式入口。 - -**最终方案**（详见 `docs/AI对话.md`）： -- 登录页只保留 Sign in with Apple 一个按钮 -- 删除手机号、邮箱、微信、验证码登录 -- 跳过按钮仅限 `#if DEBUG`，Release 不展示 -- 登录页文案极简：品牌 + 一句话价值主张 + Apple 登录按钮 + 协议入口 - -### 4.3 浅色/深色模式双主题（P1 新增）✅ 已完成 - -**实现方式**： - -| 改造项 | 状态 | -|--------|------| -| `Color(light:dark:)` 自适应 helper | ✅ `DesignTokens.swift` 新增基于 `UITraitCollection.userInterfaceStyle` 的动态颜色 | -| 28 个颜色 token 双主题化 | ✅ 背景(4) + 文字(9) + 边框(5) + 填充(6) + 品牌色/彩色半透不变 | -| 渐变自适应 | ✅ `page`/`splash` 渐变改用自适应 Color token | -| 硬编码色值替换 | ✅ 13 处内联 `Color(hex:)` 替换为自适应 token | -| ColorSchemeManager | ✅ `Core/Appearance/ColorSchemeManager.swift`，@AppStorage 持久化，支持系统/浅色/深色 | -| 移除强制深色 | ✅ 移除 4 处 `.preferredColorScheme(.dark)` | -| 设置页切换入口 | ✅ ProfileView 外观行改为可点击，confirmationDialog 三选一 | - -**文件变更**： -- 新增：`Core/Appearance/ColorSchemeManager.swift` -- 修改：`DesignTokens.swift`（颜色全量自适应 + 渐变） -- 修改：`AIStudyAppApp.swift`（根视图用 manager 控制 scheme） -- 修改：`ContentView.swift`、`LoginView.swift`（移除强制暗黑） -- 修改：`ProfileView.swift`（外观切换入口） -- 修改：`SplashPage.swift`、`ZXTabBar.swift`、`ZXAIInteractionRow.swift`、`ZXChartView.swift`、`AIFeedbackPage.swift`、`WelcomePage.swift`、`OnboardingPage.swift`、`GoalSetupPage.swift`、`ZXSTaskRow.swift`、`ZXIconBtn.swift`（内联色值→token） - -### 4.4 语言系统（P1 新增） - -**现状**：所有文案硬编码中文在 SwiftUI View 中，无 Localizable.strings。 - -**要求**：先只支持中文，但搭建好本地化基础设施，后续加语言时只需加翻译文件。 - -**需实现**： - -| 步骤 | 说明 | -|------|------| -| 创建 `Localizable.strings` (Base) | 中文作为 Base 语言，不设 `zh-Hans` | -| 封装 `ZXLocalized` 辅助 | `String(localized:)` + `Text("key")` 的 SwiftUI 原生方式 | -| 迁移硬编码文案 | 逐文件将文案替换为 LocalizedStringKey | -| 设置页语言入口 | 预留语言切换 UI，当前仅显示"中文" | - -### 4.5 无障碍 - -**现状**：未考虑 VoiceOver、Dynamic Type、高对比度等无障碍需求。 - -**至少需做**： -- 关键按钮添加 `.accessibilityLabel` -- 确保 Dynamic Type 下布局不破碎 -- 重点页面 VoiceOver 测试 - -### 4.6 样式规范 - -已于 `docs/样式规范.md` 中梳理完整的样式规范文档，涵盖： -- 色彩系统（背景/文字/品牌语义色/边框/填充） -- 渐变体系（页面、品牌、卡片、进度条、CTA 等 11 组渐变） -- 圆角、间距、尺寸 token -- 字体层级（12 级定义） -- 共享组件目录（20+ 组件，含导航、按钮、卡片行、数据展示、输入、标签等） -- 页面布局模式（主 Tab 页、子页面、卡片、输入框、状态标签的标准写法） -- 设计决策与约束 - -**后续新页面必须遵循 `docs/样式规范.md`**，复用已有组件和 token，禁止随意使用内联颜色/间距/字体。 - -### 4.7 动效 - -**计划要求**（`官网与技术基础.md` 第 6.3 节）： -- P0：页面过渡、按钮反馈、加载状态、AI 分析中状态、学习完成反馈 -- P1：今日任务卡片动效、进度条更新、AI 结果分块出现 - -**当前**：仅有基础 SwiftUI 隐式动画（withAnimation），未实现任何计划中的动效。 - ---- - -## 五、数据层缺失 - -### 5.1 Model 定义 - -**现状**：所有数据通过 View 内局部变量或硬编码定义，无独立 Model 文件。 - -**计划中定义的核心实体**（`Demo与MVP.md`）： - -``` -User -├── id, appleUserId, displayName, email -├── preferredLanguage, createdAt, lastLoginAt, status - -KnowledgeBase -├── id, title, description, language, targetUser -├── createdAt, updatedAt - -LearningPath -├── id, knowledgeBaseId, title, description -├── estimatedDays, order - -Lesson -├── id, pathId, title, content, objectives -├── keyPoints, recallQuestions, practicePrompt -├── order, estimatedMinutes - -LearningSession -├── id, userId, lessonId -├── startedAt, endedAt, userInput -├── aiAnalysis, masteryScore, weakPoints -├── nextSuggestion, reviewAt - -AIAnalysis -├── id, userId, sessionId -├── inputText, outputJson, masteryScore -├── weakPoints, suggestions -├── modelName, createdAt, costEstimate - -ReviewTask -├── id, userId, lessonId, sourceSessionId -├── reviewType, scheduledAt, completedAt, status - -Feedback -UserLearningProfile -``` - -**需实现**：在 `Features/*/Models/` 下创建对应的 Swift struct（需 Codable、Identifiable）。 - -### 5.2 API Contract - -**现状**：无 API 类型定义。 - -**建议**：参考计划中定义的 JSON 结构，先创建 Swift Model，再定义 API 请求/响应类型（Request/Response struct），实现前后端类型同构。 - -### 5.3 数据流规范 - -**现状**：View 直接持有 @State，无数据流管理。 - -**建议**： -- ViewModel 持有 @Published 状态 -- ViewModel 通过 Service 获取数据 -- Service 通过 Repository 访问数据源 -- View 通过 @StateObject / @ObservedObject 绑定 ViewModel - ---- - -## 六、工程化缺失 - -### 6.1 大文件拆分 ✅ - -**已完成**： - -| 原文件 | 拆分结果 | -|--------|----------| -| `AIStudyAppApp.swift` (~190行) | 保留 App/Root/OnboardingFlowView，页面移入 `Features/Onboarding/` | -| `DailyThinkingPage.swift` (~200行) | 拆为 5 个文件（DailyThinking / RecallTest / WeakPoints / AIFeedback / AIChat） | -| `LibrarySubpages.swift` (~112行) | 已删除，拆为 6 个独立页面文件 | - -### 6.2 共享组件管理 ✅ - -**已完成**：20 个共享组件集中到 `Shared/Components/`，原文件中的定义已移除。 - -``` -Shared/Components/ -├── ZXTabBar.swift ├── ZXBackHeader.swift -├── ZXIconBtn.swift ├── ZXScoreBox.swift -├── ZXAIInputBar.swift ├── ZXOutlineBtn.swift -├── ZXQuickAction.swift ├── ZXAIInteractionRow.swift -├── ZXCardRow.swift ├── ZXChip.swift -├── ZXImportOption.swift ├── ZXWeakRow.swift -├── ZXStatBadge.swift ├── ZXProfileStat.swift -├── ZXProfileMenuRow.swift ├── ZXAchievementBadge.swift -├── ZXChartView.swift ├── ZXSTaskRow.swift -├── FeatureRow.swift ├── ReviewTaskRow.swift -├── ZXLoadingView.swift ├── ZXErrorView.swift -└── ZXEmptyView.swift -``` - -### 6.3 测试 - -**现状**：无任何测试代码。 - -**至少需要**： -- ViewModel 单元测试（当 ViewModel 创建后） -- Service 层单元测试（Mock Repository） -- 关键 UI 流程的 Snapshot 测试 - -### 6.4 CI/CD - -**现状**：无。 - -**建议**（后续）： -- GitHub Actions / Xcode Cloud 自动构建 -- TestFlight 自动分发 - -### 6.5 崩溃监控与埋点 - -**现状**：无。 - -**建议**：接入 Firebase Crashlytics 或类似服务，至少在 TestFlight 阶段要有崩溃收集能力。 - ---- - -## 七、优先级建议 - -### P0 — 必须在接后端前完成 - -| 步骤 | 项目 | 理由 | 设计文档 | -|------|------|------|----------| -| ① | 创建 Auth Model（AuthModels + User） | 所有后续步骤的数据基础 | 第十章 步骤 1 ✅ | -| ② | 实现 Keychain 存储层 | Token 安全存储是登录的前提 | 第十章 步骤 2 ✅ | -| ③ | 搭建网络层最小实现（APIClient） | 所有后端交互的唯一通道 | 第十章 步骤 3 ✅ | -| ④ | 实现 AuthService（Apple 登录 + 后端调用） | 用户身份是学习记录的前提 | `docs/AI对话.md`、第十章 步骤 4 ✅ | -| ⑤ | 实现 AppSession（全局登录状态） | 统一的登录态管理 | 第十章 步骤 5 ✅ | -| ⑥ | 实现 LoginView + LoginViewModel | 替换当前过度实现的登录页 | `docs/AI对话.md`、第十章 步骤 6 ✅ | -| ⑦ | 改造 App 入口启动逻辑 | Token 分流替换 @AppStorage | 第十章 步骤 7 ✅ | -| — | 创建 Model 层（其余数据实体） | 是 Service/ViewModel/API 的基础 | 本文档 5.1 节 ✅ | -| — | 实现复习计划独立页 | 计划标记 P0 | ✅ | -| — | 拆分大文件 + 集中共享组件 | 降低后续修改的认知负担 | 本文档 6.1/6.2 节 ✅ | -| — | 添加加载/错误/空状态处理 | 真机使用的基本体验保障 | `Shared/Components/` (ZXLoadingView, ZXErrorView, ZXEmptyView) ✅ | - -### P1 — 与后端对接同步推进 - -| 优先级 | 项目 | 理由 | -|--------|------|------| -| P1 | 浅色/深色模式双主题 | 覆盖所有页面和 DesignTokens，工作量较大 ✅ | -| P1 | 语言系统搭建（中文 Base） | 先建基础设施，后续加语言不返工 ✅ | -| P1 | 搭建 ViewModel 层（逐步迁移） | 架构分层，但不阻塞功能开发 ✅ | -| P1 | 搭建 Service 层 | 随 API 对接自然建立 ✅ | -| P1 | 实现反馈页 | TestFlight 内测必须 ✅ | -| P1 | 实现设置页完整功能 | 外观切换、语言入口、复习提醒等 ✅ | - -### P2 — App Store 前完成 - -| 优先级 | 项目 | 理由 | -|--------|------|------| -| P2 | Repository 层 | 当需要本地缓存 + 网络切换时再做 ✅ | -| P2 | 动效补充 | 体验优化，不阻塞功能 ✅ | -| P2 | 无障碍适配 | App Store 审核加分项 ✅ | -| P2 | 测试 | 用户量增长后需要 ✅ | -| P2 | Tab 结构调整决策 | 需要更多用户反馈来决策 ✅ | - -### Tab 结构分析 - -**当前 5-Tab 结构**： - -| Tab | 页面 | 核心功能 | -|-----|------|----------| -| AI | AIHomeView | AI 对话入口 + 每日思考 + 薄弱点 | -| 知识库 | LibraryHomeView | 知识库浏览 + 导入 + 搜索 | -| 学习 | StudyHomeView | 今日任务 + 进度 + 每周活跃 | -| 分析 | AnalysisHomeView | 学习时长 + 掌握度 + 雷达图 | -| 我的 | ProfileView | 个人信息 + 设置 + 成就 | - -**问题诊断**： -1. **AI 与学习边界模糊** — AI 对话产生学习记录，但学习任务在独立 Tab，用户需要在两个 Tab 间切换 -2. **分析 Tab 内容单薄** — 纯展示仪表盘，无交互深度，与"学习"Tab 的进度卡片有重叠 -3. **知识库入口过重** — 知识库本质是学习的前置步骤，独立 Tab 使其脱离学习流程 - -**可选方案**： - -| 方案 | 结构 | 优点 | 缺点 | -|------|------|------|------| -| A: 保持现状 | 5 Tab 不变 | 无改动成本 | 上述问题持续 | -| B: 合并 AI+学习 | 4 Tab（学习/AI、知识库、分析、我的） | AI 与学习一体化 | 需重设计学习首页 | -| C: 合并分析入学习 | 4 Tab（AI、知识库、学习+分析、我的） | 分析数据有上下文 | 学习页信息密度增加 | -| D: 精简 3 Tab | 3 Tab（学习、知识库、我的） | 最简洁，AI 内嵌学习 | 分析页降级为次级入口 | - -**建议**：MVP 阶段保持方案 A，收集用户反馈后优先尝试方案 C（分析并入学习）。触发条件：分析 Tab 的周活跃用户 < 20%。 - ---- - -## 八、总结 - -当前 iOS 项目完成了 UI 层的全量搭建（21 页），但缺少"能让产品真正运转"的架构底座和数据能力。核心矛盾是： - -> UI 超前，架构滞后。页面能点，但无数据、无认证、无 AI、无服务。 - -### 当前进度（2026-05-10） - -**P0 — 全部完成 ✅**： -1. ✅ Apple 登录 + Auth 体系（9 个文件） -2. ✅ Model 层（10 个数据实体） -3. ✅ 网络层最小实现（APIClient + Endpoint + Error） -4. ✅ App 入口重构（AppSession 驱动路由，替代 @AppStorage） -5. ✅ 复习计划独立页（ReviewPlanView） -6. ✅ 大文件拆分（3 个大文件拆为 15+ 个独立文件） -7. ✅ 共享组件集中管理（`Shared/Components/` 下 20+ 个组件） -8. ✅ 加载/错误/空状态处理（ZXLoadingView / ZXErrorView / ZXEmptyView） - -**P1 — 部分完成**： -- ✅ 浅色/深色模式双主题（DesignTokens 自适应 + ColorSchemeManager + 移除强制暗黑） -- ✅ 语言系统搭建（中文 Base，Localizable.strings + ZXStrings + LanguageManager） -- ✅ 搭建 ViewModel 层（ReviewPlanViewModel + AIChatViewModel + StudyHomeViewModel） -- ✅ 搭建 Service 层（5 个 Service 协议 + 实现 + 20 个 APIEndpoint） -- ✅ 实现反馈页（TestFlight 内测必须） -- ✅ 设置页外观切换（ColorSchemeManager + ProfileView confirmationDialog） -- ✅ 设置页完整功能（5 个子页面 + 外观/语言切换） - -**接下来推荐顺序**： - -``` -1. 语言系统搭建（基础设施优先，避免后续返工） - ├── 创建 Localizable.strings (Base = 中文) - ├── 迁移硬编码文案到 LocalizedStringKey - └── 设置页预留语言入口（当前仅显示中文） - ↓ -2. 浅色/深色模式双主题（体验升级，需全量回归） - ├── DesignTokens 定义 light/dark 双套色值 - ├── 替换所有内联 Color(hex:) 为 token 引用 - ├── 设置页新增外观切换（跟随系统 / 浅色 / 深色） - └── 全页面浅色模式验证 - ↓ -3. 反馈页 + 设置页补全（独立页面，不依赖其他改造） - ↓ -4. ViewModel 层迁移（逐步，不阻塞功能） - ↓ -5. Service 层搭建（随 API 对接自然建立） -``` - ---- - -## 九、AI对话.md 登录方案摘要 - -> `docs/AI对话.md` 是登录模块的详细实现规范。以下为关键决策的结构化提取，便于对照实施。 - -### 9.1 登录入口决策 - -**第一版只保留**： -``` -Sign in with Apple -``` - -**删除这些入口**： -- 手机号登录 / 邮箱登录 / 微信登录 / 验证码登录 - -**"跳过"按钮**： -- `#if DEBUG` 保留，Release 不展示 -- 理由：避免匿名用户后续迁移（学习记录、AI 分析绑定用户身份） - -### 9.2 登录页内容 - -``` -知习 - -更懂你，更会学。 - -用 AI 把知识库、主动回忆和间隔复习连接起来， -从"看过"走向"真正学会"。 - -[ Sign in with Apple ] - -登录即代表你同意《用户服务协议》和《隐私政策》 -``` - -### 9.3 完整登录流程 - -``` -App 启动 - ↓ -AppSession 检查 Keychain 是否有 refreshToken - ↓ -有 token → 调用 /auth/refresh 或 /users/me - ├─ 成功 → 进入主界面 - └─ 失败 → 清空 token，进入登录页 - ↓ -无 token → 进入登录页 - ↓ -用户点击 Sign in with Apple - ↓ -ASAuthorizationController 获取： - · identityToken - · authorizationCode - · userIdentifier - · email / fullName（Apple 可能不返回） - ↓ -POST /api/auth/apple - ↓ -后端返回 { accessToken, refreshToken, expiresIn, user } - ↓ -accessToken / refreshToken 存入 Keychain - ↓ -判断 user.onboardingCompleted - ├─ false → 引导页 / 学习目标设置 - └─ true → 主界面（ContentView） -``` - -### 9.4 需要新增的 9 个文件 - -| 层 | 文件 | 职责 | -|----|------|------| -| Model | `Core/Models/AuthModels.swift` | AppleLoginRequest、AuthResponse 等 Codable struct | -| Model | `Core/Models/User.swift` | 用户实体 | -| Storage | `Core/Storage/KeychainStore.swift` | 通用 Keychain 读写封装 | -| Storage | `Core/Storage/TokenStore.swift` | Token 专用存取（save/load/clear） | -| Service | `Core/Services/AuthServiceProtocol.swift` | AuthService 协议定义 | -| Service | `Core/Services/AuthService.swift` | ASAuthorizationController 集成 + 后端调用 | -| App | `App/AppSession.swift` | @MainActor 全局登录状态 | -| View | `Features/Auth/Views/LoginView.swift` | 纯 Apple 登录按钮 UI | -| ViewModel | `Features/Auth/ViewModels/LoginViewModel.swift` | @Published isLoading/errorMessage | - -### 9.5 API Contract - -```swift -// 请求 → POST /api/auth/apple -struct AppleLoginRequest: Encodable { - let identityToken: String - let authorizationCode: String? - let userIdentifier: String - let fullName: AppleFullName? - let email: String? -} - -struct AppleFullName: Encodable { - let givenName: String? - let familyName: String? -} - -// 响应 -struct AuthResponse: Decodable { - let accessToken: String - let refreshToken: String - let expiresIn: Int - let user: User -} -``` - -### 9.6 关键约束 - -| 约束 | 说明 | -|------|------| -| Token 存 Keychain | 不存 UserDefaults | -| 不用 @AppStorage 控制登录 | 登录状态由 AppSession + Keychain token 决定 | -| View 不写网络请求 | 网络调用在 Service 层 | -| View 不处理 Apple 登录细节 | ASAuthorizationController 逻辑在 AuthService | -| 不改变现有主页面 UI | 只替换入口路由逻辑 | - ---- - -## 十、登录模块可行实施计划 - -以下是按依赖关系排列的 7 个实施步骤。每步独立可验证，后一步依赖前一步完成。 - -### 整体依赖图 - -``` -步骤1: Model ─────────────────────────────────────────┐ - ↓ │ -步骤2: KeychainStore / TokenStore ────────────────────┤ - ↓ │ -步骤4: APIClient / APIEndpoint ─┐ │ - ↓ │ │ -步骤3: AuthService ←────────────┘ │ - ↓ │ -步骤5: AppSession ─────────────────────────────────────┤ - ↓ │ -步骤6: LoginView + LoginViewModel ────────────────────┘ - ↓ -步骤7: 改造 App 入口启动逻辑（AIStudyAppApp.swift） -``` - ---- - -### 步骤 1：创建 Auth Model ✅ 已完成（2026-05-10） - -**产出文件**： -- `Core/Models/AuthModels.swift` -- `Core/Models/User.swift` - -**内容**： -```swift -// AuthModels.swift -struct AppleLoginRequest: Encodable { ... } -struct AppleFullName: Encodable { ... } -struct AuthResponse: Decodable { ... } - -// User.swift -struct User: Codable, Identifiable { - let id: String - let appleUserId: String - let displayName: String? - let email: String? - let preferredLanguage: String - let onboardingCompleted: Bool - let createdAt: String - let lastLoginAt: String? - let status: String -} -``` - -**依赖**：无 - -**验证**：Xcode 编译通过 - ---- - -### 步骤 2：实现 Keychain 存储层 ✅ 已完成（2026-05-10） - -**产出文件**： -- `Core/Storage/KeychainStore.swift` -- `Core/Storage/TokenStore.swift` - -**KeychainStore 职责**：通用 Keychain 读写，封装 `SecItemAdd`/`SecItemCopyMatching`/`SecItemDelete`，支持 save/load/delete 操作。 - -**TokenStore 职责**： -```swift -protocol TokenStoreProtocol { - func saveAccessToken(_ token: String) throws - func getAccessToken() throws -> String? - func saveRefreshToken(_ token: String) throws - func getRefreshToken() throws -> String? - func clearAll() throws -} -``` - -**依赖**：步骤 1（Model 定义，具体来说不需要 Model 依赖，TokenStore 操作的是原始 String） - -**验证**：可写简单单元测试验证存取清除 - ---- - -### 步骤 3：搭建网络层最小实现 ✅ 已完成（2026-05-10） - -> 注意：这一步和 AuthService 互相依赖——AuthService 需要 APIClient 发请求，但可以先建网络层骨架。做的时候步骤 3 和 4 可以部分并行：先建 APIClient 基础，再写 AuthService 时补充 Auth 相关 endpoint。 - -**产出文件**： -- `Core/Network/APIClient.swift` -- `Core/Network/APIEndpoint.swift` -- `Core/Network/APIError.swift` - -**最小接口**： -```swift -// APIClient -class APIClient { - init(baseURL: URL, tokenStore: TokenStoreProtocol?) - func request(_ endpoint: APIEndpoint) async throws -> T - func requestVoid(_ endpoint: APIEndpoint) async throws -} - -// APIEndpoint -enum APIEndpoint { - case appleLogin(AppleLoginRequest) - case refreshToken(String) - case me - // 后续扩展其他 endpoint -} - -// APIError -enum APIError: Error { - case network(Error) - case httpError(Int) - case decoding(Error) - case unauthorized -} -``` - -**依赖**：步骤 1（Model）、步骤 2（TokenStore） - -**验证**：Xcode 编译通过，可以先 mock 一个请求验证 pipeline 跑通 - ---- - -### 步骤 4：实现 AuthService ✅ 已完成（2026-05-10） - -**产出文件**： -- `Core/Services/AuthServiceProtocol.swift` -- `Core/Services/AuthService.swift` - -**AuthServiceProtocol**： -```swift -protocol AuthServiceProtocol { - func loginWithApple() async throws -> AuthResponse - func refreshSession() async throws -> AuthResponse - func logout() async throws - func fetchCurrentUser() async throws -> User -} -``` - -**AuthService 实现要点**： -1. 集成 `ASAuthorizationController`（需 `import AuthenticationServices`） -2. 获取 identityToken、authorizationCode、userIdentifier -3. 调用 `APIClient.request(.appleLogin(request))` -4. 将返回的 token 写入 TokenStore -5. refreshSession：用 refreshToken 换新 token - -**依赖**：步骤 1（AuthModels）、步骤 2（TokenStore）、步骤 3（APIClient） - -**验证**：Xcode 编译通过，可在模拟器点击 Apple 登录（后端未就绪时用 mock） - ---- - -### 步骤 5：实现 AppSession ✅ 已完成（2026-05-10） - -**产出文件**： -- `App/AppSession.swift` - -**关键代码骨架**： -```swift -@MainActor -final class AppSession: ObservableObject { - @Published var currentUser: User? - @Published var isAuthenticated = false - @Published var isLoading = true - @Published var authError: String? - - private let authService: AuthServiceProtocol - private let tokenStore: TokenStoreProtocol - - func bootstrap() async { - // 1. 检查 Keychain 是否有 refreshToken - // 2. 有 → 调用 refreshSession() - // 3. 成功 → isAuthenticated=true, currentUser=user - // 4. 失败 → 清空 token, isAuthenticated=false - // 5. 无 → isAuthenticated=false - // 6. isLoading = false - } - - func loginWithApple() async { ... } - func logout() { ... } -} -``` - -**依赖**：步骤 4（AuthService）、步骤 2（TokenStore） - -**验证**：模拟器启动时可根据 Keychain 状态正确分流 - ---- - -### 步骤 6：实现 LoginView + LoginViewModel ✅ 已完成（2026-05-10） - -**产出文件**： -- `Features/Auth/Views/LoginView.swift` -- `Features/Auth/ViewModels/LoginViewModel.swift` - -**LoginView**： -- 品牌标题"知习" + 副标题 -- Sign in with Apple 按钮（ASAuthorizationAppleIDButton） -- Loading 状态（ProgressView） -- Error 提示 -- `#if DEBUG` 跳过按钮 -- 协议入口链接 - -**LoginViewModel**： -```swift -@MainActor -final class LoginViewModel: ObservableObject { - @Published var isLoading = false - @Published var errorMessage: String? - - func loginWithApple() async { - isLoading = true - errorMessage = nil - do { - try await appSession.loginWithApple() - } catch { - errorMessage = "登录失败：\(error.localizedDescription)" - isLoading = false - } - } -} -``` - -**依赖**：步骤 5（AppSession） - -**验证**：模拟器显示登录页，点击 Apple 登录按钮触发流程，loading 状态可展示 - ---- - -### 步骤 7：改造 App 入口启动逻辑 ✅ 已完成（2026-05-10） - -**修改文件**：`AIStudyAppApp.swift` - -**改动要点**： -1. 注入 `AppSession` 为 `@StateObject` -2. 启动时调用 `appSession.bootstrap()` -3. 用 `appSession.isLoading / isAuthenticated / currentUser?.onboardingCompleted` 替换原来的 `@AppStorage("hasCompletedOnboarding")` -4. 路由逻辑： - ``` - isLoading → Splash（启动加载中） - !isAuthenticated → LoginView - onboardingCompleted == false → OnboardingFlowView - onboardingCompleted == true → ContentView - ``` - -**依赖**：步骤 1-6 全部完成 - -**验证**：完整启动流程测试—— -- 首次启动 → 登录页 → Apple 登录（mock） → 引导页 → 目标设置 → 主界面 -- 二次启动（有有效 token）→ 直接进主界面 -- Token 过期 → 登录页 - ---- - -### 实施俯视图 - -``` -步骤 1 ──→ 步骤 2 ──→ 步骤 3 ──→ 步骤 4 ──→ 步骤 5 ──→ 步骤 6 ──→ 步骤 7 -Model Keychain 网络层 AuthSvc AppSession LoginUI 入口改造 -(0依赖) (无依赖) (依赖1,2) (依赖1-3) (依赖2,4) (依赖5) (依赖1-6) -``` - -每一步均可独立编译验证。后端 API 未就绪时，步骤 4-7 可以用 mock 数据先行开发，后端就绪后仅替换 APIClient 的真实 endpoint。 - -### 文件目录结构（完成后） - -``` -AIStudyApp/ -├── App/ -│ └── AppSession.swift ← 新增 -├── Core/ -│ ├── Models/ -│ │ ├── AuthModels.swift ← 新增 -│ │ └── User.swift ← 新增 -│ ├── Network/ -│ │ ├── APIClient.swift ← 新增 -│ │ ├── APIEndpoint.swift ← 新增 -│ │ └── APIError.swift ← 新增 -│ ├── Services/ -│ │ ├── AuthServiceProtocol.swift ← 新增 -│ │ └── AuthService.swift ← 新增 -│ ├── Storage/ -│ │ ├── KeychainStore.swift ← 新增 -│ │ └── TokenStore.swift ← 新增 -│ └── DesignSystem/ -│ └── DesignTokens.swift （已有，不变） -├── Features/ -│ ├── Auth/ -│ │ ├── Views/ -│ │ │ └── LoginView.swift ← 新增 -│ │ └── ViewModels/ -│ │ └── LoginViewModel.swift ← 新增 -│ ├── AI/ （已有） -│ ├── Library/ （已有） -│ ├── Study/ （已有） -│ ├── Analysis/ （已有） -│ └── Profile/ （已有） -└── AIStudyAppApp.swift ← 修改 -``` diff --git a/开发计划/miniapp-projects/.gitkeep b/开发计划/miniapp-projects/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/开发计划/web-projects/.gitkeep b/开发计划/web-projects/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/开发计划/webApp-projects/.gitkeep b/开发计划/webApp-projects/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/技术设计/api-server/[设计中]-AI架构设计.md b/技术设计/api-server/AI架构设计.md similarity index 95% rename from 技术设计/api-server/[设计中]-AI架构设计.md rename to 技术设计/api-server/AI架构设计.md index 69abf85..dcf8dd5 100644 --- a/技术设计/api-server/[设计中]-AI架构设计.md +++ b/技术设计/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 ## 一、核心原则 diff --git a/技术设计/api-server/[进行中]-Redis缓存设计.md b/技术设计/api-server/Redis缓存设计.md similarity index 100% rename from 技术设计/api-server/[进行中]-Redis缓存设计.md rename to 技术设计/api-server/Redis缓存设计.md diff --git a/开发计划/api-server/[进行中]-后端开发优先级.md b/技术设计/api-server/后端开发路线图.md similarity index 94% rename from 开发计划/api-server/[进行中]-后端开发优先级.md rename to 技术设计/api-server/后端开发路线图.md index 9c00088..5a9cc7c 100644 --- a/开发计划/api-server/[进行中]-后端开发优先级.md +++ b/技术设计/api-server/后端开发路线图.md @@ -7,57 +7,57 @@ ## 总优先级总表 -| 优先级 | 层级 | 核心模块 | -|--------|------|----------| -| P0 | 后端地基 | 安全配置、数据库(Prisma+MySQL)、统一工程规范(响应/错误/DTO/Guard) | -| P1 | 身份权限 | Auth(Apple/Refresh/Logout)、Users、Role、Resource Permission | -| P2 | 知识系统 | KnowledgeBase、KnowledgeItem、Tag、Search | -| P3 | 学习闭环 | LearningSession、ActiveRecall、AIAnalysis、FocusItem、Review、LearningActivity | -| P4 | AI 基础设施 | AIGateway、PromptTemplate、AIUsageLog、AIQuota、AIWorkflow | -| P5 | 文件导入 | File/Storage、DocumentImport、KnowledgeGeneration | -| P6 | 商业化 | Plans、Membership、Subscription(Apple IAP)、Payment、Refund | -| P7 | 用户 Web 后台 | Web Console、批量上传/导入/导出 | -| P8 | 管理员后台 | Admin Users、Admin Knowledge、AI Cost、Feedback、Audit Log | -| P9 | 客服反馈 | Feedback、SupportTicket、Dify 智能客服、HelpCenter | -| P10 | 通知任务 | Notifications、Push(APNs)、BullMQ Worker、Scheduler | -| P11 | 学习画像 | LearningAnalytics、UserLearningProfile、LearningReport | -| P12 | 公开分享 | Visibility、ShareLink、Public Knowledge | -| P13 | 合规配置 | SystemConfig、Privacy、Delete Account、Data Export | -| P14 | 增长归因 | Attribution、ProductAnalytics、Campaign Tracking | +| 优先级 | 层级 | 核心模块 | 状态 | +|--------|------|----------|------| +| P0 | 后端地基 | 安全配置、数据库(Prisma+MySQL)、统一工程规范(响应/错误/DTO/Guard) | ✅ | +| P1 | 身份权限 | Auth(Apple/Refresh/Logout)、Users、Role、Resource Permission | ✅ | +| P2 | 知识系统 | KnowledgeBase、KnowledgeItem、Tag、Search | ✅（Tag/Search 待补） | +| P3 | 学习闭环 | LearningSession、ActiveRecall、AIAnalysis、FocusItem、Review、LearningActivity | ✅ | +| P4 | AI 基础设施 | AIGateway、PromptTemplate、AIUsageLog、AIQuota、AIWorkflow | 🔶 1/5 Workflow | +| P5 | 文件导入 | File/Storage、DocumentImport、KnowledgeGeneration | 🔶 DB 层完成 | +| P6 | 商业化 | Plans、Membership、Subscription(Apple IAP)、Payment、Refund | ⏳ | +| P7 | 用户 Web 后台 | Web Console、批量上传/导入/导出 | ⏳ | +| P8 | 管理员后台 | Admin Users、Admin Knowledge、AI Cost、Feedback、Audit Log | ⏳ | +| P9 | 客服反馈 | Feedback、SupportTicket、Dify 智能客服、HelpCenter | 🔶 Feedback ✅ | +| P10 | 通知任务 | Notifications、Push(APNs)、BullMQ Worker、Scheduler | 🔶 Notifications ✅ | +| P11 | 学习画像 | LearningAnalytics、UserLearningProfile、LearningReport | ⏳ | +| P12 | 公开分享 | Visibility、ShareLink、Public Knowledge | ⏳ | +| P13 | 合规配置 | SystemConfig、Privacy、Delete Account、Data Export | ⏳ | +| 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()` 保护。 + 优先级：最高。 先做两层权限。 diff --git a/技术设计/api-server/后端待完成事项清单.md b/技术设计/api-server/后端待完成事项清单.md new file mode 100644 index 0000000..dc1f147 --- /dev/null +++ b/技术设计/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 文件存储接入 +``` diff --git a/技术设计/api-server/已完成/[已完成]-后端实现状态.md b/技术设计/api-server/已完成/[已完成]-后端实现状态.md new file mode 100644 index 0000000..f26a3e0 --- /dev/null +++ b/技术设计/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 + 审计日志 diff --git a/技术设计/api-server/已完成/[已完成]-安全规范.md b/技术设计/api-server/已完成/[已完成]-安全规范.md index bc2e1ca..f473048 100644 --- a/技术设计/api-server/已完成/[已完成]-安全规范.md +++ b/技术设计/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` 归属： diff --git a/技术设计/api-server/已完成/[已完成]-已实现功能汇总.md b/技术设计/api-server/已完成/[已完成]-已实现功能汇总.md new file mode 100644 index 0000000..ea0b860 --- /dev/null +++ b/技术设计/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` / `Array` 内存存储 +- 所有 `generateShortId()` 调用 +- 所有 `OnModuleInit` 种子假数据 +- 所有 `'anonymous'` fallback diff --git a/开发计划/api-server/已完成/[已完成]-当前状态与决策清单.md b/技术设计/api-server/已完成/[已完成]-当前状态与决策清单.md similarity index 100% rename from 开发计划/api-server/已完成/[已完成]-当前状态与决策清单.md rename to 技术设计/api-server/已完成/[已完成]-当前状态与决策清单.md diff --git a/技术设计/api-server/[进行中]-架构总览.md b/技术设计/api-server/架构总览.md similarity index 97% rename from 技术设计/api-server/[进行中]-架构总览.md rename to 技术设计/api-server/架构总览.md index f14ba85..810c264 100644 --- a/技术设计/api-server/[进行中]-架构总览.md +++ b/技术设计/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 diff --git a/开发计划/ios-projects/[参考]-功能需求清单.md b/技术设计/ios-projects/功能需求清单.md similarity index 88% rename from 开发计划/ios-projects/[参考]-功能需求清单.md rename to 技术设计/ios-projects/功能需求清单.md index 9d036e7..9eb66af 100644 --- a/开发计划/ios-projects/[参考]-功能需求清单.md +++ b/技术设计/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** | 反馈页 | 未实现 ❌ | +| **P1** | 设置页 | `ProfileView` ✅（含 5 个子页面 + 外观/语言切换） | +| **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 登录 | -| 架构 | MVVM + Service | View 内聚 | 需重构分层 | -| 多语言 | 架构预留 | 未实现 | 需添加本地化 | -| 后端对接 | REST API | 无 | 需接入 | -| AI 集成 | 真实 AI 分析 | 静态 Mock | 需接入 AI API | -| 数据持久化 | 本地缓存 + Keychain | 无 | 需实现 | -| Tab 设计 | 4 个 Tab | 5 个 Tab | 多了"分析"Tab | -| 反馈页 | P1 优先级 | 未实现 | 需添加 | -| 复习计划页 | P0 优先级 | 部分实现 | 需独立设计 | +| 登录 | Sign in with Apple | Apple 登录 ✅ | 已实现 | +| 架构 | MVVM + Service | 部分 MVVM + Service 层 ✅ | ViewModel 迁移进行中 | +| 多语言 | 架构预留 | Localizable.strings + LanguageManager ✅ | 仅中文，英文待补 | +| 后端对接 | REST API | Auth 已对接 ✅ | 其他页面待接 | +| AI 集成 | 真实 AI 分析 | 静态 Mock | 待接后端 AI API | +| 数据持久化 | 本地缓存 + Keychain | Keychain ✅ | 本地缓存待建 | +| Tab 设计 | 4 个 Tab | 5 个 Tab | 待决策 | +| 反馈页 | P1 优先级 | ✅ | — | +| 复习计划页 | P0 优先级 | ✅ | — | diff --git a/开发计划/ios-projects/已完成/[已完成]-差距分析.md b/技术设计/ios-projects/已完成/[已完成]-差距分析.md similarity index 100% rename from 开发计划/ios-projects/已完成/[已完成]-差距分析.md rename to 技术设计/ios-projects/已完成/[已完成]-差距分析.md diff --git a/技术设计/ios-projects/已完成/[已完成]-已实现功能汇总.md b/技术设计/ios-projects/已完成/[已完成]-已实现功能汇总.md new file mode 100644 index 0000000..8f2582c --- /dev/null +++ b/技术设计/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 引用 diff --git a/技术设计/ios-projects/[进行中]-架构设计.md b/技术设计/ios-projects/架构设计.md similarity index 72% rename from 技术设计/ios-projects/[进行中]-架构设计.md rename to 技术设计/ios-projects/架构设计.md index 653184c..2ebf7bf 100644 --- a/技术设计/ios-projects/[进行中]-架构设计.md +++ b/技术设计/ios-projects/架构设计.md @@ -79,18 +79,19 @@ AIStudyApp/ └── Tab "我的" → NavigationStack { ProfileView } ``` -## 三、数据流（当前均为静态 Mock） +## 三、数据流 -所有页面目前使用 `@State` 管理的本地假数据，尚未接入真实后端： +> 详细实现状态见 [`已完成/[已完成]-已实现功能汇总.md`](./已完成/[已完成]-已实现功能汇总.md) -| 数据 | 当前状态 | +| 层 | 当前状态 | |------|----------| -| 用户信息 | ProfileView 中硬编码 | -| 知识库列表 | LibraryHomeView 中硬编码 4 个 | -| 学习任务 | StudyHomeView 中硬编码 5 个 | -| AI 分析结果 | 各 AI 页面静态文本 | -| 学习统计 | AnalysisHomeView 中硬编码 | -| 登录状态 | @AppStorage 布尔值控制 | +| Auth | ✅ 已对接后端（Apple 登录 + JWT + refresh） | +| Network | ✅ APIClient + Endpoint + Error | +| Service | 🔶 AuthService 完成，其余 Service 协议已定义 | +| ViewModel | 🔶 部分页面已迁移（ReviewPlan/AIChat/StudyHome） | +| Model | ✅ 10 个数据实体 | +| Storage | ✅ KeychainStore + TokenStore | +| 其他页面数据 | ❌ 仍为静态 Mock（知识库/学习/复习/分析） | ## 四、技术栈 @@ -105,35 +106,26 @@ AIStudyApp/ ## 五、与计划架构的差异 -计划文档（`官网与技术基础.md`）中定义的 iOS 目录结构： +计划文档中定义的 iOS 目录结构 vs 当前实现： ``` 计划架构 当前实现 ───────────────────────────────── ───────────────── App/AIStudyApp.swift AIStudyAppApp.swift ✅ App/AppConfig.swift 未实现 ❌ -App/AppRouter.swift 未实现 ❌ -Core/Network/ 未实现 ❌ -Core/Auth/ 未实现 ❌ -Core/Storage/ 未实现 ❌ -Core/Localization/ 未实现 ❌ -Core/DesignSystem/ DesignTokens.swift ✅ (部分) +App/AppRouter.swift AppSession 替代 ✅ +Core/Network/ APIClient + Endpoint + Error ✅ +Core/Auth/ AuthService + AuthServiceProtocol ✅ +Core/Storage/ KeychainStore + TokenStore ✅ +Core/Localization/ ZXStrings + LanguageManager ✅ +Core/DesignSystem/ DesignTokens.swift ✅ Features/*/Views/ Features/*/ ✅ -Features/*/ViewModels/ 未实现 ❌ (View 内聚状态) -Features/*/Models/ 未实现 ❌ (无独立 Model) -Shared/Components/ 分散在各 View 文件中 ⚠️ -Shared/Extensions/ 仅 Color hex 扩展 ✅ +Features/*/ViewModels/ 🔶 部分完成 +Features/*/Models/ ✅ Core/Models/ 下 10 个实体 +Shared/Components/ Shared/Components/ 下 20+ 组件 ✅ +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` diff --git a/技术设计/ios-projects/[设计中]-登录集成.md b/技术设计/ios-projects/登录集成.md similarity index 100% rename from 技术设计/ios-projects/[设计中]-登录集成.md rename to 技术设计/ios-projects/登录集成.md diff --git a/技术设计/ios-projects/缺失项与待补全方向.md b/技术设计/ios-projects/缺失项与待补全方向.md new file mode 100644 index 0000000..234a5cc --- /dev/null +++ b/技术设计/ios-projects/缺失项与待补全方向.md @@ -0,0 +1,87 @@ +# iOS 缺失项与待补全方向 + +> 仅列出当前未完成的项目。已完成内容见 [`已完成/[已完成]-已实现功能汇总.md`](./已完成/[已完成]-已实现功能汇总.md) +> +> 更新时间：2026-05-17 + +--- + +## 一、后端 API 对接（当前最优先） + +Auth 已对接。以下页面仍使用静态 Mock 数据，待接后端： + +| 页面 | 需对接的 API | +|------|-------------| +| LibraryHomeView | GET /api/knowledge-bases | +| LibraryDetailPage | GET /api/knowledge-bases/:id/items | +| StudyHomeView | GET /api/learning-sessions | +| DailyThinkingPage | POST /api/active-recall/answers | +| AIFeedbackPage | GET /api/ai-analysis/:id | +| ReviewPlanView | GET /api/reviews/due | +| AnalysisHomeView | GET /api/learning-activity/summary | + +--- + +## 二、架构层待推进 + +### ViewModel 迁移（部分完成） + +ReviewPlanViewModel、AIChatViewModel、StudyHomeViewModel 已完成。其余页面仍为 View 内聚状态，待逐步迁移。 + +### Repository 层 + +当需要本地缓存 + 网络切换时再建，当前阶段不紧急。 + +--- + +## 三、动效 + +计划要求（P0）：页面过渡、按钮反馈、加载状态、AI 分析中状态、学习完成反馈。当前仅有基础 SwiftUI 隐式动画。 + +--- + +## 四、无障碍 + +关键按钮添加 `.accessibilityLabel`，确保 Dynamic Type 下布局不破碎，重点页面 VoiceOver 测试。 + +--- + +## 五、测试 + +- ViewModel 单元测试 +- Service 层单元测试（Mock Repository） +- 关键 UI 流程 Snapshot 测试 + +--- + +## 六、CI/CD + +- GitHub Actions / Xcode Cloud 自动构建 +- TestFlight 自动分发 +- 崩溃监控（Firebase Crashlytics 或类似） + +--- + +## 七、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. 无障碍基础适配 +``` diff --git a/技术设计/web-projects/[设计中]-设计文档.md b/技术设计/web-projects/设计文档.md similarity index 100% rename from 技术设计/web-projects/[设计中]-设计文档.md rename to 技术设计/web-projects/设计文档.md diff --git a/技术设计/总待完成清单.md b/技术设计/总待完成清单.md new file mode 100644 index 0000000..d09b814 --- /dev/null +++ b/技术设计/总待完成清单.md @@ -0,0 +1,203 @@ +# 知习 总待完成清单 + +> 整合后端、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 | CI/CD | GitHub Actions 自动构建 + TestFlight 分发 | [缺失项 六](./ios-projects/缺失项与待补全方向.md) | +| I16 | 崩溃监控 | Firebase Crashlytics 或 Sentry | [缺失项 六](./ios-projects/缺失项与待补全方向.md) | +| I17 | ViewModel/Service 单元测试 | Mock Repository 测试 | [缺失项 五](./ios-projects/缺失项与待补全方向.md) | +| I18 | 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 批（本月，核心链路）： + B7-B11 → B12-B15 → I1-I7 ✅ + AI Workflows → 异步化 → iOS 前后端打通（已打通） + +第 3 批（TestFlight 前）： + I8-I13 → B16-B22 → S6-S9 → W1-W3 + iOS ViewModel迁移 → 存储补全 → 验证机制 → 官网修复 + +第 4 批（App Store 前）： + I14-I18 → S10-S13 → W4-W7 + 埋点/CI/CD/测试 → 运营准备 → 官网细节 + +第 5 批（远期）： + B23-B26 + 商业化 → 后台 → 客服 +``` diff --git a/开发计划/[进行中]-潜在问题清单.md b/技术设计/潜在问题清单.md similarity index 100% rename from 开发计划/[进行中]-潜在问题清单.md rename to 技术设计/潜在问题清单.md diff --git a/开发计划/[进行中]-阶段路线图.md b/技术设计/阶段路线图.md similarity index 100% rename from 开发计划/[进行中]-阶段路线图.md rename to 技术设计/阶段路线图.md diff --git a/长期规划/[参考]-产品与用户模块.md b/长期规划/[参考]-产品与用户模块.md index ecd3ead..eef0296 100644 --- a/长期规划/[参考]-产品与用户模块.md +++ b/长期规划/[参考]-产品与用户模块.md @@ -94,6 +94,6 @@ ## 相关文档 -- [阶段路线图](../../开发计划/[进行中]-阶段路线图.md) +- [阶段路线图](../../技术设计/阶段路线图.md) - [技术与交付模块](./[参考]-技术与交付模块.md) - [商业化与支付模块](./[进行中]-商业化与支付模块.md) diff --git a/长期规划/[参考]-技术与交付模块.md b/长期规划/[参考]-技术与交付模块.md index d2f6a79..0703b95 100644 --- a/长期规划/[参考]-技术与交付模块.md +++ b/长期规划/[参考]-技术与交付模块.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) -- [后端开发优先级](../../开发计划/api-server/[进行中]-后端开发优先级.md) +- [AI架构设计](../../技术设计/api-server/AI架构设计.md) +- [后端开发优先级](../../技术设计/api-server/后端开发路线图.md) diff --git a/长期规划/[设计中]-合规与公司化模块.md b/长期规划/[设计中]-合规与公司化模块.md index 0a8a94f..2660f6a 100644 --- a/长期规划/[设计中]-合规与公司化模块.md +++ b/长期规划/[设计中]-合规与公司化模块.md @@ -44,7 +44,7 @@ ## 相关文档 -- [阶段路线图](../../开发计划/[进行中]-阶段路线图.md) +- [阶段路线图](../../技术设计/阶段路线图.md) - [商业化与支付模块](./[进行中]-商业化与支付模块.md) ## 负责人 diff --git a/长期规划/[设计中]-数据反馈与迭代模块.md b/长期规划/[设计中]-数据反馈与迭代模块.md index 8b3804c..6b55936 100644 --- a/长期规划/[设计中]-数据反馈与迭代模块.md +++ b/长期规划/[设计中]-数据反馈与迭代模块.md @@ -42,7 +42,7 @@ ## 相关文档 -- [阶段路线图](../../开发计划/[进行中]-阶段路线图.md) +- [阶段路线图](../../技术设计/阶段路线图.md) - [运营与客服模块](./运营与客服/[进行中]-运营与客服模块.md) ## 负责人 diff --git a/长期规划/[进行中]-个人开发者创业计划.md b/长期规划/[进行中]-个人开发者创业计划.md index 98a7620..db80e7b 100644 --- a/长期规划/[进行中]-个人开发者创业计划.md +++ b/长期规划/[进行中]-个人开发者创业计划.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) | diff --git a/长期规划/[进行中]-商业化与支付模块.md b/长期规划/[进行中]-商业化与支付模块.md index de318cb..86bae51 100644 --- a/长期规划/[进行中]-商业化与支付模块.md +++ b/长期规划/[进行中]-商业化与支付模块.md @@ -85,5 +85,5 @@ ## 相关文档 -- [阶段路线图](../../开发计划/[进行中]-阶段路线图.md) +- [阶段路线图](../../技术设计/阶段路线图.md) - [合规与公司化模块](./[设计中]-合规与公司化模块.md) diff --git a/长期规划/营销与增长/[进行中]-营销与增长模块.md b/长期规划/营销与增长/[进行中]-营销与增长模块.md index 9673139..72deff9 100644 --- a/长期规划/营销与增长/[进行中]-营销与增长模块.md +++ b/长期规划/营销与增长/[进行中]-营销与增长模块.md @@ -77,5 +77,5 @@ AI 生成内容草稿 → 人审核修改 → 人手动发布 → AI 辅助分 ## 相关文档 -- [阶段路线图](../../../开发计划/[进行中]-阶段路线图.md) +- [阶段路线图](../../../技术设计/阶段路线图.md) - [营销冷启动调研方案](./[参考]-营销冷启动调研方案.md) diff --git a/长期规划/运营与客服/[进行中]-运营与客服模块.md b/长期规划/运营与客服/[进行中]-运营与客服模块.md index c448493..99b4a6a 100644 --- a/长期规划/运营与客服/[进行中]-运营与客服模块.md +++ b/长期规划/运营与客服/[进行中]-运营与客服模块.md @@ -86,6 +86,6 @@ iOS App → NestJS 后端 → Dify API → Dify 知识库 ## 相关文档 -- [阶段路线图](../../../开发计划/[进行中]-阶段路线图.md) +- [阶段路线图](../../../技术设计/阶段路线图.md) - [数据反馈与迭代模块](../[设计中]-数据反馈与迭代模块.md) - [客服设计详案](./[参考]-客服设计详案.md)