lcap-frontend-library 0.0.1

package/packages/lcap-frontend-library/scripts/bash/list-specs.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# 列出当前项目下的规范需求目录（Spec Driven Development）
+# 用法: .specify/scripts/bash/list-specs.sh
+
+current_dir=$(pwd)
+specs_dir="${SPECS_DIR:-$current_dir/specs}"
+
+if [ ! -d "$specs_dir" ]; then
+  echo "规范需求根目录不存在: $specs_dir"
+  echo "可通过环境变量 SPECS_DIR 指定，或先运行 create-spec.sh 创建首个需求目录。"
+  exit 0
+fi
+
+echo "规范需求目录: $specs_dir"
+echo "---"
+for dir in "$specs_dir"/*; do
+  [ -d "$dir" ] || continue
+  echo "  $(basename "$dir")"
+done

package/packages/lcap-frontend-library/scripts/node/setup-extension-project.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * 扩展依赖库工程初始化：合并 package.json（keywords、Vitest、Playwright devDeps）、
+ * 写入 playwright.config.ts、scripts/get-available-port.sh、e2e 目录、合并 .gitignore（Playwright 产物）、注入 Vitest exclude 配置。
+ * 用法: node setup-extension-project.mjs <项目根目录>
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const projectDir = process.argv[2];
+if (!projectDir) {
+  console.error('用法: node setup-extension-project.mjs <项目根目录>');
+  process.exit(1);
+}
+
+function detectFramework(projectDirPath, pkg) {
+  const keywords = (pkg.keywords || []).map((k) => String(k).toLowerCase());
+  if (keywords.includes('react')) return 'react';
+  if (keywords.includes('vue3')) return 'vue3';
+  if (keywords.includes('vue')) return 'vue2';
+
+  for (const name of ['vite.config.mjs', 'vite.config.js']) {
+    const vitePath = join(projectDirPath, name);
+    if (!existsSync(vitePath)) continue;
+    const content = readFileSync(vitePath, 'utf8');
+    if (content.includes("framework: 'react'")) return 'react';
+    if (content.includes("framework: 'vue3'")) return 'vue3';
+    if (content.includes("framework: 'vue2'")) return 'vue2';
+  }
+  return 'vue3';
+}
+
+// ─── 1. package.json ───────────────────────────────────────────────────────────
+const pkgPath = join(projectDir, 'package.json');
+const raw = readFileSync(pkgPath, 'utf8');
+const pkg = JSON.parse(raw);
+const framework = detectFramework(projectDir, pkg);
+
+if (!Array.isArray(pkg.keywords)) pkg.keywords = [];
+if (!pkg.keywords.includes('AIGC')) pkg.keywords.push('AIGC');
+
+pkg.scripts = pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+pkg.scripts.test = 'vitest run --silent';
+pkg.scripts['test:e2e'] =
+  "HTTP_PROXY='' http_proxy='' HTTPS_PROXY='' https_proxy='' E2E_PORT=$(bash scripts/get-available-port.sh) playwright test";
+
+pkg.devDependencies =
+  pkg.devDependencies && typeof pkg.devDependencies === 'object' ? pkg.devDependencies : {};
+
+const ADD_DEV_DEPENDENCIES = {
+  '@playwright/test': '^1.58.2',
+  jsdom: '^29.0.0',
+};
+
+if (framework === 'vue3') {
+  ADD_DEV_DEPENDENCIES['@vue/test-utils'] = '^2.4.6';
+} else if (framework === 'vue2') {
+  if (!pkg.devDependencies['@vue/test-utils']) {
+    ADD_DEV_DEPENDENCIES['@vue/test-utils'] = '^1.3.5';
+  }
+}
+
+Object.entries(ADD_DEV_DEPENDENCIES).forEach(([name, version]) => {
+  if (!pkg.devDependencies[name]) {
+    pkg.devDependencies[name] = version;
+  }
+});
+
+writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+
+// ─── 2. scripts/get-available-port.sh（从 skill 源文件复制到项目内）────────────
+const scriptsDir = join(projectDir, 'scripts');
+if (!existsSync(scriptsDir)) mkdirSync(scriptsDir, { recursive: true });
+
+const portScriptSrc = join(__dirname, '..', 'bash', 'get-available-port.sh');
+const portScriptDest = join(scriptsDir, 'get-available-port.sh');
+writeFileSync(portScriptDest, readFileSync(portScriptSrc, 'utf8'));
+chmodSync(portScriptDest, 0o755);
+
+// ─── 3. playwright.config.ts ───────────────────────────────────────────────────
+const playwrightConfig = `import { defineConfig, devices } from '@playwright/test';
+
+const port = parseInt(process.env.E2E_PORT || '60000', 10);
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  use: { baseURL: \`http://localhost:\${port}\` },
+  webServer: {
+    command: \`npm run start -- -p \${port}\`,
+    url: \`http://localhost:\${port}\`,
+    reuseExistingServer: !process.env.CI,
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+        // channel: 'chrome', // TODO: 配置为系统已安装的浏览器 channel（chrome / msedge 等）
+      },
+    },
+  ],
+});
+`;
+
+writeFileSync(join(projectDir, 'playwright.config.ts'), playwrightConfig);
+
+// ─── 4. .gitignore（追加 Playwright 产物忽略规则）──────────────────────────────
+const gitignorePath = join(projectDir, '.gitignore');
+let gitignoreContent = '';
+if (existsSync(gitignorePath)) {
+  gitignoreContent = readFileSync(gitignorePath, 'utf8');
+}
+const gitignoreLinesToAdd = [];
+if (!gitignoreContent.includes('playwright-report')) gitignoreLinesToAdd.push('playwright-report');
+if (!gitignoreContent.includes('test-results')) gitignoreLinesToAdd.push('test-results');
+if (gitignoreLinesToAdd.length > 0) {
+  const prefix =
+    gitignoreContent === '' ? '' : gitignoreContent.endsWith('\n') ? '\n' : '\n\n';
+  const header = gitignoreContent.includes('# Playwright') ? '' : '# Playwright\n';
+  writeFileSync(
+    gitignorePath,
+    gitignoreContent + prefix + header + gitignoreLinesToAdd.join('\n') + '\n',
+  );
+}
+
+// ─── 5. e2e/ 目录（Playwright 测试文件存放位置）───────────────────────────────
+const e2eDir = join(projectDir, 'e2e');
+if (!existsSync(e2eDir)) mkdirSync(e2eDir, { recursive: true });
+
+const gitkeep = join(e2eDir, '.gitkeep');
+if (!existsSync(gitkeep)) writeFileSync(gitkeep, '');
+
+// ─── 6. vite.config: 注入 Vitest exclude 配置 ───────────────────────────
+function injectVitestExclude(viteConfigPath) {
+  if (!existsSync(viteConfigPath)) return;
+  let viteConfig = readFileSync(viteConfigPath, 'utf8');
+  if (viteConfig.includes('exclude:')) return;
+  const replaced = viteConfig.replace(
+    /test:\s*\{[\s\S]*?environment:\s*'jsdom',?\s*\}/,
+    `test: {\n      environment: 'jsdom',\n      exclude: ['**/node_modules/**', '**/e2e/**', '**/dist-theme/**'],\n    }`,
+  );
+  if (replaced !== viteConfig) {
+    writeFileSync(viteConfigPath, replaced);
+  }
+}
+
+injectVitestExclude(join(projectDir, 'vite.config.mjs'));
+injectVitestExclude(join(projectDir, 'vite.config.js'));
+
+const frameworkNote =
+  framework === 'vue2'
+    ? '（vue2：Storybook7 + vite-plugin-vue2；e2e 配置已注入，与 vue3 行为一致）'
+    : framework === 'react'
+      ? '（react 依赖库暂不在本 skill 脚手架支持范围内）'
+      : '（vue3：默认模板）';
+
+console.log(
+  `✅ [${framework}] 已写入 playwright.config.ts、scripts/get-available-port.sh、e2e/、.gitignore，并更新 package.json。${frameworkNote}`,
+);

package/packages/lcap-frontend-library/templates/component-self-check.md

@@ -0,0 +1,31 @@
+# 组件提交前自检表
+
+提交代码前请对照本清单逐项勾选，确保无遗漏。可与 plan.md 的「验收检查清单」及「鲁棒性检查」一并使用。
+
+## 数据与状态
+
+- [ ] 是否处理了**空数据 / 空 URL** 的情况？（如 `fileUrl`、`data`、`options` 为空或未传时的展示与不报错）
+- [ ] 是否处理了**网络请求失败**或**加载失败**的情况？（有 Error 状态与用户可感知的提示，不白屏不静默）
+- [ ] 异步加载组件是否具备 **Loading / Error / Empty** 的完整状态与 UI？
+
+## 布局与交互
+
+- [ ] **缩放、翻页、Resize** 等交互在不同容器宽度下是否均正常？（小容器不大面积错位，大容器不溢出或已按 spec 约定处理）
+- [ ] 带工具栏的容器是否已按约定设置默认位置（建议顶部，除非 spec 另有要求）？
+
+## 样式与主题
+
+- [ ] 样式是否**完全使用** LCAP/平台提供的 **CSS 变量**（见 theme-variables-*.md），无写死颜色/间距？
+- [ ] 是否会被外部 CSS（如父级 `max-width`、`overflow`）意外破坏？根节点透传是否正常？
+- [ ] 组件是否使用 `<style scoped>` 或 `<style module>`？是否存在裸 `<style>` 污染全局？（见 workflow-guardrails 规则 9）
+- [ ] 内联 `:style` 是否仅用于运行时动态计算的值（如 Canvas backgroundImage、prop 计算宽高）？
+
+## 测试与验收
+
+- [ ] 单测中 Mock 的三方组件事件是否与真实行为一致（经实测或文档确认）？
+- [ ] E2E 是否存在被注释掉或**规避**的失败用例？若有 Timeout 是否已排查并修复？
+- [ ] `npm run test`、`npm run test:e2e` 与 `npm run build` 是否**均已通过**？
+
+---
+
+> 可选：实现阶段可在 tasks 或自检验收时引用本表（`templates/component-self-check.md`）进行最后一轮勾选。

package/packages/lcap-frontend-library/templates/component-template.md

@@ -0,0 +1,96 @@
+# [组件中文名称]（[组件英文名称]）
+
+<!--
+  [MANDATORY CHECK] 若为复杂展示/容器类组件（如 PDF、图表、富文本、强依赖容器尺寸）：
+  1. 「视觉与交互契约」为必填，不得留空或写「不适用」。
+  2. 必须明确：初始状态、响应式行为、溢出规则、Resize 行为、可观测 DOM 状态。
+  3. 即使用户输入为「完整需求」，若缺失上述契约，也必须补全后再写入 spec。
+-->
+
+- **生成时间**：[DATE]
+
+## 概述
+
+* 组件名称：[组件英文名称]（[组件标签: 例如 `<qr-code>`]）
+* 技术栈：Vue3
+* 核心职责：[组件核心职责]
+* 适用场景：[典型使用场景描述]
+* 依赖：[依赖成熟三方npm 仓库，及其使用描述]
+
+## 功能
+
+### 1.[功能名称]
+
+#### 描述
+
+[功能描述]
+
+#### 验收标准
+
+- [ ] [验收条件1]
+- [ ] [验收条件2]
+
+#### 接口设计
+
+[相关属性|事件|插槽设计]
+
+#### 使用示例
+
+[使用代码示例]
+
+## 视觉与交互契约
+
+<!-- 复杂展示/容器类组件必填；简单原子组件可简述「不适用」。生成 spec 时必须逐项填充，不得整体留空。 -->
+
+### 视觉表现 (Visual Contract)
+
+- **初始状态**：[描述未加载/加载中/空数据时的视觉，以及用户“第一眼”看到的比例与布局，如：占满容器、固定宽高比]
+- **响应式行为**：[描述容器尺寸变化时的适配策略，如：容器驱动/内容驱动、等比例缩放、重绘、滚动条出现]
+- **溢出规则**：[描述内容超出时的处理，如：组件内滚动/容器外滚动/裁剪/自动缩放]
+
+### 交互副作用 (Interaction Side-effects)
+
+- **Resize 行为**：[描述窗口或容器 Resize 时的逻辑，如：重绘/防抖/节流/触发库 API 更新]
+- **可观测 DOM 状态**：[描述验收时可检查的 DOM 特征，如：某元素存在、clientWidth 随 scale 变化、特定 class 切换；供测试与验收标准引用]
+- **其他副作用**：[描述操作对周边或父容器的影响，如：缩放导致布局重排、弹窗对页面滚动的影响；无则填「无」]
+
+## 接口定义 (属性 & 事件 & 方法 & 插槽)
+
+### 属性
+
+<!-- 支持双向绑定的属性：组件内部变更时需通过事件回写父组件，便于 v-model / 设计器绑定 -->
+
+| 属性名称 | 描述 | 类型 | 可选值 | 默认值 | 是否双向绑定 |
+|:---|:---|:---|:---|:---|:---|
+
+### 事件
+
+<!-- 特别注意: 事件参数仅允许有一个 event 参数 -->
+
+| 事件名称 | 描述 | 回调参数 | 参数类型 |
+|:---|:---|:---|:---|
+
+### 方法
+
+<!-- 如果有则生成对应的api -->
+
+| 方法名称 | 描述 | 参数 | 返回值 |
+|:---|:---|:---|:---|
+
+### 插槽
+
+| 插槽名称 | 描述 | 参数 |
+|:---|:---|:---|
+
+## 样式定制
+
+<!-- 如果组件支持主题/样式定制，列出相关 CSS 变量 -->
+
+| CSS 变量 | 描述 | 默认值 |
+|:---|:---|:---|
+
+## 注意事项
+
+<!-- 使用限制、边界条件、已知问题等 -->
+
+* [注意事项1]

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

@@ -0,0 +1,52 @@
+# [库名] — 库级迁移验证报告
+
+**验证时间**：[ISO 8601]
+**library_status**：🏁 library-verified / ❌ FAIL
+**触发方式**：自动（末资产 verified）/ 显式 `--finalize-library`
+
+---
+
+## 资产统计
+
+| 类型 | 总数 | ✅ verified | 🚫 blocked |
+|------|------|-------------|------------|
+| component | | | |
+| logic | | | |
+| shared-composable | | | |
+
+---
+
+## 三门禁证据（库级）
+
+| 命令 | 退出码 | 结果摘要 |
+|:---|:---|:---|
+| `npm run test` | | |
+| `npm run build` | | |
+| `npm run test:e2e` | | N/A 若无可 E2E 组件 |
+
+---
+
+## 产物验证（4 项，与 create BUILD-VERIFY 一致）
+
+| # | 检查项 | 结果 | 证据 |
+|:--|:---|:---|:---|
+| 1 | package.json name/version | | |
+| 2 | nasl.extension.json 存在 | | |
+| 3 | ZIP 产物存在 | | |
+| 4 | viewComponents 全量非空 | | |
+
+---
+
+## 阻塞资产
+
+| 资产名 | 状态 | 原因 |
+|:---|:---|:---|
+| — | — | 无 |
+
+---
+
+## 总体结论
+
+**PASS** / **CONDITIONAL PASS** / **FAIL**
+
+**说明**：[如有 CONDITIONAL PASS，列出 ⚠️ 机制差异引用各资产 report.md]

package/packages/lcap-frontend-library/templates/logic-template.md

@@ -0,0 +1,44 @@
+# [逻辑中文标题]（[函数名 snake_case]）
+
+- **生成时间**：[DATE]
+- **绑定端**：pc / h5 / both
+
+## 概述
+
+* 函数名：[functionName]
+* 核心职责：[描述]
+* 依赖：[nasl 类型 / 第三方]
+
+## 功能
+
+### 1. [功能名称]
+
+#### 描述
+
+[功能描述]
+
+#### 验收标准
+
+- [ ] [验收条件1]
+- [ ] [验收条件2]
+
+#### 接口设计
+
+| 参数 | nasl 类型 | 说明 |
+|------|-----------|------|
+| … | … | … |
+
+| 返回值 | nasl 类型 | 说明 |
+|--------|-----------|------|
+| … | … | … |
+
+#### 使用示例
+
+```typescript
+// TS 调用示例
+```
+
+## 注意事项
+
+- 须 `import '@nasl/types'`
+- 须 `@NaslLogic` JSDoc

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

@@ -0,0 +1,84 @@
+# [库名] 迁移清单
+
+> 资产级状态追踪。每个命令执行时自动更新对应行。
+> 详细报告 → 各资产 `specs/<NN>-<资产名>/report.md`。
+
+**源码库**：[Vue2 源码路径]
+**目标工程**：[Vue3 工程路径]
+**最后更新**：[DATE]
+
+---
+
+## 迁移进度
+
+总资产: N | ✅ 完成: X | 🔨 进行中: Y | ⏳ 待开始: Z | 🚫 阻塞: W
+进度: [████████░░] X/N (XX%)
+
+---
+
+## 库级状态
+
+| 字段 | 值 |
+|------|-----|
+| library_status | ⏳ in-progress |
+| library_verified_at | — |
+| 末次库级三门禁 | — |
+
+---
+
+## 资产状态表
+
+| # | 资产名 | 类型 | 复杂度 | 推荐序号 | depends_on | 状态 | Stories 来源 | Mixin 依赖 |
+|:--|:---|:---|:---|:---|:---|:---|:---|:---|
+| 01 | [资产名] | component / logic / shared-composable | HIGH/MED/LOW | 1 | — | ⏳ pending | block.stories.js | [列表] |
+
+---
+
+## 状态流转
+
+| 状态 | 含义 | 由哪个命令设置 |
+|:---|:---|:---|
+| ⏳ pending | 已识别，未开始 | migrate.scan |
+| 🔍 spec-done | 行为真值已提取 | migrate.spec |
+| 🔄 planned | 迁移方案已制定 | migrate.plan |
+| 📋 tasks-ready | TDD 编排已完成 | migrate.tasks |
+| 🔴 red-in-progress | RED 阶段进行中 | migrate.red |
+| 🔴 red-done | 测试已编码（全 FAIL） | migrate.red |
+| 🟢 green-in-progress | GREEN 阶段进行中 | migrate.green |
+| 🟢 green-done | 实现完成（测试全 PASS） | migrate.green |
+| ✅ verified | 等价性验证通过 | migrate.check |
+| 🚫 blocked | 阻塞（需用户介入） | 断路器触发 |
+
+---
+
+## 推荐迁移顺序
+
+> 由 migrate.scan 计算：shared-composable → logic → component（depends_on 拓扑序）。
+
+1. [资产名]（类型，推荐序号 1）
+2. ...
+
+---
+
+## 共享依赖
+
+### Mixin 全量清单
+
+| Mixin 文件 | 方法数 | 被引用次数 | 引用组件 |
+|:---|:---|:---|:---|
+| [mixin.js] | N | M | [组件1, 组件2] |
+
+### 第三方依赖
+
+| 库名 | 版本 | 引用组件 |
+|:---|:---|:---|
+| [lib] | ^x.y.z | [组件列表] |
+
+---
+
+## 更新规则
+
+- 仅改本表对应行的状态列
+- 状态变更由各 migrate 命令自动驱动
+- 🚫 blocked 时须在对应资产 report.md 中记录详情
+- 禁止手动跳跃状态（必须按流转顺序）

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

@@ -0,0 +1,138 @@
+# [资产名] — 迁移方案
+
+**Date**：[YYYY-MM-DD]
+**Input**：`specs/<NN>-<资产名>/spec.md`（行为真值）
+
+---
+
+## 摘要
+
+[3～5 句话概括：迁移对象、核心复杂点、主要技术路线（Mixin 拆分策略、第三方处理、样式方案）。]
+
+**资产类型**：component / logic / shared-composable
+
+---
+
+## 转换策略表
+
+> 每项必须引用 KB 章节名（§mixin-composable、§vue3-children-clone、§pitfalls 等）。规则以 knowledge-base 为准，不得凭 AI 记忆。
+
+| Vue2 模式 / 决策点 | Vue3 目标 | KB 章节 | 备注 |
+|:---|:---|:---|:---|
+| （按 spec 与 KB 填写） | | | |
+
+**logic 资产**：以下节标 **N/A** — api.ts、ideusage、Stories、CSS 变量、Storybook。
+**shared-composable**：以下节标 **N/A** — api.ts、ideusage、Stories。
+
+### Mixin → Composable 映射（→ §mixin-composable）
+
+| Mixin 文件 | 方法/属性 | 有调用点 | Composable 目标 | 拆分理由 |
+|:---|:---|:---|:---|:---|
+| [mixin.js] | [method] | ✓/✗ | useXxx.ts / 不迁移 | [业务边界说明] |
+
+**规则确认**：
+- [ ] 全量方法已列出，无调用点的标记「不迁移」
+- [ ] 按业务边界拆分，非按生命周期
+- [ ] defineExpose 仅暴露原版已有 methods
+- [ ] 副作用配套 onUnmounted 销毁
+
+### 样式转换（→ §css-vars + theme-variables-element-plus.md）
+
+| 原始变量/硬编码值 | Element Plus 目标变量 | 验证状态 |
+|:---|:---|:---|
+| --cursor-pointer | `pointer`（直接值） | ✓ 存在于文档 |
+| #409eff | `var(--el-color-primary)` | ✓ 存在于文档 |
+| 14px (font-size) | `var(--el-font-size-base)` | ✓ 存在于文档 |
+
+**样式隔离**：`<style scoped>`（→ workflow-guardrails 规则 9）
+
+### 第三方库处理
+
+| 库名 | Vue2 初始化方式 | Vue3 初始化方式 | 注意事项 |
+|:---|:---|:---|:---|
+| [库名] | [如 mounted 内 new Xxx()] | [如 onXxxReady 回调内] | [→ §pitfalls: 第三方 init 时机] |
+
+---
+
+## 风险与陷阱（→ KB §pitfalls 逐条核对）
+
+| # | 陷阱摘要（来自 §pitfalls） | 是否命中 | 预防/处理 |
+|:--|:---|:---|:---|
+| 1 | | ✓/✗ | |
+| … | （与 §pitfalls 叙事条数一致，plan 阶段逐条填写） | | |
+
+**预估复杂度**：HIGH / MEDIUM / LOW
+**主要复杂点**：[列出 1-3 个最关键的难点]
+
+---
+
+## 资产类型说明
+
+| 类型 | 本模板使用的节 |
+|------|----------------|
+| component | 全文（含 ideusage、stories、css-vars） |
+| logic | 跳过 ideusage、stories、css-vars、E2E；使用 logic 文件表 |
+| shared-composable | 跳过 api.ts、ideusage、stories、css-vars、E2E；仅 composable + 测试 |
+
+### logic 文件路径表（类型=logic 时使用）
+
+| 模块 | 产出路径 | 测试层 |
+|------|----------|--------|
+| 逻辑函数 | `src/logics/<name>.ts` | Vitest(返回值) |
+| 导出 | `src/logics/index.ts` | — |
+| 单测 | `src/logics/__tests__/<name>.spec.ts` | — |
+
+### shared-composable 文件路径表（类型=shared-composable 时使用）
+
+| 模块 | 产出路径 | 测试层 |
+|------|----------|--------|
+| Composable | `src/composables/use<Xxx>.ts` | Vitest(返回值) |
+| 单测 | `src/composables/__tests__/use<Xxx>.spec.ts` | — |
+
+---
+
+## 文件路径规划表（路径锁定）
+
+> 路径为**相对扩展工程根目录**的完整路径，禁止模糊表述。
+
+| 模块 | 职责 | 产出路径 | 测试层 | 操作 |
+|:---|:---|:---|:---|:---|
+| api.ts | NASL 接口声明 | `src/components/<name>/api.ts` | — | 新增 |
+| ideusage.json | IDE 设计器配置 | `src/components/<name>/ideusage.json` | — | 新增 |
+| index.vue | UI 组装 + 模板 | `src/components/<name>/index.vue` | Vitest(DOM) + E2E | 新增 |
+| useXxx.ts | [业务逻辑描述] | `src/components/<name>/composables/useXxx.ts` | Vitest(返回值) | 新增 |
+| index.ts | 桶文件导出 | `src/components/<name>/index.ts` | — | 新增 |
+| block.stories | 画布拖拽 story | `src/components/<name>/stories/block.stories.js` | — | 新增 |
+| example.stories | 功能 demo | `src/components/<name>/stories/example.stories.js` | — | 新增 |
+| 单测 | Vitest | `src/components/<name>/__tests__/index.spec.ts` | — | 新增 |
+| E2E | Playwright | `e2e/<name>.spec.ts` | — | 新增 |
+
+**测试层说明**（→ workflow-guardrails §8）：
+- `Vitest(返回值)` — 纯逻辑，直接断言返回
+- `Vitest(调用参数)` — 调用浏览器 API，仅 mock 验证调用参数
+- `Vitest(DOM) + E2E` — DOM 操作，Vitest 验证结构，E2E 验证渲染
+
+---
+
+## 复杂度评估
+
+| 维度 | 评估 | 说明 |
+|:---|:---|:---|
+| Mixin 数量 | N | [列出] |
+| Props 数量 | N | — |
+| 第三方库 | N | [列出] |
+| **综合复杂度** | HIGH/MEDIUM/LOW | — |
+
+---
+
+## 用户审批门禁
+
+⛔ **以上方案需用户确认后方可进入 migrate.tasks。**
+
+**确认要点**：
+- [ ] 转换策略是否合理（每项有 §id 引用）
+- [ ] 文件路径规划是否正确
+- [ ] 已识别风险是否已有应对
+- [ ] 复杂度评估是否准确
+
+**隐式审批**：用户回复含 tasks/继续/开始/OK → 视为通过。