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

ADDED Requirements

Requirement: Web 管理端以 Fresh Mint 规范为唯一视觉权威

web-admin 工程的界面实现 SHALL 以 docs/web-admin-ui-spec-fresh-mint.md 及其中引用的 docs/fresh-mint-green.html 为权威来源；主色链 SHALL 使用文档定义的 Mint 绿系（如 --primary #10b981 等），不得擅自替换为小程序品牌色。

Scenario: 新增列表页

• WHEN 在 web-admin 新增标准列表/表单页
• THEN 页面结构 SHALL 对齐规范中的布局顺序（筛选 → 工具栏 → 列表 → 分页等）及模板页（如 #/demo/unit、#/demo/order）所体现的模式

Requirement: 小程序以三墙 Demo 体系为唯一视觉权威

miniprogram 工程的界面 SHALL 以 docs/miniprogram-ui-spec-sanqiang.md 及其中列出的 mobile-ui/sanqiang-*.html 为权威来源；品牌绿、大麦黄与中性色 SHALL 采用规范 §2 Token，不得直接复用 Web 端 Fresh Mint 色板作为主色。

Scenario: 新增小程序页面

• WHEN 新增客户端/供应商/配送端页面
• THEN 页面 SHALL 遵循规范中的统一骨架（Header 渐变、卡片圆角节奏、底部固定区等）及状态标签语义色

Requirement: 禁止跨端调色板混用

除非产品书面要求，Web 管理端 SHALL NOT 使用小程序规范中的 #0a9f6d 等作为主色；小程序 SHALL NOT 使用 #10b981 作为主色替代品牌绿。

Scenario: Code review

• WHEN PR 修改全局主题或主按钮色
• THEN 审查者 SHALL 对照对应端 UI 规范文档中的 Token 表拒绝跨端拷贝色值

Requirement: 树形主数据展示规则

涉及树形主数据（分类、库位、组织等）时，Web 端 SHALL 遵循：下拉/树节点展示本级名称，选中后在输入框、表格、导出与查看弹窗中展示全路径；路径分隔符 SHALL 与工程约定一致（当前为 /，见 web-admin/src/utils/tree-path.ts 与规范 §5.6）。

Scenario: 树选择与表格列

• WHEN 用户在树形选择器中选择末级节点
• THEN 表格与只读视图 SHALL 展示完整祖先路径而非仅末级名称

Requirement: 弹窗与遮罩

Web 管理端弹窗 SHALL 遵循规范：表单 label-position="top"；遮罩 SHALL NOT 使用背景模糊（backdrop-filter: none 等与仓库既有策略一致）。

Scenario: 新增编辑弹窗

• WHEN 使用 Element Plus el-dialog 承载表单
• THEN 表单标签位置与遮罩样式 SHALL 符合 docs/web-admin-ui-spec-fresh-mint.md 中 el-dialog 小节

Requirement: 小程序媒体与触控

小程序列表缩略图、轮播与详情图 SHALL 遵循 docs/miniprogram-ui-spec-sanqiang.md §7.0 的宽高比与 mode 约定；可点击控件 SHALL 满足最小触控区域（规范中的 44×44 等要求）。

Scenario: 商品列表缩略图

• WHEN 展示商品列表缩略图
• THEN 图片区域 SHALL 为 1:1 且使用 aspectFill（与规范 §7.0.1 一致）

Requirement: 列表面板主标题装饰

web-admin 中列表面板 panel-top 下的主标题（h2.title-bar-heading）SHALL 在标题文案前展示 主色竖条（与全局 app.scss 中 h2.title-bar-heading::before 一致）；含「租户」「用户」等易歧义文案的标题 SHALL 通过 App.vue 中 panelTitleBarTextRules 显式纳入竖条样式，避免子串误匹配为其它图标。

Scenario: 租户列表标题

• WHEN 打开 #/system/tenant 租户管理页
• THEN 「租户列表」标题 SHALL 显示绿色竖条装饰，且 SHALL NOT 因「租户」含「用户」子串而显示用户类图标

Requirement: 新增与编辑弹窗布局与视口留白

使用 Element Plus el-dialog 承载新增/编辑表单时，系统 SHALL 满足：

1. 水平栅格：默认使用 两列 栅格（.form-grid-2，grid-template-columns: repeat(2, minmax(0, 1fr))，gap: 12px 20px）；字段较多时 SHALL 通过加宽 width 并选用 .form-grid-3、.form-grid-4 或 .form-grid-5 扩展列数，列数上限为 5；跨整行长字段 SHALL 使用 .form-col-span-2（grid-column: 1 / -1）。
2. 窄屏回退：视口或表单区过窄时，栅格 SHALL 回退为更少列或单列（与全局 app.scss 中 @media (max-width: 900px)、(max-width: 560px) 规则一致）。
3. 定位：弹窗 SHALL 相对视口水平与垂直居中（依赖 ElConfigProvider 的 dialog.alignCenter 及 Element Plus 默认遮罩层居中行为）。
4. 高度与滚动：使用 .dialog-form-layout 类名的弹窗壳层 SHALL max-height: calc(100vh - 100px)，保证相对视口上下各 至少约 50px 可视留白；弹窗 SHALL NOT 以固定高度占满视口；当内容超出时 仅 .el-dialog__body 区域出现纵向滚动条，页头与底栏固定不滚动。

Scenario: 租户新增弹窗

• WHEN 在租户管理页打开新增或编辑租户弹窗
• THEN 表单 SHALL 以两列栅格展示常规字段、备注跨两列；弹窗 SHALL 带 dialog-form-layout 且正文区在内容过多时可滚动

Scenario: 高字段数弹窗

• WHEN 某业务弹窗字段超过两列舒适排布
• THEN 实现 SHALL 增加 el-dialog 的 width 并选用 form-grid-3 至 form-grid-5 之一，且 SHALL NOT 使用超过 5 列的栅格类

Requirement: 图标组件使用 Element Plus 图标

web-admin 中的图标 SHALL 优先使用 Element Plus 内置图标（@element-plus/icons-vue），通过 ArtSvgIcon 组件的 EP 图标映射（src/utils/ui/ep-icon-map.ts）渲染；SHALL NOT 在新增代码中直接使用 Iconify 远程图标名（如 ri:xxx、fluent:xxx）。仅在 Element Plus 无等价图标时，方可保留 Iconify 图标名作为例外。

Scenario: 新增菜单路由

• WHEN 在 src/router/modules/ 中新增路由并设置 meta.icon
• THEN icon 值 SHALL 使用 ep-icon-map.ts 中已注册的名称（如 setting、grid），SHALL NOT 使用 ri: 前缀的 Iconify 名

Scenario: 新增界面图标

• WHEN 在页面或组件中新增图标
• THEN SHALL 使用 <ArtSvgIcon icon="ep-icon-name" /> 或 <el-icon><XxxIcon /></el-icon>，SHALL NOT 使用 <ArtSvgIcon icon="ri:xxx" /> 除非 Element Plus 无等价图标

Scenario: 新增 Element Plus 图标

• WHEN Element Plus 提供了新的所需图标但 ep-icon-map.ts 尚未注册
• THEN 开发者 SHALL 先在 ep-icon-map.ts 中注册映射条目，再在业务代码中使用

Requirement: 表格操作列固定在右侧

web-admin 中所有业务列表页（系统管理、业务模块等，不含 Demo 参考页）的 el-table 操作列 SHALL 使用 fixed="right" 固定在表格右侧。宽度规则：2 个按钮时 width="260"，3 个按钮时 width="320"，4 个及以上按钮时 width="400"。全局 CSS 通过 .el-table-fixed-column--right 选择器（注意：Element Plus 使用单短横线，非双下划线）提供固定列样式。

Scenario: 新增系统管理列表页

• WHEN 在系统管理模块下新增列表页面（如用户管理、角色管理等）
• THEN 表格操作列 SHALL 设置 fixed="right"，宽度按按钮数设置：≤ 2 按钮用 width="260"，3 按钮用 width="320"，≥ 4 按钮用 width="400"

Scenario: Code review 表格列

• WHEN PR 包含新增或修改的 el-table-column 且 label="操作"
• THEN 审查者 SHALL 确认该列包含 fixed="right" 属性，且宽度与按钮数量匹配（2 按钮 260px，3+ 按钮 320px）