0260bcd8e2
- 新版设计各域 SoT 按本轮实现同步：总体架构、模块设计、接口契约、数据模型、功能规格、文件设计与决策记录。 - 接口契约生成物重新导出（openapi 与前端客户端随契约一致）。 - 实现回顾与专项检查台账保留历史结论；本轮收尾发现另见 .agents.local 下的收尾报告与审查处置。
69 lines
4.4 KiB
Markdown
69 lines
4.4 KiB
Markdown
<!-- 导航元信息: {"内容描述": "S01 正式变更", "使用场景": "设计、实现或评审对应主题", "使用要求": "与阅读指南的主题权威分工一致"} -->
|
||
# S01 正式变更
|
||
|
||
## 职责与对象
|
||
|
||
共同的审阅、并发、幂等和原子提交保护，不解释其他模块的任意字段值。
|
||
|
||
实例归属以[总体架构](../总体架构.md)为准；结构、状态和公开外壳分别引用数据模型与接口契约。
|
||
|
||
## 公开接口
|
||
|
||
| 用例 | 输入责任 | 输出与后果 |
|
||
|------|----------|------------|
|
||
| open_review | 候选与展示的具体版本 | 绑定差异和范围的审阅记录 |
|
||
| prepare_change | 类型化目标、批准身份和依赖 | 具名参与者组成的变更清单 |
|
||
| commit_change | 变更清单与命令身份 | 完整提交回执或整体回滚 |
|
||
| read_receipt | 作者、用途和命令身份 | 原请求的结果 |
|
||
| 读取回执于 | 同库同用途数据库工厂创建的受控连接、认证作者与命令ID | 在调用方事务内只读真实回执；不创建连接、不提交或回滚、不产生新批准 |
|
||
|
||
所有接口在本模块的接口.py 暴露。输入输出类型由同一公开表面导出，外部不导入私有模型或 SQL。
|
||
|
||
## 内部职责
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| 接口.py | 正式变更公开用例和可导入合同 |
|
||
| 模型.py | 正式变更稳定对象、外壳及内部状态 |
|
||
| 存储.py | 正式变更所属记录的 SQL 与版本读写 |
|
||
| 作者审阅.py | 审阅版本、差异哈希及批准范围 |
|
||
| 状态迁移.py | 共用候选状态与合法迁移 |
|
||
| 幂等命令.py | 同请求回执重放、异请求拒绝 |
|
||
| 版本检查.py | 目标、候选和被审版本 |
|
||
| 依赖锁.py | 来源、结构及当前有效指针的稳定锁序 |
|
||
| 提交事务.py | 原子执行具名类型化参与者 |
|
||
| 修改影响.py | 变更影响与复核任务登记 |
|
||
|
||
完整路径及运行模板见[目标文件清单](../项目目录与文件职责.md)。逐文件意图、边界与目标见[文件合同](../文件设计/后端-S01-正式变更.md)。
|
||
|
||
## 实现约束
|
||
|
||
- 参与者由启动与业务接口登记，不接受来自模型或浏览器的回调代码。S01 不反向导入各业务模块或 S04，参与者通过共用合同执行所属模块的校验和写入。
|
||
- 稳定锁序覆盖目标、结构、投影和来源当前有效指针；其他更新入口使用同一协议。
|
||
- 审阅记录不等于批准；正式动作必须匹配被审版本和批准清单。
|
||
- 事件、派生任务、回执与业务版本一起提交，连接失败后可重放同一结果。
|
||
|
||
当前共用入口对应 `打开审阅`、`准备变更`、`提交变更`、`读取回执`。准备变更在只读连接中返回参与者和影响，不能被当作批准或传回服务端直接执行。提交点重新读取业务快照，并由登记的依赖维护者按稳定顺序锁定当前指针；维护者必须保留行锁到同一事务结束。目标和候选缺少当前指针保护时拒绝提交。S04和各业务owner在后续消费包登记自己的维护者与具体请求类型，S01不据类型名拼SQL。
|
||
|
||
回执固定实际被审的目标、候选、结构、投影和来源依据，以及审阅ID、参与者结果与影响ID。候选检查由业务owner判断，拒绝或暂缓不要求检查通过；人工保存不产生候选采纳决定。影响记录表示待复核事项，具体章后任务仍由对应业务参与者与S02接通，不能据此宣称已执行派生任务。
|
||
|
||
## 协作与失败
|
||
|
||
由 B01/B02/B04/B05/B06/B07/S04 等内容维护者调用；数据库只提供共同事务上下文。
|
||
|
||
任何参与者、来源、结构、审阅或幂等验证失败整包回滚。
|
||
|
||
## 验收行为
|
||
|
||
- 原子性。
|
||
- 同键异请求。
|
||
- 源变竞争。
|
||
- 结构切换竞争。
|
||
- 迟到批准。
|
||
|
||
验收入口和替换条件见[迁移与验收](../迁移与验收.md)；这些条目是目标行为，不是已通过测试的声明。
|
||
|
||
## 无变化保存
|
||
|
||
B01档案参与者在目标锁、作者及版本CAS、S04绑定和当前投影校验后比较规范值与有效绑定。完全相同返回did_change=false/no_change=true，保留独立命令回执及当前revision，不新增业务历史或profile_changed。不同命令同值可成功；旧revision仍拒绝；A→B→A保留真实历史。S01依据每个参与者结果过滤归属于该参与者的影响，不跳过其他参与者；回执汇总did_change与no_change。
|