@agile-team/wl-skills-ui 1.6.2

package/skills/element/component-family/SKILL.md

@@ -0,0 +1,71 @@
+# Skill: element/component-family
+
+## 定位
+
+用于治理 Element Plus 首批 B 端高频组件族的统一视觉，包括 card、tabs、descriptions、tree、drawer、upload、steps、overlay、navigation、feedback。
+
+核心原则：wk-skills-ui 优先保证样式绝对管控。无论项目使用纯 `el-*`、老旧封装、Base*/jh*/C_*，还是 wl-skills-kit 最佳写法，都先通过 L1/L2 样式层统一视觉，再按需引导规范化重构。
+
+## 覆盖组件
+
+| 组件族 | 标签 | 典型场景 |
+|---|---|---|
+| card | `el-card` | 列表容器、详情卡片、统计卡片 |
+| tabs | `el-tabs` `el-tab-pane` | 详情页 Tab、配置页 Tab、主从信息切换 |
+| descriptions | `el-descriptions` | 只读详情、字段展示 |
+| tree | `el-tree` | 左树右表、组织树、区域树 |
+| drawer | `el-drawer` | 抽屉详情、抽屉编辑 |
+| upload | `el-upload` | 附件上传、图片上传、文件列表 |
+| steps | `el-steps` `el-step` | 审批流、流程状态 |
+| overlay | `el-popover` `el-tooltip` `el-dropdown` | 辅助说明、溢出提示、更多操作 |
+| navigation | `el-menu` `el-breadcrumb` | 导航、面包屑 |
+| feedback | `el-empty` `el-result` `el-alert` `el-badge` `el-timeline` | 空状态、异常状态、提示反馈 |
+
+## 扫描规则
+
+| Rule | 含义 |
+|---|---|
+| R031 | `el-card` 建议标识 detail-card/stat-card/wk-card 等场景 class |
+| R032 | `el-tabs` 建议标识 detail-tabs/config-tabs/wk-tabs 等场景 class |
+| R033 | `el-descriptions` 建议使用 border 或统一详情容器 |
+| R034 | `el-drawer` 建议明确 size |
+| R035 | `el-upload` 建议配置 accept/limit/tip |
+| R036 | `el-steps` 建议明确 active/process-status/finish-status |
+| R037 | `el-empty` / `el-result` / `el-alert` 建议提供统一操作入口 |
+
+## B 端业务场景识别
+
+扫描报告的 `componentCoverage.businessScenarios` 会识别：
+
+- `query-table`：查询区 + 表格
+- `toolbar-actions`：工具栏 / 批量操作栏
+- `tree-table`：左树右表
+- `dialog-form`：弹窗表单
+- `drawer-detail`：抽屉详情 / 抽屉编辑
+- `detail-card`：详情卡片
+- `tab-workbench`：Tab 工作台 / Tab 详情
+- `attachment-upload`：附件上传
+- `process-flow`：流程 / 审批
+- `feedback-state`：空状态 / 异常状态
+
+## AI 使用流程
+
+1. 识别当前页面是否命中上述组件族。
+2. 优先确认项目是否加载 `@agile-team/wk-skills-ui/styles` 或 `styles/presets/skin`。
+3. 运行 `wks_ui_scan --output json` 获取 `componentCoverage`。
+4. 如果只是视觉不统一，优先使用 wk-skills-ui 样式层解决。
+5. 如果扫描结果提示页面结构、BaseTable、renderOps 等规范问题，再桥接 wl-skills-kit。
+
+## 推荐 MCP
+
+- `wks_ui_route_intent`：根据用户自然语言判断组件族和治理流程。
+- `wks_ui_scan`：只读扫描并输出组件覆盖。
+- `wks_ui_recommend_flow`：根据扫描 JSON 推荐下一步。
+- `wks_ui_fix_dry_run`：修复前预览，不直接写入。
+
+## 执行约束
+
+- 不为了样式统一强制改业务结构。
+- 不把老项目强制迁移到 wl-skills-kit。
+- 不直接删除项目已有封装。
+- 修复前必须先 dry-run 并给用户确认。

package/skills/element/el-dialog/SKILL.md

@@ -0,0 +1,124 @@
+---
+description: |
+  弹窗组件规范 Skill — el-dialog 内分页位置、嵌套表格操作列按钮风格标准。
+  覆盖规则：R011 R015。
+applyTo: "**/*.vue"
+---
+
+# 弹窗组件规范
+
+## R011 — 分页器必须放在 `<template #footer>` 中 【高危】
+
+弹窗内的 `el-pagination` 必须在 `#footer` slot 内，不得放在内容区（会导致布局溢出）。
+
+```diff
+<el-dialog v-model="visible" title="选择记录">
+  <el-table :data="list" empty-text="暂无数据">
+    <!-- 表格内容 -->
+  </el-table>
+- <el-pagination ... />
+
++ <template #footer>
++   <div class="dialog-footer-pagination">
++     <el-pagination
++       v-model:current-page="page.current"
++       v-model:page-size="page.size"
++       :total="page.total"
++       layout="total, sizes, prev, pager, next"
++     />
++   </div>
++ </template>
+</el-dialog>
+```
+
+---
+
+## R015 — 弹窗嵌套表格操作列必须用 `jh-op-btn` 图标按钮 【高危】
+
+弹窗内 `el-table` 的操作列**不得使用 `el-button link`**，必须与主列表操作列风格一致。
+
+```diff
+<!-- ❌ 旧写法 -->
+<el-table-column label="操作" width="120">
+  <template #default="{ row, $index }">
+    <el-button size="small" link type="danger"
+      @click="handleDeleteItem(row, $index)">删除</el-button>
+    <el-button size="small" link type="primary"
+      @click="handleViewItem(row)">查看</el-button>
+  </template>
+</el-table-column>
+
+<!-- ✅ 新写法 -->
+<el-table-column label="操作" width="100" align="center">
+  <template #default="{ row, $index }">
+    <button class="jh-op-btn jh-op-view" type="button" title="查看"
+      @click.stop="handleViewItem(row)">
+      <el-icon><View /></el-icon>
+    </button>
+    <button class="jh-op-btn jh-op-del" type="button" title="删除"
+      :disabled="optr === 'view'"
+      @click.stop="handleDeleteItem(row, $index)">
+      <el-icon><Delete /></el-icon>
+    </button>
+  </template>
+</el-table-column>
+```
+
+或使用 `renderOps` 更简洁：
+
+```typescript
+{ label: '操作', width: 100, align: 'center',
+  defaultSlot: ({ row, $index }) => renderOps([
+    { type: 'view', onClick: () => handleViewItem(row) },
+    { type: 'del',  show: optr.value !== 'view', onClick: () => handleDeleteItem(row, $index) },
+  ])
+}
+```
+
+---
+
+## 支持的图标类型
+
+| CSS 类       | 图标   | 适用场景  |
+| ------------ | ------ | --------- |
+| `jh-op-del`  | Delete | 删除/移除 |
+| `jh-op-view` | View   | 查看/详情 |
+| `jh-op-edit` | Edit   | 编辑/修改 |
+
+---
+
+## 弹窗标准结构
+
+```html
+<el-dialog
+  v-model="visible"
+  title="选择记录"
+  width="900px"
+  :close-on-click-modal="false"
+>
+  <!-- 搜索区（可选） -->
+  <div class="search-bar">...</div>
+
+  <!-- 表格 -->
+  <el-table :data="list" empty-text="暂无数据" height="400">
+    <el-table-column
+      type="selection"
+      width="55"
+      align="center"
+      header-align="center"
+    />
+    ...列定义...
+  </el-table>
+
+  <!-- Footer：分页 + 操作按钮 -->
+  <template #footer>
+    <div class="dialog-footer">
+      <el-pagination ... />
+      <div class="footer-btns">
+        <el-button @click="visible = false">取消</el-button>
+        <el-button type="primary" @click="handleConfirm">确定</el-button>
+      </div>
+    </div>
+  </template>
+</el-dialog>
+```

package/skills/element/el-form/SKILL.md

@@ -0,0 +1,84 @@
+---
+description: |
+  表单控件规范 Skill — el-input / el-select / el-date-picker / el-form 的尺寸、宽度、labelWidth 标准。
+  覆盖规则：R006 R007 R008。
+applyTo: "**/*.vue"
+---
+
+# 表单控件规范
+
+## R006 — el-input / el-select 必须 `size="small"` 【中危】
+
+全局统一 `size="small"`，确保 32px 高度的密度体验。
+
+```diff
+- <el-input v-model="form.name" placeholder="请输入">
++ <el-input size="small" v-model="form.name" placeholder="请输入">
+
+- <el-select v-model="form.type">
++ <el-select size="small" v-model="form.type">
+```
+
+> 可以通过全局配置 `ElConfigProvider` 统一设置，但建议显式声明，避免嵌套组件污染。
+
+---
+
+## R007 — el-date-picker 必须 `style="width:100%"` 【中危】
+
+el-date-picker 默认宽度不会自动撑满 el-form-item，必须显式设置。
+
+```diff
+- <el-date-picker v-model="form.date" type="date" placeholder="请选择">
++ <el-date-picker style="width:100%" v-model="form.date" type="date" placeholder="请选择">
+```
+
+---
+
+## R008 — el-form `labelWidth` 建议 ≥ 150px 【低危】
+
+```diff
+- <el-form :model="form" labelWidth="100px">
++ <el-form :model="form" labelWidth="150px">
+```
+
+> 本系统内最长标签"隐患排查内容及标准"9字 ≈ 126px + padding ≈ 142px，`150px` 为安全兜底值。
+> 此规则**需人工确认**，不自动修改（部分特殊布局可能需要不同值）。
+
+---
+
+## 完整标准表单示例
+
+```html
+<el-form :model="form" label-width="150px" label-position="right">
+  <el-row :gutter="20">
+    <el-col :span="12">
+      <el-form-item label="姓名" prop="name">
+        <el-input size="small" v-model="form.name" placeholder="请输入姓名" />
+      </el-form-item>
+    </el-col>
+    <el-col :span="12">
+      <el-form-item label="所属部门" prop="dept">
+        <el-select size="small" v-model="form.dept" placeholder="请选择">
+          <el-option
+            v-for="o in deptOptions"
+            :key="o.value"
+            :label="o.label"
+            :value="o.value"
+          />
+        </el-select>
+      </el-form-item>
+    </el-col>
+    <el-col :span="12">
+      <el-form-item label="开始日期" prop="startDate">
+        <el-date-picker
+          style="width:100%"
+          size="small"
+          v-model="form.startDate"
+          type="date"
+          placeholder="请选择日期"
+        />
+      </el-form-item>
+    </el-col>
+  </el-row>
+</el-form>
+```

package/skills/element/el-table/SKILL.md

@@ -0,0 +1,86 @@
+---
+description: |
+  表格组件规范 Skill — el-table / BaseTable / el-table-column 的对齐、空状态、selection 列标准。
+  覆盖规则：R001 R002 R003 R014。
+applyTo: "**/*.vue"
+---
+
+# 表格组件规范
+
+## R001 — el-table-column 必须 `align="center"` 【高危】
+
+**所有列**（含 selection / index）均必须居中对齐。
+
+```diff
+- <el-table-column label="名称" prop="name">
++ <el-table-column align="center" label="名称" prop="name">
+
+- <el-table-column type="selection" width="70" align="left">
++ <el-table-column type="selection" width="55" align="center" header-align="center" fixed="left">
+
+- <el-table-column type="index" width="80">
++ <el-table-column type="index" align="center" width="60">
+```
+
+> ⚠️ selection 列：`width=55`，`align="center"` **且** `header-align="center"` 两者必须同时设置，缺一会导致复选框垂直错位。
+
+---
+
+## R002 — el-table 必须 `empty-text="暂无数据"` 【中危】
+
+```diff
+- <el-table :data="list">
++ <el-table :data="list" empty-text="暂无数据">
+```
+
+---
+
+## R003 — BaseTable 必须 `empty-text="暂无数据"` 【中危】
+
+```diff
+- <BaseTable :hook="page">
++ <BaseTable :hook="page" empty-text="暂无数据">
+```
+
+---
+
+## R014 — selection 列必须 `header-align="center"` 【中危】
+
+```diff
+- <el-table-column type="selection" width="55" fixed="left" align="center">
++ <el-table-column type="selection" width="55" fixed="left" align="center" header-align="center">
+```
+
+---
+
+## 完整标准写法示例
+
+```html
+<el-table :data="list" empty-text="暂无数据">
+  <el-table-column
+    type="selection"
+    width="55"
+    fixed="left"
+    align="center"
+    header-align="center"
+  />
+  <el-table-column type="index" align="center" width="60" label="序号" />
+  <el-table-column align="center" prop="name" label="名称" min-width="120" />
+  <el-table-column align="center" prop="status" label="状态" width="90">
+    <template #default="{ row }">
+      <!-- 使用 renderTagSlot 渲染彩色 Tag，见 tag-status/SKILL.md -->
+    </template>
+  </el-table-column>
+</el-table>
+```
+
+---
+
+## labelWidth 选取建议
+
+| 最长标签字数 | 建议 labelWidth             |
+| ------------ | --------------------------- |
+| ≤ 5 字       | `100px`                     |
+| 6~7 字       | `120px`                     |
+| 8~9 字       | `150px`（**推荐统一值**）   |
+| ≥ 10 字      | `180px`（特殊表单单独处理） |

package/skills/element/el-tag/SKILL.md

@@ -0,0 +1,127 @@
+---
+description: |
+  枚举/状态/分类展示规范 Skill — 表格列中遇到枚举值时，按字段语义选择正确的渲染函数。
+  包含状态类/分类类/编号类/数值类/警示文本类五种渲染模式，及静态 map 与动态字典两种接入方式。
+applyTo: "**/*.{ts,vue}"
+---
+
+# 枚举/状态/分类展示规范
+
+> 凡是表格列，遇到**枚举值**，必须按下表分类选择渲染函数，禁止纯文本展示。
+
+---
+
+## 五类字段 → 五种渲染方式
+
+| 字段类别                    | 典型字段                               | 视觉效果         | 渲染函数                    |
+| --------------------------- | -------------------------------------- | ---------------- | --------------------------- |
+| **状态类**（二元/流转）     | enableStatus、permitStatus、riskStatus | 实心彩色 Tag     | `renderTagNode(v, MAP)`     |
+| **分类/级别类**（归档属性） | coursewareType、trainLevel、planType   | 镂空 outline Tag | `renderClassifyTag(v, MAP)` |
+| **编号/代码类**             | riskNo、planNo、fileNo                 | 蓝色圆角徽标     | `renderBadge(v)`            |
+| **数值型**                  | baseCount、score                       | 绿色圆角徽标     | `renderCountBadge(v)`       |
+| **警示文本型**              | evaluateStandard                       | 红色字体         | `renderDangerText(v)`       |
+
+---
+
+## 状态类颜色语义（强制规范）
+
+| 状态含义                        | ElTag type         | 例子                       |
+| ------------------------------- | ------------------ | -------------------------- |
+| 正常 / 有效 / 已完成 / 启用     | `success`（绿）    | 已启用、证书有效、已完工   |
+| 警告 / 临时 / 待处理 / 即将过期 | `warning`（橙）    | 即将过期、待审批           |
+| 停用 / 驳回 / 已过期 / 危险     | `danger`（红）     | 已停用、审批驳回、证书过期 |
+| 草稿 / 未开始 / 中性            | `info`（灰）       | 草稿、未处理               |
+| 主流程默认状态                  | `"primary"` / `""` | 作业中、处理中             |
+
+---
+
+## 判断原则
+
+```
+字段名含 Status / State / Flag   → 状态类 → renderTagNode
+字段名含 Type / Level / Kind / Category → 分类类 → renderClassifyTag
+字段名含 No / Code / Id（非主键） → 编号类 → renderBadge
+字段名含 Count / Score / Weight   → 数值类 → renderCountBadge
+字段名含 Reason / Standard / 文本  → 警示文本 → renderDangerText
+```
+
+---
+
+## 静态 Map（字典固定时）
+
+```typescript
+import { renderTagNode, renderClassifyTag } from '@agile-team/wk-skills-ui/runtime';
+
+export const MY_STATUS_MAP = {
+  "0": { label: "待处理", type: "info" },
+  "1": { label: "处理中", type: "primary" },
+  "2": { label: "已完成", type: "success" },
+  "3": { label: "已驳回", type: "danger" },
+} as const;
+
+// 在 columnsDef 中：
+{ name: 'myStatus', label: '状态', width: 90,
+  defaultNode: ({ row }) => renderTagNode(row.myStatus, MY_STATUS_MAP) }
+```
+
+---
+
+## 动态字典（后端配置时）
+
+```typescript
+import { renderDictClassifyTag } from '@agile-team/wk-skills-ui/runtime/common-preset';
+
+// 只需定义颜色映射，label 由字典动态获取
+export const TRAIN_LEVEL_COLOR_MAP: Record<string, string> = {
+  "1": "",         // 公司级（蓝）
+  "2": "warning",  // 部门级（橙）
+  "3": "info",     // 班组级（灰）
+};
+
+// 在 columnsDef 中：
+{ name: 'trainLevel', label: '培训级别', width: 100,
+  defaultSlot: ({ row }) => renderDictClassifyTag(row.trainLevel, 'trainLevel', TRAIN_LEVEL_COLOR_MAP) }
+```
+
+> 注意：使用 `renderDictClassifyTag` 前需调用 `setDictResolver(fn)` 注入字典查询函数。
+
+---
+
+## 通用业务预设（已内置，无需重新定义）
+
+`installCommonPreset()` 后通过 `defineColumns()` 自动生效：
+
+| 字段名             | 渲染         | 常量                    |
+| ------------------ | ------------ | ----------------------- |
+| `riskLevel`        | 风险分级 Tag | `RISK_LEVEL_MAP`        |
+| `taskStatus`       | 排查任务状态 | `TASK_STATUS_MAP`       |
+| `riskStatus`       | 隐患状态     | `RISK_STATUS_MAP`       |
+| `permitStatus`     | 作业票状态   | `PERMIT_STATUS_MAP`     |
+| `trainStatus`      | 培训状态     | `TRAIN_STATUS_MAP`      |
+| `credentialStatus` | 证书状态     | `CREDENTIAL_STATUS_MAP` |
+| `coursewareType`   | 课件类型     | `COURSEWARE_TYPE_MAP`   |
+
+---
+
+## R009 — 状态字段禁止纯文本渲染 【高危，需人工确认】
+
+```diff
+// ❌ 纯文本
+{ name: 'status', label: '状态' }
+
+// ✅ 使用 defineColumns 自动映射（enableStatus / riskLevel 等已注册字段）
+// 或显式指定渲染器：
+{ name: 'status', label: '状态', width: 90,
+  defaultNode: ({ row }) => renderTagNode(row.status, MY_STATUS_MAP) }
+```
+
+## R010 — 分类字段必须 `effect="plain"` 【中危，需人工确认】
+
+```diff
+// ❌ 分类字段用实心 Tag
+h(ElTag, { type: 'warning' }, () => label)
+
+// ✅ 分类字段用镂空 Tag
+h(ElTag, { type: 'warning', effect: 'plain', size: 'small' }, () => label)
+// 或直接用 renderClassifyTag(value, MAP)
+```

package/skills/layouts/detail-page/SKILL.md

@@ -0,0 +1,99 @@
+---
+description: |
+  详情页骨架 Skill — 检测/对齐 .detail-page 只读展示页面结构，
+  适用于流程详情、档案详情、记录详情等以 el-descriptions 或自定义 label-value 为主的页面。
+applyTo: "**/*.vue"
+---
+
+# layouts/detail-page SKILL
+
+## 适用场景
+
+**只读展示页**：以 `el-descriptions` 或自定义 label-value 卡片为主，可附带子表格（只读）。
+
+---
+
+## Detect — 识别详情页
+
+```
+检测条件（满足任意 2 项即判定）：
+✓ 文件名含 Detail / Info / Profile / View（如 DetailPage.vue / InfoView.vue）
+✓ 页面以 el-descriptions 为主体
+✓ 路由 path 含 /detail/:id 或 /view/:id
+✓ 页面顶部有面包屑 + 返回按钮
+✓ 无 el-form 表单提交逻辑
+```
+
+---
+
+## Diagnose — 诊断问题
+
+| 问题 | 规则 | 说明 |
+|---|---|---|
+| 根节点缺少 `.detail-page` | L-301 | 应为 `<div class="detail-page">` |
+| 子表格有操作列文字按钮 | R015 | 详情页内嵌 el-table 也须用 jh-op-btn（仅下载/查看类图标）|
+| 状态字段纯文本展示 | R009 | 详情页状态字段也应用 renderTagNode |
+| label-value 未用统一 class | L-302 | 自定义 label-value 应用 `.detail-item` 统一间距 |
+| 硬编码颜色 | R016-R018 | 详情页强调色应用 CSS Token |
+
+---
+
+## Repair — 修复指引
+
+### 标准结构（el-descriptions 版）
+
+```vue
+<template>
+  <div class="detail-page">
+    <!-- 顶部操作栏 -->
+    <div class="detail-page__header">
+      <el-page-header @back="$router.back()" :content="pageTitle" />
+      <div class="detail-page__actions">
+        <el-button icon="Edit" @click="handleEdit">编辑</el-button>
+      </div>
+    </div>
+
+    <!-- 基本信息卡片 -->
+    <el-card class="detail-page__card" header="基本信息">
+      <el-descriptions :column="2" border>
+        <el-descriptions-item label="名称">{{ info.name }}</el-descriptions-item>
+        <el-descriptions-item label="状态">
+          <component :is="renderTagNode(info.enableStatus, ENABLE_STATUS_MAP)" />
+        </el-descriptions-item>
+        <el-descriptions-item label="创建时间">{{ info.createTime }}</el-descriptions-item>
+        <el-descriptions-item label="备注" :span="2">{{ info.remark }}</el-descriptions-item>
+      </el-descriptions>
+    </el-card>
+
+    <!-- 子表格（只读，可选） -->
+    <el-card class="detail-page__card" header="关联记录">
+      <el-table :data="subList" empty-text="暂无数据">
+        <el-table-column type="index" label="序号" width="60" align="center" />
+        <el-table-column prop="name" label="名称" align="center" />
+        <el-table-column label="操作" width="80" align="center">
+          <template #default="{ row }">
+            <button class="jh-op-btn jh-op-view" title="查看" @click="viewAttach(row)">
+              <el-icon><View /></el-icon>
+            </button>
+          </template>
+        </el-table-column>
+      </el-table>
+    </el-card>
+  </div>
+</template>
+```
+
+### SCSS 对应
+
+```scss
+// styles/layouts/_detail-page.scss 已提供基础骨架
+// .detail-page__card 提供卡片间距
+// .detail-page__header 提供顶部操作栏布局
+```
+
+---
+
+## 关联资源
+
+- 样式实现：[styles/layouts/_detail-page.scss](../../../styles/layouts/_detail-page.scss)
+- 相关 skills：[element/el-table](../../element/el-table/SKILL.md) | [layouts/form-dialog](../form-dialog/SKILL.md)