# 知习后端待完成事项清单

> 按业务开发顺序排列。**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 集成
```
