@zeyue0329/xiaoma-cli 1.21.0 → 1.22.0

package/src/zqyl-skills/xiaoma-zqyl-ui-spec/SKILL.md

@@ -0,0 +1,478 @@
+---
+name: xiaoma-zqyl-ui-spec
+description: 中企云链页面视觉与交互规范：布局间距、Design Tokens、标题层级、查询表格/表单/弹窗/提示/反馈的展示与操作规则。用于新建或审查 Vue2 页面时统一展示效果。在用户上传需求文档、PRD、原型图/截图，或提及云链交互规范、页面规范、视觉规范、Design Tokens、列表页/表单页/弹窗展示效果、需对照规范检查页面时使用。 Use when creating, reviewing, or refactoring any ZQYL (中企云链) Vue2 page — it is the entry point that decides platform, page type, and which page/component skills to read.
+---
+
+# 云链 UI 视觉与交互规范
+
+技术栈：**Vue2 + Element UI + zqyl-component-base**。
+
+本 skill 专注**页面级视觉规则与交互规范**：间距、对齐、操作优先级、反馈层级、三端 Design Tokens。新建或审查页面时，按下方流程与自检清单对照执行。
+
+---
+
+## 从需求/原型生成页面
+
+用户只需提供**需求文档**和/或**原型图**（可附简短口头说明），**不必手填字段清单**。按下列流程自动解析并生成代码。
+
+### 必用 skill（按顺序）
+
+1. **本 skill（xiaoma-zqyl-ui-spec）** — 视觉与交互规则 + 下方提取清单
+2. **页面整包** — 先判定**平台端**（front / mid / backend），再按页面类型**选用已安装的**对应整包：
+
+命名规则：`xiaoma-zqyl-{页面类型}-{平台}`
+
+| 页面类型 | 后台 backend | 中台 mid | 前台 front |
+| --- | --- | --- | --- |
+| 列表页 | `xiaoma-zqyl-list-page-backend` | `xiaoma-zqyl-list-page-mid` | `xiaoma-zqyl-list-page-front` |
+| 表单详情页 | `xiaoma-zqyl-form-detail-page-backend` | `xiaoma-zqyl-form-detail-page-mid` | `xiaoma-zqyl-form-detail-page-front` |
+| 反馈页 | `xiaoma-zqyl-feedback-page-backend` | `xiaoma-zqyl-feedback-page-mid` | `xiaoma-zqyl-feedback-page-front` |
+| 批量导入弹窗 | `xiaoma-zqyl-import-dialog-page-backend` | `xiaoma-zqyl-import-dialog-page-mid` | `xiaoma-zqyl-import-dialog-page-front` |
+
+三端骨架与配套组件不同（如中台列表用 `ylManagerTitle` + `ylMpsTable`，前台/后台列表用 `ylTitle` + `ylTableSimple`），**不可混用**。
+
+3. **组件 skill（必装）** — 组件 Props / 列配置 / 查询项等细节从已安装的**单组件 skill** 读取（随 XiaoMa `zqyl` 模块一并安装，无需单独下载）：
+
+命名规则：`xiaoma-zqyl-{组件 key}-{平台}`，组件 key 全小写 kebab-case，例如 `xiaoma-zqyl-search-form-backend`、`xiaoma-zqyl-data-census-backend`、`xiaoma-zqyl-button-backend`。
+
+**29 个组件 key 的完整清单（含 8 类图表、中台专有组件、三端覆盖情况）见 [components-index.md](./components-index.md)** —— 拼 skill 名前先查它，不要凭组件中文名猜。
+
+| 场景 | 常见组件 skill |
+| --- | --- |
+| 页头标题 | `xiaoma-zqyl-title-{平台}` |
+| 查询区 | `xiaoma-zqyl-search-form-{平台}` |
+| 表格 | `xiaoma-zqyl-table-simple-{平台}` |
+| 列表页统计区 | `xiaoma-zqyl-data-census-{平台}` |
+| 导入/导出/上传（左侧图标） | `xiaoma-zqyl-button-{平台}` |
+| 弹窗 | `xiaoma-zqyl-dialog-{平台}` |
+| 可编辑业务表单（新建/编辑页字段块） | `xiaoma-zqyl-form-editor-{平台}` |
+| 只读业务表单（查看/审批页字段块） | `xiaoma-zqyl-form-view-{平台}` |
+| 详情分块折叠 | `xiaoma-zqyl-collapse-{平台}`、`xiaoma-zqyl-module-{平台}` |
+| 中台页头 / 中台主列表（**仅 mid**） | `xiaoma-zqyl-manager-title-mid`、`xiaoma-zqyl-mps-table-mid` |
+| 趋势 / 占比 / 对比 / 排名 / 转化 / 仪表盘 | `xiaoma-zqyl-{line,bar,pie,funnel,gauge}-chart-{平台}` |
+| 流程图 / 地图 / 热力图 | `xiaoma-zqyl-{flow,map,heatmap}-chart-{平台}` |
+
+**组件细节唯一来源**：读取对应 `xiaoma-zqyl-{组件 key}-{平台}` 独立组件 skill；页面整包**不含** `components/` 副本。上表只列高频场景，**完整 29 个组件 key 见 [components-index.md](./components-index.md)**。
+
+4. **Element UI（最后兜底）** — 无对应 `zqyl-component-base` 封装、或未安装组件 skill 时：
+
+- 使用 Element UI 原生组件（`el-button` 等）
+- **数据表格不得用 `el-table` 兜底**：须优先 `ylTableSimple`（中台主列表除外，见下）；读 `xiaoma-zqyl-table-simple-{平台}` skill
+- **仍须遵守本 skill** 的布局间距、按钮优先级、表格对齐、提示位置等视觉与交互规则
+- 常规按钮用 `el-button`；仅当本 skill「按钮」章节要求左侧图标时才用 `ylButton`
+- **表单详情页的标准字段块不得因兜底而手写 `el-form` / `view-item`**；须先补全入口组件注册并读 `xiaoma-zqyl-form-editor-{平台}` / `xiaoma-zqyl-form-view-{平台}` skill
+
+### 组件选型优先级（总结）
+
+```
+xiaoma-zqyl-ui-spec（视觉与交互总则）
+  → 页面整包 pages/*.md（搭骨架 + 配套组件索引）
+  → 独立组件 skill xiaoma-zqyl-{key}-{平台}（填 props / 列 / 查询项等细节）
+  → 检查项目入口是否已全局注册对应 base 组件（缺则补注册）
+  → 项目内已有用法（仅限：路由路径、接口调用、业务枚举；**不含**表单/表格 markup 选型）
+  → Element UI 兜底（视觉仍按 xiaoma-zqyl-ui-spec）
+```
+
+**表单详情页禁止因 legacy 页面而降级**：即使同仓库存在 `el-form` + 手写 `view-item` 的旧页，新建/改版表单详情页仍**必须**走 `xiaoma-zqyl-form-detail-page-{平台}` + `xiaoma-zqyl-form-editor-{平台}` / `xiaoma-zqyl-form-view-{平台}` 组件 skill；旧页写法不可作为表单区实现依据。
+
+**数据表格禁止因 legacy 页面而降级**：即使同仓库存在手写 `el-table` 的旧页，新建/改版页面中凡数据表格区仍**必须**优先 `ylTableSimple`（中台列表页主表格默认 `ylMpsTable`）；**禁止**以旧页为由直接使用 `el-table`。
+
+### 工作流
+
+```
+1. 读用户输入（文档 / 图片 / 口头描述）
+2. 判定平台端（front / mid / backend）+ 页面类型 + 目标路径（缺则问 1 个关键问题）
+3. 从需求中提取结构化信息（见下方「提取清单」）
+4. 按「组件选型优先级」生成：页面整包搭骨架 → 读取匹配的组件 skill 填细节 → Element UI 兜底
+5. 交付前走「交付自检清单」
+6. 输出：改了哪些文件、与需求差异/待确认项
+```
+
+### 页面类型识别
+
+| 信号 | 类型 | 整包（将 `{平台}` 换为 front / mid / backend） |
+| --- | --- | --- |
+| 查询条件 + 表格 + 分页 | 列表页 | `xiaoma-zqyl-list-page-{平台}` |
+| 表单字段 + 保存/提交/审批 | 表单详情页 | `xiaoma-zqyl-form-detail-page-{平台}` |
+| 成功/失败结果、404、无数据全页 | 反馈页 | `xiaoma-zqyl-feedback-page-{平台}` |
+| 批量导入（下载模板 + 上传 + 导入结果） | 批量导入弹窗 | `xiaoma-zqyl-import-dialog-page-{平台}` |
+
+**数据统计看板/仪表盘**（只有指标卡 + 图表、**没有**查询区和数据表格）**无专用页面模板**，也**不要**去套列表页模板（列表页 skill 明确把"无表格的仪表盘"列为不适用）：直接自建骨架，按下列四条落地：
+
+1. 页头：后台 `xiaoma-zqyl-title-backend`、前台 `xiaoma-zqyl-title-front`、**中台必须 `xiaoma-zqyl-manager-title-mid`**（中台页面页头默认 ylManagerTitle —— `xiaoma-zqyl-title-mid` 虽然存在，但其正文明写「勿默认使用本组件」；勿把 `{平台}` 直接代成 mid）
+2. 指标卡用 `xiaoma-zqyl-data-census-{平台}`；该组件**自带 `el-card`**，勿再外套卡片
+3. 图表区每块放在自己的 `el-card` 内，用 `el-row :gutter="16"`（中台 `8`，与 design-tokens.md 的 `spacingBase` 取值一致）分栏：并排双图 `:span="12"`，通栏单图 `:span="24"`；卡片间距同 tokens（前台/后台 16px、中台 8px）
+4. 图表 skill 名按 [components-index.md](./components-index.md) 的「图表组件」表取 `*-chart-{平台}`；组件的 props / ECharts option 细节以该 skill 为准
+
+页面**同时**有查询条件 + 数据表格、图表只是其中一个区块时，仍按列表页模板走，图表作为区块嵌入。
+
+### 平台判定（先做这一步，且只做一次）
+
+`zqyl` 模块会把三端 skill **一次性全部装入** skills 目录（96 个），同名组件在三端各有一份且描述高度相似——**选错平台等于整页组件选型全错**（如把 `ylManagerTitle` + `ylMpsTable` 写进后台仓库）。因此在打开任何页面/组件 skill 之前，先按下列优先级定平台，且**只选用其中一端**：
+
+| 优先级 | 依据 |
+| --- | --- |
+| 0 | **用户在本次会话中明确指定**「前台 / 中台 / 后台」，或明说这个页面要上哪个系统 —— 用户的话**永远最大**，即使与下面任何一条冲突 |
+| 1 | **安装时已固定的平台**：读 `{project-root}/_xiaoma/zqyl/config.yaml` 的 `platform` 键；值为 `backend` / `mid` / `front` 时直接采用，不再往下推断；值为 `all` 或文件不存在则继续往下；值不在这三者之内（疑似拼错）→ 继续往下推断，并在回复里提示用户 `platform` 值无效 |
+| 2 | **当前工作区项目名**：zqyl-manager → `-backend`；mps-main → `-mid`；zqyl-crclopen → `-front` |
+| 3 | **项目内已有页面**：出现 `ylManagerTitle` / `ylMpsTable` → mid；`ylTitle` + `ylTableSimple` → backend 或 front（再按项目名/路由前缀区分） |
+| 4 | 仍无法确定 → **只问一句**平台端，勿猜测 |
+
+**冲突处理**：优先级 0 与 1 打架时（如仓库固定 `front`、但用户说"这页要上中台"）→ **按用户说的做**，并在回复里点一句"本页按中台生成，与本仓库固定的 front 不同"，让用户有机会纠正；不要沉默地按 config 覆盖用户。跨端生成时一并提示：目标端组件（如 `ylManagerTitle` / `ylMpsTable`）通常不在当前仓库的依赖里，代码的真实落位多半是目标端仓库。
+
+> **易错点**：skill 名里唯一含 `manager` 的是中台组件 `xiaoma-zqyl-manager-title-mid`（指 ylManagerTitle），**它与后台仓库 `zqyl-manager` 毫无关系**。在 zqyl-manager 里开发要选 `-backend`，别被这个词面撞车带偏。
+
+**建议**：单端项目在安装时就把 `zqyl.platform` 选成对应平台（`npx @zeyue0329/xiaoma-cli install --set zqyl.platform=backend`），之后所有会话在用户未另行指定时按**优先级 1** 直接命中，彻底消除三端误匹配（用户在会话中明说另一端时，仍按优先级 0 走）。
+
+**始终先读 xiaoma-zqyl-ui-spec 判定平台**，再打开 `xiaoma-zqyl-{页面类型}-{平台}` 整包；不要同时套用两个平台的 `pages/*.md`。
+
+混合场景（如列表 + 统计区 + 弹窗表单）：**主页面按主类型走页面整包**；统计区、弹窗、上传等读对应**组件 skill**（如 `xiaoma-zqyl-data-census-{平台}`、`xiaoma-zqyl-dialog-{平台}`）。
+
+### 表单详情页组件选型（强制）
+
+识别为**表单详情页**（新增/编辑/查看/审批）后，按卡片区块选型：
+
+| 区块类型 | 必用组件 | 禁止 |
+| --- | --- | --- |
+| 标准字段块（**整卡全只读**，如审批查看） | `ylFormView` | 手写 `el-form` + `el-form-item`；手写 `view-item` |
+| 标准字段块（**含可编辑字段**；含同卡只读+可编辑混排） | **单个** `ylFormEditor`（只读项 `disabled: true` 或 `slot`） | 同卡 `ylFormView` + `ylFormEditor` 拆分；手写 `view-item` |
+| 动态行表格（相似问、明细行、可增删行） | **`ylTableSimple`**（`:isTableForm="true"` / 自定义 `slot` 列） | 直接 `el-table`；用 `ylFormEditor` 承载整表 |
+| 附件 | `ylFileUpload` | — |
+
+**同卡混排（强制）**：同一 `el-card` / `ylCollapse` 内若既有只读回显又有待填字段 → **整体一个 `ylFormEditor`**，只读字段 `disabled: true`（或 slot 内只读展示 + 文字按钮）；**禁止**先 `yl-form-view` 再 `yl-form-editor`。
+
+**默认规则**：原型里带「基础信息」等卡片 + 若干 label/输入框 → 该卡片**必须**走 Editor/View，不得因项目存在 legacy 页面而改用手写表单。
+
+**参考页优先级**（仅标准字段块）：
+1. 同项目已用 `yl-form-editor` / `yl-form-view` 的页面（如 `serviceInterfaceDetail.vue`）
+2. `xiaoma-zqyl-form-editor-{平台}` / `xiaoma-zqyl-form-view-{平台}` 组件 skill 示例
+3. ❌ 不得参考仍用手写 `el-form` / `view-item` 的 legacy 页作为新页模板
+
+### 提取清单（自动完成，勿让用户逐项填写）
+
+**列表页**：页面标题、模块路径、查询项（标签/控件类型）、表格列（金额右对齐/状态枚举）、表格上/行内操作、接口 URL（对接项目 `INTERFACE` 或接口模块；未知则留空并 `TODO`，**禁止 mock 数据**）、Tab/统计区等差异。
+
+**表单详情页**：标题、返回（**未说明位置时：前台/中台 → `ylTitle` 左侧；后台 → `ylTitle` 右侧**）、只读/可编辑、分区与字段、附件、**其他页面级操作按钮（默认放 `ylTitle` 右侧）**、**卡片模块操作（未说明位置时放小标题右侧）**、接口与路由；**整卡全只读 → `ylFormView`**；**含可编辑或同卡混排 → 单个 `ylFormEditor`**；数据表格 → **`ylTableSimple`**。
+
+**原型图/截图**：自上而下识别标题区 → 提示 → 查询区 → 表格/表单 → 底栏；对照 ylSearchForm / ylFormEditor 等组件能力；不确定处用 `TODO` 列出（接口常量、字段映射），**勿用假数据占位**。
+
+### 生成约束
+
+- **禁止 mock 数据**：表格 `loadData`、表单 `reqData`、统计区 `ylDataCensus`、下拉 `data` 等均走接口；`data()` 中保持空数组/空对象，在 `created` / `mounted` 或组件查询链路中请求赋值；**禁止** `mounted` 写死分页 total、**禁止**手写演示行
+- Vue2 Options API + `zqyl-component-base`
+- **`zqyl-component-base` 全局注册（样式 + 组件）**：生成页面前先读**项目入口文件**（以项目实际配置为准，常见为 `src/main.js`）：
+  - 样式：`import 'zqyl-component-base/lib/theme-chalk/component.css'`（无则补一次）
+  - 组件：优先 `import zqylComponentBase from 'zqyl-component-base'` + `Vue.use(zqylComponentBase)` 一次性全局注册；或与规范平台一致逐组件 `Vue.component(...)`。**禁止**在每个 `.vue` 页面里重复 `import` 样式或 `import { ylTitle, … } from 'zqyl-component-base'` 再写 `components: { … }`。页面模板直接使用 `<yl-title>`、`<yl-form-editor>` 等即可。
+  - 项目内 legacy 组件（如 `ylManagerTitle`）可继续在入口单独 `Vue.component`，勿与 base 同名覆盖除非有意迁移。
+- **列表页组件选型**（见对应平台整包，勿跨端套用）：
+  - 后台 / 前台：`ylTitle` + `ylSearchForm` + `ylTableSimple`
+  - 中台：`ylManagerTitle` + `ylSearchForm` + `ylMpsTable`
+- **表单详情页组件选型**（见 `xiaoma-zqyl-form-detail-page-{平台}` 整包 + 下方强制规则）：
+  - **整卡全只读** → `ylFormView`（`:form-data` + `:req-data`）
+  - **含可编辑字段**（含同卡只读+可编辑混排）→ **单个** `ylFormEditor`（`:show-submit-button="false"`；只读项 `disabled: true`；提交由 **`ylTitle` 右侧按钮**或 `ylContainerFoot` 触发）
+  - **同卡混排禁止** `ylFormView` + `ylFormEditor` 同卡拆分
+  - **操作按钮默认位置**：需求未说明时，**返回** → 前台/中台 **`ylTitle` 左侧**（`:disabledBack="false"`），后台 **`ylTitle` 右侧插槽**（`:disabledBack="true"`）；**其他页面级**放 **`ylTitle` 右侧插槽**；**卡片模块级**（如添加行）放 **小标题行右侧**，**不要**默认放表格/内容区最下方；仅需求明确要求「底部置底/底栏固定」时才用 `ylContainerFoot`
+  - 生成前检查**项目入口文件**是否已注册 `ylFormEditor`、`ylFormView`；**缺失则补注册**，不得因此退回手写 `el-form`
+  - 必读 `xiaoma-zqyl-form-editor-{平台}` / `xiaoma-zqyl-form-view-{平台}` 组件 skill，不得跳过
+  - 数据表格（列表、弹窗、表单详情、抽屉等）：**优先 `ylTableSimple`**，读 `xiaoma-zqyl-table-simple-{平台}` skill；**禁止**默认 `el-table`
+  - **中台列表页**主表格默认 **`ylMpsTable`**（非 `ylTableSimple`）
+- 只改本页与必要路由/接口文件，不顺带重构
+- **最多问 1～2 个阻塞问题**（如平台端、文件目录、接口是否已有）
+- 参考已有页面时：**表单字段块**仅参考已使用 `ylFormEditor` / `ylFormView` 的页面；legacy 手写表单页不得作为新页字段块模板
+
+---
+
+## 执行流程
+
+```
+1. 判定平台端 → backend（后台）/ mid（中台）/ front（前台）
+2. 判定页面类型 → 列表 / 表单详情 / 弹窗 / 反馈页
+3. 读取 design-tokens.md 取色值、间距、字号
+4. 按页面类型套用下方规则 + reference.md 细则
+5. 交付前走「交付自检清单」
+```
+
+---
+
+## 平台选择
+
+前台 / 中台 / 后台 **Design Tokens 分平台维护**；前台与后台一致，中台卡片间距为 8px。差异仅在组件选型与页面骨架，详见 [design-tokens.md](./design-tokens.md)。
+
+| 端 | 典型项目 | 主色 | 卡片圆角 | 卡片间距 |
+| --- | --- | --- | --- | --- |
+| **后台** backend | zqyl-manager | `#288CE9` | 0 | `16px 16px 0` |
+| **中台** mid | mps-main | `#288CE9` | 0 | `8px 8px 0` |
+| **前台** front | zqyl-crclopen | `#288CE9` | 0 | `16px 16px 0` |
+
+完整 Token 见 [design-tokens.md](./design-tokens.md)。
+
+---
+
+## 全局视觉规则
+
+### 布局与间距
+
+- **基础间距**：前台/后台卡片间距、边距为 **16px**；**中台卡片间距为 8px**。提示与标题/内容间距均为 16px。
+- **侧导航布局**：顶栏在最上层，阴影落在页面标题之上；标题与顶栏相连无间隙。
+- **通栏布局**（无侧导航）：前台/后台卡片四边 16px；中台四边 8px，带阴影。
+- **页面背景**：`#F5F7FA`（`bgContainer`）；卡片背景 `#FFFFFF`。
+- **可点击元素**：`cursor: pointer`（按钮、链接、下拉、Tab、可排序表头等）。
+
+### 字体与颜色
+
+- **正文字号** 14px；标题区常用 14px bold / `#303133`。
+- **正文色** `#606266`；次要文字 `#909399` / `#C0C4CC`。
+- **边框** `#DCDFE6`；表格线 `#EBEEF5` / `#E8E8E8`。
+- **语义色**：success `#67C23A`、warning `#E6A23C`、danger `#F56C6C`。
+
+### 卡片与阴影
+
+- 卡片：`box-shadow: 0 0 5px 0 rgba(0,0,0,0.09)`；圆角 **0**；内边距 **24px**。
+- 按钮间距 **8px**（`btnGap`）。
+
+---
+
+## 页面标题（视觉层级）
+
+| 类型 | 视觉要点 |
+| --- | --- |
+| **一级标题** | 顶栏下方、与导航相连；顶栏阴影覆盖标题 |
+| **带 Tab 标题** | 标签后可跟数量 `标签名(12)`；待办/待确认 Tab 右上角红点 |
+| **二级标题** | **前台/中台**：左侧返回按钮；右侧放页面级操作按钮；可带 Tab。**后台**：返回默认在标题右侧，其他页面级操作同侧排列 |
+| **标题栏高度** | 56px；左右内边距 24px |
+
+组件：`ylTitle`（前台/后台）、`ylManagerTitle`（中台）。
+
+---
+
+## 查询表格（视觉 + 交互）
+
+### 查询区
+
+| 规则 | 说明 |
+| --- | --- |
+| 输入框宽度 | 固定值，不随内容伸缩 |
+| 标签字数 | 建议 ≤8 字 |
+| 条件 < 3 个 | 仅「查询」按钮 |
+| 条件 ≥ 3 个 | 「查询」+「重置」 |
+| 对齐 | 查询按钮与条件**左对齐** |
+| 换行 | 宽度不足时条件自动换行 |
+| 少条件 | 可与表格同卡片 |
+
+组件：`ylSearchForm`，少条件时 `:isCard="true"` 与表格同卡。
+
+### 表格上方操作（整体操作）
+
+- **位置**：表格上方或与表格右对齐的操作区（含 `ylTitle` 右侧 default 插槽、表格标题行 `text-right`）；最重要操作在**最右**。
+- **主按钮**：整组操作**仅 1 个**实心 primary（`type="primary"`，**不加** `plain`），通常为最右侧「新增」类操作。
+- **其余按钮**：同组内**所有**非主按钮须写 `type="primary" plain`（含查看/编辑/删除/批量导入等），**禁止**使用默认样式 `<el-button>`（无 `type`）。
+- **文字链接**：不改变表格数据的操作（跳转、说明）用 link + 前置图标。
+
+### 行内操作（优先级从左到右）
+
+```
+流程类（申请/支付/还款/邀请/上传）
+→ 常规类（查看/编辑）
+→ 低频类（下载/导出）
+→ 删除（始终最后）
+```
+
+- 仅 1 个按钮：除编辑/删除/下载导出外，建议实心 primary。
+- 多个按钮：**仅最右 1 个**实心 `type="primary"`；其余全部 `type="primary" plain`；有新增时新增为最右实心 primary。
+- 跳转外链/其他页：文字链接 + 图标。
+
+### 表格组件选型
+
+| 场景 | 组件 |
+| --- | --- |
+| 前台/后台任意数据表格 | **`ylTableSimple`** |
+| 中台列表页主表格 | **`ylMpsTable`** |
+| 降级 `el-table` | 仅 `ylTableSimple` 无法满足且需求明确要求时 |
+
+### 表格视觉
+
+| 项 | 规则 |
+| --- | --- |
+| 对齐 | 默认左对齐；金额/数量**右对齐**；大写金额左对齐 |
+| 空值 | 显示 `-`，不可留空（流程中暂空除外） |
+| 溢出 | `text-overflow: ellipsis`；hover Tooltip 全文 |
+| 表头折行 | 最多 2 行 |
+| 无数据 | 「暂无数据」占位 |
+| 分页 | 默认 **20** 条；可选 20 / 50 / 100 |
+| 多选 | 表头显示「已选 N 条」；半选 indeterminate |
+| 最小列宽 | 编号 ~200px、公司名 ~180px、金额 ~120px、日期 ~110px、姓名/状态 ~80px |
+| 横向溢出 | 标题列 + 操作列固定，内容区横向滚动 |
+
+组件：`ylTableSimple`（前台/后台）、`ylMpsTable`（中台）。
+
+### 表格变体
+
+- **带 Tab**：切换标签查不同数据；改查询条件后各 Tab 同步刷新。
+- **二级/双重 Tab**：查询仅作用于当前 Tab；切换 Tab 保留各自查询条件与结果。
+- **统计区**：标题下方大数字 + 标签，如 `10,007,000,000.00 / 贴现总额（元）`。
+
+---
+
+## 表单（视觉 + 交互）
+
+| 项 | 规则 |
+| --- | --- |
+| 框体最大宽度 | **480px**，超出不再变宽 |
+| 单列 | 单卡片居中；提交按钮在表单项最下方（不置底）；**不加** `el-card-padding-bottom0`；`label-width="auto"` 且表单项标题**不限 8 字**、取消 label `ellipsis` |
+| 双列/三列 | 等宽排列；`ylFormEditor` 在 `layout="double"` 时字段默认 `span: 12`（半行），**勿因日期区间等较宽控件擅自设 `span: 24`**；独占整行须原型明确，详见 `xiaoma-zqyl-form-editor-{平台}` 的 span 选型 |
+| 复合表单 | 多卡片时按列均分，每列左对齐 |
+| 只读 | 整体左对齐；标题不折行、内容可折行；**不显示**必填 `*` 与填写提示 |
+| 长只读项 | 三列布局中长项独占一行 |
+| 多卡片提交 | 需求**未说明**按钮位置：**返回** → 前台/中台 **`ylTitle` 左侧**，后台 **`ylTitle` 右侧**；**其他页面级**放 **`ylTitle` 右侧**；需求**明确要求置底**时用 `ylContainerFoot` |
+| 卡片小标题 class | **后台** → `yl_manager_subheading`（加粗 16px + 左侧蓝条）；**中台 / 前台** → `yl-title-sub`（14px，无竖条）。**禁止跨端混用** |
+| 卡片模块操作 | 某卡片/小模块有操作按钮且**未说明**位置：放 **小标题同一行右侧**（`el-row.mb16` + 左 **`yl-title-sub`（中台/前台）或 `yl_manager_subheading`（后台）** + 右 `text-right`）；**勿**默认放在表格/内容区最下方 |
+| 数据表格 | **全页优先 `ylTableSimple`**；中台列表主表用 `ylMpsTable`；**禁止**默认 `el-table` |
+| 分步表单 | 冗长或不熟悉任务分步，注意信息分类与层级 |
+
+### 文件上传
+
+组件 `yl-file-upload`：
+
+- 单文件 `type: sole`：「点击上传」+ tip；已传可查看/删除/重传。
+- 多文件 `type: multi`：「点击上传」/「继续上传」；「已上传文件(n/m)」汇总。
+- 列表 `type: list`：文件名列表 + 类型图标 + 删除。
+- 约束写在 `tip` 或按钮右侧；次要提示在控件下方左对齐。
+
+---
+
+## 弹窗与抽屉
+
+| 项 | 规则 |
+| --- | --- |
+| 高度 | **200px ~ 550px**；超出滚动 |
+| 表单列数 | **不支持三列** |
+| 单行查询 | 查询 + 表头置顶 + 分页置底，仅表格区滚动 |
+| 多行查询 | 查询与表格同滚；默认显示 20 条 |
+| 合计行 | 与分页一致置底（多行查询时随内容滚） |
+| 只读 | 内容仅查看时不展示底部操作按钮，通过标题栏关闭；`el-dialog__body` 保留 24px 底边距 |
+| 表格 | 遵循全页 **`ylTableSimple` 优先**规则；行内操作用 `attr.type: 'handle'` |
+| 未选中 | 单选/多选表格弹窗：未选时操作按钮置灰 |
+| 底部提示 | 次要信息放 footer **按钮左侧**（左文右按钮） |
+| 多层级 | 支持弹窗上再弹窗 |
+| 无数据 | 仍显示标题/表头，避免像加载慢 |
+
+组件：`ylDialog`。复杂详情用 **Drawer**（纵向空间更大；标题 `#303133` 加粗，距下方 24px）。
+
+---
+
+## 提示与反馈
+
+### 提示位置（间距均为 16px）
+
+| 位置 | 放置 |
+| --- | --- |
+| 全局提示 | 页面顶部或 `ylTitle` 正下方，`margin-top: 16px`（`page-global-tip`） |
+| 查询与表格间独立提示 | **列表页常用**：`ylSearchForm` 与 `el-card.yl-tabs-table` 之间的**同级独立块**，`margin-top: 16px`（`list-page-tip`）；**勿**放入表格卡 |
+| 卡片提示 | **表单详情等业务卡片**内，卡片标题下方，`margin-bottom: 16px`（`card-inner-tip`）；列表页表格卡默认不用 |
+| 表格操作提示行 | 表格卡内 `el-row.mb16` 左侧纯文本（≤40 字）；短文案**不用** `ylTips` |
+| 表单项提示 | 控件下方，与框体左对齐 |
+
+**列表页整块 `ylTips` 选型**：原型在查询下、表格上 → 用「查询与表格间独立提示」；**禁止**默认与 `ylTableSimple` 同包在 `el-card.yl-tabs-table`（详见 `xiaoma-zqyl-tips-{平台}` skill）。
+
+组件：`ylTips`。样式分标准（标题+正文+链接）/ 简略（≤2 行无标题）/ 极简（表单项）。
+
+- **警示类**：权限问题等，常显。
+- **信息类**：操作前须知，可关闭。
+
+### 文字说明
+
+- **操作说明**（弱于警示）：标题下方，尽量简短。
+- **表格表头说明**：≤40 字可与按钮同行；超出整行；重要信息用警示色。
+- **注释说明**：表单/表格**底部**，低优先级。
+
+### 反馈层级
+
+| 场景 | 方式 |
+| --- | --- |
+| 表单校验错误 | 输入框标红 + 下方错误文案 |
+| 操作成功 | Message 轻提示，自动消失 |
+| 需打断确认 | MessageBox |
+| 复杂反馈 | 弹窗 |
+| 流程结束 | 跳转结果页 |
+| 页面异常 | 数据异常页 + 操作引导 |
+
+组件：`ylEmptyPage`（无数据/404/网络/权限）。
+
+---
+
+## 常用 CSS 片段
+
+```css
+/* 全局提示：紧挨标题下方 */
+.page-global-tip { margin-top: 16px; }
+
+/* 列表页：查询区与表格卡之间的独立提示 */
+.list-page-tip { margin-top: 16px; }
+
+/* 卡片内提示：与下方内容相隔 16px */
+.card-inner-tip { margin-bottom: 16px; }
+
+/* 表格金额列 */
+.text-right { text-align: right; }
+
+/* 可点击 */
+.cursor-pointer { cursor: pointer; }
+```
+
+---
+
+## 交付自检清单
+
+**布局**
+
+- [ ] 卡片/区块间距是否正确（前台/后台 16px、中台 8px）
+- [ ] 页面背景 `#F5F7FA`，卡片白底 + 正确阴影
+- [ ] 可点击元素有 `cursor: pointer`
+- [ ] 使用统一 Design Tokens（按端取值，中台卡片间距 8px）
+
+**列表页**
+
+- [ ] 数据表格使用 `ylTableSimple`（非 `el-table`；中台列表主表用 `ylMpsTable`）
+- [ ] 查询条件数量决定有无「重置」
+- [ ] 查询按钮左对齐；表格操作右对齐
+- [ ] 整块 `ylTips` 落位与原型一致：查询下/表格上时用 `list-page-tip` 独立块，**不在** `el-card.yl-tabs-table` 内
+- [ ] 整体/行内操作主按钮 ≤1；删除在最后
+- [ ] 页头/表格操作区：仅最右 1 个实心 primary，其余均为 `type="primary" plain`（禁止无 type 默认按钮）
+- [ ] 空单元格为 `-`；溢出 ellipsis + Tooltip
+- [ ] 金额右对齐；分页默认 20
+
+**表单页**
+
+- [ ] 输入框最大宽 480px
+- [ ] 只读无 `*` 与填写提示
+- [ ] 需求未说明时，**返回**：前台/中台在 `ylTitle` 左侧，后台在 `ylTitle` 右侧
+- [ ] 需求未说明时，**其他页面级**操作按钮在 `ylTitle` 右侧（非 `ylContainerFoot`）
+- [ ] 卡片模块操作（如「添加」）未说明位置时，在小标题行右侧（非表格/内容区最下方）
+- [ ] 卡片小标题 class 与平台一致：**中台/前台** `yl-title-sub`；**后台** `yl_manager_subheading`；**禁止**中台/前台使用 `yl_manager_subheading`
+- [ ] 使用 `ylContainerFoot` 时，需求已明确要求置底，且不与页头重复按钮
+- [ ] `ylContainerFoot` 主操作按钮在 **`#center` 插槽**（居中）；**禁止**默认插槽 flex `space-between` 把按钮顶到右侧
+- [ ] **整卡全只读**使用 `ylFormView`；**同卡混排只读+可编辑**使用**单个** `ylFormEditor`（只读项 `disabled`），**禁止**同卡 View+Editor 拆分
+- [ ] 可编辑标准字段块使用 `ylFormEditor`（非整块手写 `el-form`）
+- [ ] 数据表格使用 `ylTableSimple`（非 `el-table`；中台列表主表除外）
+- [ ] 入口已注册 `ylFormEditor` / `ylFormView`（缺则已补注册）
+
+**弹窗**
+
+- [ ] 高度 200px ~ 550px；无三列表单
+- [ ] 只读弹窗无底部操作按钮
+- [ ] 单行查询时仅表格区滚动
+- [ ] 无数据仍显示表头
+
+**提示与反馈**
+
+- [ ] 全局/卡片/表单项提示位置与 16px 间距正确
+- [ ] 校验、成功、确认各用对应反馈层级
+
+---
+
+## 延伸阅读
+
+- 完整交互细则：[reference.md](./reference.md)
+- 三端 Design Tokens：[design-tokens.md](./design-tokens.md)
+- 项目源码 Token 定义：`src/utils/tokens.js`
+- 规范平台在线预览：`zqyl-component-spec-platform` 各 SpecDetail 页

package/src/zqyl-skills/xiaoma-zqyl-ui-spec/VERSION.md

@@ -0,0 +1,30 @@
+## 版本
+
+- **上游规范包版本**：1.1.0
+- **上游发布日期**：2026-07-22
+- **摘要**：新增图表组件与导入弹窗模板；列表/表单详情 skill 增强；生成效果案例完善
+
+本套规范随 XiaoMa CLI 的 `zqyl` 模块分发。升级方式：重新运行 `npx @zeyue0329/xiaoma-cli install` 并勾选 **ZQYL Spec** 模块，安装器会覆盖同名 skill 目录。
+
+### 本版要点
+
+- 新增 8 类图表组件 skill（折线/柱状/饼图/漏斗/仪表盘/流程/地图/热力）及「批量导入弹窗」页面模板
+- 列表页变体并入列表页 skill；表单详情页增加只读区、单列布局等示例
+- 生成效果案例扩充（流转查询、数据统计看板等）
+
+### XiaoMa 适配说明
+
+- skill 名统一改为 `xiaoma-zqyl-*` 前缀、全小写 kebab-case，并与目录名严格一致（XiaoMa skill 契约 + Claude Skill 规范要求）
+- 组件 key 的 camelCase 写法改为 kebab-case（`searchForm` → `search-form`、`dataCensus` → `data-census`）
+- 三端 `yunlian-ui-spec` 内容完全一致，合并为单一入口 skill `xiaoma-zqyl-ui-spec`
+- 新增 `components-index.md`（29 个组件 key × 三端覆盖表）：上游把组件清单放在整包 `README.md` 里，而 README 不随 skill 安装，导致 8 类图表 skill 从任何入口都不可达
+- 新增安装期 `zqyl.platform` 变量（落到 `_xiaoma/zqyl/config.yaml`）+ SKILL.md「平台判定」优先级表：三端 96 个 skill 同时安装，平台选错等于整页组件选型全错
+- 每条平台后缀 skill 的 description 追加「适用于…」平台锚点
+
+### 与上游的有意分叉（重新导入上游包时必须重新施加）
+
+| 位置 | 上游原文 | 本包 | 原因 |
+| --- | --- | --- | --- |
+| `xiaoma-zqyl-search-form-{backend,mid,front}/SKILL.md` 第 123/152/189/221 行（共 12 处） | `:platformType="yx"` / `"mps"` / `"yxManager"` | `:platformType="'yx'"` / `"'mps'"` / `"'yxManager'"` | 前导冒号使其成为 v-bind **表达式**，Vue2 会去解析裸标识符 `yx`，复制即 `ReferenceError` 渲染崩溃。同包页面模板（`pages/listPage.md`）本来就写的是带引号的正确形式 |
+
+> 上游仍存在、**本包未改**的问题清单见仓库 `docs/zqyl-upstream-issues.md`（已反馈规范平台方）。

package/src/zqyl-skills/xiaoma-zqyl-ui-spec/components-index.md

@@ -0,0 +1,55 @@
+# 组件 skill 索引（29 个组件 key：27 个三端通用 × 3 + 2 个中台专有 = 83 个 skill）
+
+组件 skill 的完整命名：**`xiaoma-zqyl-{组件 key}-{平台}`**，组件 key 为下表第一列（全小写 kebab-case），平台为 `backend` / `mid` / `front`。
+例：查询区用后台 → `xiaoma-zqyl-search-form-backend`；中台主列表 → `xiaoma-zqyl-mps-table-mid`。
+
+先按需求判定平台端（见 SKILL.md「平台判定」），再从下表取组件 key 拼出 skill 名读取；**不要**凭组件中文名猜 skill 名。
+
+## 通用组件
+
+| 组件 key | 组件 | backend | mid | front |
+| --- | --- | :-: | :-: | :-: |
+| `title` | 标题（ylTitle） | ✅ | ✅ | ✅ |
+| `container-foot` | 页面底部（ylContainerFoot） | ✅ | ✅ | ✅ |
+| `tips` | 提示（ylTips） | ✅ | ✅ | ✅ |
+| `data-census` | 数据统计（ylDataCensus） | ✅ | ✅ | ✅ |
+| `search-form` | 查询条件（搜索表单）（ylSearchForm） | ✅ | ✅ | ✅ |
+| `table-simple` | 表格（简版）（ylTableSimple） | ✅ | ✅ | ✅ |
+| `form-editor` | 表单编辑（ylFormEditor） | ✅ | ✅ | ✅ |
+| `form-view` | 表单查看（ylFormView） | ✅ | ✅ | ✅ |
+| `file-upload` | 文件上传（ylFileUpload） | ✅ | ✅ | ✅ |
+| `preview` | 文件预览（ylPreview） | ✅ | ✅ | ✅ |
+| `dialog` | 弹窗（ylDialog） | ✅ | ✅ | ✅ |
+| `drawer` | 抽屉（el-drawer） | ✅ | ✅ | ✅ |
+| `message-feedback` | 消息提示 / 确认框（Message / MessageBox） | ✅ | ✅ | ✅ |
+| `popover` | 气泡提示（el-popover） | ✅ | ✅ | ✅ |
+| `collapse` | 折叠（ylCollapse） | ✅ | ✅ | ✅ |
+| `module` | 折叠模块（ylModule） | ✅ | ✅ | ✅ |
+| `empty-page` | 空页面（ylEmptyPage） | ✅ | ✅ | ✅ |
+| `button` | 按钮（ylButton） | ✅ | ✅ | ✅ |
+| `select-tree` | 下拉树选择（ylSelectTree） | ✅ | ✅ | ✅ |
+
+## 图表组件
+
+需求出现「趋势 / 占比 / 对比 / 排名 / 转化 / 仪表盘 / 流程图 / 地图 / 热力」等看板类诉求时，按下表取对应图表 skill。骨架怎么搭看页面形态：**纯看板**（只有指标卡 + 图表）按 SKILL.md「数据统计看板/仪表盘」四条自建；**查询 + 表格 + 图表区块**的页面仍走列表页模板，图表作为区块嵌入。
+
+| 组件 key | 图表 | backend | mid | front |
+| --- | --- | :-: | :-: | :-: |
+| `line-chart` | 折线图（ylLineChart） | ✅ | ✅ | ✅ |
+| `bar-chart` | 柱状图（ylBarChart） | ✅ | ✅ | ✅ |
+| `pie-chart` | 饼图（ylPieChart） | ✅ | ✅ | ✅ |
+| `funnel-chart` | 漏斗图（ylFunnelChart） | ✅ | ✅ | ✅ |
+| `gauge-chart` | 仪表盘（ylGaugeChart） | ✅ | ✅ | ✅ |
+| `flow-chart` | 工作流组件（ylFlowChart） | ✅ | ✅ | ✅ |
+| `heatmap-chart` | 热力图（ECharts Heatmap） | ✅ | ✅ | ✅ |
+| `map-chart` | 地图（ECharts Map） | ✅ | ✅ | ✅ |
+
+## 中台专有
+
+| 组件 key | 组件 | backend | mid | front |
+| --- | --- | :-: | :-: | :-: |
+| `manager-title` | 标题（中台）（ylManagerTitle） | — | ✅ | — |
+| `mps-table` | 表格（中台）（ylMpsTable） | — | ✅ | — |
+
+`manager-title`（ylManagerTitle）与 `mps-table`（ylMpsTable）**只有 mid 端**。中台页面页头默认 ylManagerTitle、列表主表格默认 ylMpsTable，勿默认用 `title` / `table-simple`。后台/前台页面**不应**把这两个组件作为默认页头/主表格选型；后台仓库若存在 legacy `ylManagerTitle`（见 design-tokens.md 三端差异表），可参考本 skill 的 Props，但页面骨架仍走 `xiaoma-zqyl-title-backend`。
+`manager-title` 名字里的 `manager` 指中台页头组件 ylManagerTitle，**与后台仓库 zqyl-manager 无关** —— 后台仓库请用 `xiaoma-zqyl-title-backend`。