# 文档导航

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

## 首读顺序

1. [`plan-config-read-v0.1.md`](plan-config-read-v0.1.md)：四条只读接口、任务发现、有界消费及外呼时段的 F00–F09/F06 执行入口、C/L/M 和 I/M/G 门禁；任务发现 v0.3 另读 [`plan-0926.md`](plan-0926.md)。原 [`plan-0918.md`](archive/plan-0918.md) 按 HEAD 原文归档，仅作旧 W00–W16 历史。
2. [`architecture/Go重写方案_v0.3.md`](architecture/Go重写方案_v0.3.md)：单节点、单 Cell、单租户的总体方案与分期。
3. [`contracts/`](contracts/)：SaaS、Dispatcher、Agent、RabbitMQ 和 OSS 的项目内契约。
4. [`acceptance/验证与切换验收_v0.3.md`](acceptance/验证与切换验收_v0.3.md)：验收门禁、证据要求和第二阶段边界。
5. [`evidence/f09-local-acceptance-v0.3.md`](evidence/f09-local-acceptance-v0.3.md) 和 [`evidence/f06-local-release-gates-v0.3.md`](evidence/f06-local-release-gates-v0.3.md)：任务发现当前项目内 Mock 与发布阻断证据；[`20260922-mq-only-local-final.md`](evidence/20260922-mq-only-local-final.md) 仅作旧 MQ-only 本地基线。

## 按职责查找

### 方案与范围

- [`architecture/Go重写方案_v0.3.md`](architecture/Go重写方案_v0.3.md)：产品范围、运行边界和阶段目标。
- [`contracts/通信与事件数据交互_v0.1.md`](contracts/通信与事件数据交互_v0.1.md)：通信、事件、AI 配置和上传边界。
- [`architecture/G0开发准备与契约冻结提案_v0.1.md`](architecture/G0开发准备与契约冻结提案_v0.1.md)：D01–D10 方向及 G0 前置。
- [`dependencies/开源组件选型与复用清单_v0.2.md`](dependencies/开源组件选型与复用清单_v0.2.md)：组件、SDK、版本和 PoC 门禁。
- [`references/OpenAPI与MQ字段索引_v0.1.md`](references/OpenAPI与MQ字段索引_v0.1.md)：旧源只读索引，不是当前 MQ-only Schema。
- [`references/saas-page-snapshot-analysis.md`](references/saas-page-snapshot-analysis.md)：SaaS 页面可见字段盘点；其中旧 MQ 配置建议已被新目标取代，非契约/验收证据。

### 契约与决策

- [`thirds/第三方对接事件与请求消费顺序_v0.1.md`](thirds/第三方对接事件与请求消费顺序_v0.1.md)：SaaS↔Dispatcher 的项目内配置与 MQ 业务契约；仅其中旧 §2.5 任务发现已由 [`thirds/v0.3.md`](thirds/v0.3.md) 项目内合同替换，[`v0.2`](thirds/v0.2.md) 为历史。取消对外查询/补传及分散事件仍待外部签收。
- [`../contracts/upstream/v1/mq.schema.json`](../contracts/upstream/v1/mq.schema.json)、[`event-payloads.schema.json`](../contracts/upstream/v1/event-payloads.schema.json)、[`mq-topology.json`](../contracts/upstream/v1/mq-topology.json)：现行 MQ 信封、事件正文、路由的机器契约。
- [`contracts/config-read-fields-v0.1-proposal.md`](contracts/config-read-fields-v0.1-proposal.md)：两只读接口字段来源、响应结构与项目自拟 Schema/Mock 示例；**不是现网 SaaS JSON 或正式合同**。
- [`decisions/`](decisions/)：已记录的关键技术决策。

### 证据

- [`evidence/README.md`](evidence/README.md)：证据与开发文档的职责边界、保留和归档规则。
- `evidence/` 保存可复核的运行事实、测试结果和边界说明；历史证据不因当前契约变化而改写。
- 旧 MQ-only 本地结论见[归档计划 §8.2](archive/plan-0918.md)和 [`20260922-mq-only-local-final.md`](evidence/20260922-mq-only-local-final.md)；**本轮新方向的状态只在[新计划 §8](plan-config-read-v0.1.md)登记**。
- 证据中的 `mock`、`mixed`、`real` 必须按原记录理解；本地或隔离通过不等于真实 SaaS、供应商、生产或容量验收通过。

### 归档

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

## 维护规则

- 不在 `docs/` 复制上游 Schema；上游契约包、生成物和字段索引保持单一来源。
- 不把证据摘要改写成新的通过结论；范围、环境和未执行项必须保持可追溯。
- 新增文档先归入方案、契约、决策、证据或归档中的一个明确类别；根目录 `plan-config-read-v0.1.md` 是总执行入口，用户指定的 `plan-0926.md` 仅说明 v0.3 任务发现分项，不另设第二个总台账；不新增无类别根文件。