# 源码拆解

这里统一存放“结合真实源码的讲解式梳理”。

这一组文档不追求一次性讲完整个系统，而是按“**少量焦点 + 全局视角 + 真实调用链**”逐段拆开，方便后续持续补充。

## 写作约定

- 每篇尽量只聚焦 `3` 个点以内，避免信息过载。
- 优先从“系统全景 → 一条真实链路 → 为什么这样分层”展开。
- 尽量带上流程图、时序图、线框图，帮助建立脑内模型。
- 优先引用当前仓库真实源码位置，而不是抽象空讲。

## 当前目录

- `01-admin-简历保存链路-全景与草稿落库.md`
  - 主题：从 `admin` 端保存草稿出发，理解请求如何进入后端并落到 `SQLite`
  - 当前包含：
    - 点 1：系统全景图
    - 点 2：一次保存草稿请求的真实时序
- `02-server-关键链路时序图.md`
  - 主题：`server` 侧登录、发布、AI、RAG 的关键时序
  - 当前包含：
    - 点 1：登录与 `/auth/me` 时序
    - 点 2：草稿保存与发布时序
    - 点 3：AI 分析与优化时序
    - 点 4：RAG 建索引与问答时序
    - 点 5：发布后 `web` 刷新生效时序 + 数据状态图
- `03-server-10分钟主链路速读.md`
  - 主题：10 分钟内建立 `server -> db -> web` 主链路脑图
  - 当前包含：
    - 点 1：按分钟分段的文件阅读顺序
    - 点 2：每段必须拿到的结论
    - 点 3：发布后刷新生效的最短 6 步复述
- `04-web-SSR-缓存策略对照图.md`
  - 主题：从 `web` 侧看请求层、Next 渲染层、HTTP 缓存头如何协同
  - 当前包含：
    - 点 1：三层缓存职责和对照矩阵
    - 点 2：发布后刷新生效时序
    - 点 3：面向当前项目的 Next 实战建议
- `05-alova-Method-first-SSR-CSR-实践与避坑.md`
  - 主题：`api-client` 的 Method-first 设计、hooks 拆分与 SSR/CSR 协作策略
  - 当前包含：
    - 点 1：为什么去掉 Promise facade，只保留 `createXxxMethod`
    - 点 2：水合、数据变化、重复请求的项目级处理方式
    - 点 3：当前已落地优化与后续可渐进演进方向
- `06-M22-AI-简历导入识别-时序图与优化路线.md`
  - 主题：M22 AI 简历导入识别的异步 Job、状态流转、容错修复与后续优化路线
  - 当前包含：
    - 点 1：上传 -> 识别 -> diff -> apply 的完整时序
    - 点 2：Job 状态机与前端轮询协作方式
    - 点 3：`details`、SSE、细粒度 diff、缓存持久化的可行方案
- `07-M22-简历导入识别-12轮源码演进.md`
  - 主题：M22 功能从第 1 轮到第 12 轮的源码级演进过程
  - 当前包含：
    - 点 1：全景架构 Mermaid 图与异步 Job 状态机
    - 点 2：repair → normalize → validate AI 输出防线
    - 点 3：SSE 实时推送机制与内存订阅
    - 点 4：输入治理的规则层 + AI 层分层设计
    - 点 5：12 轮演进速览表与四条工程原则
- `08-RAG-检索与问答-管线与重排拆解.md`
  - 主题：RAG 检索与问答的完整管线拆解
  - 当前包含：
    - 点 1：三通道检索架构（Milvus / JSON / SQLite）与路由决策
    - 点 2：5 层重排管道（策略检测 → section加权 → 噪音诊断 → 去噪 → 证据分层）
    - 点 3：配置驱动的重排策略（keywordHints / sectionBoost / selection）
    - 点 4：ask 问答管线（双源合并 → 两段门控 → 流式/非流式 LLM）
    - 点 5：ECS 本地搜索兼容方案与封装拆分评价
- `09-M23-AI-Chat-流式对话与治理闭环源码梳理.md`
  - 主题：M23 公开站 AI Chat 从流式接口到全局 Drawer、会话持久化与 Admin 治理的完整源码拆解
  - 当前包含：
    - 点 1：头像入口 -> consent -> public claim -> Drawer 打开的真实时序
    - 点 2：SSE 事件流（start/token/citation/block/summary/done/error）与前端状态更新
    - 点 3：`ai_chat_*` 持久化模型、summary 节点、Dock 恢复与治理台视角
    - 点 4：分层验证清单（API Client / Server / Web / Admin）

## 后续计划

后续继续沿着这条主线补：

- 为什么要拆成 `controller -> service -> repository`
- 发布链路为什么不是简单“改状态”
- `summary` 接口为什么是后端成熟化的一步
- 前端缓存层如何和后端草稿 / 发布态配合
- web 侧从 `no-store` 渐进到 `revalidate/tag` 的迁移节奏
