# DataDownload 文档导航

本目录采用“按关注点加载”的文档结构。AI 和开发者不应默认加载全部文档；先读本页，再根据任务选择最少的必要文件。

目录内的 [`AGENTS.md`](AGENTS.md) 将同样的加载规则声明为 AI 工作约束，避免后续代理又默认读取完整归档。

## 文档职责

| 文档 | 内容 | 何时读取 |
|---|---|---|
| [requirements.md](requirements.md) | 产品需求、权限、状态语义、文件行为和验收标准 | 讨论业务行为、判断方案是否符合需求时 |
| [technical-design.md](technical-design.md) | 领域模型、RequestKey、Frozen、存储、并发、FaultRecord 和接口设计 | 修改后端模型、服务或 API 时 |
| [implementation-status.md](implementation-status.md) | 当前已实现能力、代码入口、已知差异和验证方式 | 开始编码、评审当前代码或交接时 |
| [../issues/data-download-open-issues.md](../issues/data-download-open-issues.md) | DD 编号问题的状态、优先级和关闭记录 | 处理具体缺陷或规划下一项工作时 |
| [archive/data-download-integrated-design-2026-09-21.md](archive/data-download-integrated-design-2026-09-21.md) | 拆分前的完整集成设计归档 | 仅在新文档缺少历史依据或需要追溯旧章节时 |
| [data-download-code-review-2026-09-19.md](data-download-code-review-2026-09-19.md) | 2026-09-19 的一次性代码审查快照 | 追溯当时问题时 |

## 推荐加载组合

- 回答“系统应该怎样工作”：本页 + `requirements.md`。
- 实施某项功能：本页 + `requirements.md` 的相关章节 + `technical-design.md` 的相关章节 + `implementation-status.md`。
- 处理 `DD-xxx`：本页 + 问题台账中的该项；再按其链接读取相关需求或设计章节。
- 核对当前代码：本页 + `implementation-status.md`，然后直接检查源码。
- 追溯旧决策：最后才读取 `archive/`，不要把归档当作当前实现事实。

## 事实优先级

发生冲突时按以下顺序判断：

1. 当前代码和自动化测试代表实际行为；
2. `implementation-status.md` 解释当前实现边界；
3. `requirements.md` 定义目标产品行为；
4. `technical-design.md` 定义实现约束；
5. 问题台账记录尚未解决的偏差；
6. `archive/` 仅用于历史追溯。

代码与需求不一致时，不应静默修改需求以迁就代码；应在问题台账新增或更新 DD 项，并明确选择修代码还是变更需求。

## 维护规则

- 产品行为变更只更新 `requirements.md`，并在技术设计中补充实现影响。
- 数据模型、并发或存储方案变更只更新 `technical-design.md`，避免把代码细节写入需求文档。
- 功能落地后更新 `implementation-status.md` 和对应 DD 状态。
- 动态缺陷、风险和待办只放问题台账，不在多个文档复制一份。
- 归档文件保持只读；新决策不得继续追加到归档。