用途:在实现开始前,把已批准的规格转化为 Sails 专属架构产物,写入 docs/plans/YYYY-MM-DD-<topic>-architecture.md。若改动已发布合约或引入新部署版本,架构说明还须定义公共路由、回复、事件、生成客户端及前端、索引器等链下消费方的兼容性预期。
主要能力与检查项:选择显式服务边界;说明状态归属;明确程序构造函数形态与存储模式;考虑路由与事件;延迟工作须基于区块并允许后续自消息;若涉及未来自动化,须明确预留 gas 或 ReservationId 的使用与时长;若消息可能进入 Waitlist,须考虑租金、过期与最大时长;明确 #[program] 与 #[service] 边界;路由、回复、事件须稳定以支持生成客户端;延迟或自调用命中 Sails 路由时须保留生成客户端或等价的路由前缀编码;考虑异步 Gear 消息流与失败路径;改动已发布合约时须分类为增量或破坏性;除非显式版本化,保留既有公共路由、回复与事件;定义合约版本与 Active、ReadOnly 等状态面;说明新部署版本对前端与索引器的影响;切换时说明新旧版本如何共存;迁移时定义导出/导入职责而非笼统“升级”。
已发布合约演进默认:公共路由、回复形状、事件负载与生成客户端预期属兼容敏感面;优先增量变更(新路由、新服务、新部署版本);定义新旧版本共存与旧版本停止写入的生命周期;状态迁移须定义 V1、V2 与链下迁移器的分工。
未来迁移就绪:识别业务关键状态,区分真源与可重建数据,说明导出方式(全量读取、选择性状态函数或显式导出方法),标注需确定性分块或规范排序的集合,说明未来是否需要 ReadOnly 生命周期模式。
限制与护栏:规格缺失时先创建规格;优先 Sails 服务组合而非临时原始 Gear 分层;生成客户端作为构造函数与服务调用的默认路由契约;不得假设延迟自动化无需未来 gas;不得把 Waitlist 存储视为免费或可无限延长;架构说明不写不影响公共合约的实现细节;不得原地修改已发布公共路由形状或事件负载,除非显式视为破坏性变更或版本化;不得假设仅重新生成 IDL 即可安全完成破坏性接口变更;不得把 Gear/Sails 演进描述为在线合约代码热替换。
路由:若问题是 Gear 或 Sails 是否暴露正确 API 族,先看 ../gear-gstd-api-map/SKILL.md;若风险主要在回复、超时、延迟工作或预留,看 ../gear-message-execution/SKILL.md;若引入同质化代币、代币记账或代币管理器拆分,看 ../../references/awesome-sails-token-patterns.md。