# Migration Protocol — 破坏性迁移 / 大版本重构 / 废弃的可复用流程（2→3）

> **生成**：2026-06-12（design-spec-process-review GAP-01 / action B1，owner ack 落地）
> **性质**：可复用流程模板,不是某一次迁移的记录。任何 2→3 任务起手读本份,按阶段走。
> **量级校准**：单 owner + AI 代理。无多人评审会 / 跨团队审批——所有 ack gate = owner 一人拍板。
> **🤖 AI 读取指引**：命中下方「触发条件」即升为 mandatory 全读;非 2→3 任务可跳过。

---

## 这份解决什么（缺口背景）

2→3 类工作（破坏性 API 改造 / 大版本迁移 / 组件·token 废弃 / 跨 consumer 重构）此前**没有可复用流程**:
- [`MIGRATION_TO_V1.md`](../MIGRATION_TO_V1.md) 是**一次性** v0→v1 consumer 升级指南（产物,不是模板）
- [`API_STABILITY.md`](../API_STABILITY.md) 有废弃**规则**（删/改名要先留 ≥1 minor 再 major 移除）,但没说"一次迁移怎么一步步走"
- [`design-process.md`](./design-process.md) 的 US-7 只覆盖**效果图重设计**,不含代码/token 全量迁移
- [`code-conventions.md`](./code-conventions.md) §场景 4（TVU 规范校正）只说"独立 refactor 任务、需用户显式发起",无执行路径

**实证代价**：Notification 双轴 breaking（v0.8.0,2026-06-11）= 一次无流程裸跑的 2→3。本份即此回流。

---

## 触发条件（命中任一 = 走本协议）

- 改动**破坏** consumer 已用的 API（props / events / slots / CSS 类 / token 名 / icon key 删改名）
- 跨多个组件 / 多 consumer 的重构、整页迁移到 TVU 规范（对应 `code-conventions.md` 场景 4.1 / 4.4）
- 组件 / token 废弃或移除
- 任何要 **major changeset** 或 v1.0 后 deprecation cycle 的改动

**不触发**：加可选 prop / 加新组件 / 非破坏性保真度修正（走常规增量 US-3 + minor changeset）。**判不准 → 当 2→3 走**（保守兜底,同 design-process 分档铁律）。

---

## 四阶段（每阶段 STOP，owner ack 后进下一阶段）

### Phase A — 迁移基线（动手前先存档"现状",防迁完无对照）

- [ ] **API 快照**：被改组件的 props / events / slots / 暴露项全枚举（迁移后对照"删了/改名了什么"）
- [ ] **Token usage 快照**：被改动涉及的 token（哪些被删 / 改名 / 重绑）
- [ ] **视觉基线**：当前 render-verification manifest 跑一遍存基线（迁移后对照不回归）
- [ ] **Consumer 影响面扫描**：谁在用这个 API（已知 consumer：MicroApps 等）——影响越大,迁移指南越要细

### Phase B — 迁移方案（决策 + 文档初稿，**owner ack gate**）

- [ ] **破坏性决策树**：
  - 改动破坏 API？ → 是 → major bump（v1.0 前 0.x.0 minor 即可,见 [`API_STABILITY.md`](../API_STABILITY.md)）
  - v1.0 后？ → 必须先 `@deprecated since X.Y.0` 留 ≥1 minor → 下个 major 才移除（不许直接删）
  - 能否提供兼容垫片 / 双形态过渡期降低 consumer 痛感？
- [ ] **迁移映射表初稿**：旧 → 新 的逐项对照（参 Notification status→form+type 的 §2 表范式）
- [ ] **major changeset 文件**：含迁移说明
- [ ] **⛔ Owner ack gate**：方案 + 映射表发 owner,确认可接受才进 Phase C

### Phase C — 实现

- [ ] **代码**：破坏性改动落地 + 新 API 全量测试（vitest / vue-tsc）
- [ ] **Figma 侧**（若含设计变更）：走 [`design-process.md`](./design-process.md) 对应档（重设计 = US-7,增量 = US-3）
- [ ] **迁移指南终版**：补真实 code diff 示例（不只 API 名,给 before/after 片段）
- [ ] **CHANGELOG**：写迁移说明 + 映射表（consumer-facing）

### Phase D — 验证 + consumer 采用

- [ ] **render-verification 全量 pass**（基线更新到新 API,A 不回归）
- [ ] **a11y CI 全绿**
- [ ] **Consumer soak**：按 [`V1_RELEASE_CHECKLIST.md` §RC Consumer 验收协议](../V1_RELEASE_CHECKLIST.md) 跑（≥1 周、0 critical、owner 单签）
- [ ] **（v1.0 path）** burn-in clock 重置记录

---

## 轻重分档（别让小破坏背全套）

| 规模 | 怎么走 |
|---|---|
| **小破坏**（单组件单 prop 删改名,无 consumer 已用 / 影响极小） | Phase A 快照 + Phase B 映射表一行 + major changeset；C/D 随常规闭环,不单列 |
| **大迁移**（跨组件 / 跨 consumer / 整页规范化 / 组件废弃） | 四阶段全走,每阶段 STOP ack |

判不准规模 → 按大迁移走。

---

## 文件关系（防混淆）

| 文档 | 角色 |
|---|---|
| **本文件** | 迁移**流程模板**（怎么走） |
| [`API_STABILITY.md`](../API_STABILITY.md) | 迁移**规则**（什么能改、废弃周期多长） |
| [`MIGRATION_TO_V1.md`](../MIGRATION_TO_V1.md) | 迁移**产物**示例（一次具体迁移指南长啥样） |
| [`V1_RELEASE_CHECKLIST.md` §RC](../V1_RELEASE_CHECKLIST.md) | Phase D 的 consumer soak 标准 |
| [`design-process.md`](./design-process.md) US-7 | 迁移的**设计/效果图侧**子流程 |
| [`code-conventions.md`](./code-conventions.md) §场景 4 | 迁移的**代码侧**意图归类入口 |