从需求到规格：翻译成工程语言

规格不替实现做决定，但必须把“什么必须为真”说清楚。AI 可以补代码，不能替业务定义口径。

一、自然语言为什么不够：歧义就是实现自由度

原始需求只有一句：

把旧的生态店铺 GMV 清洗逻辑迁移成 Java 链路。

这句话没有回答平台范围、统计日期、销售与退款口径、目标表、失败策略、重跑语义和汇总刷新条件。人类工程师会在实现中不断回头确认；AI 更容易用常见样例替你补全。代码越快产出，错误假设也越快固化。

因此，规格要把业务意图翻译成三类内容：

1. 事实：旧链路当前到底怎样运行；
2. 决策：迁移后哪些行为必须保持，哪些可以改进；
3. 验证：用什么输入与结果证明迁移没有改变口径。

二、先建立证据链，再写目标方案

GMV 迁移不是绿地开发。规则分散在历史文档、Kettle 任务、SQL、存储过程、源表字段和调用关系中。规格的第一部分不是“新系统怎么设计”，而是旧逻辑证据表：

证据项	需要记录的内容	不能直接推断的内容
平台范围	天猫、得物、京东、抖音、快手、拼多多、微信视频号、社交、唯品	平台名称相似不代表口径相同
数据来源	源库、源表、关键字段、过滤条件	文档描述不能替代实际 SQL
日期口径	支付、发货、完成、结算或其他日期	不能统一假设一个日期字段
金额口径	销售、退款、优惠、运费、取消单如何处理	不能仅凭字段名判断正负方向
归属规则	类目、品牌、部门、店铺的映射与兜底	缺失值不能静默归入默认部门
输出与依赖	目标表、汇总刷新、下游报表	平台执行成功不等于整批完整

每条结论要标记“已由代码/SQL证实”“由文档说明”“待业务确认”。这样可以区分事实与猜测，也方便后续补证。

三、工程规格的八个组成部分

一份能交给 AI 执行的规格，至少包含：

• 目标：迁移旧逻辑并保持既有 GMV 业务口径；
• 范围：九个平台，总控编排、平台执行器、共享规则、结果与汇总；
• 输入：平台集合、开始日期、结束日期、目标表、save、continueOnError；
• 输出：每个平台的状态、行数、耗时、错误原因，以及整批是否完整；
• 不变量：平台特例不泄漏到总控，预览不写库，任一失败不刷新完整汇总；
• 失败语义：停止还是继续、如何记录、能否重跑、哪些副作用禁止发生；
• 边界：总控、平台执行器、规则服务、Mapper、汇总服务各自负责什么；
• 验收：旧新结果核对、异常路径、目标表白名单和回归测试。

规格必须同时声明非目标：不在迁移中重定义业务口径，不顺手改源表，不把所有平台揉成一套“大一统 SQL”，也不把尚未核对的结果说成生产验证完成。

四、用 EARS 句式把规则变成可验证行为

EARS 的价值不是格式漂亮，而是强迫每条规则出现触发条件和可观测结果：

WHEN 选择一个受支持的平台并提供有效日期范围
THEN 系统 SHALL 调用该平台对应的执行器，并返回行数、耗时和状态。

WHILE save=false
THE SYSTEM SHALL 仅执行查询与结果预览，不删除、不写入、不刷新汇总。

WHILE save=true
THE SYSTEM SHALL 仅允许写入配置白名单中的目标表。

IF 任一平台执行失败
THEN 系统 SHALL 记录平台级失败原因；根据 continueOnError 决定继续或停止，且不得刷新完整汇总。

WHEN 所选平台全部成功
THEN 系统 SHALL 刷新完整汇总，并记录本次运行范围与结果。

这些规则可以直接映射成自动化测试、日志断言和人工验收步骤。

五、生态店铺 GMV 清洗迁移规格样例

5.1 业务目标

把分散在旧文档、历史任务和数据库调用链中的规则，治理为九个平台执行模块与统一总控。迁移完成后，指定日期范围内的新旧结果应可对照，平台级差异可以定位到来源和规则。

5.2 模块边界

模块	负责	不负责
总控编排	参数校验、平台选择、执行顺序、失败策略、结果聚合、通知与汇总门禁	平台特殊 SQL 与字段口径
平台执行器	单平台查询、清洗、映射、写入和平台级结果	调度其他平台、决定整批是否完整
共享规则服务	类目、部门等真正跨平台稳定的规则	吞并平台差异
目标表配置	白名单和环境配置	接受任意表名
汇总服务	所有平台成功后的统一刷新	在部分失败时伪造完整结果

5.3 输入契约

platforms: 支持的平台集合；为空时是否代表全部平台必须明确
startDate / endDate: 必填，开始日期不能晚于结束日期
targetTable: 必须命中受控白名单
save: false=预览，true=执行写入
continueOnError: true=记录失败后继续，false=首个失败即停止

5.4 输出契约

每个平台返回：平台标识、执行状态、读取行数、写入行数、耗时、错误类型与错误摘要。整批返回：请求范围、成功/失败平台集合、是否完整、是否刷新汇总。

输出不能只给一个 success=true。调用者需要知道“哪些平台成功、哪些失败、是否产生写入、完整汇总是否刷新”。

5.5 错误契约

场景	错误码	副作用
不支持的平台	UNKNOWN_PLATFORM	不执行
日期范围无效	INVALID_DATE_RANGE	不执行
目标表不在白名单	TARGET_TABLE_NOT_ALLOWED	不写入
单平台执行失败	PLATFORM_GENERATION_FAILED	记录平台结果，不刷新完整汇总
部分成功	PARTIAL_RESULT	明确返回失败平台，不能包装成完整成功

5.6 重跑语义

重跑不能由 AI 自行决定。需要根据旧逻辑与业务确认，明确采用覆盖、追加还是清理后重建。无论采用哪种方式，都要满足：范围可定位、执行可追踪、失败不会污染完整汇总、重复触发不会产生无法解释的数据。

六、验收矩阵

用例	预期结果
选择一个平台 + 有效日期 + save=false	返回预览结果，无删除、插入和汇总刷新
选择多个平台 + save=true	各平台由独立执行器处理，返回平台级统计
传入未知平台	在执行前拒绝，返回 UNKNOWN_PLATFORM
传入非白名单目标表	拒绝写入，返回 TARGET_TABLE_NOT_ALLOWED
某平台失败 + continueOnError=false	记录失败并停止后续平台，不刷新完整汇总
某平台失败 + continueOnError=true	继续其余平台，整批标记为部分结果，不刷新完整汇总
所选平台全部成功	刷新完整汇总并记录运行结果
同范围重新执行	严格按已确认的重跑策略处理，结果可追溯
新旧链路同范围核对	输出行数、销售额、退款额和关键维度差异；未核对项保持待验证

“测试通过”只证明实现符合规格。旧新口径一致还需要数据核对证据，两者不能互相替代。

七、规格怎样交给 AI

不要只把整篇文档塞进一个会话。按职责拆成工作单：

1. 证据梳理：只读旧文档、SQL 和调用关系，产出口径矩阵；
2. 契约设计：冻结输入、输出、错误码、模块边界和不变量；
3. 平台迁移：一次只实现一个平台执行器；
4. 总控编排：基于稳定契约组织选择、失败策略和汇总门禁；
5. 独立验证：只读规格与 diff，验证边界和异常路径；
6. 数据核对：同范围运行旧新链路，记录差异与解释。

每张工作单都要写清可改文件、禁止事项、验收命令和汇报格式。AI 可以在局部自由实现，但不能改变业务口径和跨模块契约。

八、本章小结

• 迁移类需求先还原事实，再设计目标结构；历史文档只是线索，不是唯一真相。
• 规格锁定必须为真的行为：九平台边界、预览/写入、失败策略、目标表白名单和汇总门禁。
• EARS 规则把业务语义变成可执行测试；模块表把职责变成可审查边界。
• 测试通过与数据口径一致是两类证据，必须分别验收。
• AI 负责受约束的分析和实现，人负责事实确认、决策、审查与最终签字。

下一章 Agent 执行，把规格拆成能被独立执行和验收的任务链。