英语学习平台：项目代码地图与方法说明#

目的：用于快速熟悉项目、面试前定位代码、现场按调用链讲解。
行号基准：本地主项目提交 48f175c90b4b8d2e63d0f93a497890ea788cf863，已按拆分后的 Agent 服务结构校对。
更新日期：2026-10-05。
注意：后续修改源码后，行号可能漂移；优先搜索本文列出的文件名、类名和方法名。

1. 阅读范围与最快阅读顺序#

本文覆盖项目的全部逻辑模块：Vue 前端、埋点 SDK、NestJS 业务服务、NestJS Agent 服务、共享基础设施、PostgreSQL 数据模型、FastAPI/Celery/Chroma 知识库服务、Docker 与反向代理。

以下内容不逐文件解释：node_modules、pnpm-lock.yaml、server-py/uv.lock、Prisma 自动生成客户端、OpenAPI 自动生成客户端、图片/CSS 等静态资源。它们不是面试时需要逐行讲解的业务代码。

建议按下面顺序阅读：

1. README.md:1：先理解产品、组件和两条主调用链。
2. server/prisma/schema.prisma:100：理解用户、学习、Agent、知识库的数据关系。
3. apps/web/src/views/Chat/index.vue:308：理解前端如何驱动 Agent。
4. server/apps/ai/src/agent/agent-runner.service.ts:63：理解 Agent 主编排；再顺着依赖读 agent-run-lifecycle.service.ts、agent-context.service.ts、agent-rag.service.ts、agent-tools.service.ts和 agent-usage.service.ts。
5. server/apps/server/src/knowledge/knowledge.service.ts:99：理解知识库上传与业务状态。
6. server-py/app/services/ingestion.py:82：理解异步解析与向量入库。
7. server-py/app/vectorstore/chroma_store.py:432：理解私有向量检索。
8. docker-compose.dev.yml:118、docker-compose.prod.yml:120：理解完整部署拓扑。

2. 一张图记住总体结构#

浏览器
  ├─ /api/v1  → NestJS Business :3000
  │              ├─ PostgreSQL：用户、课程、学习、知识库元数据
  │              ├─ MinIO：头像、课程资源、私人原始文档
  │              └─ FastAPI：创建/删除/核对索引
  │
  └─ /ai/v1   → NestJS Agent :3001
                 ├─ PostgreSQL：会话、消息、Run、Action、Checkpoint
                 ├─ 学习 Tool：读取/修改真实学习数据
                 └─ FastAPI：私人知识库检索

FastAPI RAG :8000
  ├─ Redis/Celery：异步任务、锁、nonce、Worker 心跳
  ├─ MinIO：读取原始 PDF/MD/TXT
  ├─ Embedding Provider：生成向量
  ├─ Chroma：保存与检索分片
  └─ HMAC 回调 Business：PROCESSING / READY / FAILED

3. 八条核心调用链（速查）#

3.1 登录与 Token 刷新#

1. 前端表单：apps/web/src/components/Login/LoginForm.vue:72 的 handleLogin() 收集表单并调用登录 API。
2. 前端 API：apps/web/src/apis/user/index.ts:15 的 login() 请求 /api/v1/user/login。
3. 路由入口：server/apps/server/src/user/user.controller.ts:34 的 login() 转给 UserService。
4. 登录逻辑：server/apps/server/src/user/user.service.ts:26 的 login() 查询用户、校验密码、更新最后登录时间并签发 Token。
5. Token 生成：server/apps/server/src/auth/auth.service.ts:12 的 generateToken() 生成 access/refresh Token，并区分 tokenType。
6. 前端持久化：apps/web/src/stores/user.ts:5 的 useUserStore 保存用户和 Token。
7. 请求注入：apps/web/src/apis/index.ts:14 与 apps/web/src/apis/index.ts:67 的请求拦截器分别给 Business/Agent 请求加 Bearer Token。
8. 自动刷新：apps/web/src/apis/token.ts:6 的 ensureAccessToken() 合并并发刷新请求；apps/web/src/apis/auth/index.ts:18 的 refreshTokenApi() 请求刷新接口。
9. 服务端鉴权：server/libs/shared/src/auth/auth.guard.ts:14 的 canActivate() 验证 access Token，并把用户信息写入 request.user。

当前实现提醒：server/apps/server/src/user/user.service.ts:37 直接比较明文密码，server/prisma/schema.prisma:107 也直接保存 password。这是必须在公开演示或面试代码审查前修复的安全问题，应改为 Argon2/bcrypt 哈希和安全迁移。

3.2 普通课程与词汇学习#

1. 课程列表页：apps/web/src/views/Course/index.vue:102 的 init() 加载全部课程和已购课程。
2. 课程 API：apps/web/src/apis/course/index.ts:4 的 getCourseList()、:8 的 getMyCourseList() 请求 Business。
3. 课程查询：server/apps/server/src/course/course.service.ts:13 的 findAll() 返回课程；:22 的 findMy() 返回当前用户已购课程。
4. 进入学习页：apps/web/src/views/Course/Learn/index.vue:302 的 getWordListData() 获取课程词汇。
5. 学习权限：server/apps/server/src/learn/learn.service.ts:100 的 getWordList() 先校验购买关系，再返回课程对应词汇。
6. 保存掌握词：前端 apps/web/src/views/Course/Learn/index.vue:288 的 saveWordMaster() 调用 apps/web/src/apis/learn/index.ts:5。
7. 服务端更新：server/apps/server/src/learn/learn.service.ts:12 的 saveWordMaster() 用事务和 Advisory Lock 并发安全地创建/更新 WordBookRecord，同时更新用户掌握词数。
8. 词库浏览：apps/web/src/views/WordBook/index.vue:111 的 getList() 调用 server/apps/server/src/word-book/word-book.service.ts:15 的 findAll() 完成标签筛选、搜索和分页。

3.3 Agent 对话与 SSE#

1. 页面初始化：apps/web/src/views/Chat/index.vue:308 的 loadConversations() 加载会话。
2. 创建会话：apps/web/src/views/Chat/index.vue:323 的 newConversation() 调用 apps/web/src/apis/agent/index.ts:9 的 createConversation()。
3. 发送消息：apps/web/src/views/Chat/index.vue:369 的 sendMessage() 创建本地占位消息，并调用 apps/web/src/apis/sse/index.ts:11 的 streamAgentMessage()。
4. SSE 客户端：streamAgentMessage() 取得有效 Token、发起 POST 流式请求、解析事件，401 时只刷新一次 Token。
5. Agent HTTP 入口：server/apps/ai/src/conversations/conversations.controller.ts:64 的 stream() 设置 SSE 头、转发事件、处理断开。
6. 主编排器：server/apps/ai/src/agent/agent-runner.service.ts:63-451 的 AgentRunnerService.run() 校验请求、按顺序调用下面的专职服务，并消费 LangGraph 流输出 SSE。
7. 运行生命周期：server/apps/ai/src/agent/agent-run-lifecycle.service.ts:46 的 createRun()、:108 的 persistUserMessage()、:133 的 completeRun()和 :173 的 failRun() 负责并发锁、Run 状态和消息落库。
8. 前端事件处理：apps/web/src/views/Chat/index.vue:429 的 handleAgentEvent() 处理状态、工具、来源、增量文本、确认 Action、测验和完成事件。
9. 停止生成：前端 apps/web/src/views/Chat/index.vue:465 的 stopGeneration() 调用 apps/web/src/apis/agent/index.ts:26；服务端 server/apps/ai/src/agent/agent-runner.service.ts:453-467 的 AgentRunnerService.cancel() 校验本机活动任务并 Abort，数据库条件取消由 agent-run-lifecycle.service.ts:262-292 的 cancelRun() 完成。
10. 完成落库：server/apps/ai/src/agent/agent-run-lifecycle.service.ts:133-171 的 AgentRunLifecycleService.completeRun() 在事务中完成 Run、保存 Assistant 消息、工具审计、引用和 Token 用量。

3.4 Agent 写操作与人工确认#

1. Agent 在 server/apps/ai/src/agent/agent-tools.service.ts:37-371 的 AgentToolsService.createTools() 中定义全部工具；agent-runner.service.ts:261-285 只负责按场景筛选可用工具。
2. create_study_plan 和 complete_study_task 不直接修改最终业务状态，而是调用 AgentActionService 创建待确认 Action。
3. 创建计划 Action：server/libs/shared/src/learning/agent-action.service.ts:23 的 prepareStudyPlan() 生成幂等键、加锁、创建 PENDING Action。
4. 创建完成任务 Action：server/libs/shared/src/learning/agent-action.service.ts:73 的 AgentActionService.prepareCompleteTask() 校验任务归属并创建待确认 Action。
5. 前端收到 action.required 后，由 apps/web/src/views/Chat/index.vue:481 的 confirmAction() 或 :495 的 rejectAction() 处理。
6. 确认入口：server/apps/ai/src/conversations/actions.controller.ts:30 的 confirm() 调用 AgentActionService.confirm()。
7. 确认与抢占：server/libs/shared/src/learning/agent-action.service.ts:116 的 AgentActionService.confirm() 通过会话锁、Action 锁、状态条件更新确保重复确认不会重复执行。
8. 实际执行：server/libs/shared/src/learning/agent-action.service.ts:190 的 AgentActionService.executeConfirmed() 按 Action 类型调用学习领域服务，并处理重试、失败和补偿。
9. 回执消息：server/libs/shared/src/learning/agent-action.service.ts:520 的 AgentActionService.ensureActionReceipt() 与 server/libs/shared/src/learning/agent-action.service.ts:536 的 persistActionReceipt() 把最终执行结果写回会话，页面刷新后仍可追溯。
10. 后台恢复：server/apps/ai/src/agent/agent-action-recovery.service.ts:41 的 runRecovery() 定期过期 PENDING、重试 CONFIRMED、补偿终态计划、清理孤立 Action。

3.5 私人文档上传与异步索引#

1. 知识库页面：apps/web/src/views/Knowledge/index.vue:200 的 upload() 调用 apps/web/src/apis/knowledge/index.ts:7。
2. Business 入口：server/apps/server/src/knowledge/knowledge.controller.ts:33 的 upload() 接收 multipart 文件并应用鉴权、限流、大小限制。
3. 业务上传：server/apps/server/src/knowledge/knowledge.service.ts:99 的 upload() 校验文件、配额和重复内容，在 PostgreSQL 建记录，并把原文件写入私有 MinIO Bucket。
4. 文件识别：server/apps/server/src/knowledge/knowledge.service.ts:810 的 KnowledgeService.inspectFile() 校验扩展名、MIME 和文件签名；同文件的 sanitizeFilename()、decodeMultipartFilename()、buildTitle() 分别清洗文件名、处理 multipart 中文文件名、生成展示标题。
5. 创建或重建索引：server/apps/server/src/knowledge/knowledge.service.ts:711 的 KnowledgeService.enqueue() 根据 reindex 分流：false 调 RagInternalClient.createIngestion() 创建入库任务，true 调 RagInternalClient.reindexDocument() 重建已有索引；两条路都会先把文档条件更新为 QUEUED。
6. FastAPI 入口：server-py/app/api/rag.py:42-72 的 create_ingestion() 负责创建任务；同文件 :75-91 的 reindex_document() 先校验 URL 与 body 的 documentId 一致，再复用 create_ingestion() 的 Bucket、对象路径、版本校验和 Celery 投递流程。
7. Celery 任务：server-py/app/tasks/celery_app.py:117 的 ingest_document() 获取文档级 Redis 锁，区分永久错误/瞬时错误，执行指数退避与失败清理。
8. 入库主流程：server-py/app/services/ingestion.py:82 的 process_ingestion() 回调 PROCESSING、下载并校验文件、解析、分片、Embedding、写 Chroma、核对数量、回调 READY。
9. 状态回调：server-py/app/services/callbacks.py:13 的 send_ingestion_callback() HMAC 调用 Business；server/apps/server/src/knowledge/internal-rag.controller.ts:18 的回调路由接收；server/apps/server/src/knowledge/knowledge.service.ts:610 的 KnowledgeService.applyRagStatus() 校验状态转换并更新 PostgreSQL。
10. 前端轮询：apps/web/src/views/Knowledge/index.vue:179 的 schedulePolling() 在仍有处理中记录时继续刷新列表。

3.6 私人 RAG 检索与可信引用#

1. 用户选择文档后发送问题，文档 ID 进入 SendAgentMessageRequest。
2. server/apps/ai/src/agent/agent-runner.service.ts:498-529 的 AgentRunnerService.validateDocumentScope() 只接受当前用户拥有、状态 READY、未删除的文档。
3. server/apps/ai/src/agent/agent-rag.service.ts:22-128 的 AgentRagService.prefetchKnowledge() 在模型运行前先检索；同文件 :241-263 的 contextualRetrievalQuery() 为短追问补充上下文。
4. server/apps/ai/src/agent/agent-tools.service.ts:201-252 的 search_knowledge_base Tool 允许模型主动再次检索，其 userId/documentIds 由服务端上下文注入。
5. server/libs/shared/src/rag/rag-internal.client.ts:77 的 searchKnowledge() 签名调用 FastAPI；:293 的 validateSearchResult() 再校验返回结构和越界结果。
6. FastAPI 入口：server-py/app/api/rag.py:134 的 search_knowledge() 限制 topK、最低分和总超时。
7. Chroma 检索：server-py/app/vectorstore/chroma_store.py:432 的 search_private() 用查询向量和 owner_user_id + PRIVATE + document allowlist 过滤，执行阈值过滤与去重。
8. 来源登记：server/apps/ai/src/agent/agent-rag.service.ts:130-142 的 AgentRagService.captureSources() 保存真实召回来源并发送 source SSE 事件。
9. 模型可见来源：server/apps/ai/src/agent/agent-rag.service.ts:144-164 的 AgentRagService.modelVisibleSources() 把内部 chunk 映射为临时 K1/K2 编号。
10. 最终校验：server/apps/ai/src/agent/agent-rag.service.ts:192-239 的 AgentRagService.finalizeGroundedCitations() 只保留回答中实际引用且本轮真实召回的来源，过滤伪造引用。

3.7 学习计划、任务、测验与掌握度#

1. 学习中心页面：apps/web/src/views/Study/index.vue:296 的 loadAll() 并行加载画像、计划、任务、测验等数据。
2. Business 门面：server/apps/server/src/study/study.service.ts:17-115 把 HTTP 参数转换为领域服务调用。
3. Agent 读取工具：server/libs/shared/src/learning/learning-tools.service.ts:8 的画像方法读取学习画像；同文件的统计、薄弱词、到期复习、近期测验方法继续补齐数据。
4. 待确认计划：server/libs/shared/src/learning/study-domain.service.ts:49 的 StudyDomainService.createPendingPlan() 创建 PENDING_CONFIRMATION 计划；同文件 :70 的 activatePlan() 在确认后激活。
5. 任务完成：server/libs/shared/src/learning/study-domain.service.ts:129 的 StudyDomainService.completeTask() 调用同文件 :692 的 completeTaskInTransaction()，并在后续判断是否完成整份计划。
6. 生成测验：server/libs/shared/src/learning/study-domain.service.ts:168 的 StudyDomainService.generateQuiz() 从薄弱词/到期复习中选题，保存服务端题目快照，返回不含答案的公开题面。
7. 防重复提交：server/libs/shared/src/learning/study-domain.service.ts:296 的 StudyDomainService.submitQuiz() 使用幂等键、Quiz Session 锁和词汇掌握度锁，只允许一次有效提交。
8. 更新掌握度：server/libs/shared/src/learning/study-domain.service.ts:417 的 StudyDomainService.updateMastery() 按正误、间隔、easeFactor 更新统计和下次复习时间。
9. 前端答题：apps/web/src/views/Study/index.vue:347 的 createQuiz() 生成；同文件 :360 的 gradeQuiz() 提交；同文件 :386 的 questionFeedback() 展示逐题反馈。

3.8 支付、WebSocket 与埋点#

1. 购买课程：apps/web/src/views/Course/index.vue:118 的 handleBuy() 打开支付组件。
2. 创建订单：apps/web/src/views/Course/components/Pay.vue:142 的 onConfirm() 调 apps/web/src/apis/pay/index.ts:5。
3. 服务端下单：server/apps/server/src/pay/pay.service.ts:30 的 createOrder() 创建本地支付记录并调用支付宝 SDK。
4. 支付回调：server/apps/server/src/pay/pay.service.ts:80 的 PayService.notify() 更新订单和课程购买关系，然后通知用户；当前代码未做支付宝回调验签、金额和商户号校验，这是明确的安全缺口。
5. WebSocket：server/apps/server/src/socket/socket.gateway.ts:14 的 SocketGateway.handleConnection() 绑定用户 Socket；同文件 :21 的 emitPaymentSuccess() 推送支付成功。
6. 前端埋点入口：apps/tracker/index.ts:9 的 Tracker 组合 UV、PV、性能、事件和错误采集。
7. SDK 方法：apps/tracker/src/uv/index.ts:15 的 getFingerprint() 生成/获取指纹；apps/tracker/src/pv/index.ts:16 的 reportPv() 监听页面访问；apps/tracker/src/performance/index.ts:5 的 reportPerformance() 上报 Web 性能；apps/tracker/src/error/index.ts:4 的 reportError() 捕获错误；apps/tracker/src/event/index.ts:4 的 reportEvent() 上报按钮点击事件。
8. Business 落库：server/apps/server/src/tracker/tracker.service.ts:20-88 分别写入访客关联、错误、事件、PV、性能和 UV 数据。

3A. 八条核心调用链（从前到后逐段详解）#

新的阅读顺序：每条链路先看浅色卡片里的“大白话主线”，弄清楚谁调用谁、为什么调用、返回后去哪；再看“代码位置速查”和后面的逐段说明。不要一开始就钻进所有判断分支。

定位格式统一说明：本章每个代码段都写成“从项目根目录开始的完整相对路径 + 行号范围 + 所属方法”。例如 server-py/app/tasks/celery_app.py:117-137 的所属方法是 ingest_document()，不再使用容易看不懂的 celery:117-137 之类简称。凡是代码里有 if、状态判断、条件更新或提前返回，说明中都会用大白话写清楚“为什么要判断、主要防止什么”。

3A.1 登录、Token 持久化、自动刷新与鉴权#

代码位置速查（看完上面的主线再查）#

handleLogin()：前端登录入口#

UserService.login()：业务端登录主逻辑#

安全理解：浏览器 MD5 只是把口令变成了另一个可重放的“口令”，不是安全存储。应该由服务端使用 Argon2/bcrypt + 随机 salt 校验，全程依靠 HTTPS。

generateToken()、ensureAccessToken() 与 Axios 重放#

AuthGuard.canActivate()：服务端鉴权#

3A.2 课程、购买权限、背词与掌握度#

代码位置速查（主链和独立入口）#

LearnService.saveWordMaster()：保存一批已掌握词#

LearnService.getWordList()：只让已购用户学对应课程#

3A.3 Agent 会话、SSE 流式输出、取消与恢复#

代码位置速查（看完上面的主线再查）#

sendMessage() 与 handleAgentEvent()：页面如何不断更新#

streamAgentMessage()：POST 方式 SSE#

AgentRunnerService.run()：Agent 主循环#

完成、取消与前端恢复#

3A.4 Agent 写操作：用户确认、避免重复执行与故障恢复#

代码位置速查（看完上面的主线再查）#

prepareStudyPlan()：每一段在做什么#

confirm()：确认不等于盲目执行#

executeConfirmed() 与恢复器#

3A.5 私人文档上传、MinIO、Celery 和 Chroma 异步入库#

代码位置速查（看完上面的主线再查）#

前端 upload() 与轮询#

KnowledgeService.upload()：业务事实与原文件#

inspectFile() 和 enqueue()#

RagInternalClient：创建端点和重建端点分别做什么#

这段三元表达式要从“问号”和“冒号”两边一起读：

const accepted = reindex
  ? await this.rag.reindexDocument(request, traceId)
  : await this.rag.createIngestion(request, traceId);

• const accepted = ...：不管走哪条路，都把 FastAPI 返回的 { jobId, documentId } 存到 accepted，供后面保存 jobId。
• reindex ? ...：reindex 为 true，执行问号后面的 reindexDocument()。
• : ...：reindex 为 false，执行冒号后面的 createIngestion()；这条就是之前遗漏解释的分支。
• 它不是两个方法都执行，每次只会执行其中一个。

FastAPI create_ingestion()、reindex_document() 与 Celery ingest_document()#

process_ingestion()：解析到 READY 的每个阶段#

applyRagStatus()：为什么迟到回调不能乱改状态#

3A.6 私人 RAG 检索、多重权限与可信引用#

代码位置速查（看完上面的主线再查）#

validateDocumentScope() 和 prefetchKnowledge()#

RagInternalClient.request() 与 validateSearchResult()#

FastAPI/Chroma 检索和服务端引用闭环#

3A.7 学习中心、计划/任务、测验与复习算法#

代码位置速查（页面读取、计划和测验）#

页面 loadAll()、createQuiz() 和 gradeQuiz()#

generateQuiz()：答案为什么不会发给前端#

submitQuiz() 与 updateMastery()#

3A.8 课程支付、支付回调、WebSocket 通知与埋点#

代码位置速查（支付与埋点是两条独立流程）#

Pay 组件与 Socket Hook#

PayService.createOrder() 和 notify()#

支付链审查重点：当前 notify() 代码中未看到支付宝回调验签、金额/商户号校验和幂等 upsert；Socket 也直接信任 handshake query 的 userId。这两点是演示项目的高优先级安全改造项，面试时应主动说明。

Tracker SDK：从浏览器到数据库#

3A.9 八条链路如何快速记忆#

4. Vue 前端代码地图#

4.1 启动、路由、状态与网络层#

4.2 页面与主要方法#

4.3 通用组件与 Hooks#

5. NestJS Business 代码地图#

5.1 启动与公共基础设施#

5.2 业务模块与方法#

6. NestJS Agent 代码地图#

6.1 启动、会话与 SSE#

6.2 Agent 拆分后的编排服务方法总览#

原来集中在 AgentRunnerService 的职责已拆成 7 个服务。Runner 只保留总编排；要找某段真正逻辑，先按下表找文件。

AgentToolsService.createTools() 中的十个工具位于 agent-tools.service.ts:37-371：学习画像、已购课程、学习统计、薄弱词、到期复习、近期测验、知识库检索、创建计划、生成测验、完成任务。

6.3 Action、Checkpoint 与 Provider#

server/apps/ai/src/chat/chat.service.ts:17 是旧版角色聊天链路；新版面试重点应讲 Conversations + AgentRunnerService 编排 + Lifecycle/Context/RAG/Tools/Usage 专职服务。旧链路可用于解释系统演进，但应说明后续需要迁移下线。

7. 知识库 Business 代码地图#

文件：server/apps/server/src/knowledge/knowledge.service.ts。

后台调度位于 knowledge-recovery.service.ts:23：模块启动后定时调用 recoverStaleDocuments() 和 reconcileReadyDocuments()，并用进程内布尔值避免同实例重入。

8. FastAPI / Celery / Chroma 代码地图#

8.1 启动、配置、资源与安全#

8.2 文档解析、分片与 Embedding#

当前解析器不支持 OCR、表格结构恢复和复杂多栏版式；扫描 PDF 会因无可提取文本失败。这是当前能力边界，不应在面试中说成“支持任意 PDF”。

8.3 入库服务与 Celery#

8.4 Chroma 方法#

文件：server-py/app/vectorstore/chroma_store.py。

当前检索是稠密向量检索，并非 BM25 + 向量的混合检索，也没有 Cross-Encoder Reranker；不要把其他工作项目中的混合检索能力说成这个仓库已经实现。

9. 跨服务通信与 HMAC#

9.1 NestJS 调 FastAPI#

文件：server/libs/shared/src/rag/rag-internal.client.ts。

server/libs/shared/src/internal-auth/internal-hmac.service.ts:31 的 sign() 创建签名；:66 的 verify() 验签。internal-hmac.guard.ts:46 的 canActivate() 再加 Redis nonce 防重放，用于 Python 回调 NestJS。

9.2 API 合约#

• Python Pydantic 请求/响应：server-py/app/schemas/rag.py:8-96。
• 导出的 OpenAPI：server-py/openapi.json。
• 生成的 TypeScript Client：server/libs/shared/src/generated/rag，不要手改。
• 根脚本 package.json 中 rag:contract 重新导出并生成；rag:contract:check 检查代码与合约是否漂移。

10. PostgreSQL 数据模型#

文件：server/prisma/schema.prisma。

迁移重点：20260722122000_add_langgraph_schema 建独立 Checkpoint Schema；20260722190000_agent_rag_learning 增加 Agent/RAG/学习模型；后续三个迁移修正掌握度回填与 QuizMode。

11. 共享类型、配置与埋点 SDK#

11.1 packages/common#

• packages/common/ai/index.ts:4-104：会话、消息、Run、Action、SSE、Usage 类型。
• packages/common/knowledge/index.ts:1-55：文档状态、列表、Citation 和检索结果。
• packages/common/study/index.ts:1-119：计划、任务、测验、弱词、复习 DTO。
• packages/common/user/index.ts:1-68：用户、登录、注册、Token Payload。
• packages/common/course/index.ts:4、word/index.ts:1、pay/index.ts:1、tracker/index.ts:1：各业务共享 DTO。

共享 DTO 只解决 TypeScript 前后端一致性；Python RAG 通过 OpenAPI 合约同步，不直接引用 TypeScript 源码。

11.2 apps/tracker#

• src/report/index.ts:1/:6：Beacon/fetch 两种上报方式。
• src/uv/index.ts:6/:15：本地 UV 标识与 FingerprintJS 指纹。
• src/pv/index.ts:4/:16：首屏和 History 路由变化的 PV。
• src/performance/index.ts:5：PerformanceObserver/Web Vitals 数据。
• src/event/index.ts:4：点击等自定义事件。
• src/error/index.ts:4：JS Error 和 Promise rejection。

12. Docker、代理、健康检查与备份#

12.1 Compose 服务定位#

开发环境服务从 docker-compose.dev.yml:118 开始：PostgreSQL 119、Redis 137、Ollama 153、MinIO 191、Chroma 220、存储初始化 235、RAG API 244、Worker 272、Migration 295、Business 304、Agent 326、Web 369。

生产环境从 docker-compose.prod.yml:120 开始：PostgreSQL 121、Redis 137、MinIO 152、Chroma 168、RAG API 188、Worker 204、Migration 215、Business 224、Agent 240、Backup 286、Web 326、Caddy 346。

12.2 镜像与代理#

• Dockerfile.server:1-46：Node 多阶段构建，一次生成 Prisma Client 并构建 Business/Agent，运行时用 node 用户。
• server-py/Dockerfile:1-28：uv 锁定依赖，Python 3.12，非 root rag 用户运行 Uvicorn。
• Dockerfile.web:1-30：构建 Tracker + Vue，产物进入 Nginx。
• deploy/nginx/default.conf:35：/api/ 代理 Business。
• deploy/nginx/default.conf:47：/ai/ 代理 Agent，并关闭缓冲以支持 SSE。
• deploy/nginx/default.conf:64：/socket.io/ 代理 WebSocket。
• deploy/nginx/default.conf:76/:87：只公开 avatar/course 对象；:98 拒绝其他 /media/，因此私人知识文件不会公开。
• deploy/caddy/Caddyfile：生产 TLS/外层反向代理入口。

12.3 备份#

• deploy/backup/backup-once.sh:60：pg_dump 生成压缩 PostgreSQL 备份。
• :69：生成 SHA-256 校验文件。
• :73-81：上传数据库备份，并把指定 MinIO Bucket mirror 到备份 S3。
• Chroma 是可从 PostgreSQL 元数据与 MinIO 原文件重建的派生数据，因此备份主链以 PostgreSQL + MinIO 为准。

13. 健康检查和故障定位#

13.1 NestJS#

• server/libs/shared/src/health/infrastructure-health.service.ts:62 的 check() 并行检查 PostgreSQL、Redis、MinIO。
• Business：server/apps/server/src/health/health.controller.ts:9/:14。
• Agent：server/apps/ai/src/health/health.service.ts:29 额外检查模型、RAG 与 Checkpoint。

13.2 Python#

• server-py/app/services/readiness.py:26 的 check() 并行检查 Redis、MinIO、Worker、Chroma、Embedding。
• :64 的 _run_check() 为每个组件统一超时和错误结构。
• server-py/app/api/health.py:12/:22 暴露 /health/live、/health/ready。

13.3 常见故障从哪里查#

14. 当前实现边界与面试前风险#

1. 密码安全：user.service.ts:37 是明文比较，必须改为密码哈希。
2. 并发配置需讲清参数语义：agent-runner.service.ts:85-89 调用 AgentConfigService.integer('AGENT_MAX_CONCURRENT_RUNS_PER_USER', 2, 1)，参数是“默认值 2、下限 1”，第四个参数才是上限；真正的并发抢占在 agent-run-lifecycle.service.ts:46-105。
3. Agent 大类拆分已落地：AgentRunnerService 已从约 1900 行缩到 540 行，运行生命周期、上下文、RAG/引用、Tools、Usage 和 Config 都已拆出。面试时应讲“Runner 仅编排，专职服务承载细节”以及如何用事务、状态条件更新和事件协议保持拆分前后行为一致。
4. 核心测试不足：当前测试主要覆盖配置与 HMAC，Agent、Action 并发、知识状态机、入库补偿和 RAG 权限需补单元/集成/E2E。
5. PDF 能力边界：只有文本提取，没有 OCR、表格和复杂布局恢复。
6. 检索能力边界：当前是 Dense Retrieval + 去重，没有 BM25 混合检索和 Reranker。
7. MCP/爬虫不在本仓库：简历中的 MCP、Multi-Agent、Playwright/Scrapy 能力需要用其他真实项目说明。
8. 旧链路并存：server/apps/ai/src/chat 是旧聊天实现，建议明确迁移计划，避免面试官误认为存在两套相互冲突的 Agent 系统。
9. 行号会漂移：修复以上问题后，用类名/方法名搜索，并更新本文的提交基准。

15. 面试现场快速定位表#

16. 一句话总结每个核心服务#

• Vue Web：负责学习、知识库、Agent 对话与确认交互，不决定权限和业务事实。
• NestJS Business：负责用户身份、课程、支付、学习、文档元数据和所有业务写入，是主要事实边界。
• NestJS Agent：负责会话、工具选择、模型编排、SSE、引用校验、Run/Action 生命周期，不直接让模型改数据库。
• FastAPI RAG：只负责文档基础设施和检索，不维护用户/课程/计划等业务真相。
• Celery Worker：把耗时解析、分片、Embedding、Chroma 写入从上传请求中解耦。
• PostgreSQL：业务事实、Agent 状态和 Checkpoint。
• MinIO：可重新索引的原始文件与公开媒体对象。
• Chroma：可重建的向量和分片派生数据。
• Redis：短期协调状态：任务队列、锁、限流、nonce、心跳，不是长期事实来源。