架构边界：防止 AI 把局部正确写成系统混乱

AI 擅长找到当前任务的最短实现路径；工程师必须让这条路径不能穿过不该穿过的边界。

一、AI 为什么天然倾向越界

当模型需要一个字段，直接访问 Mapper 比通过领域契约更短；当某个平台有特殊规则，在总控里加一个 if 比维护独立执行器更快；当测试需要完整结果，先刷新汇总再处理失败也更容易让 happy path 通过。

这些动作在当前 diff 中可能都“有效”，但会把变化方向不同的东西黏在一起：平台源表一变，总控要跟着变；某个平台口径一变，所有平台都要回归；部分失败被误标为完整，经营报表开始使用不可解释的数据。

所以边界不能只写“保持分层”。它必须回答：谁拥有规则、谁可以依赖谁、跨层通过什么契约、违规如何自动发现。

二、GMV 清洗链路的职责边界

模块	负责	不负责	允许依赖
GmvGenerateOrchestrator	参数校验、平台选择、执行顺序、失败策略、结果聚合、汇总门禁	平台 SQL、销售/退款特殊口径	PlatformExecutor、目标表配置、汇总服务
PlatformExecutor	单平台数据读取、清洗、字段映射、平台级写入与结果	调用其他平台、决定整批是否完整	当前平台 Mapper、共享规则服务
GmvRuleService	真正跨平台稳定的类目、部门等规则	覆盖平台特例	受控配置与规则数据
GmvTargetTableProperties	目标表白名单与环境差异	接受请求传入的任意表名	配置系统
GmvSummaryService	所选平台全部成功后的完整汇总刷新	在部分失败时刷新	已完成的平台结果

最重要的结构决策是：总控只认识执行器契约，不认识九个平台的 Mapper。 新增或调整平台时，变化应收敛在平台模块；总控只处理跨平台稳定的控制逻辑。

三、边界规格要写成可检查陈述

【总控边界】
- 总控 SHALL 通过 PlatformExecutor 注册表选择平台
- 总控 SHALL NOT 直接依赖任一平台 Mapper
- 总控 SHALL NOT 包含平台销售、退款、日期字段的特殊分支

【平台边界】
- 每个平台 SHALL 独立实现统一输入输出契约
- 平台执行器 SHALL 返回读取行数、写入行数、耗时和失败原因
- 平台执行器 SHALL NOT 触发整批汇总刷新

【数据边界】
- save=false SHALL 不产生删除、插入和汇总刷新
- save=true SHALL 只允许写入目标表白名单
- 任一平台失败 SHALL NOT 把整批标记为完整

这样的陈述可以进入代码审查、测试和静态规则；“注意解耦”不可以。

四、三层强制：让边界不依赖自觉

第一层：文档约束

在项目规则和工作单中写出模块职责、允许依赖和禁止事项。它解决“模型是否看见边界”。

第二层：目录与接口

让结构本身表达边界：

gmv/
  orchestrator/       # 只依赖 executor contract
  executor/           # PlatformExecutor 与注册表
  platform/
    tmall/
    jd/
    douyin/
    ...
  rules/              # 共享规则
  summary/            # 完整汇总
  config/             # 目标表白名单

平台 Mapper 放在平台包内部，不作为总控可直接使用的公共接口。目录不能彻底阻止越界，但能让错误依赖在 diff 中非常显眼。

第三层：架构测试与 CI

noClasses()
    .that().resideInAPackage("..gmv.orchestrator..")
    .should().dependOnClassesThat()
    .resideInAnyPackage("..gmv.platform..mapper..");

再配合测试检查预览副作用、目标表白名单和汇总门禁。文档告诉 AI 为什么，结构引导它怎么写，CI 负责在它没遵守时阻止合入。

五、边界为什么能提高并行度

边界清晰后，可以让不同上下文并行处理不同平台，因为它们共享稳定契约，不需要改同一个总控文件。并行的前提不是 Agent 数量，而是：

• 输入输出契约已经冻结；
• 文件归属不重叠；
• 共享规则有单独负责人；
• 独立 Review 检查跨模块影响；
• 集成测试验证整批语义。

如果每个执行器都需要修改总控 if-else，说明扩展点没有建立，并行只会制造合并冲突。

六、边界 Review 清单

• 新平台是否只通过执行器注册进入系统？
• 总控是否出现平台名、平台字段或平台 SQL？
• 平台模块是否擅自刷新完整汇总？
• 共享规则是否真正在多个平台保持同一语义？
• 请求参数能否绕过目标表白名单？
• 失败路径是否仍能把部分结果包装为成功？
• 为通过测试，是否把测试专用分支写进生产代码？

七、边界也需要重画

边界不是永远不变。如果多次需求都同时修改两个模块，可能不是执行者持续越界，而是职责划分已经不符合变化方向。此时应由人发起结构决策：记录背景、候选方案、迁移成本和兼容策略，再同步修改接口、目录、规则与测试。

AI 可以分析影响面和生成迁移代码，但“边界应该怎么重画”是长期维护成本与业务方向的取舍，不能由一次局部任务自动决定。

八、本章小结

• 模型倾向局部最短路径，架构边界负责保护长期变化成本。
• GMV 链路的核心边界是总控只依赖执行器契约，平台特例留在平台模块。
• 文档、目录/接口、架构测试三层共同强制，不能只靠提醒。
• 边界清晰才有安全并行；契约未冻结时，多 Agent 只会并行制造分歧。
• 边界失效时要由人重画，并记录迁移决策，不能让局部实现顺手改架构。