lcap-frontend-library 0.0.1

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

@@ -0,0 +1,299 @@
+# [组件名称] - 实现计划
+
+**Date**：`[YYYY-MM-DD]`  
+**Input**：`specs/[###-组件短名]/spec.md`（路径以实际规范目录为准）
+
+---
+
+## 摘要
+
+[用 3～6 句话概括：要解决什么问题、主要技术路线（依赖与栈）、与 spec「概述」一致。]
+
+---
+
+## 技术上下文
+
+> 与下文「目标与范围」「技术架构方案」**互填**，避免同一事实两处矛盾。
+
+| 键 | 内容 |
+|:---|:---|
+| **语言 / 技术栈** | [Vue2 / Vue3 / React，与「组件信息」一致] |
+| **主要依赖** | [见「建议依赖」；无则写 N/A] |
+| **测试** | 栈与目录约定见 **§五 · 测试约定**；执行级细则见 `commands/speckit.plan.md` 与 SKILL.md |
+| **目标平台** | [浏览器 / 设计器；与 spec 一致] |
+| **存储** | 无（纯前端组件） |
+| **性能 / 约束** | [首屏、大数据量、Canvas 等；与 spec 非功能需求对应；无则 N/A] |
+| **范围** | [与「MVP 约定」一致，一句话] |
+
+---
+
+## 规范门禁
+
+*计划定稿或评审前自查；与 `implementation-rules.md` 及 SKILL 对齐。与 **§六** 主题相近：本节为「计划能否定稿」，§六为「实现能否提交」。*
+
+- [ ] 接口与 spec 一致，类型均为 NASL，无滥用 `Object` / `any`（验收时对照 **§二**）
+- [ ] **idetype** 与 **Slots** 与 **§一 · LCAP 必要产出** 一致（规则仅以该段为准）
+- [ ] **样式与主题**：**§三** 已在计划阶段填表，不推迟到实现再定
+- [ ] **测试**：实现顺序含 **§五** 所列层级（单测、example.stories、e2e；工程已配置 `test:e2e` 时）；失败修复后再勾选
+- [ ] **功能内聚**：spec 交互已在 **§一 · 内置 UI 控件清单** 落实；与 **§二 · Methods** 边界一致，未默认推给插槽或仅 Method
+- [ ] **模块化**：已填「文件路径与模块化规划」表；主文件过长时已有 composables/hooks 抽离路径
+
+---
+
+## 文档与源码产出
+
+### 规范侧（`specs/`，相对仓库或沙箱根）
+
+```text
+specs/[###-组件短名]/
+├── spec.md              # 需求与接口来源
+├── plan.md              # 本文件（/speckit.plan 输出）
+└── tasks.md             # /speckit.tasks 输出（非本命令生成）
+```
+
+### 源码侧（扩展工程根目录，路径以实际脚手架为准；计划阶段须将 `[组件目录]` 等写死为真实路径）
+
+**结构约束**：**勿将整块业务与算法堆在 `index.vue`（或 `index.tsx`）**。入口文件以模板组装、事件转发、与子模块组合为主；可复用计算、数据变换、与三方库交互等应拆入 `utils/`、`composables/` 或子组件（本模板未列子组件目录时可在计划中补充路径），避免单文件过长、难以测试与维护。
+
+```text
+<扩展工程根>/
+├── src/components/[组件目录 kebab-case]/
+│   ├── api.ts                       # NASL、@ExtensionComponent、ideusage
+│   ├── utils/                       # Vue3：公用纯函数、与展示无关的工具（.ts）
+│   ├── composables/                 # 可选：useXxx（.ts）；从 index 抽离的响应式/侦听/生命周期/ref 编排，勿堆在单文件；纯函数放 utils
+│   ├── stories/
+│   │   ├── block.stories.{js|tsx|jsx}   # 画布拖拽初始（单 story）
+│   │   └── example.stories.{js|tsx|jsx}  # 功能 demo：本地调试与 e2e
+│   ├── __tests__/
+│   │   └── *.spec.ts                # Vitest 单元/交互测试
+│   └── index.vue                    # 或 index.tsx：入口与视图编排；**非**所有逻辑的实现处
+├── e2e/                             # Playwright → 组件目录下 example.stories
+└── playwright.config.ts             # create-extension-project / setup-extension-project 初始化后通常已有
+```
+
+上表为**通用目录约定**；下方「文件路径与模块化规划」须填**本组件实例**的确定路径，二者配合使用，勿只写其一。
+
+### 文件路径与模块化规划（必填）
+
+> 路径均为 **相对扩展工程根目录** 的完整路径，与上表「组件目录」一致；**禁止**模糊表述。简单组件可仅一行 View；复杂组件须拆行列出 composables/utils 等。
+> **模式 C（增量修改）**：仅列本次变更涉及的文件，"操作"列标注 `新增` 或 `修改`。
+
+| 模块名称 | 职责描述 | 抽离方式 | 产出路径（相对扩展工程根） | 测试层 | 操作 |
+|:---|:---|:---|:---|:---|:---|
+| **View 层** | 模板结构、内置工具栏/操作区、样式与组装 | `index.vue` | `src/components/[组件目录 kebab]/index.vue` | Vitest(结构) + E2E(渲染) | 新增 / 修改 |
+| **[如：绘图逻辑]** | [如：画布初始化、网格、Resize] | [如：`useFabric.ts`（Vue3 composable）] | `src/components/[组件目录 kebab]/composables/useFabric.ts` | Vitest(调用参数) + E2E(产出值) | 新增 / 修改 |
+| **[如：业务]** | [如：风险计算、映射] | [如：`useRiskColoring.ts` / `utils/map.ts`] | `src/components/[组件目录 kebab]/composables/useRiskColoring.ts` | Vitest(返回值) | 新增 / 修改 |
+
+<!-- 模式 A/B（新组件）时"操作"列全部为"新增"；模式 C 按实际填写 -->
+
+**测试层填写规则**（依据 workflow-guardrails §8「值的来源」）：
+- 模块内部**不调用**浏览器 API（Canvas/WebGL/getBoundingClientRect 等）→ `Vitest(返回值)`
+- 模块内部**调用**浏览器 API → `Vitest(调用参数)` + `E2E(产出值)`，Vitest 仅 mock API 验证调用参数，禁止断言返回值/渲染产出
+- View 层 → `Vitest(结构)` + `E2E(渲染)`
+
+---
+
+## 规范例外（仅当需偏离 implementation-rules / SKILL 时填写）
+
+| 偏离项 | 为何需要 | 更简单方案不可用的原因 |
+|:---|:---|:---|
+| [如：某处暂写死色值] | [场景] | [原因] |
+
+---
+
+## 一、目标与范围
+
+### 组件信息
+
+| 项目 | 说明 |
+|------|------|
+| **组件 Tag** | [如 `<qr-code>`，kebab-case] |
+| **组件类名** | [如 QrCode，大驼峰，与 Tag 对应] |
+| **技术栈** | [Vue2/Vue3/React] |
+| **idetype** | [element / container / modal / drawer / messager / popover 等] |
+| **核心职责** | [简述组件的核心功能] |
+
+<!-- idetype 参考：references/lcap-extension-component/ide 下对应文档 -->
+
+### 建议依赖
+
+| 依赖包 | 版本 | 用途 |
+|--------|------|------|
+| [如 qrcode.vue] | [如 3.x] | [如 二维码生成] |
+
+<!-- 若依赖的三方库存在**必填参数**未在 spec 中体现，须在下方「接口设计」中补充对应 Props/Options。-->
+
+### LCAP 必要产出
+
+| 产出 | 说明 |
+|------|------|
+| **api.ts** | 组件配置、Props/Events/Slots/Methods 描述，参考 component/api.md |
+| **block.stories.{js\|tsx}** | 拖拽到画布后的初始代码，参考 component/block.md |
+| **ideusage** | 页面设计器适配，参考 component/ide.md、ide/element.md 或 ide/container.md 等 |
+
+**idetype 与插槽必须一致**（门禁、§四、§六 均以此为准，不重复展开）：
+- 仅 **element**（原子组件如 button、text）在 api.ts 中**不定义 Slots**；**container、modal、drawer、messager、popover** 均需按 spec 在 api.ts 中保留并定义插槽，不得误删。
+- **若 spec 或 api.ts 中已定义插槽（Slots），则 idetype 不得为 element**，必须根据组件形态选择 container（容器）、modal（弹窗）、drawer（抽屉）、messager（消息弹出）或 popover（弹出层）之一，否则设计器行为与插槽定义矛盾。
+
+### MVP 约定
+
+| 项目 | 约定 |
+|------|------|
+| 功能范围 | [本期实现的验收点，与 spec 对应] |
+| 不包含 | [暂不支持、不在 skill 脚手架范围的内容] |
+
+### 实现风险
+
+| 风险点 | 风险等级 | 应对方案 |
+|--------|----------|----------|
+| [如：第三方库不支持 SSR] | 高/中/低 | [方案] |
+
+### 技术架构方案（涉及三方库或复杂布局时必填）
+
+- **开发前置检查 / 技术调研**：在编写代码前须输出并写入本节的调研结论：
+  - 当前安装的依赖库版本（`npm list <package>` 或 package.json 锁定版本）。
+  - 该版本中 Props、Events、Methods 的**确切列表**（对照 `node_modules/<package>/package.json` 的 exports/types 或官方文档）。
+  - 组件的默认布局方案（如：工具栏在顶部、边距 20px 等，与 spec 视觉契约一致）。
+- **技术预研 (Spike)**：对核心依赖库 API 的实测结论（如：属性优先级、事件顺序、是否注入内联 style）；预研中发现的坑（SSR、Mounted/Updated 时机、ResizeObserver 需求）及对策。
+- **数据与状态流向**：`Props → Internal State → Library API → DOM` 的映射关系（可列表或简短描述）。
+- **布局计算公式（若适用）**：关键尺寸计算逻辑，如：`DisplayWidth = Math.min(ContainerWidth, ContentWidth * Scale)`。
+
+#### 内置 UI 控件清单（存在用户可感知交互时必填；纯展示无操作可写「无」并简述）
+
+- [ ] **工具栏 / 操作区**：如 [按钮：导入]、[按钮：删除]、[按钮：绘制]…（与 spec 逐项对应）
+- [ ] **交互反馈**：如 Loading、空态、错误提示、禁用态…
+- [ ] **视觉对齐**：关键区域（如工具栏背景）映射至主题变量（**§三** 填具体变量名）
+
+---
+
+## 二、接口设计（Props / Events / Slots / Methods）
+
+按 spec 中的「接口定义」列出，类型须使用 NASL 类型（nasl.core.String、Integer、Boolean 等），禁止 Object、any。支持**双向绑定**的 Props 需在组件内部变更时通过对应事件回写父组件，并在 api.ts 中标注。**表单类组件**（输入框、选择器、开关、日期选择等）的 value（或 spec 约定的“值”属性）必须支持双向绑定，详见 component/platform/form.md。
+
+### Props
+
+与**展示直接相关**的属性（如 data、options、config 等）须设**合理默认值**，确保未传入或传入空数据时也能正常渲染、不报错、不白屏（如空数组、空对象或占位内容）。**实现与验收时的默认值要求以此段为准**，§六 仅作勾选提醒。
+
+| 属性 | 类型 | 默认值 | 双向绑定 | Setter | 说明 |
+|------|------|--------|----------|--------|------|
+| [属性名] | [nasl.core.xxx] | [默认] | 是/否 | [InputSetter/EnumSelectSetter 等] | [说明] |
+
+### Events
+
+| 事件名 | 回调参数 | 说明 |
+|--------|----------|------|
+| [如 onExport] | [如 event: { fileName: nasl.core.String }] | [触发时机] |
+
+### Slots
+
+| 插槽名 | 说明 |
+|--------|------|
+| [如 slotDefault、slotContent] | [用途] |
+
+> **Methods 与内聚性**：优先通过**内置 UI**（按钮、工具栏等）触发组件内逻辑，保证功能在组件内可完整演示与验收。仅当能力**必须**由外部页面流程（如全局保存、路由级编排）驱动时，再定义为 `Method`；避免用 Method 替代本应在组件内完成的默认交互。
+
+### Methods（若有）
+
+| 方法名 | 参数 | 返回 | 说明 |
+|--------|------|------|------|
+| [如 exportPng] | [fileName?: string] | void | [用途] |
+
+---
+
+## 三、样式与主题适配 (Style & Theme)
+
+依据 `implementation-rules.md` 规则 4，必须明确组件内部 CSS 变量与平台全局主题变量的映射关系。**计划阶段必须在本节填表，不得推迟至实现阶段再决定。** 涉及 Canvas/WebGL/JS 绘图时，须在表中注明「渲染策略」：**CSS 渲染**（用于容器等，支持 var）；**JS 渲染**（Canvas 等用绝对值，禁止将 var 传给绘图 API，见规则 4「例外：Canvas 与 JS 绘图」）。
+
+| 组件 CSS 变量 | 映射的平台主题变量 | 默认值参考 | 渲染策略 | 说明 |
+|:---|:---|:---|:---|:---|
+| [如 --qr-code-color] | [如 --el-color-primary] | [如 #409eff] | CSS 渲染 | [用途说明] |
+| [如 Canvas 背景] | — | [如 #ffffff] | **JS 渲染**（Canvas 专用，禁止变量） | [如：确保扫码识别率] |
+
+> **注意**：Vue3 请参考 `platform/theme-variables-element-plus.md`，React 请参考 `platform/theme-variables-ant-design.md`；Vue2 等见 `platform/theme-variables-*.md`。禁止在组件内写死颜色、间距等魔法值。Canvas/JS 绘图须用绝对值或 getComputedStyle 取计算值，见 implementation-rules 规则 4「例外：Canvas 与 JS 绘图」。
+
+### 样式隔离方式
+
+依据 `workflow-guardrails.md` 规则 9，组件样式必须使用 `<style scoped>` 或 `<style module>`，禁止裸 `<style>`。内联 `:style` 仅用于运行时动态计算的值（如 Canvas 生成的 backgroundImage、由 prop 计算的宽高）。
+
+| 样式类型 | 放置方式 | 示例 |
+|:---|:---|:---|
+| 静态布局（position/z-index/pointer-events 等） | `<style scoped>` | `.overlay { position: absolute; pointer-events: none; }` |
+| 主题变量引用 | `<style scoped>` | `color: var(--el-color-primary)` |
+| 运行时动态值 | 内联 `:style` | `:style="{ backgroundImage: url(${url}) }"` |
+
+---
+
+## 四、ideusage 配置要点
+
+根据 idetype 填写必选配置，参考 `references/lcap-extension-component/ide/index.md` 及 **与当前 idetype 对应的文档**（如 ide/element.md、ide/container.md、ide/modal.md、ide/drawer.md、ide/popover.md 等），无需阅读该目录下全部文档。**插槽与 idetype 规则见 §一 · LCAP 必要产出**，本节只填具体配置项。
+
+| 配置项 | 值 | 说明 |
+|--------|-----|------|
+| idetype | [element/container/...] | 组件类型 |
+
+---
+
+## 五、实现顺序
+
+状态：`[ ]` 待执行 | `[>]` 执行中 | `[X]` 已完成
+
+| 序号 | 状态 | 任务 | 依赖 | 验收标准 |
+|------|------|------|------|----------|
+| 1 | [ ] | 创建组件目录与骨架（组件文件、目录结构） | - | 文件路径符合项目约定 |
+| 2 | [ ] | 编写 api.ts：Props、Events、Slots、Options 类 | 1 | 与 spec 接口定义一致，类型为 NASL |
+| 3 | [ ] | 配置 ideusage（idetype、editable 等） | 2 | 符合 component/ide 规范 |
+| 4 | [ ] | [功能点一：如 二维码生成与展示] | 2, 3 | [对应 spec 验收标准] |
+| 5 | [ ] | [功能点二：如 PNG 导出] | 4 | [对应 spec 验收标准] |
+| 6 | [ ] | 编写 block.stories | 4, 5 | 仅静态属性，无事件/外部绑定 |
+| 7 | [ ] | 编写 example.stories 各功能 demo | 4, 5, 6 | 每个功能一个 story，与 spec 验收一一对应，供本地调试与 e2e |
+| 8 | [ ] | 功能测试（Vitest + Playwright e2e） | 4, 5, 6, 7 | 见下方 **测试约定** |
+| 9 | [ ] | 自检验收 | 8 | 对照 spec 与 plan.md 逐条通过 |
+
+### 测试约定（权威说明）
+
+以下为本计划在**测试策略与命令**上的唯一展开处；技术上下文表、§六 仅作引用。
+
+- **单元 / 交互**：Vitest + @vue/test-utils；用例与 spec 验收对应；测试文件 `<组件目录>/__tests__/*.spec.ts`；`npm run test`。
+- **端到端**：针对 **example.stories** 各功能 demo；**storyId**、Playwright 目录、端口与 `test:e2e`、脚手架约定、禁止事项等以 `commands/speckit.plan.md` 与 SKILL.md「Playwright e2e 测试规范」为准。
+- **任务 8 完成标准**：Vitest 覆盖各功能；e2e 覆盖各 demo，`npm run test:e2e`（或工程脚本）通过；监听控制台报错并有断言。
+
+---
+
+## 六、验收检查清单
+
+*提交前对照；与「规范门禁」互补（见门禁段首说明）。*
+
+**接口与 api.ts**（细则 **§二**）
+
+- [ ] api.ts 中 Props/Events/Slots 与 spec 一致；每项含描述、NASL 类型、默认值或示例
+- [ ] 无 Object/any；双向绑定与 form.md 要求已落实
+
+**组件实现（SKILL.md）**
+
+- [ ] 展示类属性默认值与 **§二 · Props** 一致；表单类 value 双向绑定见 platform/form.md
+- [ ] 根节点透传 **style、class、data-\***；插槽 EmptySlot 见 platform/slot.md（若适用）
+- [ ] 样式使用全局主题变量（**§三**）；内部图标为 SVG（`<svg>` / `<use>`）
+
+**ideusage、stories、测试**
+
+- [ ] ideusage 与 **§一 LCAP**、**§四** 一致
+- [ ] block.stories、example.stories 符合 component/block.md；demo 与 spec 验收对应
+- [ ] **§五 · 测试约定** 已满足；`npm run test` / `npm run test:e2e` 通过
+
+**spec 与构建**
+
+- [ ] spec 验收与注意事项已满足；`npm run build` 通过
+
+**内聚与模块化**
+
+- [ ] 交互由内置 UI 覆盖或已在 plan 中说明例外（与 **§一 · 内置 UI**、**§二 · Methods** 一致）
+- [ ] `index.vue` / `index.tsx` 以组装为主；抽离路径与「文件路径与模块化规划」一致
+
+**鲁棒性**
+
+- [ ] **初始化**：空数据、加载中、加载失败的视觉表现已定义
+- [ ] **尺寸**：容器从 0 到放大时可正常显示（不白屏、不溢出或已约定溢出规则）
+- [ ] **样式**：与 **§三** 一致；不会被外部 CSS（如 `max-width`）意外破坏
+- [ ] **性能**：频繁操作（Resize、连续缩放等）已做防抖或节流（若适用）
+
+提交前可对照 `templates/component-self-check.md` 做最后一轮自检。

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

@@ -0,0 +1,148 @@
+# 对抗性自检报告：[组件名称]
+
+- **自检时间**：[DATE]
+- **组件目录**：[如 specs/xx-pdf-preview/ 或 src/components/pdf-preview]
+- **自检范围**：api.ts、e2e、样式、plan.md
+
+---
+
+## 一、接口与测试覆盖率矩阵 (API vs. Test Coverage)
+
+| 类型 | 名称 | 是否有 e2e 覆盖 | 备注 |
+|:---|:---|:---|:---|
+| Prop | [如 fileUrl] | 是 / 否 | [若无覆盖则写：缺用例，建议补充 xxx] |
+| Method | [如 zoomIn] | 是 / 否 | |
+| Method | [如 zoomOut] | 是 / 否 | |
+| Event | [如 onPageChange] | 是 / 否 | |
+
+**本维度结论**：通过 / 不通过（待修复项见下方）
+
+**待修复项**（若无则填「无」）：
+- [ ] [如：zoomIn/zoomOut 无测试覆盖] → 建议：[补充对应测试用例并断言关键可观测状态]
+
+---
+
+## 二、逻辑与样式冲突审计 (Logic-Style Conflict Audit)
+
+| 逻辑描述 | 涉及属性/API | 可能冲突的 CSS | 冲突说明 | 结论 |
+|:---|:---|:---|:---|:---|
+| [如：scale 控制缩放] | [scale, transform] | [如 canvas 的 max-width: 100%] | [max-width 锁定宽度，scale 无法扩张] | 待修复 / 无冲突 |
+
+**本维度结论**：通过 / 不通过（待修复项见下方）
+
+**待修复项**（若无则填「无」）：
+- [ ] [如：canvas 的 max-width: 100% 压制缩放] → 建议：[改为 max-width: none 或由 JS 控制，并复测缩放]
+
+### 样式隔离检查（Style Isolation Inspection）
+
+| 检查项 | 当前状态 | 结论 |
+|:---|:---|:---|
+| 是否使用 `<style scoped>` 或 `<style module>` | [scoped / module / 裸 style] | 通过 / 待修复 |
+| 内联 `:style` 是否仅含动态计算值 | [是 / 存在静态属性内联（如 position/pointer-events/z-index）] | 通过 / 待修复 |
+| 是否存在为迁就 Vitest 而内联的静态样式 | [否 / 是（列出具体属性）] | 通过 / 待修复 |
+
+---
+
+## 三、平台规范合规性扫描 (Platform Compliance Scan)
+
+| 文件 | 位置（选择器/行） | 当前值 | 应替换为 | 状态 |
+|:---|:---|:---|:---|:---|
+| [如 PdfPreview.vue] | [.toolbar 或 行号] | [#f5f7fa] | [var(--el-fill-color-light)] | 待修复 / 已修复 |
+
+**渲染引擎兼容性**：若组件涉及 Canvas/SVG 动态生成，传给绘图 API 的颜色须为**计算后的绝对值**，不得直接传入 `var(--*)` 字符串（见 implementation-rules 规则 4「例外：Canvas 与 JS 绘图」）。
+
+| 检查项 | 动作 | 结论 |
+|:---|:---|:---|
+| **JS 绘图变量解析** | 检索 `canvas`、`ctx`、`qrcode` 等关键字，核对传入绘图 API 的颜色参数是否为绝对值 | 待修复 / 通过 |
+
+**变量合法性校验**：组件内使用的 `var(--*)` 须在对应技术栈的 `platform/theme-variables-*.md` 中有定义；未在文档中出现的变量名记为待修复。
+
+| 使用的变量 | 是否在 theme-variables-*.md 中定义 | 备注 |
+|:---|:---|:---|
+| [如 var(--el-fill-color-light)] | 是 / 否 | [若否：实际文档中为 --el-xxx，建议修正] |
+
+**本维度结论**：通过 / 不通过（待修复项见下方）
+
+**待修复项**（若无则填「无」）：
+- [ ] [如：background-color: #f5f7fa] → 建议：[替换为 var(--el-fill-color-light)]
+- [ ] [如：var(--el-color-primary-light) 在 theme-variables 中未定义] → 建议：[改为文档中存在的变量名，如 --el-color-primary-light-3]
+- [ ] [如：Canvas 绘图传入了 var(--el-xxx)] → 建议：[用 getComputedStyle 取计算值或改用绝对值，见 implementation-rules 规则 4 例外]
+
+---
+
+## 四、E2E 断言深度评估 (Assertion Depth Audit)
+
+| 功能点 | 当前断言类型 | 是否满足 spec 验收 | 建议 |
+|:---|:---|:---|:---|
+| [如：缩放] | [存在性：toBeVisible()] | 否 | [补充 getBoundingClientRect 或 scale 状态断言] |
+| [如：翻页] | [物理状态：数量/文本] | 是 | - |
+
+### Vitest 职责越界检查（workflow-guardrails 规则 8）
+
+| 检查项 | 当前状态 | 结论 |
+|:---|:---|:---|
+| Vitest 中是否使用 `getComputedStyle` | [否 / 是（列出位置）] | 通过 / 待修复 |
+| Vitest 中是否断言 Canvas/SVG 渲染产出 | [否 / 是（如 toDataURL、data:image）] | 通过 / 待修复 |
+| Vitest 中是否断言 offsetWidth/getBoundingClientRect | [否 / 是] | 通过 / 待修复 |
+| Mock 是否仅用于防崩溃+验证参数（非伪造返回值） | [是 / 存在断言 mock 返回值] | 通过 / 待修复 |
+| Vitest 中是否验证 CSS 渲染效果（定位/穿透/层叠） | [否 / 是] | 通过 / 待修复 |
+
+**本维度结论**：通过 / 不通过（待修复项见下方）
+
+**待修复项**（若无则填「无」）：
+- [ ] [如：缩放仅有 toBeVisible，未验证尺寸变化] → 建议：[补充对 canvas 宽高或 scale 的 expect]
+- [ ] [如：Vitest 中使用了 getComputedStyle] → 建议：[改用 element.style.xxx 或移至 E2E]
+
+**维度四动态验证说明**（若本维度修改了 e2e 用例）：须在下文「测试运行证据」中体现 `test:e2e` 的复跑结果且为**通过**；工程须已配置 `test:e2e`（见 speckit.plan / `setup-extension-project.mjs`），否则先补齐再测。
+
+---
+
+## 五、生命周期与资源清理审计 (Lifecycle & Cleanup Audit)
+
+| 使用的 API/实例 | 是否在 onUnmounted/cleanup 中清理 | 结论 |
+|:---|:---|:---|
+| [如 ResizeObserver] | 是 / 否（缺 disconnect） | 待修复 / 通过 |
+| [如 window.addEventListener] | 是 / 否（缺 removeEventListener） | 待修复 / 通过 |
+| [如 PDF 实例 / pdfDoc.destroy()] | 是 / 否 | 待修复 / 通过 |
+
+**本维度结论**：通过 / 不通过（待修复项见下方）
+
+**待修复项**（若无则填「无」）：
+- [ ] [如：ResizeObserver 未在 onUnmounted 中 disconnect] → 建议：[在 onUnmounted 中调用 resizeObserver.disconnect()]
+
+---
+
+## 六、汇总与修复验证
+
+### 测试运行证据（日志摘要，必填）
+
+**说明**：须根据**实际在终端执行的命令**填写；**禁止**在未执行或未看到成功输出时勾选下方「通过」。可脱敏路径、token；日志可截断为关键行。
+
+| 命令 | 是否执行 | 退出码 | 结果摘要 |
+|:---|:---|:---|:---|
+| `npm run test` | 是 / 未执行（说明原因） | [如 0] | [如 vitest: 12 passed；或失败时 1～2 行关键错误] |
+| `npm run build` | 是 / 未执行 / 不适用 | [如 0] | [简述] |
+| `npm run test:e2e` | 是 | [须为 0] | [须为通过摘要，如 playwright: N passed] |
+
+**环境/配置问题排查记录**（若曾失败）：简述现象 → 已采取的修复（端口、baseURL、启动 Storybook 等）→ **直至通过**。
+
+---
+
+**五维度通过情况**：
+- 维度一（接口与覆盖率）：通过 / 不通过
+- 维度二（逻辑-样式冲突）：通过 / 不通过
+- 维度三（平台规范合规，含变量合法性）：通过 / 不通过
+- 维度四（E2E 断言深度）：通过 / 不通过
+- 维度五（生命周期与资源清理）：通过 / 不通过
+
+**待修复项清单**（合并上述所有待修复项，若无则填「无」）：
+1. [描述] → 文件/位置 → 建议
+2. …
+
+**修复后验证**（须与上表「测试运行证据」一致；**不得**仅勾选而无终端摘要）：
+- [ ] 已对上述待修复项**全部**修复并复检通过
+- [ ] `npm run test`：已在终端执行且上表为**通过**摘要
+- [ ] `npm run build`：已执行且上表为**通过**摘要（或本工程不适用已注明）
+- [ ] `npm run test:e2e`：已在终端执行且上表为**通过**摘要
+
+**自检闭环声明**：本报告提交时，五维度均为**通过**，上表三项命令均为成功输出，**无**未关闭待修复项。

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

@@ -0,0 +1,81 @@
+# 任务清单：[组件名称]
+
+基于 [spec.md](../spec.md) 与 [plan.md](../plan.md)。
+
+**进度**：0 / N 已完成
+
+<!-- 状态说明：[ ] 待执行 | [>] 执行中 | [X] 已完成 -->
+
+**产出路径约定**：凡涉及文件的「产出」须使用 **相对扩展工程根** 的完整路径（与 `plan.md`「文档与源码产出」及 **「文件路径与模块化规划」** 表一致），例如 `src/components/<组件目录 kebab>/api.ts`、`…/composables/useXxx.ts`。**禁止**仅写文件名；多文件可列多条。**必须在此路径**类表述与 `/speckit.tasks`、`/speckit.implement` 命令中的说明一致。模式 C（增量修改）时，产出路径须标注操作类型：`（新增）` 或 `（修改）`。
+
+**代码质量验收（适用时写入各任务「验收」）**：
+
+- [ ] `index.vue` / `index.tsx` **仅**含模板与 UI 组装、必要编排；**非**所有业务逻辑的实现处；复杂逻辑已在 `composables/`、`utils/` 等 **plan.md 已规划路径**
+- [ ] 产出文件路径与 `plan.md`「文件路径与模块化规划」**完全一致**（无擅自改目录）
+- [ ] 与 spec 对应的交互由**内置 UI** 可触达（或与 plan 已声明的插槽/Method 边界一致）
+
+---
+
+## 任务列表
+
+### 任务 0：技术原型验证（可选，涉及三方库或复杂布局时建议必做）
+
+- **状态**：[ ]
+- **描述**：在正式编码前验证技术路径可行性（如：最小 Demo 验证三方库的缩放/渲染 API、ResizeObserver 行为）。
+- **依赖**：无
+- **产出**：预研结论或可运行的最小示例（可放在临时脚本或 `src/components/<组件目录>/` 下可删除的 spike 文件，路径仍须写明）；风险与对策记录到 plan.md 的「技术架构方案」。
+- **验收**：
+  - [ ] 核心 API 行为已实测并记录
+  - [ ] 已知坑与对策已写入计划
+- **备注**：
+
+---
+
+### 任务 1：[任务标题]
+
+- **状态**：[ ]
+- **描述**：[任务描述，如：在现有骨架中完善 NASL 定义、实现 xxx 功能。]
+- **依赖**：无
+- **产出**（路径必填，示例）：
+  - `src/components/<组件目录 kebab>/api.ts`（**必须在此路径**）（新增 / 修改）
+- **验收**：
+  - [ ] [验收标准一，对应 spec]
+  - [ ] [验收标准二；涉及 DOM/尺寸/弹窗时宜含**可观测的 DOM 状态**，如：某元素的 clientWidth、可见性等]
+  - [ ] （适用时）见文首「代码质量验收」
+- **备注**：[执行中遇到的问题或决策记录，无则留空]
+
+---
+
+### 任务 2：[任务标题]
+
+- **状态**：[ ]
+- **描述**：[任务描述。]
+- **依赖**：任务 1
+- **产出**（路径必填，示例）：
+  - `src/components/<组件目录 kebab>/index.vue`（**必须在此路径**；React 则为 `index.tsx`）
+  - `src/components/<组件目录 kebab>/utils/foo.ts`（若本任务新增工具文件）
+- **验收**：
+  - [ ] [验收标准一]
+  - [ ] （适用时）见文首「代码质量验收」
+- **备注**：[执行中遇到的问题或决策记录，无则留空]
+
+---
+
+### 可选：环境兼容性验收
+
+- **状态**：[ ]
+- **描述**：对不同容器尺寸、关键浏览器或分辨率做专项验收（复杂组件建议做）。
+- **依赖**：功能任务与 e2e 均已完成
+- **验收**：
+  - [ ] 小容器（如 320px 宽）下无白屏/错位
+  - [ ] 大容器下无溢出或已按 spec 约定处理
+- **备注**：
+
+---
+
+<!-- 按 plan.md 的「实现顺序」继续添加任务，每项任务对应一个实现步骤。涉及 stories / e2e / 单测时，产出中须分别写明，例如：
+  - src/components/<组件目录>/stories/block.stories.tsx
+  - src/components/<组件目录>/stories/example.stories.tsx
+  - e2e/workshop-floor-plan.spec.ts
+  - src/components/<组件目录>/index.spec.ts
+-->