LegacySystemModernizationEngineSkill afrexai-legacy-modernization

遗留系统现代化引擎

评估、规划和执行遗留系统现代化的完整方法论 — 从单体分解到云迁移。适用于任何技术栈，任何规模。

---

第1阶段：系统评估

现代化简报

system_name: "[名称]"
age_years: 0
primary_language: ""
framework: ""
database: ""
deployment: "on-prem | VM | container | serverless"
lines_of_code: 0
team_size: 0
monthly_users: 0
annual_revenue_supported: "$0"
compliance_requirements: []
known_pain_points: []
business_driver: "cost | speed | talent | risk | compliance | scale"
timeline_pressure: "low | medium | high | critical"
budget_range: "$0-$0"
sponsor: ""

技术债务清单

将每个维度评分1-5（1=严重，5=健康）：

维度	分数	证据
代码质量 — 测试覆盖率、复杂度、重复
架构 — 耦合、模块化、清晰边界
基础设施 — 部署自动化、监控、扩展
依赖项 — 过时库、EOL框架、安全漏洞
数据 — schema质量、迁移历史、备份/恢复
文档 — 准确性、覆盖率、入职效果
运维 — 部署频率、MTTR、事故率
安全 — 认证模式、加密、审计跟踪、合规差距
开发者体验 — 构建时间、本地设置、调试工具
业务逻辑清晰度 — 文档化规则、逻辑测试覆盖率

总计：/50

• 40-50: 健康 — 增量改进
• 30-39: 老化 — 针对性现代化
• 20-29: 遗留 — 需要系统性现代化
• 10-19: 严重 — 现代化或替换

依赖风险矩阵

对于每个主要依赖项：

dependency: ""
current_version: ""
latest_version: ""
eol_date: ""  # 终止生命周期
security_vulns: 0  # 已知CVEs
upgrade_difficulty: "trivial | moderate | hard | rewrite"
business_risk: "low | medium | high | critical"
alternatives: []

优先级规则：

• EOL在12个月内 → P0
• 已知未修补CVEs → P0
• 落后3+主要版本 → P1
• 无活跃维护者 → P1
• 其他所有情况 → P2

---

第2阶段：策略选择

现代化策略决策矩阵

策略	何时使用	风险	成本	速度	干扰
Rehost (lift & shift)	数据中心退出，最小变化	低	低	快	低
Replatform (lift & optimize)	云优势无需重写	低-中	中等	中等	低-中
Refactor (restructure)	良好代码，不良架构	中等	中等	中等	中等
Re-architect (rebuild patterns)	单体→服务，新模式	高	高	慢	高
Rebuild (rewrite)	小型系统，明确需求	非常高	非常高	非常慢	非常高
Replace (buy/SaaS)	商品功能	中等	可变	快	高
Retire	不再需要	无	负面	即时	低
Retain (do nothing)	工作正常，其他优先级	无	持续	N/A	无

策略选择决策树

系统是否仍然需要？
├─ 不 → RETIRE
├─ 是 → 是否是商品（CRM、电子邮件等）？
│  ├─ 是 → REPLACE (购买SaaS)
│  └─ 否 → 代码是否可维护？
│     ├─ 是 → 是否架构是问题？
│     │  ├─ 是 → RE-ARCHITECT (绞杀者图)
│     │  └─ 否 → 是否基础设施是问题？
│     │     ├─ 是 → REPLATFORM
│     │     └─ 否 → REFACTOR逐步
│     └─ 否 → 系统是否小（<50K LOC）？
│        ├─ 是 → 需求能否清晰定义？
│        │  ├─ 是 → REBUILD
│        │  └─ 否 → REFACTOR + RE-ARCHITECT
│        └─ 否 → STRANGLER FIG (永远不会大爆炸重写)

大重写反模式

永远不要完整重写大型系统。 它失败的几率超过70%，因为：

1. 旧系统不断增加功能 — 移动目标
2. 隐藏的业务规则只存在于代码中 — 它们会丢失
3. 时间线总是比估计的长2-3倍
4. 过渡期间需要维护两个系统
5. 团队在完成前就筋疲力尽了

总是使用绞杀者图代替。 逐步替换。

---

第3阶段：绞杀者图模式

工作原理

1. 确定边界 — 功能、页面或API端点
2. 构建替代品 — 新栈、新模式
3. 路由流量 — 代理/外观将请求发送到新旧系统
4. 验证一致性 — 相同行为，相同数据
5. 切换 — 移除代理，退役旧代码
6. 重复 — 下一个边界

绞杀者外观YAML

facade_name: "[API网关/反向代理/BFF]"
routing_rules:
  - path: "/api/users/*"
    target: "new-service"
    status: "migrated"
    migrated_date: "2025-01-15"
  - path: "/api/orders/*"
    target: "legacy"
    status: "planned"
    target_date: "2025-Q2"
  - path: "/api/reports/*"
    target: "legacy"
    status: "not-planned"
    notes: "低优先级，很少使用"

迁移顺序规则

1. 从最简单、最孤立的模块开始 — 建立信心
2. 然后是最高价值的业务能力 — 早期证明ROI
3. 将最难、最耦合的部分留到最后 — 团队先学习模式
4. 永远不要早期迁移认证/身份 — 它触及一切
5. 迁移数据访问层之前迁移业务逻辑 — 清洁数据=清洁迁移
6. 始终保留旧系统作为回退，直到新系统被证明

双写/数据同步模式

模式	何时	复杂度	风险
双写	两个系统同时写入	高	数据不一致
CDC (Change Data Capture)	从旧系统流向新数据库的变化流	中等	延迟，排序
ETL批同步	定期批量同步	低	过时数据
事件源桥接	从旧系统事件，新系统中重放	高	Schema映射
从新系统读取，向旧系统写入	过渡期	中等	路由复杂性

黄金规则： 选择一个真理来源。永远不要同时让两个系统拥有相同的数据。

---

第4阶段：单体分解

领域发现

在拆分单体之前，确定有界上下文：

1. 事件风暴 （首选） — 领域事件、命令、聚合的便签
2. 代码分析 — 查找相关类/表的集群
3. 团队分析 — 哪些团队拥有哪些功能？
4. 数据耦合分析 — 哪些表一起连接？

有界上下文YAML

context_name: ""
description: ""
team: ""
entities: []
commands: []
events_published: []
events_consumed: []
database_tables: []
external_integrations: []
coupling_score: 0  # 0=独立，10=深度耦合
extraction_difficulty: "easy | moderate | hard | very-hard"
business_value: "low | medium | high | critical"

提取优先级矩阵

在业务价值 (Y) × 提取难度 (X) 上绘制上下文

	简单	中等	困难
高价值	🟢 首先做	🟡 其次做	🟠 仔细计划
中等价值	🟢 快速获胜	🟡 评估ROI	🔴 可能不值得
低价值	🟡 如果简单，为什么不	🔴 跳过	🔴 绝对跳过

服务提取清单

对于每个被提取的服务：

• [ ] 有界上下文清晰定义
• [ ] API合同设计（OpenAPI规范）
• [ ] 数据库分离（无共享表）
• [ ] 集成身份验证/授权
• [ ] 事件发布用于跨服务通信
• [ ] 电路断路器用于回呼单体
• [ ] 监控和警报配置
• [ ] 独立部署管道
• [ ] 流量路由功能标志
• [ ] 文档化回滚计划
• [ ] 性能基线捕获（之前/之后）
• [ ] 数据迁移脚本测试
• [ ] 与单体集成测试通过
• [ ] 编写现场运行手册

---

第5阶段：数据库现代化

数据库迁移策略

策略	描述	停机时间	风险
并行运行	新旧数据库并行，同步两者	零	高复杂度
蓝绿	完整副本，切换DNS	分钟	中等
滚动	逐表迁移	每表零	中等
大爆炸	停止，迁移，启动	小时	高

Schema演进规则

1. 始终添加 — 添加列/表，同一版本中不删除
2. 两阶段删除 — 版本1：停止写入。版本2：删除列（在回填验证后）
3. 默认值始终 — 每个新列都有默认值
4. 向后兼容 — 旧代码在推出新schema期间必须能够工作
5. 同时索引 — 永远不要锁定生产表
6. 用生产规模数据测试 — 100行≠100M行

数据质量门

迁移数据前：

table: ""
row_count_source: 0
row_count_target: 0
count_match: false
checksum_match: false
null_analysis: "pass | fail"
referential_integrity: "pass | fail"
business_rule_validation: "pass | fail"
sample_manual_review: "pass | fail"
performance_benchmark: "pass | fail"
rollback_tested: false

规则： 在切换前所有门必须通过。没有例外。

---

第6阶段：云迁移

云就绪评估

对每个工作负载评分：

因素	分数 (1-5)	注释
无状态设计
配置外部化
标准输出日志
健康检查端点
优雅关闭
水平可扩展性
秘密管理
12因素合规性

35-40: 云原生就绪 25-34: 需要小修改 15-24: 需要重大重构 8-14: 需要重大重新设计

云迁移清单

• [ ] 设计网络架构（VPC、子网、安全组）
• [ ] 配置身份和访问管理
• [ ] 验证数据驻地要求
• [ ] 合规性映射（云控制 ↔ 要求）
• [ ] 完成成本估算（TCO比较）
• [ ] 更新灾难恢复计划
• [ ] 迁移监控和警报
• [ ] 计划DNS和证书管理
• [ ] CDN配置
• [ ] 在云环境中进行负载测试
• [ ] 安全扫描管道
• [ ] 验证备份和恢复
• [ ] 更新云操作运行手册
• [ ] 团队培训云平台
• [ ] 评估供应商锁定

从第一天开始成本优化

• 正确大小实例 — 从小开始，用数据扩展
• 预留/承诺使用 — 使用数据后3个月
• 现货/抢占式 — 用于批处理作业，CI/CD，开发/测试
• 自动扩展 — 在晚上、周末缩小规模
• 存储层 — 根据访问模式热/暖/冷/存档
• 标记一切 — 按团队、服务、环境分配成本
• 每月审查 — 未使用资源，过大实例

---

第7阶段：API现代化

API包装模式

对于没有API的遗留系统：

1. 屏幕抓取适配器 — 解析HTML/mainframe屏幕
2. 数据库水龙头 — 直接从遗留数据库读取（只读！）
3. 基于文件的集成 — 监视文件夹，解析文件
4. 消息队列桥 — 遗留写入队列，新读取
5. RPC包装器 — 通过REST/gRPC公开现有功能

API合同优先迁移

endpoint: "/api/v2/orders"
legacy_source: "stored_procedure: sp_GetOrders"
new_implementation: "orders-service"
migration_status: "legacy | dual-run | new-only"
contract_changes:
  - field: "order_date"
    old_format: "MM/DD/YYYY string"
    new_format: "ISO 8601"
    adapter: "date_format_adapter"
  - field: "status"
    old_values: ["A", "C", "P"]
    new_values: ["active", "completed", "pending"]
    adapter: "status_code_mapper"
parity_tests: 47
parity_passing: 47

---

第8阶段：测试策略

迁移测试金字塔

         / 烟雾测试  \           ← 整个系统活着？
        / 平行测试    \          ← 旧新行为相同？
       / 集成测试   \         ← 服务协同工作？
      / 合同测试      \        ← API合同得到尊重？
     / 性能测试     \       ← 不比之前慢？
    / 数据验证测试   \      ← 数据迁移正确？
   /  单元测试               \     ← 新代码工作？

平行测试框架

对于每个迁移的功能：

feature: ""
test_type: "api_parity | ui_parity | data_parity"
method: "shadow traffic | replay | parallel run"
sample_size: 0
match_rate: "0%"  # 目标：99.9%+
mismatches_investigated: 0
mismatches_accepted: 0  # 已知故意差异
mismatches_bugs: 0
sign_off: false

影子流量 — 复制生产请求到新系统，比较响应（不要将新响应提供给用户）。

性能回归规则

• P95延迟不得超过比旧系统多10%
• 吞吐量必须满足或超过相同负载下的旧系统
• 数据库查询次数不得每请求增加
• 内存使用不得超过比旧系统多20%
• 如果任何指标回归 → 在继续之前进行调查

---

第9阶段：团队与流程

现代化团队结构

角色	责任	何时需要
现代化负责人	策略、排序、阻塞	全职
遗留专家	知道哪里埋藏着尸体	按需、随叫随到
新平台工程师	构建目标架构	全职
数据工程师	迁移、同步、验证	阶段依赖
QA/测试工程师	平行测试、自动化	全职
DevOps/平台	CI/CD，基础设施	按需
产品负责人	业务优先级、验收	按需

从遗留中挖掘知识

现代化最危险的部分是丢失未记录的业务规则。

1. 代码考古学 — git blame，找到最老未变的代码，理解为什么
2. 采访利益相关者 — “如果我们改变了X会破坏什么？”
3. 生产日志分析 — 哪些边缘案例实际上发生了？
4. 错误处理审查 — 每个catch块都是文档化的业务规则
5. 测试套件审查 — 测试描述预期行为
6. 配置审查 — 魔法数字、功能标志、覆盖

沟通计划

受众	频率	内容
执行赞助商	双周	进度、风险、预算、时间线
工程团队	每周	冲刺目标、技术决策、阻塞
依赖团队	每月	即将到来的变化、迁移日期、API变化
最终用户	每次迁移	正在改变什么，何时，如何影响他们

---

第10阶段：风险管理

前10大现代化风险（预建）

#	风险	可能性	影响	缓解
1	丢失未记录的业务规则	高	严重	代码考古学 + 利益相关者访谈 + 平行测试
2	时间线低估	非常高	高	初始估计的2倍，分阶段检查点
3	数据迁移损坏	中等	严重	校验和、并行运行、回滚计划
4	功能一致性差距	高	高	影子流量测试、用户验收测试
5	团队知识流失（人员离职）	中等	高	文档化一切，结对编程，知识共享
6	迁移期间遗留系统变化	高	中等	功能冻结或双写合同
7	性能回归	中等	高	每个阶段负载测试，性能预算
8	范围蔓延（迁移时改进）	非常高	中等	严格"迁移，不改进"规则第1阶段
9	集成失败	中等	高	合同测试，断路器，回退路由
10	利益相关者疲劳	高	中等	早期快速获胜，可见进度仪表板

杀伤标准

如果触发杀伤标准：停止现代化。

• 预算超出初始估计的2倍，完成<50%
• 迁移后无法验证关键业务规则
• 项目期间团队流失>30%
• 迁移工作导致遗留系统稳定性下降
• 业务背景变化（M&A、转型、日落）

如果触发杀伤标准： 稳定已完成的工作，记录学习，6个月后重新评估。

---

第11阶段：模式与剧本

语言/框架迁移模式

Java → 现代Java (8→17+)

• 记录，密封类，模式匹配
• 虚拟线程（Project Loom）每个请求一个线程
• 迁移构建：Maven→Gradle或更新Maven插件
• Spring Boot 2→3：javax→jakarta命名空间

Python 2→3

• 使用2to3工具自动转换
• 修复：print()，除法，unicode，dict方法
• 升级依赖项（检查py3兼容性）

jQuery→React/Vue

• 从页面部分提取组件
• 状态管理取代DOM操作
• 事件处理程序成为组件方法
• Ajax调用成为API服务层

单体→微服务

• 绞杀者图（见第3阶段）
• 从读取模型（报告，搜索）开始
• 首先提取无状态服务
• 共享数据库 → 数据库每服务最后

本地→云

• 首先重新托管（提升&转移）
• 然后重新平台（托管服务）
• 然后重新架构（云原生模式）
• 永远不要错过步骤 — 每个步骤都证明价值

COBOL/主机现代化

1. API包装 — 将CICS/IMS事务公开为REST API
2. 屏幕抓取 — 自动化3270终端交互
3. 逐步提取 — 一次一个事务
4. 数据复制 — DB2/VSAM → PostgreSQL/cloud DB
5. 规则提取 — COBOL段落 → 业务规则引擎
6. 永远不要一次性重写全部 — 几十年的业务逻辑 = 几十年的边缘案例

微服务反模式避免

反模式	症状	修复
分布式单体	服务必须一起部署	识别并打破耦合
共享数据库	多个服务写入相同表	数据库每服务
同步链	A调用B调用C调用D	异步事件，编排
纳米服务	数百个微小服务	合并相关服务
共享库用于业务逻辑	库更新破坏消费者	重复代码>共享耦合
无API版本控制	破坏性更改级联	语义版本控制，弃用政策

---

第12阶段：指标与报告

现代化健康仪表板

project: ""
assessment_date: ""
overall_health: "green | yellow | red"

progress:
  modules_total: 0
  modules_migrated: 0
  modules_in_progress: 0
  percent_complete: "0%"
  
velocity:
  modules_per_sprint: 0
  estimated_completion: ""
  on_track: true

quality:
  parity_test_pass_rate: "0%"
  production_incidents_from_migration: 0
  rollbacks: 0
  
risk:
  open_risks: 0
  p0_risks: 0
  blocked_items: 0

cost:
  budget_total: "$0"
  budget_spent: "$0"
  budget_remaining: "$0"
  burn_rate_monthly: "$0"

100分现代化质量量表

维度	权重	分数 (0-10)	加权
策略清晰度	15%
风险管理	15%
测试严谨性	15%
数据完整性	15%
架构质量	10%
团队能力	10%
利益相关者对齐	10%
文档化	10%
总计	100%		/100

90-100: 模范 — 参考项目 70-89: 强 — 小改进 50-69: 足够 — 处理差距 低于50: 有风险 — 暂停并重新评估

每周状态模板

## 现代化状态 — [日期]周

### 进度
- 本周迁移的模块：[N]
- 总共迁移：[N]/[总数] ([X]%)
- 按计划进行[目标日期]：[是/否]

### 完成
- [本周发货的内容]

### 进行中
- [正在处理的内容]

### 阻塞
- [卡住的内容和需要什么]

### 风险
- [新或变化的风险]

### 下周
- [下个冲刺的计划]

---

边缘案例

“我们需要现代化但不能停止添加功能”

• 绞杀者图 — 在新功能周围现代化
• 仅在迁移该模块时对遗留模块进行功能冻结
• 从第一天起在新栈中构建新功能

“我们不知道系统做什么”

• 从可观察性开始：记录日志、跟踪、指标
• 运行2-4周以了解实际使用模式
• 代码覆盖率分析显示实际执行的代码
• 采访任期最长的团队成员

“需要同时现代化多个系统”

• 按依赖顺序排列 — 下游优先
• 共享服务（认证、数据）现代化一次，重用
• 永远不要并行超过2个现代化流

“原始开发人员已经离开”

• 将代码视为文档
• 在任何迁移工作之前投资2-4周进行代码考古学
• 将新开发人员与业务利益相关者配对
• 在更改任何内容之前为现有行为编写测试

“我们正在被收购/合并系统”

• 首先映射重叠功能
• 选择每个领域的"获胜者"系统 — 不要合并代码库
• 系统之间的API集成层
• 完全整合的现实时间表为18个月

“合规要求旧系统”

• 在迁移期间维护合规证据链
• 双审计期间使用两个系统
• 从第一天起让合规团队参与迁移计划
• 文档控制映射：旧控制 → 新实现

---

自然语言命令

命令	操作
“评估这个系统进行现代化”	运行完整的技术债务清单
“我们应该使用哪种现代化策略？”	走过策略决策树
“计划绞杀者图迁移”	生成绞杀者外观YAML + 序列
“分解这个单体”	领域发现 + 有界上下文映射
“迁移这个数据库”	数据质量门 + 迁移策略
“检查云就绪度”	运行云就绪评估
“创建迁移测试计划”	构建测试金字塔与平行测试
“风险是什么？”	生成前10大风险登记册
“我们如何从[X]迁移到[Y]？”	特定模式剧本
“现代化状态更新”	生成每周状态模板
“评估这个现代化项目”	运行100分质量量表
“我们应该停止这个现代化吗？”	评估杀伤标准