事务、并发与副作用

规则 CORE-TX-001。分层正文见业务分层。

写用例的事务如何生效

Service 负责业务编排与事务边界，组合多个 Manager 完成一次用例。必须同时满足：Spring 管理的 Service、事务代理实际拦截该调用、选定数据栈的事务管理器、所有需要原子性的访问参加同一事务。

不要只添加 @Transactional 后便宣称支持回滚。对象自己调用自己的方法、直接 new Service、不同 DataSource/ConnectionFactory 或独立订阅都可能不符合预期边界。

同步真实样例：CategoryDefinitionService。它使用类级只读事务与写动作覆盖；复制模式时同时核对传播、回滚异常和方法覆盖。

响应式事务

事务随 Publisher 的订阅链工作。使用匹配的响应式事务管理器以及应用已经采用的事务声明/操作器，确保多个 Manager 返回的 Publisher 被组合在同一条链中。

• 延迟读取上下文与依赖，不在组装 Publisher 时执行写操作。
• 顺序依赖使用正确的链式组合，不能调用 subscribe() 后立刻返回成功。
• 业务方法不通过 block() 借用阻塞链。
• onErrorResume 把异常转换为正常完成可能改变回滚结果，使用前明确语义并测试。

数据库写入与外部副作用

afterSave 等钩子处于 Manager 生命周期中，不代表外层事务已经提交。外部消息、HTTP 调用或不可撤销动作，应使用具有明确提交与失败语义的方案。

树节点移动会先更新子孙的标签路径，再更新 ID 路径，两步都按旧 ID 路径及 / 分隔边界筛选；当前节点由正常更新生命周期保存。调用这类 Manager 必须处于同一 Service 事务，避免中途失败留下部分路径。真实 SQL 与回滚验证见 TreeMoveJdbcIntegrationTest。

Core 服务缓存有提交后失效协调，见缓存指南；集成事件区分事务内内部事件和提交后蒸馏事件，见事件指南。蒸馏事件仍属于 JVM 内事件，不承诺跨进程可靠投递。

幂等与并发由业务定义

先说明唯一业务键、重复请求应该报错还是返回已有结果，以及并发竞争允许的结果，再选择数据库唯一约束、锁、条件更新或其他方案。

CreateOrRefreshManager 复用创建/更新生命周期，但不是数据库原子 upsert，也不是所有并发场景的幂等保证。唯一性检查与最终写入之间仍要考虑竞争。

验证

事务测试必须通过真实代理入口执行：第一张表写成功、第二步人为失败，最后在事务之外查询，确认第一步也回滚。再验证成功提交后的最终数据和副作用。

测试方法外层自动回滚可能掩盖被测 Service 没有事务的问题；要明确哪一层开启事务。缓存/事件测试分别覆盖提交、回滚和无事务路径；并发要求用可重现竞争场景验证。