---
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<string, T>` / `Array<T>` 内存存储
- 所有 `generateShortId()` 调用
- 所有 `OnModuleInit` 种子假数据
- 所有 `'anonymous'` fallback