--- source: startup-plan/个人开发者创业 v0.1 + 完全版 + AI回答.md 架构深化方案 updated: 2026-05-17 --- # 知习 api-server 后端架构规划 > 「知习」是一款 AI-first 的系统化学习 App。后端需要同时服务 iOS App 和 Web 官网。 > 核心功能包括知识库、主动回忆、AI 学习分析、间隔复习、待巩固项、学习活跃记录、消息通知和反馈。 ## 当前状态 > 详细实现进度见 [`已完成/[已完成]-已实现功能汇总.md`](./已完成/[已完成]-已实现功能汇总.md) 和 [`已完成/[已完成]-后端实现状态.md`](./已完成/[已完成]-后端实现状态.md) **已部署**：api.longde.cloud（NestJS + Prisma + MySQL + Docker + Nginx + SSL） **编译**：`npx tsc --noEmit` 0 errors **全局守卫**：JwtAuthGuard → RolesGuard（USER/ADMIN/SUPER_ADMIN） **业务模块**：14/14 完成（Auth → System） **AI**：三层架构落地，1/5 Workflow 完成 **待推进**：AI Workflows（费曼/导入/复习卡片/趋势）、BullMQ/Redis 异步化、iOS 对接、Admin 后台 --- ## 1. 架构总览：模块化单体 + Redis + Worker **不要微服务。** 当前最适合的是： > **模块化单体架构 Monolithic Modular Architecture** > > 一个后端项目，内部按业务模块拆清楚。 ```text iOS App Web 官网 ↓ 统一 API 后端（NestJS 模块化单体） ↓ 数据库 / Redis / 文件存储 / AI 服务 ↓ Worker 异步任务 ``` --- ## 2. 最终技术栈 ```text 后端框架：NestJS + TypeScript ORM：Prisma 数据库：PostgreSQL（推荐），MySQL 亦可 缓存/队列：Redis 队列系统：BullMQ 接口文档：Swagger / OpenAPI 文件存储：本地开发先本地存，后期接对象存储 AI：Provider 抽象 + 一个真实模型 + MockProvider 部署：Docker Compose 反向代理：Nginx 域名：api.longde.cloud ``` Docker Compose 项目服务规划： ```text api-server — NestJS 后端 postgres — 主数据库 redis — 缓存 + 队列 worker — 异步任务处理 nginx — 反向代理 + HTTPS ``` --- ## 3. 为什么选这个技术栈 ### NestJS 项目会越来越模块化。NestJS 的模块结构适合长期维护： ```text 用户 / 知识库 / 学习记录 / AI 分析 / 复习计划 / 待巩固项 / 通知 / 反馈 / 订阅 ``` Express 也能做，但后期容易自己手写一堆规范，最后变乱。 ### Prisma - 类型安全的 ORM，自动生成 TypeScript 类型 - 迁移管理清晰 - 与 NestJS 集成良好 - AI Agent 按 schema 生成代码能力好 ### PostgreSQL（优于 MySQL） - 更适合 JSON 数据（AI 分析结果） - 支持全文检索 - 后续可扩展 pgvector 做向量检索 - 如果更熟悉 MySQL，也可以先用 MySQL ### Redis + BullMQ Redis 不只是缓存，在知习系统里做四件事： ```text 缓存 → 短期数据加速 队列 → AI 分析 / 资料导入 / 通知任务 限流 → AI 调用频控 / 用户请求限流 临时状态 → 任务处理中状态 / 防重复提交锁 ``` --- ## 4. 前后端职责分离 | 端 | 职责 | |---|------| | iOS 客户端 | 页面展示、用户交互、本地状态、登录入口、学习流程体验 | | 后端 API | 用户身份、AI API 代理、学习记录、AI 分析、学习画像、复习计划、待巩固项、通知、反馈 | | Worker | AI 分析任务异步处理、资料导入异步处理、通知分发 | | AI 模型 | 分析用户输入、生成学习反馈、识别薄弱点、生成复习建议、辅助学习对话 | | 官网 | 产品介绍、SEO、隐私政策、用户协议、支持页面、等待名单 | --- ## 5. 数据库和 Redis 的分工 ``` PostgreSQL / MySQL：长期真实数据 Redis：短期状态、缓存、队列、限流 文件存储：PDF、图片、附件 AI 服务：分析、总结、生成复习题 ``` 一句话： > **数据库存事实，Redis 管状态。** ### Redis 适合做 - AI 分析任务队列 - 资料导入任务队列 - 通知任务队列 - 用户请求限流 - AI 调用次数计数 - 任务处理中状态 - 防重复提交锁 - 短期缓存 ### Redis 不适合做主数据 这些必须进数据库： - 用户资料 - 知识库 - 学习记录 - AI 分析结果 - 待巩固项 - 复习计划 - 学习活跃记录 - 通知记录 --- ## 6. 后端目录结构 ```text api-server/ ├── src/ │ ├── main.ts │ ├── app.module.ts │ │ │ ├── config/ │ │ ├── app.config.ts │ │ ├── database.config.ts │ │ ├── redis.config.ts │ │ ├── jwt.config.ts │ │ ├── ai.config.ts │ │ └── storage.config.ts │ │ │ ├── common/ │ │ ├── constants/ │ │ ├── decorators/ │ │ ├── guards/ │ │ ├── interceptors/ │ │ ├── filters/ │ │ ├── pipes/ │ │ ├── dto/ │ │ ├── types/ │ │ └── utils/ │ │ │ ├── infrastructure/ │ │ ├── database/ │ │ ├── redis/ │ │ ├── queue/ │ │ ├── ai/ │ │ │ ├── prompts/ │ │ │ └── providers/ │ │ ├── storage/ │ │ └── logger/ │ │ │ ├── modules/ │ │ ├── auth/ │ │ ├── users/ │ │ ├── knowledge-base/ │ │ ├── knowledge-items/ │ │ ├── document-import/ │ │ ├── learning-session/ │ │ ├── active-recall/ │ │ ├── ai-analysis/ │ │ ├── review/ │ │ ├── focus-items/ │ │ ├── learning-activity/ │ │ ├── notifications/ │ │ ├── feedback/ │ │ └── system/ │ │ │ └── workers/ │ ├── ai-analysis.worker.ts │ ├── document-import.worker.ts │ └── notification.worker.ts │ ├── prisma/ │ ├── schema.prisma │ └── migrations/ │ ├── docker-compose.yml ├── Dockerfile ├── .env.example └── package.json ``` --- ## 7. 各模块职责 ### 7.1 Auth 模块 负责 Apple 登录、JWT、刷新 Token、退出登录、账号注销。 App Store 上架要求 Sign in with Apple，这是必须做的。 ### 7.2 Users 模块 负责用户资料、头像、昵称、学习身份、学习方向、学习偏好。 ### 7.3 Knowledge Base 模块 负责知识库创建、列表、详情、编辑、删除、标签。 ### 7.4 Knowledge Items 模块 负责具体知识点、章节、内容段落、关键概念、标签、关联关系。 ### 7.5 Document Import 模块 负责上传文件、粘贴文本、链接导入、导入状态、解析进度、导入成功/失败。 这里非常适合用 Redis Queue 做异步处理。 ### 7.6 Learning Session 模块 负责一次学习过程：开始学习、结束学习、学习时长、学习内容、学习模式、完成状态。 这是学习活跃图的数据来源之一。 ### 7.7 Active Recall 模块 负责主动回忆：回忆问题、用户回答、语音回答、回答提交、回答历史。 ### 7.8 AI Analysis 模块 负责提交分析任务、分析状态、AI 分析结果、掌握度、薄弱点、改进建议、下一步建议。 **必须走 Redis Queue 异步处理。** ### 7.9 Focus Items 模块 「待巩固项」——类似 GitHub Issue，但在知习里叫待巩固项。 负责：AI 自动生成待巩固项、用户手动添加、状态（待处理/已加入复习/已完成）、关联知识点、关联学习记录。 ### 7.10 Review 模块 负责复习卡片、到期复习、间隔复习计划、复习结果、掌握程度选择、下次复习时间。 ### 7.11 Learning Activity 模块 负责学习活跃图：每日学习时长、主动回忆次数、复习次数、AI 分析次数、完成学习闭环次数、学习活跃度等级。 活跃图数据最终写入数据库，Redis 可做临时累计。 ### 7.12 Notifications 模块 负责复习提醒、AI 分析完成提醒、学习建议、系统通知、已读/未读。 ### 7.13 Feedback 模块 负责 Web 和 App 反馈：用户反馈、问题类型、邮箱、设备、处理状态。 ### 7.14 System 模块 健康检查、应用状态、基础运维接口。 --- ## 8. 模块优先级 ### v0.1 必须实现 ```text auth users knowledge-base knowledge-items learning-session active-recall ai-analysis focus-items review learning-activity feedback system ``` ### v0.1 暂缓 ```text document-import — 先手动录入内容 notifications — 先不做推送 billing — 暂无付费 subscription — 暂无订阅 admin-dashboard — 暂无管理后台 team — 单人使用 ``` --- ## 9. API 路由规划 ```text GET /api/health POST /api/auth/apple POST /api/auth/refresh POST /api/auth/logout GET /api/users/me PATCH /api/users/me PATCH /api/users/me/preferences GET /api/knowledge-bases POST /api/knowledge-bases GET /api/knowledge-bases/:id PATCH /api/knowledge-bases/:id DELETE /api/knowledge-bases/:id GET /api/knowledge-bases/:id/items GET /api/knowledge-items/:id POST /api/knowledge-items POST /api/imports GET /api/imports/:id/status POST /api/learning-sessions POST /api/learning-sessions/:id/end GET /api/active-recalls POST /api/active-recalls/:id/submit POST /api/ai-analysis GET /api/ai-analysis/:id GET /api/ai-analysis/jobs/:jobId/status GET /api/focus-items POST /api/focus-items PATCH /api/focus-items/:id POST /api/focus-items/:id/complete GET /api/reviews/due POST /api/reviews/:id/submit GET /api/activity/heatmap GET /api/activity/summary GET /api/notifications POST /api/notifications/:id/read POST /api/feedback ``` --- ## 10. 关键请求流程 核心异步流程详见 [23. 异步模块额外文件 - AI 分析模块完整流程](#23-异步模块额外文件queue--processor)。 --- ## 11. 核心 AI 接口 ### POST /api/ai-analysis（提交异步任务） 输入： ```json { "sessionId": "session_001", "lessonId": "lesson_001", "userInput": "用户写下的答案或笔记", "context": { "lessonTitle": "材料阅读方法", "objectives": ["理解材料结构", "提取关键要点"], "keyPoints": ["问题", "原因", "影响", "对策"] } } ``` 返回： ```json { "jobId": "job_abc123", "status": "pending" } ``` ### GET /api/ai-analysis/jobs/:jobId/status（查询状态） ```json { "jobId": "job_abc123", "status": "completed", "result": { "masteryScore": 3, "understandingLevel": "基本理解", "summary": "用户能理解主要内容，但要点不完整。", "strengths": ["表达清楚"], "weakPoints": ["遗漏关键要点", "逻辑层次不足"], "suggestions": ["补充第二个要点", "先概括再展开"], "reviewNeeded": true, "nextAction": "明天重新回答本节主动回忆问题。" } } ``` --- ## 12. AI Provider 层设计 ```text AIService ├── MiniMaxProvider ├── DeepSeekProvider ├── OpenAIProvider └── MockProvider ``` ### MockProvider v0.1 强烈建议做 MockProvider： - 没有 API Key 时也能开发 - AI 服务出问题时能测试流程 - 降低开发成本 - 方便录 Demo ### 候选模型 MiniMax / DeepSeek / 通义千问 / OpenAI / Claude / Gemini ### 模型选择原则 1. 中文能力好 2. 成本可控 3. API 稳定 4. 支持结构化输出 5. 速度可以接受 6. 容易接入 7. 可替换 --- ## 13. 核心实体/数据模型 ```text User ├── id ├── appleUserId ├── displayName ├── email ├── preferredLanguage ├── learningDirection ├── createdAt ├── lastLoginAt └── status KnowledgeBase ├── id ├── userId ├── title ├── description ├── language ├── tags ├── createdAt └── updatedAt KnowledgeItem ├── id ├── knowledgeBaseId ├── parentId ├── title ├── content ├── type (chapter/section/concept) ├── objectives ├── keyPoints ├── recallQuestions ├── order └── estimatedMinutes DocumentImport ├── id ├── userId ├── knowledgeBaseId ├── sourceType (file/text/link) ├── status (pending/processing/completed/failed) ├── result ├── createdAt └── completedAt LearningSession ├── id ├── userId ├── knowledgeItemId ├── startedAt ├── endedAt ├── durationSeconds ├── mode (reading/recall/review) └── completedAt ActiveRecall ├── id ├── sessionId ├── question ├── userAnswer ├── answerType (text/voice) ├── submittedAt AIAnalysis ├── id ├── jobId ├── userId ├── sessionId ├── inputText ├── outputJson ├── masteryScore ├── weakPoints ├── suggestions ├── modelName ├── costEstimate ├── status (pending/processing/completed/failed) ├── createdAt └── completedAt FocusItem ├── id ├── userId ├── knowledgeItemId ├── aiAnalysisId ├── title ├── description ├── status (pending/in_review/completed) ├── createdAt └── completedAt ReviewTask ├── id ├── userId ├── knowledgeItemId ├── focusItemId ├── reviewType ├── scheduledAt ├── completedAt ├── masteryChoice ├── nextReviewAt └── status LearningActivity ├── id ├── userId ├── date ├── durationSeconds ├── recallCount ├── reviewCount ├── analysisCount ├── closedLoopCount ├── activityLevel └── updatedAt Notification ├── id ├── userId ├── type ├── title ├── body ├── data (JSON) ├── isRead └── createdAt Feedback ├── id ├── userId ├── type ├── content ├── email ├── device ├── status └── createdAt ``` --- ## 14. 掌握度评分（0-5分） ```text 0 = 没有作答 / 无法判断 1 = 基本没理解 2 = 理解较弱 3 = 基本理解 4 = 理解较好 5 = 掌握很好 ``` 这不是考试分数，是产品内部用于安排复习和学习建议的参考值。 --- ## 15. 账号体系 ### 第一版登录方式 ```text Sign in with Apple ``` 暂不做：微信登录、手机号登录、邮箱密码登录、Google 登录。 ### 账号边界 第一版账号只解决：登录、识别用户、保存学习记录、保存 AI 分析结果、保存基础偏好。 暂不做：好友系统、用户主页、头像上传、多登录方式绑定、复杂权限系统。 --- ## 16. 部署方案 ### 当前服务器 - IP: 81.70.187.179 - 配置: 4 核 4G，40G SSD - 当前运行: Gitea（端口 3000）+ Nginx - SSH: ubuntu 用户 + WangDL.pem 密钥 ### 推荐部署方式 ```text Nginx — 反向代理，已有 api-server (NestJS) — 端口 3001 postgres / mysql — 端口 5432 / 3306 redis — 端口 6379 worker (BullMQ) — 同代码仓库，独立进程 gitea — 端口 3000，继续保留 ``` 建议新增 Nginx 配置 `api.longde.cloud` → 反向代理到 NestJS 端口。 ### 资源评估 Gitea 当前资源占用很低（内存 ~500MB），剩余 ~3GB 内存、33GB 磁盘足够跑 api-server + PostgreSQL + Redis。 --- ## 17. 域名与 Nginx 规划 ```text longde.cloud 官网首页 api.longde.cloud 后端 API（需新增 Nginx 配置） git.longde.cloud Gitea 代码仓库（已有） ``` ### 待新增 Nginx 配置（api.longde.cloud） ```nginx server { server_name api.longde.cloud; location / { proxy_pass http://127.0.0.1:3001; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } listen 443 ssl; ssl_certificate /etc/letsencrypt/live/api.longde.cloud/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/api.longde.cloud/privkey.pem; } ``` --- ## 18. 技术里程碑 ### 里程碑 1：最小后端 - NestJS 项目初始化 - Prisma schema 定义 - PostgreSQL/MySQL 连接 - 用户表、知识库表 - AI MockProvider - Swagger 文档 ### 里程碑 2：真实 AI 接入 - Redis + BullMQ 接入 - AI Provider 抽象 - 接入一个真实模型 - AI 分析异步流程 - Worker 处理 AI 任务 ### 里程碑 3：TestFlight 前准备 - Sign in with Apple - 后端用户身份记录 - 基础错误处理 - Docker Compose 一键部署 - Nginx 反向代理配置 --- ## 19. 商业化与支付（未来） ### 支付流程 ```text 用户在 iOS App 内付款 → Apple IAP 完成交易 → 后端记录用户权益 → 用户获得权益 ``` ### 核心 不要让 Apple IAP 成为整个商业系统。真正核心的是： ```text 用户系统 + 订单系统 + 权益系统 ``` ### 当前暂缓 Apple IAP / 月订阅 / 年订阅 / 免费试用 / 订阅权益系统 / AI 成本精算 --- ## 20. 当前技术不做清单 - 微服务 / Kubernetes / 多云部署 - 完整后台管理系统 / CMS - 完整 RAG / 向量数据库（第一版） - 多模型自动路由 - AI Agent 工具调用系统 - 支付系统 - 复杂数据分析平台 - Android / Web 学习端 --- ## 21. 四层代码分层原则 整体分四层，每一层有明确的职责边界： ```text Controller 层：接收请求，处理参数，返回响应 Service 层：业务逻辑 Repository 层：数据库读写 Infrastructure 层：Redis、Queue、AI、Storage 等基础设施 ``` 简单理解： ```text Controller 不写业务 Service 不直接写复杂 SQL Repository 不写业务判断 Infrastructure 不知道具体业务，只提供能力 ``` 一句话纪律： ```text Controller = 接口 Service = 业务 Repository = 数据库 Infrastructure = 外部能力 Queue/Processor = 异步任务 DTO = 请求/响应结构 ``` 第一版不要追求所有业务一次写完，但**架构模板必须先统一**。 --- ## 22. 模块内部统一模板 每个业务模块都按这个结构来。以 `knowledge-base` 为例： ```text modules/knowledge-base/ ├── knowledge-base.module.ts ├── knowledge-base.controller.ts ├── knowledge-base.service.ts ├── knowledge-base.repository.ts ├── dto/ │ ├── create-knowledge-base.dto.ts │ ├── update-knowledge-base.dto.ts │ ├── query-knowledge-base.dto.ts │ └── knowledge-base-response.dto.ts ├── types/ │ └── knowledge-base.types.ts └── constants/ └── knowledge-base.constants.ts ``` ### 22.1 xxx.module.ts ```text 作用： - 注册 controller - 注册 service - 注册 repository - 引入依赖模块 - 导出给其他模块使用 ``` ```ts @Module({ controllers: [KnowledgeBaseController], providers: [KnowledgeBaseService, KnowledgeBaseRepository], exports: [KnowledgeBaseService], }) export class KnowledgeBaseModule {} ``` ### 22.2 xxx.controller.ts **只做这些事：** 1. 定义路由 2. 接收参数 3. 调用 service 4. 返回结果 **不要在 Controller 里写业务判断。** ```ts @Controller('knowledge-bases') export class KnowledgeBaseController { constructor(private readonly service: KnowledgeBaseService) {} @Post() create(@Body() dto: CreateKnowledgeBaseDto, @CurrentUser() user: UserPayload) { return this.service.create(user.id, dto); } @Get() findAll(@CurrentUser() user: UserPayload, @Query() query: QueryKnowledgeBaseDto) { return this.service.findAll(user.id, query); } @Get(':id') findOne(@Param('id') id: string, @CurrentUser() user: UserPayload) { return this.service.findOne(user.id, id); } } ``` ### 22.3 xxx.service.ts **这里写：** 1. 权限判断 2. 业务规则 3. 调用 repository 4. 调用其他模块 service 5. 调用 queue / AI / Redis 6. 组织返回结果 ```ts @Injectable() export class KnowledgeBaseService { constructor( private readonly repository: KnowledgeBaseRepository, ) {} async create(userId: string, dto: CreateKnowledgeBaseDto) { const count = await this.repository.countByUserId(userId); if (count >= MAX_KNOWLEDGE_BASE_COUNT) { throw new BadRequestException('知识库数量已达到上限'); } return this.repository.create(userId, dto); } async findOne(userId: string, id: string) { const knowledgeBase = await this.repository.findById(id); if (!knowledgeBase || knowledgeBase.userId !== userId) { throw new NotFoundException('知识库不存在'); } return knowledgeBase; } } ``` ### 22.4 xxx.repository.ts **只写数据库操作，不写复杂业务。** ```ts @Injectable() export class KnowledgeBaseRepository { constructor(private readonly prisma: PrismaService) {} create(userId: string, dto: CreateKnowledgeBaseDto) { return this.prisma.knowledgeBase.create({ data: { userId, name: dto.name, description: dto.description }, }); } findById(id: string) { return this.prisma.knowledgeBase.findUnique({ where: { id } }); } countByUserId(userId: string) { return this.prisma.knowledgeBase.count({ where: { userId } }); } } ``` ### 22.5 dto/ DTO 就是接口输入输出的数据结构。 用途： 1. 校验请求参数 2. 生成 Swagger 文档 3. 让接口结构清楚 ```ts export class CreateKnowledgeBaseDto { @ApiProperty({ example: '认知心理学' }) @IsString() @IsNotEmpty() name: string; @ApiProperty({ example: '系统学习认知心理学基础概念', required: false }) @IsOptional() @IsString() description?: string; } ``` ### 22.6 types/ 放模块内部类型。如果是数据库模型，不放这里，放 Prisma。 ```ts export type KnowledgeBaseStatus = 'active' | 'archived'; export interface KnowledgeBaseStats { itemCount: number; completedCount: number; reviewDueCount: number; } ``` ### 22.7 constants/ 放模块常量。 ```ts export const MAX_KNOWLEDGE_BASE_COUNT = 20; export const DEFAULT_KNOWLEDGE_BASE_COVER = 'default-blue'; ``` --- ## 23. 异步模块额外文件（Queue + Processor） 涉及异步任务的模块，需要在标准模板上加 `queue`、`processor`、`jobs`。 以 `ai-analysis` 为例： ```text modules/ai-analysis/ ├── ai-analysis.module.ts ├── ai-analysis.controller.ts ├── ai-analysis.service.ts ├── ai-analysis.repository.ts ├── ai-analysis.queue.ts ← 封装 BullMQ 队列 ├── ai-analysis.processor.ts ← 消费任务，调用大模型 ├── dto/ │ ├── create-ai-analysis.dto.ts │ ├── query-ai-analysis.dto.ts │ └── ai-analysis-response.dto.ts ├── jobs/ │ └── ai-analysis.job.ts ← 队列任务数据结构 ├── types/ │ └── ai-analysis.types.ts └── constants/ └── ai-analysis.constants.ts ``` ### 文件职责 | 文件 | 职责 | |------|------| | `controller` | 接收创建分析任务、查询分析结果的接口 | | `service` | 创建任务、查询状态、组织业务流程 | | `repository` | 读写 AI 分析任务和分析结果 | | `queue` | 封装 BullMQ 队列添加任务 | | `processor` | 真正消费任务，调用大模型 | | `jobs/xxx.job.ts` | 定义队列任务的数据结构 | ### AI 分析模块完整流程 ```text App 提交回答 ↓ Controller 接收请求 ↓ Service 创建分析任务 ↓ Repository 写入数据库 job 记录 ↓ Queue 加入 Redis 队列 ↓ Processor 后台消费任务 ↓ AI Service 调用大模型 ↓ Repository 写入分析结果 ↓ 生成待巩固项 ↓ 生成复习计划 ↓ 通知用户 ``` --- ## 24. AI 层设计：不允许业务模块直接调大模型 SDK ### 原则 后面肯定会换模型、换供应商，所以 AI 不要写死在业务模块里。 **不推荐：** ```ts // 不要直接在业务 service 里写 await openai.chat.completions.create(...) ``` **应该：** ```text 业务模块 → AiService → 具体 Provider ``` ```ts @Injectable() export class AiService { constructor(private readonly provider: AiProvider) {} analyzeActiveRecall(input: ActiveRecallAnalysisInput) { return this.provider.generateActiveRecallAnalysis(input); } } ``` 这样从 OpenAI 换 DeepSeek、Gemini、Claude，都不用改业务代码。 --- ## 25. Infrastructure 层详细拆解 `infrastructure` 是所有模块共用的底层能力。 ```text infrastructure/ ├── database/ │ ├── prisma.module.ts │ └── prisma.service.ts │ ├── redis/ │ ├── redis.module.ts │ ├── redis.service.ts │ └── redis.constants.ts │ ├── queue/ │ ├── queue.module.ts │ ├── queue.constants.ts │ └── queue.service.ts │ ├── ai/ │ ├── ai.module.ts │ ├── ai.service.ts │ ├── ai-provider.interface.ts │ ├── providers/ │ │ ├── openai.provider.ts │ │ ├── deepseek.provider.ts │ │ └── mock-ai.provider.ts │ └── prompts/ │ ├── active-recall-analysis.prompt.ts │ └── focus-item-generation.prompt.ts │ ├── storage/ │ ├── storage.module.ts │ ├── storage.service.ts │ └── local-storage.provider.ts │ └── logger/ ├── logger.module.ts └── app-logger.service.ts ``` --- ## 26. Common 层详细拆解 ```text common/ ├── decorators/ │ └── current-user.decorator.ts ├── guards/ │ ├── jwt-auth.guard.ts │ └── optional-auth.guard.ts ├── interceptors/ │ └── response.interceptor.ts ├── filters/ │ └── http-exception.filter.ts ├── pipes/ │ └── validation.pipe.ts ├── dto/ │ ├── pagination.dto.ts │ └── api-response.dto.ts ├── types/ │ ├── user-payload.type.ts │ └── pagination.type.ts ├── constants/ │ └── app.constants.ts └── utils/ ├── date.util.ts ├── hash.util.ts └── id.util.ts ``` --- ## 27. 模块复杂度分级 ### 简单模块 结构 `module + controller + service + repository + dto` 适用于：`feedback`、`system`、`notifications`（初版） ### 中等模块 结构 `module + controller + service + repository + dto + types + constants` 适用于：`users`、`knowledge-base`、`knowledge-items`、`learning-session`、`review`、`focus-items` ### 复杂模块 结构 `module + controller + service + repository + queue + processor + jobs + dto + types + constants` 适用于：`ai-analysis`、`document-import`、`notifications`（后期） --- ## 28. 初始化顺序 第一版不要所有业务都写完。先搭基础设施骨架： ```text 1. infrastructure/database 2. infrastructure/redis 3. infrastructure/queue 4. infrastructure/ai 5. common 6. system/health 7. auth skeleton 8. users skeleton 9. knowledge-base skeleton 10. ai-analysis skeleton ``` 这样就够开始开发。