lcap-frontend-library 0.0.1

package/packages/lcap-frontend-library/workflows/migrate/flow.md

@@ -0,0 +1,302 @@
+# Vue2 依赖库 → Vue3 迁移：流程编排（Superpowers-Native）
+
+> 基于 Superpowers 等价性证明范式。与 create/evolve 共用阶段骨架，命令为 migrate.*。
+> 但每个阶段的内在逻辑忠于"受限收敛"而非"自由创作"。
+
+---
+
+## 输入
+
+用户指定 **Vue2 依赖库源码路径**（`sourceDir`），例如：
+> 把 /path/to/cw_audio_library 迁移到 Vue3
+> 迁移 cw_audio_view 组件
+> /migrate.scan /path/to/source
+
+## 输出
+
+一个**完整可构建的 LCAP 扩展依赖库项目**，满足：
+- 所有单元测试通过（`npm run test`）
+- 构建成功（`npm run build`）
+- E2E 测试通过（`npm run test:e2e`）
+- 行为等价矩阵全行 ✅ 或 ⚠️（无 ❌）
+- 5 维自检报告全部 PASS
+- 与 Vue2 行为 1:1 对齐
+
+---
+
+## Superpowers 核心公理
+
+```
+公理 1: Vue2 源码 = 唯一行为真值（不可推断、不可臆测）
+公理 2: 测试 = 真值的形式化编码（测试定义目标，非验证手段）
+公理 3: GREEN = 等价性的构造性证明（测试全通过 ⟹ 行为等价）
+公理 4: 断路器 = 不可能性的早期识别（路径不通 → 停止 → 质疑）
+公理 5: 证据铁律 = 每个声明须可验证（终端退出码 ≠ "应该通过"）
+```
+
+---
+
+## 执行规则
+
+- **命令驱动**：每个阶段对应一个 `commands/migrate.*.md`，按其指令执行
+- **TDD 铁律**：先写测试确认 FAIL → 再写代码至 PASS（不可跳过/逆序）
+- **RED/GREEN 物理分离**：RED 未完成不能进 GREEN，这是结构性强制
+- **三门禁**：`npm run test` + `npm run build` + `npm run test:e2e` 全部 exit 0
+- **零容忍**：失败测试不可删除/跳过/注释，必须修复至通过
+- **断路器**：同一错误模式连续 3 次修复失败 → 停止 → 质疑方案
+- **知识库优先**：步骤标注「→ §xxx」时，必须先读 `knowledge-base.md` 对应章节
+- **禁止条款**：每个命令有明确"不允许做什么"，体现受限收敛本质
+- **行为等价矩阵**：贯穿 tasks→red→green→check，确保无行为遗漏
+- **真值溯源**：每个决策必须可追溯到 Vue2 源码或 §section-id
+- **所有文档落入工程内部**：`<vue3-project>/specs/` 目录
+
+---
+
+## 7 命令总览
+
+```
+┌─── 库级（执行 1 次）──────────────────────────────────────────┐
+│ migrate.scan       全景扫描 + 工程创建 + 迁移清单初始化          │
+└──────────────────────────────────────────────────────────────┘
+
+┌─── 资产级（每资产循环）──────────────────────────────────────┐
+│ migrate.spec       Vue2 行为真值提取 → spec.md               │
+│ migrate.plan       转换映射 + 路径锁定 → plan.md  ⛔审批      │
+│ migrate.tasks      TDD 编排 + 行为等价矩阵 → tasks.md        │
+│ migrate.red        Phase RED：行为编码为测试（确认 FAIL）      │
+│ migrate.green      Phase GREEN：代码收敛至 PASS               │
+│ migrate.check      三门禁 + 等价性审计 → report.md            │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**无 migrate.status 命令**——状态追踪通过 `specs/manifest.md` 实现，各命令自动读写。
+
+## 先验引用策略（按阶段 + 资产类型）
+
+| 阶段 | 作用 | KB | 附加 references |
+|------|------|-----|-----------------|
+| scan | 全景+类型+工程 | §process-* 子集 | logic 扫时 nasl-logic-authoring |
+| spec | 行为真值 | 全文（仅提取） | logic → nasl-logic-authoring |
+| plan | 转换方案 | 全文 | component → lcap-extension-component；logic → nasl-logic-authoring |
+| tasks | 矩阵+TDD | §process-matrix/e2e | logic/shared 无 E2E |
+| red | FAIL 测试 | §process-e2e | logic/shared vitest only |
+| green | PASS 实现 | 全文 | 同 plan |
+| check | 审计+产物 | 全文 | component §alignment-checklist；logic L1–L3；shared S1–S3 |
+
+## 资产类型（→ §process-asset-types）
+
+| 类型 | 说明 |
+|------|------|
+| component | 扩展组件（默认路径） |
+| logic | @NaslLogic 逻辑函数 |
+| shared-composable | 多组件共享 Mixin（scan 升格） |
+
+scan 写入 manifest：`类型`、`depends_on`、`推荐序号`。spec 前检查 depends_on 已 verified。
+
+## migrate.check = self-check + build-verify
+
+| create/evolve 阶段 | migrate 对应 |
+|--------------------|--------------|
+| self-check（6） | check §A 三门禁 + §B 等价审计 |
+| build-verify（7） | check §C 产物验证 + §E 库级收尾 |
+| — | check §D 跨资产回归（migrate 特有） |
+
+---
+
+## 阶段 1：SCAN
+
+执行 `commands/migrate.scan.md`（传入 sourceDir）
+
+**执行逻辑**：
+1. 扫描 Vue2 源码，识别全部组件与逻辑函数
+2. 对每个资产定位 stories 真值来源（→ §stories-truth）
+3. 创建/检测 Vue3 目标工程（→ §process-scaffold）
+4. 确保测试基础设施（vitest + playwright + 动态端口）
+5. 初始化 `specs/manifest.md` 迁移清单
+
+**成功标准**：
+- Vue3 扩展工程已创建（含 `package.json`、`src/`、`node_modules/`、`playwright.config.ts`、`e2e/`）
+- `npm run dev` 可启动 Storybook
+- `specs/manifest.md` 已创建，包含全部待迁移资产
+- 每个资产的 stories 真值路径已确定
+- shared-composable 资产已识别（若适用）
+- manifest 含推荐迁移顺序与 library_status
+
+---
+
+## 阶段 2：SPEC
+
+执行 `commands/migrate.spec.md`（传入资产名）
+
+**执行逻辑**：
+1. 完整读取 Vue2 源文件（组件代码 + stories + mixin + 样式）
+2. 系统性提取行为规格（props/events/methods/slots/响应式/生命周期/mixin调用点）
+3. 记录 stories 真值（block + example 完整内容）
+4. 输出 spec.md（纯事实，禁止推断/评价/建议转换方案）
+
+**成功标准**：
+- `specs/<NN>-<资产名>/spec.md` 已创建
+- Mixin 全量方法已列出（含调用点分析）
+- Props/Events/Methods/Slots 完整提取
+- 第三方集成的初始化/销毁序列完整记录
+- `specs/manifest.md` 该资产状态 → `🔍 spec-done`
+
+**核心纪律**：只记录、不判断。"它现在做什么" ≠ "它应该怎么转"。
+
+---
+
+## 阶段 3：PLAN
+
+执行 `commands/migrate.plan.md`（传入资产名）
+
+**执行逻辑**：
+1. 读取 spec.md（行为真值）
+2. 按 knowledge-base 映射转换策略（→ §mixin-composable, §vue3-children-clone, §css-vars；component 另读 lcap-extension-component）
+3. 逐条核对 §pitfalls
+4. 规划文件结构与路径锁定
+5. ⛔ 用户审批门禁
+
+**成功标准**：
+- `specs/<NN>-<资产名>/plan.md` 已创建
+- 每个转换决策引用 §section-id
+- 文件路径规划表完整（含测试层标注）
+- 风险/陷阱命中表已填写
+- 用户已确认方案
+- `specs/manifest.md` 该资产状态 → `🔄 planned`
+
+---
+
+## 阶段 4：TASKS
+
+执行 `commands/migrate.tasks.md`（传入资产名）
+
+**执行逻辑**：
+1. 读取 spec.md + plan.md
+2. 从 spec.md 提取全部行为条目，初始化行为等价矩阵
+3. 按 TDD 阶段编排 Phase RED / Phase GREEN 任务组
+4. 确保矩阵每行有对应 RED 测试任务
+
+**成功标准**：
+- `specs/<NN>-<资产名>/tasks.md` 已创建
+- 行为等价矩阵已初始化（spec 每行为有对应行）
+- Phase RED / GREEN 任务组结构清晰
+- RED 组完成前不可进入 GREEN 组（铁律已标注）
+- `specs/manifest.md` 该资产状态 → `📋 tasks-ready`
+
+---
+
+## 阶段 5：RED
+
+执行 `commands/migrate.red.md`（传入资产名）
+
+**执行逻辑**：
+1. 读取 spec.md + plan.md + tasks.md（RED 组）
+2. 编写 Vitest 单测（按优先级 P1-P5）
+3. 编写 E2E 测试骨架（pageerror + console 监听，过滤网络资源 404）
+4. 运行 `npm run test` → 确认全部 FAIL
+5. 填充行为等价矩阵"RED 测试编码"列
+
+**成功标准**：
+- 测试文件已创建（vitest + e2e）
+- `npm run test` → exit ≠ 0（测试存在且 FAIL）
+- 若测试意外 PASS → 断言太宽泛，重写
+- tasks.md RED 组标记 [x]
+- 行为等价矩阵"测试编码"列已填充
+- `specs/manifest.md` 该资产状态 → `🔴 red-done`
+
+---
+
+## 阶段 6：GREEN
+
+执行 `commands/migrate.green.md`（传入资产名）
+
+**执行逻辑**：
+1. 读取测试文件 + plan.md + tasks.md（GREEN 组）
+2. 按资产类型 scaffold（component → create-component-files；logic → create-logic-files；shared → Edit）
+3. 按 plan.md 文件路径表顺序实现（component：api.ts → ideusage → composables → template → stories → css）
+4. 迭代直到 `npm run test` → PASS
+5. 填充行为等价矩阵"GREEN 实现"列
+
+**成功标准**：
+- `npm run test` → exit 0（全部 PASS）
+- tasks.md GREEN 组标记 [x]
+- 行为等价矩阵"实现"列已填充
+- `specs/manifest.md` 该资产状态 → `🟢 green-done`
+
+**断路器**：3 次同一错误 → 停止 → 等待用户决策
+
+---
+
+## 阶段 7：CHECK
+
+执行 `commands/migrate.check.md`（传入资产名）
+
+**零信任要求**：CHECK 阶段遵循零信任验证协议——必须重新读取 spec/plan/tasks/源码（禁止基于 GREEN 阶段记忆判断），三门禁必须在本阶段重新执行并记录退出码。
+
+**执行逻辑**：
+1. 三门禁（npm run test + build + test:e2e → 全部 exit 0）
+2. 行为等价矩阵逐行验证（填充"等价状态"列）
+3. 五维度对抗性审计
+4. 发现问题 → 修复 → 重跑三门禁 → 闭环
+
+**成功标准**：
+- §A–§D 按资产类型完成；component 含产物验证 4 项证据
+- §E：全部资产 verified 时产出 `specs/library-report.md` 且 `library_status=🏁`
+- 支持 `--finalize-library` 显式库级收尾
+- 行为等价矩阵无 ❌ 行
+- `specs/<NN>-<资产名>/report.md` 已生成
+- `specs/manifest.md` 该资产状态 → `✅ verified`
+
+---
+
+## 产出结构
+
+```
+<vue3-project>/
+├── src/
+│   ├── components/<asset>/
+│   │   ├── api.ts                      ← lcap-extension-component 规范
+│   │   ├── index.vue                   ← 仅 UI 组装
+│   │   ├── index.ts                    ← 桶文件具名导出（→ §plugin-barrel）
+│   │   ├── ideusage.json               ← lcap-extension-component 规范
+│   │   ├── composables/useXxx.ts       ← Mixin 拆分
+│   │   ├── stories/block.stories.js    ← 1:1 静态
+│   │   ├── stories/example.stories.js  ← 功能 demo
+│   │   └── __tests__/index.spec.ts     ← vitest
+│   └── logics/                         ← §logics-boundary + nasl-logic-authoring
+├── e2e/<asset>.spec.ts                 ← playwright
+└── specs/                              ← 迁移文档（工程内部）
+    ├── manifest.md                     ← 迁移清单 + 状态追踪
+    └── <NN>-<资产名>/
+        ├── spec.md                     ← Vue2 行为真值
+        ├── plan.md                     ← 转换策略
+        ├── tasks.md                    ← TDD 编排 + 行为等价矩阵
+        └── report.md                   ← 等价性证明报告
+```
+
+---
+
+## 模板一览
+
+| 模板文件 | 使用阶段 | 用途 |
+|:---|:---|:---|
+| `templates/migration-manifest-template.md` | SCAN（初始化） | 迁移清单 + 状态追踪格式 |
+| `templates/migration-spec-template.md` | SPEC（输出） | Vue2 行为规格提取的标准格式 |
+| `templates/migration-plan-template.md` | PLAN（输出） | 转换策略 + 文件规划 + 风险 |
+| `templates/migration-tasks-template.md` | TASKS（输出） | TDD 编排 + 行为等价矩阵 |
+| `templates/migration-report-template.md` | CHECK（输出） | 三门禁证据 + 矩阵验证 + 五维审计 |
+| `templates/library-report-template.md` | CHECK §E | 库级验证报告 |
+
+---
+
+## 核心约束
+
+- Vue2 源码是行为的唯一真值，不可凭 AI 知识推断行为
+- 严格遵循 NASL 类型系统：仅允许 `nasl.core.*`、`nasl.collection.*`，禁止 Object/any
+- 组件必须使用 CSS 变量实现主题适配，禁止硬编码颜色/间距（→ §css-vars）
+- v-model 使用 `value` + `update:value` 约定，非 `modelValue`（→ §pitfalls）
+- 桶文件必须具名导出，禁止 `export *`（→ §plugin-barrel）
+- Mixin 必须确认调用点再迁移，死代码不建 composable（→ §mixin-composable）
+- 测试零容忍：禁止删除/跳过失败用例，Timeout 按逻辑 Bug 排查修复
+- 每个 PASS/FAIL 声明必须有终端执行证据，禁止"应该通过"
+- 行为等价矩阵不允许有 ❌ 行留到最终（必须修复或标记有意差异）