121 lines
4.1 KiB
Markdown
121 lines
4.1 KiB
Markdown
|
---
|
|||
|
|
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
|