Migration Assistant

迁移助手

语言: English | 简体中文

引导系统性代码迁移、框架升级与技术现代化。

使用方式

迁移类型

风险评估矩阵

工作流程

1. 评估 - 评估现状、识别破坏性变更
2. 规划 - 建立含依赖关系的迁移清单
3. 准备 - 设定 codemods、兼容层、功能旗标
4. 迁移 - 分阶段执行迁移并测试
5. 验证 - 执行完整测试套件、检查回归
6. 清理 - 移除兼容层、旧依赖

API 迁移契约测试

当 API endpoint 从一个技术栈迁至另一个（PHP → .NET、Express → Spring、Python → Go），对新实现的单元测试只验证新 DTO——无法捕捉「旧版有但新版漏掉的字段」。字段缺漏、字段 rename、类型漂移，以及顶层 vs nested 层级漂移等问题会静默流入生产，导致仍预期旧版 shape 的既有前端失灵。

仅靠单元测试、集成测试或 code review 无法防止。2026-05-24 真实 PROD 事故：67/67 测试全绿流入正式环境，由客户发现缺漏。

强制规则

每个被迁移的 API endpoint 必须至少有一份 contract test，比对新实现的 response 与从 legacy 实现捕获的 fixture。验证的是结构性等价（keys、type、层级位置），而非值等价。

Fixture 捕获协议

Legacy 仍运行（典型迁移窗口）：

# 1. Capture ≥3 representative inputs (happy path, edge case, empty result)
curl -X POST $LEGACY_BASE/endpoint -d @input1.json \
  > tests/fixtures/migration/endpoint/scenario1.json
curl -X POST $LEGACY_BASE/endpoint -d @input2_empty.json \
  > tests/fixtures/migration/endpoint/scenario2_empty.json
curl -X POST $LEGACY_BASE/endpoint -d @input3_edge.json \
  > tests/fixtures/migration/endpoint/scenario3_edge.json

# 2. Scrub PII and volatile values (timestamps, generated IDs)
jq 'walk(if type == "string" and test("@") then "redacted@example.com" else . end)' \
  tests/fixtures/migration/endpoint/scenario1.json > tmp && mv tmp ...

# 3. Commit fixtures
git add tests/fixtures/migration/endpoint/

Legacy 已退役但 source 可读：

• 追踪 legacy source code，手动构建预期的 response shape
• 将每个字段的来源（SQL 列、计算式、hardcoded）记录于同位置的 .notes.md 文件

Contract test 模板

C# / xUnit：

[Theory]
[InlineData("scenario1")]
[InlineData("scenario2_empty")]
[InlineData("scenario3_edge")]
public async Task Endpoint_ResponseShape_MatchesLegacyFixture(string scenario)
{
    var fixture = LoadFixture($"migration/endpoint/{scenario}");
    var response = await CallNewImpl(fixture.Input);
    // StructuralEquivalence checks keys + types + placement, ignores values
    StructuralEquivalence.Assert(response, fixture.ExpectedShape);
}

TypeScript / Jest：

import { structuralEquivalence } from "./test-utils/structural-equivalence";

describe.each([
  ["scenario1"],
  ["scenario2_empty"],
  ["scenario3_edge"],
])("Endpoint response shape vs legacy fixture (%s)", (scenario) => {
  test("matches", async () => {
    const fixture = loadFixture(`migration/endpoint/${scenario}.json`);
    const response = await callNewImpl(fixture.input);
    structuralEquivalence(response, fixture.expectedShape);
  });
});

structuralEquivalence / StructuralEquivalence.Assert 规则：每一层具备相同的 key 集合（不可缺漏、不可多出，除非明确 opt in）、每个 key 具相同的基本类型、相同的层级位置（顶层 vs nested）。值可以不同（timestamps、IDs）；类型与结构不可不同。

逐字段迁移审计清单

合并任何被迁移的 endpoint 前：

• 所有 legacy response 字段皆 mapping 至新 DTO（无 silent drop）
• 尽量保留命名（避免将 TotalX rename 而丢失「per-member」语意）
• 保留顶层 vs nested 层级位置
• 已验证类型兼容性（string→int 转换为明确而非巧合）
• Error path return code 与 legacy 一致（509 而非 506；404 而非 400）
• Contract test fixture 已 commit 至 tests/fixtures/migration/
• Cross-link 至 contract-test-assistant 做持续的消费端验证

Cutover 后生产数据对账

实现：XSPEC-284 R2（轴③持久化数据语义）／关闭 UDS issue #134。

Contract test 与 behavior-snapshot 只能捕捉接口分歧，对持久化数据语义分歧视而不见。两者共有两个盲区：(1) 你只能验证你想得到要列举的规则——真正出包的永远是没人写下来的隐含规则（某字段何时非零、何时被覆写）；(2) per-request parity ≠ data-at-rest parity——由异步程序（DR sync、结算批次、状态对账器）对 live 外部供应商写入的字段，不是可重放的确定性请求，其正确性只在真实生产量的聚合中浮现。

事故指纹（#134）

某企业 SMS 平台 PHP→.NET 重写：每笔金额由异步 DR sync 覆写（record.Cost = gatewayDr.Cost）。legacy 对 carrier-failure 仍计费，rewrite 写入 gateway 回报的 0 → cutover 边界两侧同一失败状态的金额分歧。所有既有 gate 全部漏接（response shape 相同 → contract test 通过；无人 curated「失败仍计费」场景；字段由后台作业对 live gateway 写入 → 不可重放）。最后靠 ops 跑生产 SUM(cost) GROUP BY status, day 跨边界汇总才发现。单日抽样甚至误判「失败不计费＝正常」——只有跨 cutover 边界的多周聚合才揭露真相。

强制规则

当 migration 将 legacy 数据载入与 new 相同的存储，新旧边界即是免费差分神谕。对每个 business-critical 持久化字段必须：定义聚合对账不变量（比对 legacy-origin vs new-origin 行沿关键维度的分布）、对生产排程执行并于分歧超过宣告容差时告警、以跨 cutover 的多周窗口调查（切忌单日抽样，抽样可能坐实错误结论）。

对账 SQL 模板

-- Reconcile a money/state field across the migration cutover boundary.
SELECT status,
       SUM(CASE WHEN created < @cutover THEN 1 ELSE 0 END)                          AS legacy_rows,
       SUM(CASE WHEN created < @cutover AND money_field > 0 THEN 1 ELSE 0 END)      AS legacy_nonzero,
       SUM(CASE WHEN created >= @cutover THEN 1 ELSE 0 END)                         AS new_rows,
       SUM(CASE WHEN created >= @cutover AND money_field > 0 THEN 1 ELSE 0 END)     AS new_nonzero
FROM records GROUP BY status;
-- Invariant: nonzero-ratio per status must not differ across the boundary beyond tolerance.

容差与告警指引

Gate 0 — 持久化业务字段的隐含规则捕获

在迁移任何写入持久化业务字段的功能前，针对每个此类字段明确回答三个问题，并将答案锁定为快照场景或对账不变量：

1. 何时设值？
2. 何时被覆写？（尤其异步路径）
3. 何时归零／清空？

高风险隐含规则检查清单 — 经验反复出现的指纹：

• 计费语义 — 提交时计费 vs 送达时计费；失败退费？
• 枚举／状态码映射 — 每个 legacy 码都映射；「成功集合」定义一致
• 空值处理 — 空字符串 vs null vs 不存在；缺值默认
• 字段命名大小写／序列化 — snake_case vs camelCase 绑定
• 时区 — 存 UTC vs local；报表边界
• 四舍五入／类型强转 — "2.00"（文本）被当 int 解析 → 掉成 0

3-gate 定位表

明确划出各 gate 之间的边界，让每个轴都有负责方、不落入缝隙：

交叉参照：behavior-snapshot（curated golden masters），observability-assistant（对账排程 + 告警模板）。

背景作业／副作用完整性

实现：XSPEC-284 R3（轴⑤）。

迁移清单与副作用 grep 只是标注背景作业——标注本身不证明任何事。背景作业可能在 manifest 列出、代码中存在，却在新系统从未真正执行。

强制规则

对每条由 legacy 带过来的背景副作用，须验证两件事——标注不够：

任一检查未过即标 not_implemented（XSPEC-199）并 block UAT／cutover——绝不把沉默、从未触发的作业当「完成」。

交叉参照：结构化日志强制事件 heartbeat / business_event（logging-standards）为检查 (b) 提供可观测的执行证据。

状态机与时序对等

实现：XSPEC-284 R8（轴⑧）→ 拆分为 XSPEC-287。

legacy 的状态转移规则与时序前提多为隐性：单笔记录的快照「看起来合法」，违规只在一连串操作的转移序列中浮现，因此 per-request 功能对等与 behavior-snapshot 对等都抓不到（与「per-request ≠ data-at-rest」「per-request ≠ 并发」同源盲区）。feature-manifest 只有 status 字段，不验证转移合法性。

Step 1 — 状态机清单来源（derive, R3）

legacy 状态转移散落于 controller／service／DB trigger。以三方交叉机械化提取状态枚举 + 合法转移集（不靠人脑回忆）：

权威性：三者不一致时，以生产实际出现过的转移为 legacy 真实行为基准（呼应 #134「以生产为准」）。代码允许但生产从未产生的转移是潜在路径；生产出现过但新 enum 禁止的转移是回归。

Step 2 — 合法转移验证（oracle, R1）

依提取出的转移图，断言新系统禁止 legacy 禁止的非法转移。当新系统允许 legacy 禁止的转移即 block（重写常放宽隐性护栏）：

• cancelled → pending（复活已取消的订单）
• refunded → paid（反退款）
• shipped → draft（倒退回不可逆点之前）

Gate 时机：pre-UAT。

Step 3 — 时序不变量侦测（oracle, R2）

断言单笔快照无法揭露的时序不变量；违反即告警：

• created_at ≤ updated_at（记录不会在存在之前被更新）
• 无未来时间戳（clock skew／默认值错误）
• 状态时间戳单调递进（paid_at ≤ shipped_at ≤ delivered_at）
• 事件排序保证被保留（事件日志不重排）

Gate 时机：pre-UAT 与 post-cutover（与上方轴③ Post-Cutover 对账共用排程）。

Step 4 — 序列／顺序对等（R4）

验证新系统保留幂等性（重复操作不产生重复状态变更）与关键事件顺序，避免重写引入顺序敏感 bug：

• 重放同一事件／消息两次只产生一次状态变更，而非两次
• 乱序投递会被拒绝或对账处理，而非静默套用
• 幂等键／去重窗口与 legacy 语义一致

与 XSPEC-286 轴⑥边界

287（本节，轴⑧）负责转移合法性 + 时序正确性（领域问题）；XSPEC-286 轴⑥负责并发竞态／隔离（性能/竞争问题）。重叠案例（并发导致非法转移）的并发面归 286、转移合法性面归本节；落地时依主导失败模式指派主责。

错误路径完整性

实现：XSPEC-284 R9（轴⑨）→ 拆分为 XSPEC-288。

最常见的迁移遗漏是「happy path 移了、错误／降级／fallback 分支整批被漏」。happy path 有明确需求，错误分支散落（try/catch 层级、自定义异常层级、特定错误码）而被静默遗失。本 skill 负责迁移 derive + 降级对等（R1/R3）；系统性遗漏分支 gap 分析 + 错误响应差分（R2/R4）落在 full-coverage-testing「Migration Error-Path Completeness」。

Step 1 — 机械化 legacy 异常/错误码清单（derive, R1）

机械化列举 legacy 错误面（不靠回忆）：grep catch／except／rescue 区块、自定义异常/错误类层级、所有错误/状态码、错误响应形状（serializer／DTO）。此清单即交给 full-coverage-testing gap 分析的错误路径待验清单。

Step 2 — 降级／Fallback 对等（R3）

legacy 降级模式只在失败时执行，容易被漏。验证新系统保留——对等上 fail closed，而非「正常路径一致、失败时行为迥异」：

• 外部服务失败 fallback 与 legacy 一致
• 重试策略（次数／backoff／放弃）与 legacy 一致
• 部分结果处理与 legacy 一致
• 断路器／超时降级与 legacy 一致

重要性分级：依生产实际触发频率排序（#134「以生产为准」）。高频生产错误分支无对映即硬 block；从未触发的潜在分支仍列入但较低优先。

交叉参照：full-coverage-testing Migration Error-Path Completeness（gap 报告 + 错误响应差分，R2/R4）；behavior-snapshot（错误响应对等）。

回滚策略

使用范例

User: /migrate "Vue 2 to 3"
AI: Migration Assessment: Vue 2 → Vue 3
    Breaking changes found: 12
    - Options API → Composition API (47 components)
    - Filters removed (8 usages)
    - Event bus removed (3 usages)
    Risk: Medium-High
    Estimated effort: 2-3 weeks
    Recommended: Staged migration with @vue/compat

下一步引导

/migrate 完成后，AI 助手应建议：

迁移分析完成。建议下一步：

• 执行 /reverse 深入理解现有代码
• 执行 /testing 确保迁移后测试通过 ⭐ 推荐
• 执行 /commit 提交迁移变更

附录：9 轴完整性矩阵

来源：XSPEC-284 Legacy Refactor Completeness Framework。「确保没有遗漏」无法用枚举证明——你只能验证你想得到要列举的东西。策略＝两条腿：(1) 从 legacy 真实 artifact 机械化推导待办清单；(2) 差分神谕让分歧自报。

每个迁移针对每一轴宣告三件事：derive（清单来源）· detect（oracle）· gate 时机。此处标为已覆盖者对映既有 UDS 标准——勿重复造轮子。

每轴宣告〔清单来源 derive｜oracle detect｜gate 时机〕；标为已覆盖者对映既有 UDS 标准，勿重复造轮子。未宣告的轴视为已知遗漏风险。本框架 P0 落地＝轴③④⑤（本 skill）；轴⑥已拆 XSPEC-286（落地于 performance-standards）、轴⑧已落地于本 skill 状态机与时序对等（XSPEC-287）、轴⑨已落地（XSPEC-288）＝本 skill 错误路径完整性（R1/R3 derive + 降级）+ full-coverage-testing（R2/R4 系统性 gap 分析 + 错误响应差分）。

参考

• 核心规范：refactoring-standards.md
• 相关：contract-test-assistant — 迁移后持续契约验证的策略
• 相关：behavior-snapshot — Curated golden-master 对等（3-gate 轴②）
• 相关：observability-assistant — Post-cutover oracle 的对账排程 + 告警规则
• 框架：XSPEC-284 Legacy Refactor Completeness Framework — 9 轴 SSOT

版本历史

AI 代理行为

完整的 AI 行为定义请参阅对应的命令文件：/migrate

授权

CC BY 4.0