# 文档导航

`docs/` 是本项目唯一的设计、契约、决策和验证文档目录。

## 首读顺序

1. [`plan-0918.md`](plan-0918.md)：W00–W16 任务台账、阅读索引、I/M/G 门禁和当前范围。
2. [`Go重写方案_v0.3.md`](Go重写方案_v0.3.md)：单节点、单 Cell、单租户的总体方案与分期。
3. [`contracts/`](contracts/)：SaaS、Dispatcher、Agent、RabbitMQ 和 OSS 的项目内契约。
4. [`验证与切换验收_v0.3.md`](验证与切换验收_v0.3.md)：验收门禁、证据要求和第二阶段边界。
5. [`evidence/20260922-mq-only-local-final.md`](evidence/20260922-mq-only-local-final.md)：当前 MQ-only 本地/隔离范围的最新汇总证据。

## 按职责查找

### 方案与范围

- [`Go重写方案_v0.3.md`](Go重写方案_v0.3.md)：产品范围、运行边界和阶段目标。
- [`通信与事件数据交互_v0.1.md`](通信与事件数据交互_v0.1.md)：通信、事件、AI 配置和上传边界。
- [`G0开发准备与契约冻结提案_v0.1.md`](G0开发准备与契约冻结提案_v0.1.md)：D01–D10 方向及 G0 前置。
- [`开源组件选型与复用清单_v0.2.md`](开源组件选型与复用清单_v0.2.md)：组件、SDK、版本和 PoC 门禁。
- [`OpenAPI与MQ字段索引_v0.1.md`](OpenAPI与MQ字段索引_v0.1.md)：旧源只读索引，不是当前 MQ-only Schema。

### 契约与决策

- [`contracts/saas-dispatcher.md`](contracts/saas-dispatcher.md)：SaaS↔Dispatcher 的 MQ-only 边界、D 身份和专用 Topic。
- [`contracts/dispatcher-agent.md`](contracts/dispatcher-agent.md)：Dispatcher↔Agent 的 Unary 与异步结果边界。
- [`contracts/saas-rabbitmq-oss-dispatcher-agent-timeline.md`](contracts/saas-rabbitmq-oss-dispatcher-agent-timeline.md)：全链路时序和 OSS 直传路径。
- [`contracts/mq-only-v1-freeze-proposal.md`](contracts/mq-only-v1-freeze-proposal.md)：已确认的 MQ-only v1 冻结方向。
- [`decisions/`](decisions/)：已记录的关键技术决策。

### 证据

- `evidence/` 保存可复核的运行事实、测试结果和边界说明；历史证据不因当前契约变化而改写。
- 当前 MQ-only 本地结论以 [`plan-0918.md` §8.2](plan-0918.md) 和 [`20260922-mq-only-local-final.md`](evidence/20260922-mq-only-local-final.md) 为准。
- 证据中的 `mock`、`mixed`、`real` 必须按原记录理解；本地或隔离通过不等于真实 SaaS、供应商、生产或容量验收通过。

### 归档

- [`archive/`](archive/) 保存已被当前基线替代、但仍需保留追溯价值的文档，以及无项目归属的旧参考资料。
- 归档文件不作为当前实现、契约或验收依据；需要引用历史事实时必须使用归档路径。

## 维护规则

- 不在 `docs/` 复制上游 Schema；上游契约包、生成物和字段索引保持单一来源。
- 不把证据摘要改写成新的通过结论；范围、环境和未执行项必须保持可追溯。
- 新增文档先归入方案、契约、决策、证据或归档中的一个明确类别，不在根目录新增无类别文件。