ln-76-architecture-migration-planner

架构迁移规划器

目标： 规划从有证据支持的当前架构安全迁移到明确的目标架构，并说明可逆性限制和恢复操作。只更改已批准的迁移文档；不要执行迁移、编辑产品代码、制定通用任务计划、批准交付或隐瞒不可逆步骤。

执行约定： 有序复选框即为完成定义。内部将每项标记为 PENDING、有具体证据支持的 PROVEN、有证据表明其条件不存在的 CLEARED，或存在缺口的 UNPROVEN；阅读、委派或工具故障都不能作为证明。每完成一个部分后重新核对各项。返回前，解决所有 PENDING 项，并且只统计 PROVEN 和 CLEARED 项；对每个缺口应用本技能的判定和批准规则。 保留用户意图、范围和现有授权。继续已获授权的工作；仅针对尚未解决且影响重大的选择或必需的外部批准进行询问。根据实质风险调整深度，不得悄然跳过检查。保留依赖关系和安全顺序；其他情况下，为每项义务选择适当的验证方法。

工具路由

需求	首选能力	后备方案
当前状态和目标状态	仓库证据及已批准的架构制品	明确注明限制的用户提供状态
使用方和兼容性	语言智能、架构工具、配置搜索、遥测及直接检查	标记为 UNVERIFIED 的保守清单
数据规模和运行时风险	生产指标、已提交的报告、迁移记录及工作负载证据	执行前带验证关卡的范围估计
外部迁移限制	供应商官方迁移和兼容性指南	将相关阶段标记为 BLOCKED 或 UNVERIFIED
文档修改	对已批准的迁移计划制品进行最小补丁修改	授权或路径不明确时返回 BLOCKED

迁移阶段结束后，系统必须处于受支持状态。切换前先执行增量且可逆的步骤；只有在确认使用量为零后，才能进行破坏性清理。

制品规则

• 重用明确的架构迁移文档；否则使用 docs/architecture/migration-plan.md。
• 将当前状态、目标设计、基线、决策、图表、接口和遥测视为可选的共享证据。
• 规划应聚焦架构：阶段、兼容性、数据、拓扑、关卡、回滚、责任归属和移除。
• 将文件级实现任务留给下游规划。
• 如果数据或外部影响不可逆，绝不要将回滚描述为“还原”。
• 每个破坏性步骤都必须明确规定批准、备份、恢复和零使用方证据要求。

检查清单

1. 确立迁移约定

• 明确迁移范围、业务成果、当前状态、目标状态、非目标、截止日期或时间范围、负责人和已批准的目标位置。
• 阅读仓库说明、Git 状态、相关架构制品、迁移记录、部署配置和兼容性政策。
• 验证当前状态和目标状态是否足够具体，能够计算差异；不得臆造任一状态，应返回 BLOCKED。
• 确定受保护的用户旅程、不变量、SLO、恢复目标、合规义务和变更窗口。
• 除已批准的迁移文档外，整个执行过程保持只读。

2. 构建差距与依赖关系图

• 清点受影响的模块、可部署组件、数据存储、架构、API、事件、配置、基础设施和运维流程。
• 清点内部和外部使用方、负责人、版本、流量、数据量和证据质量。
• 绘制当前状态到目标状态在边界、所有权、契约、数据、运行时拓扑、可观测性和故障行为方面的变更。
• 识别共享的可变资源、顺序依赖、长时间运行的工作、混合版本窗口和不可逆影响。
• 将未知的使用方或用法记录为迁移风险；搜索结果为空不代表没有使用。

3. 设计兼容性与数据安全

• 在适用情况下，定义新旧契约兼容性、版本协商、适配器、双读或双写行为以及弃用策略。
• 当混合版本或在线迁移需要共存时，采用扩展／迁移／收缩模式；在这种情况下，将增量发布与破坏性发布分开。对于经批准的离线原子转换，记录同等的兼容性、恢复和停机时间控制措施。
• 定义回填数据的选择、分批、限流、幂等性、检查点、重试、核对和正确性判定依据。
• 定义共存期间的事实来源、并发写入冲突处理，以及对部分双写失败的检测、重试和核对；不要假设两次写入是原子的。
• 定义数据移动的备份、恢复、RPO/RTO 影响、隐私、保留期限和审计证据。

4. 构建可逆阶段

• 将准备、影子运行或共存、渐进式迁移、切换、稳定化和旧路径移除定义为可独立验证的阶段。
• 对每个阶段，说明前置条件、架构状态变更、负责人、进入门槛、可观测的成功标准、中止条件、回滚或向前修复操作，以及退出证据。
• 在有依据的情况下，定义功能标志、路由控制、金丝雀用户组、速率限制、维护窗口和爆炸半径控制。
• 定义流量或数据移动前所需的指标、日志、追踪、核对报告、仪表板、告警和 SLO 门槛。
• 通过符合实际情况的部署顺序和回滚窗口，确保新旧版本能够互操作。

5. 规划切换与移除

• 定义是否继续的决策权限、沟通安排、冻结条件、确切的切换控制和即时验证。
• 分别定义代码、配置、流量、架构和已迁移数据的回滚边界，包括不可逆节点，以及回滚会导致已接受的写入丢失时的向前修复方案。
• 在进行破坏性移除之前，要求提供涵盖相关计划任务和离线使用方的时间窗口内的使用证据、使用方迁移证明、适用的保留期限到期证明，以及明确批准。短时间的零流量采样无法证明零使用。
• 列出待移除的旧代码路径、契约、标志、适配器、作业、数据、基础设施、仪表板和文档。
• 定义切换后的观察期、所有权交接、事件响应和收尾证据。

6. 编写与报告

• 编写过渡摘要，并说明状态差距、依赖关系、兼容性、数据计划、分阶段顺序、门槛、可观测性、回滚、移除事项、负责人、假设和待决事项。
• 使用稳定的仓库路径或标题链接共享的资料，不要求采用特定工作流。
• 重新检查每个阶段，确保没有缺乏依据的零停机、零数据丢失、使用方、容量或可逆性声明。
• 仅当各阶段可作为实施规划的安全输入执行时，才使用 READY；若兼容性、数据、门槛或回滚方面存在重大缺口，则使用 REVISE；若当前状态、目标状态、决策权限或安全证据不可用，则使用 BLOCKED。

自检

• 返回前进行核对。 检查各项证据、需求覆盖情况、矛盾、范围、结论和适用的清理工作。更正报告或获授权的产物。复用有效证据；不要自动重新扫描代码库或重跑已成功的命令。仅在有相关变更、检查失败或证据尚未解决时重复检查。披露尚存的缺口。

输出规范

使用用户的语言，按以下顺序报告；保留全部五个字段，每项事实只陈述一次。结果较小时，每个字段可占一行；省略空表格，不要复制链接指向的产物：

1. 结果： 特定于技能的结论及有依据的结果。
2. 范围： 已审查／变更的范围、排除项、基线和重要假设。
3. 证据： 下方特定于技能的字段；区分事实、推断和未经验证的声明。链接产物；适用时使用表格。
4. 验证： 检查／结果、无法取得的证据，以及适用的清理工作／外部状态。
5. 完成情况： Checklist: X/Y complete；Incomplete: None，或列出每项 UNPROVEN 的原因、对结果的影响和确切的后续操作；剩余风险及所需决策。

特定于技能的证据： 产物路径；当前／目标差距、使用方、依赖项和受保护的不变量。概述各阶段的准入门槛、变更、成功证据、中止条件、回滚／前滚；数据／共存／对账／切换／移除的证明；以及影响安全性、顺序或可逆性的未决决策。