architecture

架构

创建或更新根目录中的 ARCHITECTURE.md。设计我们计划构建的系统。 将此文档作为长期维护的系统文档，与 REQUIREMENTS.md 并列。 使用 /requirements 记录产品需求，使用 /spec 记录功能的技术变更。

流程

1. 阅读需求、仓库说明、现有架构，以及相关代码、架构描述、测试和基础设施。新系统可能尚无代码。
2. 找出影响系统的决策：边界、职责、数据所有权、依赖关系和质量约束。对缺失且影响重大的决策提出问题；有依据时，建议一种方案并说明其权衡。
3. 选择满足需求的最简单结构。对于影响重大的决策，说明所选方案、最有力的替代方案、选择理由和主要代价。相关时考虑沿用现有系统。不会影响选择的方案比较可以略过。
4. 按照下方的结构撰写架构。始终包含架构图和数据流图。引用需求，而非复制需求内容。
5. 根据需求追踪关键的成功和失败流程。检查所有权、契约、数据一致性、安全性、恢复方式和可衡量的限制。
6. 完成架构后停止，供评审使用。不要规划任务或进行实现。

文档结构

• 摘要和目标： 系统、主要部分、事实来源，以及驱动设计的需求。
• 系统边界： 用户、外部系统、组件和重要接口。包含所需的架构图和数据流图。
• 职责和依赖关系： 各部分负责什么、不负责什么，以及依赖关系的指向。
• 数据模型： 核心实体、关系、标识符、所有权、生命周期、约束、一致性规则、保留期限和存储选择。适用时包含实体关系图。引用较大的架构描述，而不是重复其中内容。
• 运行时流程： 重要的执行顺序、数据流动、事务、副作用、故障、重试和恢复方式。
• 安全和运维： 对设计有影响的信任边界、授权、部署、可观测性、资源限制和运维人员的恢复方式。
• 运行预期： 对设计有影响的预期工作负载、延迟、可用性、恢复和成本限制。使用有依据的目标；记录影响重大的未知事项及其影响，而不是编造数字。产品限制请引用需求。
• 通往目标系统的路径： 对于现有系统，说明重要差距、兼容性约束、迁移方式和必要时的回滚方式。功能细节保留在规格中，交付任务放在 /plan。
• 决策和状态： 将决策标记为拟议或已接受。另行说明当前系统中已实现、缺失或不同的部分。接受决策不代表已经实现。
• 风险和验证： 尚未解决的决策、假设、质量场景，以及验证设计所需的检查。

图示

始终包含一个 Mermaid 图，展示主要组件、外部参与者、数据存储和数据流。一个图可以同时涵盖架构和流程；如果合在一起会难以阅读，则使用第二个图。

使用清晰的标签、带标签的箭头，以及表示系统边界或信任边界的分组。展示各部分之间传递的内容，而不只是它们之间的连接。留出充足的间距，让布局易于理解。使用克制且一致的配色，并确保对比度足够、易于阅读。避免箭头交叉和装饰性细节。图示过于拥挤时，按流程拆分，并保留概览图。

完成前渲染并检查图示。检查标签、箭头方向、可读性，以及图示是否与书面设计一致。添加说明文字，解释主要流程和读者需要了解的边界。

图示为必需内容。仅在有助于解释系统时才使用其他章节；合并相关内容，省略空章节。在此描述通用规则；将特性专属的架构变更和迁移放入其规格说明中。

针对现有实现的说法，请依据权威文件或运行时证据进行核实。明确标注未来行为和假设。未经人工批准，不得将提案标记为已接受。为重要的架构规则分配稳定的 INV-n ID，并注明预期的执行方式和验证依据。

当已接受的变更影响所有权、依赖关系、接口、存储数据、信任边界、部署或硬性限制时，更新本文档。保持本文档为最新状态。保留有价值的内容和稳定引用；在规格说明中保留特性决策历史。

返回内容

报告文档路径、主要决策和权衡、实现缺口，以及任何阻塞性问题。