提交

openspec/changes/zkxw-engineering-standards/specs/ui-conventions/spec.md

@@ -168,17 +168,26 @@ Web 管理端弹窗 SHALL 遵循规范：表单 `label-position="top"`；遮罩
 
 ### Requirement: 表格操作列固定在右侧
 
-`web-admin` 中所有业务列表页（系统管理、业务模块等，不含 Demo 参考页）的 `el-table` 操作列 SHALL 使用 `fixed="right"` 固定在表格右侧。宽度规则：2 个按钮时 `min-width="260"`，3 个按钮时 `min-width="320"`，4 个及以上按钮时 `min-width="400"`。全局 CSS 通过 `.el-table-fixed-column--right` 选择器（注意：Element Plus 使用单短横线，非双下划线）提供固定列样式。
+`web-admin` 中**保留操作列**的业务列表页（系统管理、业务模块等，不含 Demo 参考页）的 `el-table` 操作列 SHALL 使用 `fixed="right"` 固定在表格右侧。宽度规则：2 个按钮时 `min-width="260"`，3 个按钮时 `min-width="320"`，4 个及以上按钮时 `min-width="400"`。全局 CSS 通过 `.el-table-fixed-column--right` 选择器（注意：Element Plus 使用单短横线，非双下划线）提供固定列样式。
+
+**例外**：遵循下文「列表主标识列链接查看与编辑删除外置」、且列表动作仅为常规「编辑」「删除」的标准 CRUD 页 **SHALL NOT** 设置操作列，此时本规则不适用。
 
 #### Scenario: 新增系统管理列表页
 
-- **WHEN** 在系统管理模块下新增列表页面（如用户管理、角色管理等）
+- **WHEN** 在系统管理模块下新增列表页面（如用户管理、角色管理等），且页面保留操作列
 - **THEN** 表格操作列 SHALL 设置 `fixed="right"`，宽度按按钮数设置：≤ 2 按钮用 `min-width="260"`，3 按钮用 `min-width="320"`，≥ 4 按钮用 `min-width="400"`
 
+#### Scenario: 标准 CRUD 列表无外置操作列
+
+- **WHEN** 新增列表页仅含常规「编辑」「删除」，并采用工具栏 + 查看弹窗 Hero 外置模式
+- **THEN** 表格 **SHALL NOT** 包含 `label="操作"` 列
+- **THEN** 本「操作列固定右侧」规则 **SHALL NOT** 适用
+
 #### Scenario: Code review 表格列
 
 - **WHEN** PR 包含新增或修改的 `el-table-column` 且 `label="操作"`
 - **THEN** 审查者 SHALL 确认该列包含 `fixed="right"` 属性，且宽度与按钮数量匹配（2 按钮 260px，3+ 按钮 320px）
+- **THEN** 若页面属于标准 CRUD + 查看弹窗且仅编辑/删除，审查者 SHALL 要求移除外置至工具栏与 `#hero-actions`，而非保留操作列
 
 ### Requirement: 表格列宽使用 min-width 实现等比缩放
 
@@ -257,32 +266,57 @@ Web 管理端弹窗 SHALL 遵循规范：表单 `label-position="top"`；遮罩
 - **WHEN** 新增弹窗表单中的某字段需要辅助说明
 - **THEN** SHALL 使用 `<template #label>字段名<span class="form-label-tip">注释内容</span></template>` 格式，SHALL NOT 将注释放在输入控件旁
 
-### Requirement: 列表行查看弹窗（按钮 + 双击）
+### Requirement: 列表主标识列链接查看与编辑删除外置
 
-`web-admin` 中**所有** `el-table` 组件——包括主列表页（标准列表、树形列表）、弹窗内嵌列表（如编辑弹窗/查看弹窗/选择弹窗中的子表格）、侧栏面板内的列表——若操作列包含「查看」「查看详情」「查看确认信息」等只读查看类按钮，SHALL 同时提供行双击触发查看的能力，实现规则如下：
+`web-admin` 中带只读查看弹窗（或等价只读详情态）的 `el-table` 列表页 SHALL 遵循：
 
-1. **操作列「查看」按钮**：操作列 SHALL 在首位包含一个「查看」按钮（`<el-icon><View /></el-icon>查看`），点击后弹出只读查看弹窗。
-2. **行双击触发**：`el-table` SHALL 监听 `@row-dblclick` 事件，双击任意行时触发与「查看」按钮相同的弹窗（即调用同一 `handleView(row)` 函数）。
-3. **条件按钮场景**：当操作列按钮随状态/Tab 变化（如待确认 Tab 显示「确认收款」，已确认 Tab 显示「查看确认信息」），`@row-dblclick` handler SHALL 仅在「查看」类按钮可见时触发对应查看函数，其余状态下可忽略或调用对应主操作函数。
-4. **弹窗组件**：查看弹窗 SHALL 优先使用 `SystemViewDialog`（`web-admin/src/components/business/system-view-dialog/index.vue`）；样式对齐 Hero 渐变头图 + 分区 KV 信息区 + 底部「关闭」按钮（详见下文「查看弹窗 KV 布局与组件选型」）。KV 信息区 SHALL 使用 `ViewKvGrid`（上下堆叠栅格）或 `ViewKvTable`（多组多列表格）；**SHALL NOT** 使用 `el-descriptions` 或历史 `.dlg-kv` 布局承载列表行查看详情。
-5. **字段内容**：查看弹窗 SHALL 展示该行记录的所有业务字段（含状态映射、字典翻译），不展示 `id`、`del_flag` 等技术字段；KV 跨列/换行规则见「查看弹窗 KV 布局与组件选型」。
-6. **区块标题样式**：查看弹窗中各区块标题（如 `SystemViewDialog` 的 section title、`bx` 模块 `.dlg-view-section-title`，渲染为 `h3`/`h4`）SHALL 与字段标签形成明显视觉区分。区块标题 SHALL 使用深色文字（`#1e293b`）配合左侧主色竖条装饰（`border-left: 3px solid #10b981`），字号 14px、`font-weight: 600`；字段标签 SHALL 为 13px、`#64748b`、`font-weight: 400`（由 `ViewKvGrid` 的 `dt` 或 `ViewKvTable` 的 `th` 统一渲染）。区块标题样式 SHALL NOT 与字段标签使用相同颜色或相近字重。
+1. **主标识列链接**：承载业务主标识的列（通常为「名称」「单号」「编号」「主题」等，如 `productName`、`customerName`、`orderNo`、`applyCode`、`planNo`）SHALL 使用 `<el-link type="primary">` 包裹展示文案，点击 SHALL 调用打开只读详情的同一函数（如 `handleView(row)`、`openView(row)`、`handleDetail(row)` 等，与 `@row-dblclick` 共用）。
+2. **操作列去重（查看）**：当主标识列已提供上述链接查看入口时，操作列 **SHALL NOT** 再包含仅用于打开同一只读详情/查看弹窗的「查看」「查看详情」等按钮。
+3. **编辑/删除外置（标准 CRUD）**：对于列表行级动作**仅含**常规「编辑」「删除」（及同类 CRUD，无审批、状态变更、安排运输等行内复合业务按钮）的标准列表页，表格 **SHALL NOT** 设置「操作」列；「编辑」「删除」SHALL 外置至以下两处：
+   - **列表工具栏**：位于「已选 N 项」与「新增」主按钮（`type="primary"` / `btn-main`）之后；**编辑** SHALL 在 `selectedRows.length === 1` 时可用，点击 SHALL 对选中行调用与行内编辑相同的 handler（如 `handleUpdate(selectedRows[0])`）；**删除** SHALL 支持批量删除，在 `selectedRows.length === 0` 时禁用，且 SHALL 复用既有创建人校验（如 `allRowsDeletableByCreator` / `canDeleteByCreator` + `CREATOR_DELETE_TIP`）；两按钮 SHALL 使用 `btn-ghost` 描边样式，**SHALL NOT** 与「新增」同列使用主色实心。
+   - **查看弹窗 Hero**：通过 `SystemViewDialog` 的 `#hero-actions` 插槽，在 Hero 区右侧展示「编辑」「删除」，对**当前查看行**执行与列表相同的 handler；删除成功后 SHALL 关闭查看弹窗并刷新列表；从详情进入编辑并保存成功后，若查看弹窗仍打开，SHALL 刷新当前详情数据。
+4. **操作列保留场景**：存在审批、状态变更、安排运输、复合主操作等**行级、状态依赖**业务按钮的列表页 **SHALL** 保留操作列，并仍遵循「表格操作列固定在右侧」；此类页面 MAY 在 `#hero-actions` 放置通用动作，但 SHOULD 避免与操作列完全重复同一入口。
+5. **行双击**：`el-table` SHALL 继续绑定 `@row-dblclick`，双击行 SHALL 触发与主标识列链接相同的查看函数。
+6. **条件按钮场景**：当操作列按钮随状态/Tab 变化（如待确认 Tab 显示「确认收款」，已确认 Tab 显示「查看确认信息」），`@row-dblclick` handler SHALL 仅在「查看」类按钮可见时触发对应查看函数，其余状态下可忽略或调用对应主操作函数。
+7. **复合主操作例外**：主操作本身为复合业务入口、不仅打开只读弹窗的按钮（如订单「查看/运营」、待办「审批」）SHALL NOT 因本规则被删除；此时仍 SHALL 在主标识列提供链接以打开只读查看/详情。
+8. **工具栏查看**：列表工具栏中的「查看」类按钮在表格主标识列已提供链接时 **SHALL NOT** 保留；单选后查看 SHALL 改由点击行内主标识链接或双击行触发。
+9. **弹窗组件与字段**：查看弹窗 SHALL 优先使用 `SystemViewDialog`（`web-admin/src/components/business/system-view-dialog/index.vue`）；样式对齐 Hero 渐变头图 + 分区 KV 信息区 + 底部「关闭」按钮（详见下文「查看弹窗 KV 布局与组件选型」）。KV 信息区 SHALL 使用 `ViewKvGrid`（上下堆叠栅格）或 `ViewKvTable`（多组多列表格）；**SHALL NOT** 使用 `el-descriptions` 或历史 `.dlg-kv` 布局承载列表行查看详情。查看弹窗 SHALL 展示该行记录的所有业务字段（含状态映射、字典翻译），不展示 `id`、`del_flag` 等技术字段。
+10. **区块标题样式**：查看弹窗中各区块标题 SHALL 与字段标签形成明显视觉区分。区块标题 SHALL 使用深色文字（`#1e293b`）配合左侧主色竖条装饰（`border-left: 3px solid #10b981`），字号 14px、`font-weight: 600`；字段标签 SHALL 为 13px、`#64748b`、`font-weight: 400`。
 
-#### Scenario: 新增系统管理列表页
+权威参考：
+- 列表无外置操作列 + 工具栏编辑/删除：`web-admin/src/views/system/user/index.vue`
+- 主标识列链接 + 工具栏编辑/删除 + 查看弹窗 Hero 编辑/删除：`web-admin/src/views/crm/product/index.vue`
+- 查看弹窗 Hero 动作区：`web-admin/src/views/crm/customer/CustomerDetailDialog.vue`（`#hero-actions`）
 
-- **WHEN** 在系统管理模块下新增标准列表页面
-- **THEN** 操作列首位 SHALL 包含「查看」按钮，且 `el-table` SHALL 绑定 `@row-dblclick="handleView"` 事件
-- **THEN** 点击「查看」按钮或双击行 SHALL 打开同一 `SystemViewDialog` 弹窗
+#### Scenario: 新增标准 CRUD 列表页
+
+- **WHEN** 在 `web-admin` 新增带只读查看弹窗的标准 CRUD 列表页，且行级动作仅为编辑/删除
+- **THEN** 主标识列 SHALL 使用 `el-link type="primary"` 触发 `handleView`
+- **THEN** 表格 **SHALL NOT** 包含「操作」列
+- **THEN** 工具栏 SHALL 在「新增」之后提供「编辑」（单选可用）与「删除」（批量可用）按钮
+- **THEN** `SystemViewDialog` SHALL 通过 `#hero-actions` 提供「编辑」「删除」
+- **THEN** `el-table` SHALL 绑定 `@row-dblclick="handleView"`（或等价 handler）
 
 #### Scenario: 现有页面补充查看弹窗
 
-- **WHEN** 为现有列表页补充查看弹窗
-- **THEN** SHALL 同时添加操作列「查看」按钮与 `@row-dblclick` 双击事件，两者调用同一个 `handleView` 函数
+- **WHEN** 为现有列表页补充查看弹窗，且行级动作仅为编辑/删除
+- **THEN** SHALL 在主标识列添加 `el-link` 与 `@row-dblclick` 双击事件，两者调用同一个查看函数
+- **THEN** SHALL NOT 在操作列再添加「查看」按钮
+- **THEN** SHOULD 移除「操作」列，将「编辑」「删除」迁移至工具栏与 `#hero-actions`
 
-#### Scenario: Code review 查看弹窗
+#### Scenario: 保留操作列的复杂业务列表
 
-- **WHEN** PR 修改列表页面且页面包含 `el-table`
-- **THEN** 审查者 SHALL 确认 `el-table` 绑定了 `@row-dblclick` 事件，且操作列包含「查看」按钮
+- **WHEN** 列表页存在审批、状态变更、安排运输等行级状态依赖按钮
+- **THEN** **SHALL** 保留操作列并设置 `fixed="right"`
+- **THEN** 主标识列仍 SHALL 提供 `el-link` 查看入口，操作列 **SHALL NOT** 包含冗余「查看」按钮
+
+#### Scenario: Code review 列表查看与 CRUD 入口
+
+- **WHEN** PR 修改列表页面且页面包含 `el-table` 与只读查看能力
+- **THEN** 审查者 SHALL 确认主标识列含 `el-link` 查看入口
+- **THEN** 审查者 SHALL 确认 `el-table` 绑定了 `@row-dblclick` 事件
+- **THEN** 若为标准 CRUD（仅编辑/删除），审查者 SHALL 确认无「操作」列，且工具栏与 `#hero-actions` 均提供编辑/删除
+- **THEN** 审查者 SHALL 确认操作列无冗余「查看」/「查看详情」按钮（复合主操作例外除外）
 
 ### Requirement: 查看弹窗 KV 布局与组件选型
 
@@ -376,7 +410,7 @@ interface ViewField {
 
 标准只读查看弹窗 **SHALL** 按以下顺序组织：
 
-1. **Hero**（`.view-hero`）：图标 + 主标题 + 可选 `meta` / `code` + 状态 Tag（hero-actions 插槽可选）
+1. **Hero**（`.view-hero`）：图标 + 主标题 + 可选 `meta` / `code` + 状态 Tag；**标准 CRUD 列表页**的「编辑」「删除」SHALL 通过 `#hero-actions` 插槽置于 Hero 区右侧（见「列表主标识列链接查看与编辑删除外置」），Footer 仍仅保留「关闭」类按钮
 2. **分区**（`.view-section`）：区块标题 + `ViewKvGrid` / `ViewKvTable` 或具名插槽（子表、附件、审批流等）
 3. **Footer**：仅「关闭」类按钮（带 `Close` 图标），**SHALL NOT** 在查看态混入提交语义
 
@@ -441,7 +475,9 @@ interface ViewField {
 
 #### Scenario: 新增 CRM 列表查看弹窗
 
-- **WHEN** 在 CRM 模块新增带【查看】按钮的列表页
+- **WHEN** 在 CRM 模块新增带只读查看能力的标准 CRUD 列表页（行级动作仅为编辑/删除）
+- **THEN** 主标识列 SHALL 使用 `el-link` 触发查看，表格 **SHALL NOT** 含「操作」列
+- **THEN** 工具栏与 `SystemViewDialog` `#hero-actions` SHALL 提供「编辑」「删除」
 - **THEN** SHALL 使用 `SystemViewDialog`（或独立 `*DetailDialog` 封装该组件）
 - **THEN** KV 字段 SHALL 通过 `ViewSection[]` + `ViewField[]` 定义，默认 4 列上下堆叠
 - **THEN** SHALL NOT 使用 `el-descriptions`
@@ -490,7 +526,7 @@ interface ViewField {
 
 #### Scenario: 站点管理查看弹窗
 
-- **WHEN** 用户点击站点管理列表中某行的「查看」按钮
+- **WHEN** 用户点击站点管理列表中主标识列（站点名称）链接
 - **THEN** 「经营范围」字段 SHALL 展示为编码对应的标签文本（如"蔬菜、水果"），SHALL NOT 展示原始编码串（如"1,2"）
 
 #### Scenario: 新增包含字典编码字段的查看弹窗
@@ -901,9 +937,9 @@ watchDebounced(
 | 展开更多 / 收起更多 | `ArrowDownBold` / `ArrowUpBold` | 筛选区 `.btn-filter-toggle`（默认折叠多行条件时） |
 | 确定 / 确认 / 提交 / 保存 | `Check` | 弹窗确认类按钮 |
 | 取消 / 关闭 | `Close` | 弹窗取消、关闭按钮 |
-| 编辑 / 修改 | `Edit` | 操作列「编辑」按钮 |
-| 删除 / 批量删除 | `Delete` | 操作列、工具栏「删除」按钮 |
-| 查看 / 详情 / 查看详情 | `View` | 操作列「查看」「详情」按钮 |
+| 编辑 / 修改 | `Edit` | 工具栏「编辑」、查看弹窗 `#hero-actions`「编辑」、操作列「编辑」按钮 |
+| 删除 / 批量删除 | `Delete` | 工具栏「删除」、查看弹窗 `#hero-actions`「删除」、操作列「删除」按钮 |
+| 查看 / 详情 | `View` | 工具栏「查看审批流」等非列表行主入口；**列表行查看由主标识列 `el-link` 或双击触发，操作列与工具栏不再放「查看」** |
 | 审批 / 审核 | `EditPen` | 操作列「审批」按钮 |
 | 配置 / 设置 | `Setting` 或 `SetUp` | 操作列「配置」按钮 |
 | 导入 / 上传 | `Upload` | 工具栏「导入」、表单「上传」按钮 |
@@ -935,7 +971,7 @@ watchDebounced(
 
 #### Scenario: 新增表格操作列按钮
 
-- **WHEN** 在表格操作列添加「编辑」「删除」「查看」等操作按钮
+- **WHEN** 在表格操作列添加「编辑」「删除」等业务操作按钮
 - **THEN** 每个按钮 SHALL 包含对应的 `<el-icon>` 子元素（如 `<el-icon><Edit /></el-icon>`），SHALL NOT 仅有文字
 
 #### Scenario: 新增工具栏主操作按钮