架构设计中的接口与调用流程交接

## 任务目标 请把已确认的需求整理为开发能够逐项实现的架构交接稿。先沿用现有系统边界，说明确有必要新增或调整的部分。 交付能用于评审或后续实施的具体方案、规则与样例；未要求实施的部分不声称已经落地。 ## 输入信息（选填） 两项均可留空，也可直接用一句话说明目标并附上已有资料。无需自行整理版本、配置或完整需求表；能读取的内容由执行者补齐。 需求或架构问题： 工程或设计资料： ## 信息不完整时 先使用本次对话中已经说明的信息；用户留空、写“暂无／不清楚”或未替换输入标记，都按缺失处理，不当作真实路径、参数或业务值。已能从资料确定的内容不重复询问，不编造文件、日志、接口、业务值或执行结果。在用户已授权的范围内读取相关工程和材料，不为补齐输入擅自扩大操作范围。 ### 优先确认 - 确认现有模块、入口、配置和数据流，标出已存在的复用能力。 - 从需求与调用方提取字段含义、状态、权限及失败处理约定，不让用户重新抄接口清单。 ### 可采用的默认处理 - 保留当前系统边界和技术选型，以最小必要变化描述职责与调用关系。 - 无性能目标时先列测量条件，不承诺吞吐；没有真实目录时明确区分拟新增位置与已存在文件。 ### 必须有依据的事项 - 影响数据归属、业务状态或外部契约的决策无法从材料确定时，集中列出对应决策及影响，不暂停无关设计。 只有缺口会改变业务结果、权限边界或关键实现，且无法从现有资料确认时，才集中提出最多 3 个关键问题；说明影响，并继续完成不依赖答案的部分。一般命名、排版和可逆实现细节按现有约定决定，不逐项等待确认。 ### 资料仍不足时的交付 - 只有业务文字时交付标明假设的模块职责、接口草案和调用流程；代码路径标为建议。 - 缺少外部接口时先明确本系统边界、所需契约和不依赖该接口的实施顺序。 ## 执行要求 按实施方案、文件职责、数据结构与接口、调用流程、待澄清事项组织交付。类图适合表达类和接口时再使用，不强迫所有语言或系统采用面向对象结构。 完成以下工作： 1. 将需求映射到现有入口和模块，区分已知约束、可自主决定的实现细节与影响架构的未知条件。没有真实目录或接口资料时，只给带假设的设计，不把猜测路径当作已存在文件；阻断条件集中说明原因和所需资料。 2. 给出实施方案及选择依据，优先复用已验证的框架、组件和部署方式。新增依赖要说明具体解决什么问题、版本约束及维护成本，不因“可扩展”就拆成多个服务，也不凭空承诺吞吐量或可用率。 3. 列出相对路径、文件职责、变更类型与所属模块，标明实际启动入口和配置读取入口。区分已存在路径与拟新增路径；避免同一责任散落多处，不能只列抽象层名称而缺少可落地文件。 4. 定义关键数据结构和接口：输入、输出、类型、必填、错误语义及调用方。涉及持久化时补上字段含义和约束；涉及身份或租户时说明校验位置、数据归属和调用上下文来源，不默认由前端传参即可可信。 5. 为主要成功路径和有业务影响的失败路径编写调用流程。流程中的模块、接口、参数和返回值必须能在前述清单找到对应定义；标出初始化、状态变化、事务边界和重试条件，不能把异常分支省略为“系统处理”。 6. 做交叉核对：每项验收条件由哪些文件和接口承接，流程引用是否悬空，错误状态是否可恢复。提供 Mermaid 时实际渲染后才能声明语法通过；没有渲染环境则标注未验证，并保留文字流程供开发核对。 ## 交付与验收 输出顺序：实施方案；文件职责表；数据结构与接口表；主要调用流程；“验收条件→接口→文件”映射；待澄清事项。表中分别保留现状、拟议变更和验证方式，不混写成已完成事实。每个待澄清项说明它会影响哪个设计决定；若只影响局部实现，先完成其余交接内容。最终以接口名称一致、文件职责清楚、需求能追溯且没有未标记假设作为评审标准。 ### 本条完成检查 - 需求、接口、数据、文件职责和调用流程名称一致。 - 现状、建议与待确认内容明确分开，开发者可据此安排可验证的工作项。 按本条要求组织结果，使用简洁中文和一致的编号、术语、缩进及空行；已有项目格式优先。只说明实际完成的内容，将采用的假设、未完成项和缺少的条件写在相关位置，不额外生成无关文档。未执行、无法复现或缺少证据的检查如实标注，不宣称已通过或已有性能收益。 ## 参考资料与适用边界 整理说明：该组织方式参考下方公开实现，权限边界和可验证性要求为本模板补充。 官方来源：https://github.com/FoundationAgents/MetaGPT/blob/11cdf466d042aece04fc6cfd13b28e1a70341b1f/metagpt/actions/design_api_an.py 来源许可说明：MIT（https://github.com/FoundationAgents/MetaGPT/blob/11cdf466d042aece04fc6cfd13b28e1a70341b1f/LICENSE）。本条为中文原创整理，来源内容与本模板补充要求已在正文区分。