按读者旅程组织。先想清楚"我是谁、我要做什么"，再选目录。
| 你的角色 | 看这里 |
|---|---|
| 对接方 / 业务方：调 HTTP API、收 MQ 消息、读写共享数据库 | api/ |
| 内部开发者：改代码、看模块边界、加新模块 | internals/ |
| 运维 / 部署方：起服务、调配置、看依赖 | ops/ |
| 贡献者：提 PR、跑测试、写迁移、走 spec-as-test 流程 | contributing.md |
| AI Agent / 新成员：从 0 理解项目 | ../CLAUDE.md |
api/ — 对外契约
| 文件 | 内容 |
|---|---|
| http_contracts.md | REST API 接口契约 |
| mq_contracts.md | MQ 消息载荷与对接说明 |
| error_codes.md | 业务错误码 |
| schemas/mysql.md | MySQL 表结构（共 12 张表） |
| schemas/qdrant.md | Qdrant collection 与 payload |
| schemas/elasticsearch.md | ES 索引结构 |
internals/ — 内部实现
| 文件 | 内容 |
|---|---|
| project_structure.md | 项目目录结构 |
| pipeline_architecture.md | 解析 Pipeline 架构 |
| parse_task_pipeline.md | 解析任务流水线状态机 |
| recall_pipeline.md | 召回 Pipeline 架构 |
| recall_http_api.md | 召回 HTTP 入口与会话/鉴权 |
| file_parser.md | 文件解析器（含回退链） |
| markdown_parser.md | Markdown 解析与 LLM 增强 |
| chunking.md | 分块策略与流水线 |
| vectorization.md | 向量化模块（dense） |
| sparse_vector.md | 稀疏向量（BGE-M3）编码与索引 |
| preprocessor.md | ES 预分词（RAGFlow） |
| es_index_storage.md | ES 索引与 BM25 检索 |
| mq.md | MQ 中间件实现 |
| llm.md | LLM 调用模块 |
| cache.md | 缓存基础设施（Redis） |
| object_storage.md | 对象存储 |
| naming_conventions.md | 命名约定 |
ops/ — 部署与配置
| 文件 | 内容 |
|---|---|
| deploy.md | 部署指南 |
| configure.md | 配置详解 |
contributing.md — 贡献者规范
涵盖分支、提交、代码风格、测试、Alembic 迁移、文档同步、spec-as-test 工作流。
- 每个事实只在一处正式描述，其他位置用链接引用。
- 文档是代码的摘要，代码是权威源。冲突时改文档不改代码。
- 临时交付物（PRD、技术方案、实施报告）放 .specs/，不进 docs/。
- 修改文档前阅读 contributing.md §七。