WangDL
fe608da385
- 文档从扁平结构迁移至分类目录 (api-server/ios-projects/web-projects/长期规划) - 更新总待完成清单 (B1-B6 全部完成, I1-I7 全部完成) - 新增后端实现状态、已实现功能汇总等已完成文档 - 新增 iOS 功能需求清单、架构设计、差距分析等文档 - 清理旧版未维护文档 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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
|