updated
知习 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
WangDL
fe608da385