lcap-frontend-library 0.0.1

package/packages/lcap-frontend-library/templates/migration-report-template.md

@@ -0,0 +1,227 @@
+# [资产名] — 迁移验证报告
+
+**自检时间**：[DATE]
+**资产**：[组件目录名]
+**资产类型**：component / logic / shared-composable
+**状态**：✅ PASS / ⚠️ CONDITIONAL PASS / ❌ FAIL
+**输入**：`specs/<NN>-<资产名>/spec.md`（行为真值）+ `specs/<NN>-<资产名>/tasks.md`（行为等价矩阵）
+
+---
+
+> **审计维分支**：component 使用维度 1–5（下文）；logic 使用 L1–L3（→ migrate.check.md）；shared-composable 使用 S1–S3（方法对齐 / 副作用清理 / 测试覆盖）。非 component 跳过 Storybook 维与 api.ts 覆盖表。
+
+## §B 等价审计
+
+**资产类型**：<!-- component | logic | shared-composable -->
+
+### component — 维度 1
+
+按 **`knowledge-base.md` §alignment-checklist** 逐项勾选（24 条）。结论列：PASS / FAIL / N/A + 证据。
+
+### logic — L1–L3
+
+按 `migrate.check.md` 定义填写 L1 签名 / L2 测试覆盖 / L3 NASL 合规。**禁止**使用 §alignment-checklist。
+
+### shared-composable — S1–S3
+
+按 `migrate.check.md` 定义填写 S1 行为等价 / S2 副作用清理 / S3 调用契约。
+
+**维度 1 / L1–L3 / S1–S3 结论**：PASS / FAIL
+**发现与修复记录**：
+- [如有修复，记录修改内容]
+
+---
+
+## 维度 2：API 覆盖矩阵
+
+> 从 api.ts 提取所有 Props（展示/交互相关）、Methods、Events，逐一核对测试覆盖。
+
+| API 项 | 类型 | Vitest 覆盖 | E2E 覆盖 | 覆盖状态 |
+|:---|:---|:---|:---|:---|
+| value | Prop | ✓ 响应式 | ✓ 渲染 | PASS |
+| onPlay | Event | ✓ emit | ✗ | 需补 E2E |
+| reload | Method | ✗ | ✗ | 需补两层 |
+
+**未覆盖项修复**：
+- [补充的测试描述 + 验证结果]
+
+**维度 2 结论**：PASS / FAIL
+
+---
+
+## 维度 3：平台合规扫描
+
+### 3.1 硬编码颜色/间距
+
+| 文件 | 位置 | 当前值 | 应替换为 | 状态 |
+|:---|:---|:---|:---|:---|
+| index.vue | .toolbar | #f5f7fa | var(--el-fill-color-light) | 已修复 / 待修复 |
+
+### 3.2 CSS 变量合法性
+
+| 使用的变量 | 是否在 theme-variables-element-plus.md 中定义 | 备注 |
+|:---|:---|:---|
+| var(--el-color-primary) | ✓ | — |
+
+### 3.3 NASL 类型检查
+
+| api.ts 位置 | 当前类型 | 应修改为 | 状态 |
+|:---|:---|:---|:---|
+| [如有 Object/any] | Object | nasl.core.String | 已修复 |
+
+### 3.4 Vue2 残留检查
+
+| 残留模式 | 文件/位置 | 状态 |
+|:---|:---|:---|
+| this.$emit | — | 无残留 ✓ |
+| this.$refs | — | 无残留 ✓ |
+| Options API | — | 无残留 ✓ |
+| process.env | — | 无残留 ✓ |
+| export * from | — | 无残留 ✓ |
+
+### 3.5 样式隔离检查
+
+| 文件 | 当前样式标签 | 是否合规 | 状态 |
+|:---|:---|:---|:---|
+| index.vue | `<style scoped>` | ✓ | PASS |
+
+**维度 3 结论**：PASS / FAIL
+
+---
+
+## 维度 4：Storybook 运行时证据
+
+### 执行记录
+
+| 项 | 内容 |
+|:---|:---|
+| 退出码 | 0 |
+| 检查 story 数 | N |
+| 结果 | ✅ 全部通过 / ❌ x/N 失败 |
+
+### Storybook 迭代记录（来自 migrate.exec + 本次复检）
+
+#### 轮次 1
+
+| 字段 | 内容 |
+|:---|:---|
+| 轮次 | 第 1 次 |
+| 时间 | [ISO 时间] |
+| 脚本/命令 | [完整命令] |
+| 结果 | ❌ x/y 失败 / ✅ 全部通过 |
+| 分类码 | GLOBAL_DEP / IMPORT_ORDER / HMR / ELEMENT_NOT_REG / ... |
+| 错误详情 | [按 story 列出 console.error / pageerror] |
+| 根因分析 | [为什么出错] |
+| 修复描述 | [改了什么文件，怎么改] |
+| 复检状态 | → 轮次 2 / ✅ 最终通过 |
+
+#### 轮次 N（最终）
+
+| 字段 | 内容 |
+|:---|:---|
+| 轮次 | 第 N 次 |
+| 结果 | ✅ 全部通过 |
+| 通过 story 数 | M/M |
+
+**维度 4 结论**：PASS / FAIL
+
+---
+
+## 维度 5：机制差异标注
+
+> 记录 Vue3 实现与 Vue2 行为之间的**有意差异**（维度 1 中标注 ⚠️ 的项汇总于此）。
+
+| 差异项 | 分类 | Vue2 行为 | Vue3 行为 | 原因 |
+|:---|:---|:---|:---|:---|
+| beforeDestroy | 框架差异 | beforeDestroy hook | onBeforeUnmount | Vue3 重命名 |
+| $listeners | 框架差异 | 透传事件监听器 | 合并到 $attrs | Vue3 移除 |
+
+**分类说明**：
+- `框架差异`：Vue3 框架本身的变化（不可避免）
+- `优化`：利用 Vue3 新能力的改进
+- `简化`：移除不再需要的兼容代码
+- `限制`：Vue3 不支持的能力（需标注替代方案）
+
+**维度 5 结论**：PASS（机制差异已标注且合理）
+
+---
+
+## 行为等价矩阵验证
+
+> 从 tasks.md 复制矩阵最终状态。矩阵有 ❌ 行则 FAIL。
+
+| # | 行为描述 | 维度 | RED 测试编码 | GREEN 实现 | 等价状态 |
+|:--|:---|:---|:---|:---|:---|
+| 1 | [行为] | [维度] | [文件:行号] | [文件:函数] | ✅/⚠️/❌ |
+
+**矩阵统计**：
+- ✅ 等价：X 项
+- ⚠️ 有意差异：Y 项（详见维度 5）
+- ❌ 缺失：Z 项（必须为 0）
+
+**矩阵结论**：PASS（无 ❌ 行）/ FAIL（存在 ❌ 行）
+
+---
+
+## 产物验证（migrate.check §C）
+
+> component：build 成功后逐项检查；logic/shared：仅 build exit 0。
+
+| # | 检查项 | 结果 | 证据 |
+|:--|:---|:---|:---|
+| 1 | package.json name/version 非空 | PASS/FAIL/N/A | |
+| 2 | nasl.extension.json 存在 | PASS/FAIL/N/A | |
+| 3 | {package}@{version}.zip 存在 | PASS/FAIL/N/A | |
+| 4 | viewComponents 含本资产组件名 | PASS/FAIL/N/A | |
+
+**§C 结论**：PASS / FAIL / N/A（logic/shared 为 N/A 除 build 外）
+
+---
+
+## 跨资产回归证据（migrate.check §D）
+
+| 命令 | 退出码 | 结果摘要 |
+|:---|:---|:---|
+| `npm run test`（全量） | | |
+| `npm run test:e2e`（全量，component 库） | | N/A |
+
+---
+
+## 测试运行证据（终端证据，必填）
+
+> **铁律**：每个 PASS 声明必须有终端执行证据。禁止「应该通过」「看起来正确」。
+
+| 命令 | 是否执行 | 退出码 | 结果摘要 |
+|:---|:---|:---|:---|
+| `npm run test` | 是 | 0 | vitest: N passed |
+| `npm run build` | 是 | 0 | 编译成功 |
+| `npm run test:e2e` | 是 | 0 | playwright: N passed |
+
+---
+
+## 总体结论
+
+| 维度 | 结论 |
+|:---|:---|
+| 行为等价矩阵 | PASS / FAIL |
+| 1. 对齐验证 | PASS / FAIL |
+| 2. API 覆盖矩阵 | PASS / FAIL |
+| 3. 平台合规扫描 | PASS / FAIL |
+| 4. Storybook 运行时 | PASS / FAIL |
+| 5. 机制差异标注 | PASS |
+| 产物验证 §C | PASS / FAIL / N/A |
+| 跨资产回归 §D | PASS / FAIL / N/A |
+
+**最终判定**：
+- **✅ PASS** — 矩阵无 ❌ + 五维度全部通过 + 三门禁 exit 0
+- **⚠️ CONDITIONAL PASS** — 通过但有已标注的机制差异（⚠️ 项）
+- **❌ FAIL** — 矩阵有 ❌ 行或维度未通过（禁止标记 verified）
+
+---
+
+## 待用户处理（仅 FAIL 时填写）
+
+- [未解决问题列表]
+- [建议操作]
+
+**经验沉淀**（可选）：如需将本次迁移经验写入 LEARNINGS，请用户主动执行「归因回流」。

package/packages/lcap-frontend-library/templates/migration-spec-template.md

@@ -0,0 +1,135 @@
+# [资产名] — Vue2 行为规格
+
+**提取时间**：[DATE]
+**源码路径**：[Vue2 源码目录路径]
+
+**资产类型**：component / logic / shared-composable（与 manifest 一致）
+
+- component：填写 Props/Events/Stories/Mixin/第三方 等节
+- logic：填写 @NaslLogic 元数据、参数、返回值、边界；Stories/api 节标 N/A
+- shared-composable：填写 Mixin 方法、副作用、调用契约；Stories/api 节标 N/A
+
+---
+
+## 概述
+
+| 项 | 内容 |
+|:---|:---|
+| **组件目录名** | [如 cw_audio_view] |
+| **组件标签** | [如 `<cw-audio-view>`] |
+| **中文名称** | [如 音频播放器] |
+| **核心职责** | [一句话描述] |
+| **第三方依赖** | [如 howler.js 2.x、moment.js] |
+| **Mixin 依赖** | [列出所有引用的 Mixin 文件名] |
+| **Stories 真值来源** | Vite 工程：`block.stories.js` / 旧工程：`docs/blocks.md` |
+
+---
+
+## Props
+
+| 属性名 | 类型（nasl.*） | 默认值（以 api.yaml 为准） | 是否双向绑定 | 验证规则 | 说明 |
+|:---|:---|:---|:---|:---|:---|
+| value | nasl.core.String | `''` | 是（update:value） | — | 音频 URL |
+
+---
+
+## Events
+
+| 事件名（on+PascalCase） | 参数签名 | 触发条件 |
+|:---|:---|:---|
+| onPlay | `{ currentTime: nasl.core.Decimal }` | 播放开始时 |
+
+---
+
+## Methods（defineExpose 暴露）
+
+| 方法名 | 参数 | 返回值 | 副作用描述 |
+|:---|:---|:---|:---|
+| reload | — | void | 重新加载音频源 |
+
+---
+
+## Slots
+
+| 插槽名 | 作用域变量 | 用途 |
+|:---|:---|:---|
+| slotDefault | — | 默认内容 |
+| slotItem | `:item` `:index`（Current<T>） | 列表项 |
+
+---
+
+## 响应式状态
+
+| 状态 | 来源（data/computed） | 依赖链 | 说明 |
+|:---|:---|:---|:---|
+| isPlaying | data → ref | — | 播放状态标识 |
+| duration | computed | value prop → howler.duration() | 总时长 |
+
+---
+
+## 生命周期行为
+
+| 生命周期 | 行为描述 |
+|:---|:---|
+| mounted | 初始化第三方实例（注意：是否在 ready 回调内） |
+| beforeDestroy | 销毁第三方实例、移除 DOM 监听 |
+| watch（哪些） | `value` → deep:false, immediate:true → 重新加载 |
+
+---
+
+## Mixin 调用点分析
+
+> 规则（→ §mixin-to-composable）：无调用不迁移。
+
+| Mixin 文件 | 方法/属性 | 本组件是否调用 | 调用位置 | 迁移目标 |
+|:---|:---|:---|:---|:---|
+| emitter.js | $emitPrevent | ✓ | methods.handleUpload | emitPrevent 工具函数 |
+| emitter.js | $on / $off | ✗ | — | 不迁移 |
+| support.js | formatDuration | ✓ | computed.displayTime | useAudio composable |
+
+---
+
+## 第三方集成
+
+| 库名 | 版本 | 初始化方式 | 配置项 | 销毁方式 |
+|:---|:---|:---|:---|:---|
+| howler.js | ^2.2.0 | `new Howl({...})` 在 ready 回调内 | src, volume, format | howl.unload() |
+
+---
+
+## 全局注册
+
+| 组件名（app.component 键） | 对应导出 | 来源 |
+|:---|:---|:---|
+| CwAudioView | `export { default as CwAudioView }` | src/components/index.ts |
+
+---
+
+## Block Stories 真值
+
+```javascript
+// 来源：[文件路径]
+export const Default = {
+  name: '默认',
+  render: () => ({ template: `<cw-audio-view value="..."></cw-audio-view>` })
+};
+```
+
+---
+
+## Example Stories 真值
+
+```javascript
+// 来源：[文件路径]
+// 每个 story 对应一个主要功能
+export const BasicPlayback = { ... };
+export const VolumeControl = { ... };
+```
+
+---
+
+## 注意事项
+
+- [从 Vue2 源码中发现的特殊行为、边界条件、已知 hack]
+- [CSS 属性选择器依赖的 prop（如 `[display="inline"]`）]
+- [Vue2 中未在 props 声明但通过 $attrs 透传的属性]

package/packages/lcap-frontend-library/templates/migration-tasks-template.md

@@ -0,0 +1,129 @@
+# [资产名] — TDD 执行编排
+
+**Date**：[YYYY-MM-DD]
+**Input**：`specs/<NN>-<资产名>/plan.md`（迁移方案）
+**资产类型**：component / logic / shared-composable
+**复杂度**：HIGH / MEDIUM / LOW
+
+---
+
+## 行为等价矩阵
+
+> 每行 = spec.md 中一个可测试行为。矩阵是迁移完成度的唯一判定依据。
+> - **RED 测试编码**列：由 migrate.red 填充（测试文件路径 + 行号）
+> - **GREEN 实现**列：由 migrate.green 填充（实现文件路径 + 函数名）
+> - **等价状态**列：由 migrate.check 填充（最终验证）
+
+| # | 行为描述（来自 spec.md） | 维度 | RED 测试编码 | GREEN 实现 | 等价状态 |
+|:--|:---|:---|:---|:---|:---|
+| 1 | [如：Props.value 接收 URL 并渲染] | Props | — | — | — |
+| 2 | [如：Events.onPlay 在播放开始时触发] | Events | — | — | — |
+| 3 | [如：Methods.reload 重新加载音频源] | Methods | — | — | — |
+| 4 | [如：Slots.slotItem 传递 :item :index] | Slots | — | — | — |
+| 5 | [如：响应式状态 isPlaying 跟踪播放] | State | — | — | — |
+| 6 | [如：mounted 时初始化 Howl 实例] | Lifecycle | — | — | — |
+| 7 | [如：beforeDestroy 时销毁实例] | Lifecycle | — | — | — |
+
+**等价状态值**：
+- ✅ 等价 — 测试通过，实现与 spec 行为一致
+- ⚠️ 有意差异 — Vue3 框架限制导致（须记录原因，归入 report 维度 5）
+- ❌ 缺失 — 无测试 / 测试未通过 / 实现遗漏（必须修复）
+- `—` — 尚未填充
+
+<!-- logic 资产示例行 -->
+<!-- | 1 | 参数 date 接受 nasl.core.DateTime | Params | — | — | — | -->
+<!-- | 2 | 返回值格式 YYYY-MM-DD | Return | — | — | — | -->
+<!-- shared-composable 示例行 -->
+<!-- | 1 | emitPrevent 返回 cancel 布尔 | Methods | — | — | — | -->
+
+---
+
+## Phase RED 任务组
+
+> 目标：将 spec.md 行为编码为测试。完成后所有测试 FAIL（证明测试有意义）。
+
+### Vitest 单元/交互测试
+
+| 序号 | 任务 | 对应矩阵行 | 测试层 | 状态 |
+|:--|:---|:---|:---|:---|
+| R1 | Props 响应性测试（默认值 + 类型 + 双向绑定） | #1 | Vitest(DOM) | [ ] |
+| R2 | Events 触发测试（参数 + 触发条件） | #2 | Vitest(emit) | [ ] |
+| R3 | Methods expose 测试（调用 + 返回值） | #3 | Vitest(返回值) | [ ] |
+| R4 | Slots 渲染测试（作用域变量传递） | #4 | Vitest(DOM) | [ ] |
+| R5 | 响应式状态测试（computed/watch 链路） | #5 | Vitest(返回值) | [ ] |
+| R6 | 生命周期行为测试（初始化/销毁） | #6, #7 | Vitest(调用参数) | [ ] |
+
+### E2E 测试
+
+| 序号 | 任务 | 对应矩阵行 | Story ID | 状态 |
+|:--|:---|:---|:---|:---|
+| RE1 | 基础渲染 + 零 console error | 全部 | `<name>--default` | [ ] |
+| RE2 | [主要交互功能] | #2 | `<name>--<story>` | [ ] |
+
+### RED 完成标准
+
+- [ ] `npm run test` exit ≠ 0（测试存在且 FAIL）
+- [ ] 矩阵"RED 测试编码"列无空行
+- [ ] 每个 describe/it 可追溯到矩阵行号
+
+---
+
+## Phase GREEN 任务组
+
+> 目标：实现代码让测试从 FAIL 收敛到 PASS。禁止修改测试。
+
+### 实现步骤
+
+> **资产类型分支**：component → G1 使用 `create-component-files.sh`；logic → `create-logic-files.sh`；shared-composable → 按 plan 路径 Edit 创建（无 scaffold）。
+
+| 序号 | 任务 | 产出文件（plan.md 路径表） | 验收 | 状态 |
+|:--|:---|:---|:---|:---|
+| G1 | 创建组件骨架 | `create-component-files.sh` | 文件存在 | [ ] |
+| G2 | 编写 api.ts | `src/components/<name>/api.ts` | 类型正确 | [ ] |
+| G3 | 编写 ideusage.json | `src/components/<name>/ideusage.json` | 与 api.ts 一致 | [ ] |
+| G4 | 迁移模板 + 逻辑 | `src/components/<name>/index.vue` + composables | — | [ ] |
+| G5 | 编写 block.stories | `src/components/<name>/stories/block.stories.js` | 1:1 静态 | [ ] |
+| G6 | 编写 example.stories | `src/components/<name>/stories/example.stories.js` | 功能 demo | [ ] |
+| G7 | CSS/主题适配 | scoped style | 无硬编码 | [ ] |
+| G8 | 桶文件导出 | `src/components/<name>/index.ts` | 具名导出 | [ ] |
+| G9 | 迭代修复至测试全过 | — | `npm run test` exit 0 | [ ] |
+
+### GREEN 完成标准
+
+- [ ] `npm run test` exit 0
+- [ ] 矩阵"GREEN 实现"列已填充
+- [ ] 无修改测试文件的 git diff
+
+---
+
+## Phase CHECK 执行清单（由 migrate.check 执行，非独立命令）
+
+> migrate.check = 等价审计 + 产物验证。本节供 tasks 内追溯，不在 RED/GREEN 阶段执行。
+
+| 序号 | 验证项 | component | logic | shared-composable |
+|:--|:---|:---|:---|:---|
+| V1 | 单测门禁 | `npm run test` exit 0 | 同左 | 同左 |
+| V2 | 构建门禁 | `npm run build` exit 0 | 同左 | 同左 |
+| V3 | E2E 门禁 | `npm run test:e2e` exit 0 | N/A | N/A |
+| V4 | 行为等价矩阵 | 无 ❌ 行 | 同左 | 同左 |
+| V5 | 等价审计维 | 五维（对齐/API/合规/Storybook/机制差异） | 三维 L1–L3（→ migrate.check） | 三维 S1–S3 |
+| V6 | 产物验证 | 4 项清单（→ migrate.check §C） | build only | build only |
+| V7 | 跨资产回归 | 全量 test + e2e | 全量 test | 全量 test |
+
+---
+
+## 复杂度自适应说明
+
+根据 plan.md 复杂度评估调整粒度：
+
+- **LOW**：R1-R6 可合并为 2-3 个任务；G4 一步到位
+- **MEDIUM**：按上表标准粒度执行
+- **HIGH**：R 和 G 任务进一步拆分（如 Mixin 多时按 composable 拆）
+
+---
+
+## 断路器记录（如触发）
+
+| 触发时间 | 错误模式 | 已尝试方案 | 决策 |
+|:---|:---|:---|:---|
+| — | — | — | — |