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

知习后端待完成事项清单

按业务开发顺序排列。2026-05-16 更新：AI 基础设施完成，12 个 Repository 全部迁到 Prisma。

---

1. 登录 / 认证模块 Auth

这是第一优先级。因为后面所有数据都要绑定 userId。

要做的接口

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

第一阶段先做

POST /api/auth/dev-login
POST /api/auth/refresh
GET  /api/users/me

Apple 登录可以随后接入，但后端结构要先预留。

需要的表

users
auth_accounts
refresh_tokens

核心逻辑

dev-login 创建 / 查找用户
生成 accessToken
生成 refreshToken
refreshToken hash 入库
/users/me 返回当前用户
refresh 接口刷新 token
logout 撤销 refreshToken

Apple 登录需要什么

后端不需要 iOS 证书，只需要：

APPLE_BUNDLE_ID=cloud.longde.AIStudyApp
APPLE_ISSUER=https://appleid.apple.com
APPLE_JWKS_URL=https://appleid.apple.com/auth/keys

Apple 登录接口核心参数：

{
  "identityToken": "eyJ..."
}

可选参数：

{
  "authorizationCode": "...",
  "userIdentifier": "...",
  "email": "...",
  "fullName": {
    "givenName": "...",
    "familyName": "..."
  }
}

---

2. 权限系统 Permission

登录后马上要做最小权限。

第一版权限规则

普通用户只能访问自己的资源
所有用户资源必须校验 userId
普通用户不能访问 /api/admin/*
知识库默认 PRIVATE
创建知识库的人就是 owner

平台角色

USER
ADMIN
SUPER_ADMIN

后期资源角色

OWNER
EDITOR
VIEWER

第一版可以先不做协作者，只做：

knowledgeBase.userId === currentUser.id

---

3. 用户模块 Users

接口

GET   /api/users/me
PATCH /api/users/me
DELETE /api/users/me

字段

id
email
nickname
avatarUrl
role
status
onboardingCompleted
createdAt
updatedAt

这个模块服务于：

App 启动恢复登录态
我的页
会员权益
学习统计
后台用户管理

---

4. 知识库模块 KnowledgeBase

登录通了以后做知识库。

接口

GET    /api/knowledge-bases
POST   /api/knowledge-bases
GET    /api/knowledge-bases/:id
PATCH  /api/knowledge-bases/:id
DELETE /api/knowledge-bases/:id

字段

id
userId
title
description
coverColor
visibility
status
itemCount
createdAt
updatedAt
deletedAt

第一版规则

默认 PRIVATE
只允许用户操作自己的知识库
暂时不做公开、分享、协作者

---

5. 知识点模块 KnowledgeItem

接口

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

字段

id
userId
knowledgeBaseId
title
content
summary
tags
sourceType
masteryLevel
createdAt
updatedAt
deletedAt

第一版先支持：

手动创建知识点
手动编辑知识点

不要一开始做 PDF 解析和 AI 自动拆分。

---

6. 学习会话模块 LearningSession

表示一次学习过程。

接口

POST /api/learning-sessions
GET  /api/learning-sessions/:id
POST /api/learning-sessions/:id/complete

字段

id
userId
knowledgeBaseId
status
startedAt
completedAt
durationSeconds
createdAt
updatedAt

---

7. 主动回忆模块 ActiveRecall

这是用户主动输出的核心。

接口

POST /api/active-recall/answers
GET  /api/active-recall/answers/:id
GET  /api/knowledge-items/:id/active-recall/answers

字段

id
userId
knowledgeItemId
learningSessionId
mode
answerText
durationSeconds
createdAt

mode 预留：

ACTIVE_RECALL
FEYNMAN
RETRIEVAL_PRACTICE

---

8. AI 分析模块 AIAnalysis

这是知习核心差异化模块。

接口

POST /api/ai-analysis/active-recall
GET  /api/ai-analysis/:id
GET  /api/active-recall/answers/:answerId/analysis

字段

id
userId
knowledgeItemId
activeRecallAnswerId
score
masteryLevel
summary
strengths
weaknesses
missingKeyPoints
misconceptions
rawResult
promptVersion
model
createdAt

输出结构示例

{
  "score": 72,
  "masteryLevel": "partial",
  "summary": "用户理解了核心定义，但缺少应用场景。",
  "missingKeyPoints": [],
  "misconceptions": [],
  "focusItems": [],
  "reviewSuggestion": {
    "shouldReview": true,
    "intervalDays": 2
  }
}

---

9. 待巩固项模块 FocusItem

AI 分析后生成的薄弱点。

接口

GET   /api/focus-items
GET   /api/focus-items/today
GET   /api/focus-items/:id
PATCH /api/focus-items/:id

字段

id
userId
knowledgeBaseId
knowledgeItemId
aiAnalysisId
title
description
reason
priority
status
createdAt
resolvedAt

状态

OPEN
REVIEWING
RESOLVED
DISMISSED

---

10. 复习模块 Review

接口

GET  /api/reviews/due
GET  /api/reviews/cards/:id
POST /api/reviews/cards/:id/answer
POST /api/reviews/cards/:id/skip

表

review_cards
review_attempts

第一版复习算法可以简单：

薄弱 → 1 天后
一般 → 3 天后
掌握 → 7 天后

---

11. 学习活跃模块 LearningActivity

接口

GET  /api/learning-activity/summary
GET  /api/learning-activity/daily
POST /api/learning-activity/events

事件

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

用于：

连续学习天数
最近 7 天学习趋势
分析首页
我的页统计

---

12. AI 基础设施模块 ✅ 已完成

包括：

✅ AIGateway       — AiGatewayService（统一入口、选模型、JSON容错、超时重试）
✅ PromptTemplate  — PromptTemplateService（key + version 注册）
✅ AIUsageLog      — AiUsageLogService + AiCostCalculatorService
✅ AIWorkflow      — ActiveRecallAnalysisWorkflow（第一个 Workflow）
⏳ AIQuota         — 待实现

已完成文件

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

数据库

✅ AiUsageLog 模型已加入 prisma schema
⚠️ db push 待 SSH 隧道连通

旧代码已清理

❌ 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	辅助模块

改动范围

12 个 repository 重写（注入 PrismaService、删除 Map/Array、删除 generateShortId）
5 个 service 微调（方法加 userId 参数）
4 个 controller 加 @CurrentUser()（FocusItems / Review / LearningActivity / Notifications）
1 个 Prisma schema 新增模型（WaitlistEntry）

统一变更

- 删除所有 generateShortId() 调用，改用 Prisma @default(cuid())
- 删除所有 OnModuleInit 种子假数据
- 所有查询方法加 userId 过滤
- 复杂字段（数组/对象）存 Prisma Json 字段

这个后面会支撑：

AI 成本计算
会员额度
后台成本看板
模型切换

---

后端阶段顺序（已完成标记 ✅）

✅ 阶段 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

✅  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. 更多 AI Workflow（知识导入、费曼分析、复习卡片生成）
⏳ 13. AI 联调 + Prompt 调优
⏳ 14. iOS 集成