FranklinWH-Toolbox/docs/data-download

DataDownload 文档导航

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

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

文档职责

文档	内容	何时读取
requirements.md	产品需求、权限、状态语义、文件行为和验收标准	讨论业务行为、判断方案是否符合需求时
technical-design.md	领域模型、RequestKey、Frozen、存储、并发、FaultRecord 和接口设计	修改后端模型、服务或 API 时
implementation-status.md	当前已实现能力、代码入口、已知差异和验证方式	开始编码、评审当前代码或交接时
../issues/data-download-open-issues.md	DD 编号问题的状态、优先级和关闭记录	处理具体缺陷或规划下一项工作时
archive/data-download-integrated-design-2026-09-21.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 状态。
• 动态缺陷、风险和待办只放问题台账，不在多个文档复制一份。
• 归档文件保持只读；新决策不得继续追加到归档。