# 知习后端待完成事项清单 > 按业务开发顺序排列。**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 集成 ```