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