450 lines
58 KiB
Markdown
450 lines
58 KiB
Markdown
# Admin 界面规范
|
||
|
||
本文件是 **Admin 样式的唯一主规范**，统一维护蓝白风格、业务密度、列表、详情、弹窗、提示文字与公共样式接入。沿用原文件路径，已有引用无需迁移。验收视口为 **1920×1080，浏览器缩放 100%**。
|
||
|
||
## 按任务阅读
|
||
|
||
先看本节和“基本原则”，再只读任务对应章节，不要求每次通读全文。
|
||
|
||
| 当前任务 | 本文入口 |
|
||
|---|---|
|
||
| 调整列表、搜索、页签、行操作 | [列表](#列表)、[尺寸与颜色](#尺寸与颜色) |
|
||
| 调整详情、费用、历史或测量 | [详情与基本信息](#详情与基本信息)、[费用、汇总与测量](#费用汇总与测量)、[历史、备注与空态](#历史备注与空态) |
|
||
| 新增、编辑、审核、上传、预览或确认弹窗 | [弹框与表单](#弹框与表单) |
|
||
| 提示小字、加载反馈、点击后页面跳动 | [提示文字与加载布局](#提示文字与加载布局) |
|
||
| 配色、工作台、指标卡或图表 | [蓝白主题与图表](#蓝白主题与图表)；需要查看样板时再打开[样板目录](界面参考/蓝白卡片式工作台风格参考.md#其他页面该参考哪个样板) |
|
||
| 公共样式维护或新页面接入 | [公共样式维护边界](#公共样式维护边界)、[新模块接入规则](#新模块接入规则) |
|
||
| 确认验收方法与证据 | [前端验收规则](Admin-Client前端原型还原验收规则.md)；其中不再另定 Admin 样式 |
|
||
|
||
## 适用范围与文档职责
|
||
|
||
- 本规范是后续 Admin 改版基线：订单与客户管理样板确立业务密度，测量样板仅供参考弹窗基础框架，其分区配色与作业布局属于局部例外；蓝白自营样板确立配色、工作台和少提示文字风格。已确认的样式优先于历史原型中的对应外观；业务字段、分组、权限、状态、API、计算口径及页面／弹窗／抽屉承载方式仍按当前业务契约和逐操作确认保留。
|
||
- 规范适用于 Admin；Client、PDA 不自动套用。按用户确定的模块和操作范围逐批实施，规范统一不代表全端已改造或验收，也不授权批量替换公共默认值或发布。
|
||
- 本文只维护当前有效规则，不并列保留已被替代的通用样式。新增确认直接修改对应条款，不在文末继续追加另一套规则。代码令牌是数值的唯一实现入口，变更须同步本文对应条款。
|
||
- [蓝白样板目录](界面参考/蓝白卡片式工作台风格参考.md)只保存页面参考和原图；[排车列表试点](Admin排车列表样式试点.md)只保存历史依据。二者不再定义通用样式。
|
||
- 模块记录只维护本模块改造范围、业务例外、检查结果与截图证据，不覆盖本文通用规则： [国内仓](Admin国内仓样式核对记录.md)、[客户管理](Admin客户管理样式核对记录.md)、[货柜管理](Admin货柜管理样式核对记录.md)、[海外仓](Admin海外仓样式核对记录.md)、[列表推广](Admin列表样式推广核对记录.md)、[自营](../apps/admin-web/src/modules/self-operated/operation-matrix.md)。只读本轮实际涉及的记录，不要求全部加载。
|
||
|
||
## 基本原则
|
||
|
||
表格顶部操作栏的基础桌面尺寸由 `DataTable.vue` 维护：`padding: 6px 12px`、`min-height: 44px`；显式接入蓝白主题的主列表使用本文“蓝白主题与图表”的 48px 最小高度。普通栏与 `.is-compact` 只改变对齐，不按 1920px 断点切换尺寸；页面不得重复声明公共 padding / height，已有移动端排列规则保留。
|
||
|
||
1. 普通业务内容采用连续白底、细边框、描述表与数据表格。短字段以“标签 + 值”连续排列，不制作独立指标卡片。
|
||
2. 先压缩重复标题、重复汇总、容器层数和无意义留白，再调整列宽与行高。正文保持可读，不通过缩小整页、浏览器缩放或截断关键值提高密度。
|
||
3. 长编号、地址、邮箱、文件名与备注允许跨列、换行或按已确认方式查看完整值。空值显示“—”或明确的未关联状态，不显示内部数据库 ID。
|
||
4. 业务状态使用现有语义色和文字。只有真实阻断、错误、风险才使用明显的警示区域。
|
||
5. 密度改造不改变计算口径、API、保存触发方式、权限资格、状态机或字段含义。遇到功能问题单独记录，不能用样式隐藏。
|
||
|
||
## 尺寸与颜色
|
||
|
||
下表是普通桌面业务布局基线；图片、长内容、错误反馈和可编辑表格可以自然增高，不能强制裁切。
|
||
|
||
| 项目 | 基线 |
|
||
|---|---|
|
||
| 正文、表格、输入文字 | 13px |
|
||
| 标签、辅助说明 | 12px；不进一步缩小 |
|
||
| 分区标题 | 14px，适度加粗 |
|
||
| 页面业务编号、弹框标题 | 16px |
|
||
| 普通页签 | 高 38px，左右内边距 16px，图文间距 6px |
|
||
| 页签图标 | 17px，固定 18px 占位，独立彩色显示 |
|
||
| 普通表格行 | 基准 36px，单元格上下内边距 4px；按内容自然增高 |
|
||
| 普通输入框与工具栏按钮 | 通常 32px |
|
||
| 表格内操作按钮 | 基准 28px；已接入标准列表使用纯文字行操作，保留焦点、禁用与处理中状态 |
|
||
| 区块间距 | 通常 12px；标准列表遵守现有 ListPageLayout 的单一间距，不叠加页级空白 |
|
||
| 普通内容内边距 | 12px；弹框正文 12px 16px |
|
||
| 容器圆角 | 普通业务数据区 0–4px；独立搜索区 5px、作业分区 8px、蓝白指标卡 16px 按各自规则，不叠加整页外框 |
|
||
| 内容底色 | 白色 |
|
||
| 表格表头 | 浅蓝底 `#edf4ff`、深蓝文字 `#284b78`，标准列表、工作台、弹框／抽屉内 Element 表格及 `density-table` 共用 |
|
||
| 描述表标签底色 | 浅灰，参考 #f8fafc / #f9fafb，不跟随表格表头变蓝 |
|
||
| 边框 | 现有 `--cc-border`；表格参考 #e5e7eb |
|
||
| 悬停、斑马纹 | 轻量区分，参考 #f3f7fb / #fcfcfd |
|
||
|
||
表头颜色由 `foundation.css` 的 `--cc-list-table-header-bg` 与 `--cc-list-table-header-text` 唯一维护。颜色优先复用当前 `--cc-*` 与 Element Plus 语义变量。金额和测量数字可使用等宽数字排版，只有总计或关键结论适度加粗，不将每个值都加粗。
|
||
|
||
## 提示文字与加载布局
|
||
|
||
2026-10-21 用户确认：Admin 页面默认不额外添加提示小字、装饰性副标题、功能介绍或独立说明行；用户明确要求展示的业务信息按实际用途保留。
|
||
|
||
- 常规加载、刷新、查询及页签切换不新增“页签数量加载中…”“数据加载中…”等独立文字行，不为每个局部请求补充提示小字。
|
||
- 加载反馈复用原位置、固定尺寸的加载图标、按钮 loading、区域遮罩或与内容等尺寸的骨架；加载前、加载中、完成后保持页签、工具栏、筛选区和表格的布局稳定，不因临时提示插入或移除而推挤内容、改变区块高度或造成页面跳动。不为被禁止的提示行额外预留空白。
|
||
- “覆盖加载状态”“保留状态反馈”不等于新增可见说明行。保留 `aria-busy` 等可访问语义；必要的读屏播报不得占用可见布局。
|
||
- 接口失败与重试、表单校验、权限限制、过期或异常状态、实际操作阻断和危险后果继续清楚反馈，在对应位置集中表达，避免重复；不得以精简小字为由隐藏影响用户判断或操作的信息。
|
||
|
||
- **详细口径按需展开。** 计算公式、统计口径、图例、来源解释和操作说明放入已有说明入口或 `InlineHelp`／tooltip，支持键盘聚焦；不为每张卡增加介绍段、装饰性副标题或长解释。确需影响判断的周期、单位和版本保留最短必要表达。
|
||
- **同一事实只讲一次。** 多张卡共用的统计周期、完整性或来源在分区层级统一表达；卡片仅显示自身特有状态。主状态、进度环、数量卡与阶段节点不重复整段等待原因。
|
||
- **异常优先合并到一个清晰入口。** 同一异常影响多块内容时，在相关区域保留一条简短状态与查看详情／重试入口；不要在每张卡和图表下重复警告。独立异常仍在对应位置明确呈现，不能合并后丢失作用范围。
|
||
- **关键异常与阻断常驻。** 当前失败、未知、陈旧、权限不足、操作阻断及危险后果必须能直接识别；细节可以展开，关键状态不能只藏进 tooltip。正常完整状态不需要逐卡反复宣告。
|
||
- **事实与视觉分开。** `0` 表示已知零值，`—` 或“待确认”表示未知；历史结果和陈旧快照要有简短标识。精简文案不得把未知显示为零、把暂停显示为完成，也不得隐藏真实风险。
|
||
|
||
库存分析样板按这套规则收敛：快照解释、“本仓概览／截至日期／采集时间”整行及图表范围说明移入已有说明入口；正常指标卡只保留名称、数值和单位，删除重复的“已确认”。真实未知、陈旧和异常继续显示简短提示。删除独占一行的“展开图表”，将图表操作并入顶部简短入口。完整数值来源、采集时点和估算细节可在说明或 tooltip 中查看；估算值必须能辨认其估算属性，不得因精简文案冒充实测值。
|
||
|
||
|
||
## 各类页面规则
|
||
|
||
### 列表
|
||
|
||
- 使用 `ListPageLayout + QueryToolbar + DataTable`，搜索／筛选区与下方表格分成独立区块，搜索区圆角统一 5px。`foundation.css` 的 `--cc-list-query-radius` 与 `--cc-list-query-gap` 维护尺寸；DataTable 筛选容器提供边框、底色及下方 16px 间距，内部 QueryToolbar 不重复套卡片。独立 QueryToolbar 使用相同圆角及列表已有区块间距。
|
||
- 同级状态／分类页签与顶部业务按钮共用工具栏：页签放 `toolbar-start`，操作放 `toolbar-actions`／`toolbar-end`，查询放 `filters`；蓝白页签加 `workbench-list-tabs`。不叠加重复路由标题、页签行、按钮行；保留真实业务子分区、统计数量、失败重试与当前范围。
|
||
- “操作”列在第一列，需要固定时固定在左侧。默认最多三个高频操作直接显示，其余用更多菜单；保留已确认的直接操作数量、权限和危险确认。更多入口为 `…`（`MoreHorizontal`），保留业务对象相关的可访问名称与悬停提示，菜单项纯文字。
|
||
- 已接入标准列表的行操作采用纯文字：无描边、填充或装饰图标，400 字重，普通操作蓝色、危险操作红色、禁用灰色、悬停无下划线。`RowActions` 用 `text-actions`；手写按钮组用 `row-actions density-actions admin-text-actions`，危险语义通过 `data-tone="danger"` 或 `type="danger"` 显式指定。统一外观由 `adminTextActions.css` 维护，不再沿用早期国内仓描边行按钮。顶部、查询及弹框提交按钮按各自用途保留，不机械套用行操作外观；尚未接入的消费者在本轮明确范围内再调整。
|
||
- 列宽按实际编号、状态和按钮数量决定，核对长编号、最多按钮、加载与权限变化；不把样板操作列宽套给所有列表。数值列右对齐，单位优先放表头；保留横向滚动、列偏好、分页和行内编辑。
|
||
- 标准 DataTable 沿用默认灰白斑马纹，不由页面显式关闭；行底色复用 `--admin-row-stripe`，悬停行、当前行及悬停单元格由 Element 状态样式处理，父表底色不穿透子表。
|
||
- `appearance="integrated"` 保留原组件组合能力，不再表示搜索与表格必须相连。样式维护在 DataTable 和公共 CSS，不为接入样式切换业务模式。
|
||
|
||
#### 公共列表能力
|
||
|
||
Admin 仍使用 Element Plus。普通 `el-select` 由构建组件解析器统一接入 `src/shared/components/AdminSelect.ts`，仅将 `filterable` 默认值设为 `true`，使用 Element Plus 原有渲染、插槽、事件和公开方法；列表、表单、弹框及分页选择框均可输入关键词筛选当前选项。已有 `remote-method`、`filter-method`、多选、禁用和清空行为保持原有配置；搜索不改变候选业务范围，也不会自动新增远程接口调用。虚拟托盘选择框 `el-select-v2` 已显式启用远程搜索。
|
||
|
||
推广时列设置显式使用 `column-settings-mode="show"`。已有 `preference-key` 保持，新接入的退货库存、流水和箱号各使用独立偏好键。存在非阻断警告时使用 `notices` 插槽，列表失败时通过 `results-visible` 隐藏结果和分页，标题、查询与重试保持可用；`before-results` 保留原统计与汇总。特殊工作台可使用 `results` 插槽承载原内容和自身分页，公共表格不重置它的页码与每页数量。
|
||
|
||
列宽保存为公共 DataTable 能力，与已有列设置一同启用（提供 `preference-key` 且列设置可用），不依赖试点样式。拖动表头边界松开时，将宽度按稳定列键写入同一份本地偏好；重排、隐藏再显示不会丢失，刷新/重新进入时恢复。账号与表格分别隔离，仅保存到当前浏览器，不跨设备同步。“恢复默认”同时重置列顺序、显隐和宽度，重新采用页面声明的 width/minWidth。未启用列设置的表格不写入列宽偏好。
|
||
|
||
#### 客户管理按钮与详情
|
||
|
||
- 客户列表、海外仓阶梯费用及关联详情、编辑、审核、预览的业务操作按钮采用纯文字；查询、重置、复制也去掉装饰图标。分页箭头、列设置、筛选布局、关闭与全屏等独立图标控件保留，处理中旋转图标保留。
|
||
- 客户列表行操作采用上文统一纯文字规则；保留原权限、操作分配、更多入口和危险确认。
|
||
- 海外仓阶梯费用列表按原档位顺序显示“天数：单价”，在费用单元格中连续排列、整组自然换行；不制作每档独立白块，不强制左右两列，不隐藏后续档位。币种只在独立列展示，计费单位保留在表头；零单价照常显示 `0`，没有档位显示“—”。列表编辑按钮沿用统一纯文字行操作。
|
||
- 阶梯费用编辑弹框中的“新增阶梯”为蓝字浅蓝边、“删除”为红字浅红边，均使用 28px 高、6px 圆角的白底纯文字按钮；客户详情的海外仓费用编辑同步执行。底部保存/取消沿用 32px 主次按钮。按钮规则同时覆盖页面与 Teleport 弹框，并显式设置普通、悬停、焦点及禁用状态，避免默认主题色覆盖。
|
||
- 客户详情保留彩色页签；企业信息用连续四组键值表，联系与合作信息保留三组键值表，长地址整行。资质文件采用连续行，企业成员使用表格。
|
||
- 客户新增/编辑保留 1120px 三列表单，入驻审核保留 1040px，箱规规则编辑保留 1200px，海外仓阶梯编辑保留 1120px。宽度属于当前内容的适配值，不推广为全局默认。
|
||
|
||
### 详情与基本信息
|
||
|
||
- 第一行集中放返回、业务编号、核心状态及主要操作。下一行用可换行摘要展示关键上下文，不使用大数字概览卡。
|
||
- 返回使用 `density-back` 轻量导航，与业务编号和状态排在同一行，保留箭头、文字、键盘焦点及原返回目标。该行并入连续白底详情区域，不为返回单独增加卡片或空白行；整柜库存的标题行与基本信息共用一个信息区。
|
||
- 页签紧接摘要。页签已表达的标题不再在正文重复占用一大行；数量、更新时间与相关操作可放紧凑工具栏。
|
||
- 短字段通常每行 4–6 组，按内容和业务分组调整，长内容跨列或整行。描述表标签浅灰、数值白底，边线连续；标签宽度以 112px 为样板参考，按字段实际长度调整。
|
||
- 保留字段顺序和业务分组，不使用会改变阅读顺序的自动密集填空布局。
|
||
- 同一个订单或实体内部的内容连续分区，不再层层套卡片。
|
||
|
||
### 费用、汇总与测量
|
||
|
||
- 汇总使用单行摘要或紧凑描述表。自动费用与其他费用保持各自业务口径，金额、单价、计费量、附加费和版本完整展示。
|
||
- 保留公式、计费依据和价格来源入口，不能为了减少行数合并不同口径的金额或重量。
|
||
- 测量各来源保留独立分组；展开时在表尾显示合计，折叠时在标题显示摘要，同一口径不在上下重复占位。
|
||
- 测量作业弹框采用用户确认的分区配色：申报与实测对比白色（`#fff`）、客户申报明细浅蓝（`#f7f9ff`）、平台实测箱规白色（`#fff`），保留细边框和 8px 圆角，不使用左侧强调色条，作为连续白底规则的局部例外。区块不得使用负外边距伸出正文；左右内边距由 `measurementDensity.css` 统一维护，通用密度规则不得将其清零。保持 1560px、92vh 居中作业弹框及原有业务分组，各区按当前确认配色呈现，不恢复已移除的绿色背景。 三个分区同级排列，客户申报不得嵌套在实测大框内。箱数、毛重、体积集中在“指标／客户申报／平台实测／差异（实测 − 申报）”表中，不在下方重复总数；未采集显示“未测量／待测量”，申报缺失显示“—”，相等显示“一致”。净重、材积重单独显示平台事实，不与申报毛重混比。 客户申报区保持只读；实际品名和预计托数放在“平台实测箱规”区，沿用原保存与权限规则。未采集时只保留主状态，有箱规和来源后显示采集来源；平台补充数据的口径说明通过提示展示。提交按钮旁显示当前订单状态、缺少测量或称重等实际阻断原因。 桌面布局中，对比区标题与客户、渠道、状态同排；申报区标题与原单据号码同排，标签和值横向排列；实测箱规标题、实际品名、预计托数及录入操作共享一行。长内容自然换行，不截断编号或缩小字号。提交阻断原因集中在固定底栏，正文不重复显示同一提示，业务状态、偏差和冲突提醒保留。
|
||
- 同一计算策略只保留一个明确操作入口，保存中、无权限、冻结与失败信息照常显示。
|
||
- 测量称重图片可用缩略图加紧凑事实行；审核称重图片使用表格承载，保留查看原图、托盘/库位信息和人工修正入口。可视化、图纸、标签预览、库位示意等按业务用途保留合适尺寸。
|
||
|
||
### 历史、备注与空态
|
||
|
||
- 大量状态历史与操作日志优先使用表格：时间、事件、状态、操作人、备注。保留全部记录和原有排序，不合并或删除相似事件。
|
||
- 长备注自然换行；简短备注也可使用连续列表。空态使用简短文字，不用大型插画或为无数据区设置大最小高度。
|
||
- 真实流程进度图可以保留，不能因日志样板是表格就删除业务需要的阶段关系。
|
||
|
||
### 弹框与表单
|
||
|
||
本节是 **Admin 弹窗基础规范** 的唯一维护入口。通用统一范围限于白底框架、基础字号与控件、标题与操作区的可用性、间距和滚动边界；不统一业务正文结构、分区数量、字段排列、固定尺寸或装饰底色。普通表单与复杂作业弹框默认白底，按各自业务组织内容。测量样板的分区配色仅适用于已明确确认的具体窗口，不自动推广到其他新增、编辑、审核、上传、预览或确认弹窗。
|
||
|
||
参考图：[测量弹窗原始截图](界面参考/Admin弹窗样板-测量.png)（原附件 `codex-clipboard-3eeb665f-6eee-437e-886b-75d3cc0dc78e.png`）。仅参考基础框架及该测量场景，不据此复制其他窗口的配色、分区、表格结构或尺寸；验收仍为 1920×1080、浏览器 100%，不按图片像素反推控件尺寸。
|
||
|
||
|
||
|
||
#### 外框、标题与滚动
|
||
|
||
- 使用白色外框、细边线和紧凑标题栏；标题为“操作名称 · 业务编号”，没有业务编号时仅显示操作名称，缺失值不以数据库 ID 补位。复用现有标题字号、字重和分隔线。
|
||
- 标题栏与底部操作区固定可见，长内容只滚动正文；同一内容区保持一个主要纵向滚动容器。明细表保留业务所需的横向滚动。
|
||
- 优先使用 `AppDialog` 的原生标题栏和已有全屏能力；关闭、全屏/退出全屏位于右上角，保留可访问名称。大型表格和作业弹窗按需启用全屏，小型确认弹窗无需强行加入全屏。
|
||
- 普通弹窗按内容自然增高，上边距参考 6vh、最大高度 88vh；测量等大型作业弹窗按已确认作业高度使用上边距 4vh、最大高度 92vh。全屏采用组件的完整视口规则。小表单不设置无业务依据的固定大高度或大块空白。
|
||
- 各操作已确认的独立页面、居中弹框或抽屉承载方式继续保留。此次统一弹窗外观不改变正式详情路由，也不将抽屉自动改成弹框。
|
||
|
||
#### 按内容选择尺寸
|
||
|
||
| 用途 | 桌面宽度参考 | 内容排列 |
|
||
|---|---|---|
|
||
| 简单确认、备注、原因填写 | 560–600px | 紧凑单列，按内容增高 |
|
||
| 普通新增、编辑 | 680–920px | 通常双列；长地址、备注、附件跨列 |
|
||
| 多字段表单、资料审核 | 1040–1200px | 短字段通常三列，按业务分组，长内容整行 |
|
||
| 批量预览、对照与选择 | 约 1100px，随实际列宽调整 | 表格为主，保留数量、逐条明细和不可操作原因 |
|
||
| 测量等大型作业 | 样板 1560px、92vh | 业务分区、作业表格和固定操作底栏 |
|
||
|
||
以上只用于没有已确认尺寸的新窗口，不作为重排现有弹框的模板，也不覆盖已有逐操作确认的业务尺寸，例如客户重置密码 520px、客户新增/编辑 1120px。复杂工作台按真实信息量保留宽高、分栏与独立工作区；宽度受视口边距约束，不靠缩小字号、隐藏字段或截断关键编号容纳内容。
|
||
|
||
#### 正文分区、配色与密度
|
||
|
||
- 默认使用白底，通过原有业务标题、间距与必要分隔线组织内容；不得因存在录入、只读、汇总或多分区就套黄、蓝、绿背景，也不为套样板新增标题、卡片或分区。
|
||
- 保留已有表单、左右分栏、主从表、步骤、树表、筛选候选、图文对照及预览区域。字段多或交互复杂不构成改成连续信息表、三列表单或同级彩色区块的理由；确有布局问题时先记录具体问题，再单独调整该窗口。
|
||
- 只读值清楚展示，可编辑控件保留可辨识的边框、焦点、标签和校验；不为了连续表外观隐藏输入特征。仅在该窗口的信息关系适合且逐项确认后使用连续编辑表，不把只读与录入强制合并、不机械横排或并入汇总末行。
|
||
- 下表只记录测量作业的已确认配色例外，不是按信息用途自动映射颜色的通用规则。其他具体窗口需要彩色分区时，在本窗口核对记录中说明业务用途与确认依据；旧批次记录中的“黄色录入区”不等于本轮已确认保留。
|
||
|
||
| 适用窗口 | 已确认分区 | 浅底色 |
|
||
|---|---|---|
|
||
| 测量作业主弹框 | 申报与实测对比 | `#fff`（白底、普通细边框） |
|
||
| 测量作业主弹框 | 客户申报明细 | `#f7f9ff` |
|
||
| 测量作业主弹框 | 平台实测箱规 | `#fff`（白底、普通细边框） |
|
||
| 测量作业主弹框 | 测量偏差提示 | `#fff`（保留红色警示文字与图标） |
|
||
|
||
- 表格单元格以白底为主，表头采用“尺寸与颜色”的统一浅蓝底、深蓝文字；普通字号、控件高度、行高、间距沿用公共令牌。单位、必填标识、校验错误、表单标签及原因说明完整保留。
|
||
- 汇总尽量只出现一次；表格已完整表达的字段不再另做统计卡片。错误、警告、成功及禁用状态继续使用现有语义，彩色分区不掩盖真实风险。
|
||
|
||
#### 输入框与字段
|
||
|
||
2026-10-22 用户确认以客户新增／编辑弹框的输入控件外观作为后续同类表单的参考；只统一控件外观与可用性，不据此复制客户的三列布局、表格结构或弹框尺寸。
|
||
|
||
- 文本、数字、日期、下拉选择及多行文本使用白底、可辨识的浅灰边框和 8px 圆角（`--cc-radius-lg`）；悬停边框加深、聚焦使用蓝色边框。普通单行控件沿用通常 32px 的公共高度，多行文本保留业务需要的行数。不能通过透明边框把可编辑内容显示成普通文字。
|
||
- 普通文本与表单数字左对齐，包括注册资本、账期等；数字增减按钮与单位、币种保留原功能。此条不改变只读数据表的金额、数量列对齐方式。
|
||
- 横向排列的表单标签与控件垂直居中，由 `adminDensity.css` 统一处理；顶部标签保持原有上下排列。普通短字段标签优先单行，较长标签按实际文字单独加宽，不缩小字号或截断标签；长地址、备注等保留已确认跨列方式。
|
||
- 占位文字简短，避免长说明被输入框截断，例如客户昵称使用“选填，默认自动生成”。标签始终保留，不能仅靠占位文字说明字段含义；详细规则确有必要时放入已有说明入口。
|
||
- 只读值直接展示，与可输入控件明确区分；禁用、权限不足、校验错误、处理中和实际操作阻断保留原反馈。精简文案不改变字段可编辑资格、保存及审核流程。
|
||
- 分区标题、已有帮助入口与该分区状态标签优先同一行，例如“企业认证资料”与“启用”；不为简短状态单独占一行。内容过长时自然换行，不强行裁切。
|
||
- 字段旁及底部不重复铺设保存／审核流程介绍、只读规则等常驻小字，按[提示文字与加载布局](#提示文字与加载布局)处理；实际风险、错误和阻断原因仍须清楚反馈。
|
||
- 实现复用 Element Plus 控件。连续编辑表内的表单通过 `density-form--outlined` 接入 [adminDensity.css](../apps/admin-web/src/styles/adminDensity.css) 的白底与中性边框规则；客户参考实现为 [CustomersView.vue](../apps/admin-web/src/modules/customers/pages/CustomersView.vue) 与 [customerDensity.css](../apps/admin-web/src/modules/customers/customerDensity.css)，后者当前限定客户编辑框的圆角和数字对齐。后续在明确修改范围内接入，通用外观维护在公共入口，不逐页复制颜色与控件规则，也不自动批量改造其他弹框。
|
||
|
||
#### 底部操作与交互
|
||
|
||
- 底部以细分隔线与正文区分，右侧排列原有取消、保存、提交等操作；一个阶段突出一个主操作，其他操作保持次级样式。按钮职责、顺序和保存触发方式按当前业务确认保留，不新增原本没有的“暂存”或“保存并提交”。
|
||
- 自定义底栏可显式使用`density-actions density-actions--footer`，由公共样式维护右对齐、换行和按钮间距，不在业务页复制底栏通用布局。
|
||
- 左侧可显示当前状态、选中数量或实际提交阻断原因，同一阻断说明集中显示；只读、预览和小型确认弹窗按其实际动作提供关闭/取消/确认。
|
||
- 审核、确认清楚展示业务对象；批量操作保留逐票预览、选中数量和不可操作原因。加载中、无数据、接口失败、无权限、禁用与处理中均应有明确反馈。
|
||
- 保留提交锁定、原有遮罩/Esc/关闭规则、未保存保护及失败上下文；全屏切换、关闭和重开不丢失应保留的输入，不允许重复提交。关闭、全屏等功能图标保留，不为统一风格给标题、字段或按钮添加装饰 Emoji。
|
||
|
||
#### 作用域与嵌套
|
||
|
||
新增、编辑先参考公共 `AppDialog`／`AppDrawer`，表单字段排列仍参考本业务已确认的样板。客户新增／编辑使用三列短字段，地址、备注和长内容跨列；小型确认框保留原宽度。智能装柜等工作台保留原有宽版和 92vh 高度，不把所有浮层压成同一尺寸。
|
||
|
||
- 标题、正文和页脚样式只匹配当前浮层的直接子节点；业务页的 `:deep` 规则也必须限定自身，不能通过任意后代选择器影响子弹框。
|
||
- 不假设 `AppDialog` 默认一定挂到 body。嵌在另一个弹框、工具栏或有裁切的容器中的独立浮层，应明确设置 `append-to-body`，并把主题类放到实际浮层根。核对关闭、重开、全屏和取消仅影响对应窗口。
|
||
- 标题与底部操作不随长正文滚走，正文使用单一纵向滚动区；真实宽表可在自己的区域横向滚动。不要通过整框 `overflow: hidden`、固定短高度或隐藏按钮解决溢出。
|
||
- 底部多按钮可换行且保持间距；已有复合底栏（统计、分页、提交等）保留自身布局，不强制改成一排普通按钮。工具栏的紧凑按钮尺寸不得传入浮层。
|
||
- 工具栏只控制自身操作按钮及已核实的包装层，遇到浮层、弹出菜单或内嵌 DataTable 就结束作用范围；保留按钮组与下拉按钮，不能为隔离而使已有操作失去样式。
|
||
- 长校验错误应占据正常布局空间，不能遮住下一行；长文件名允许换行，文件选择、上传和删除按钮保持可用宽度。必填标识、字段标签、错误和提交反馈不为清爽而删除。
|
||
|
||
#### 公共维护与分模块落地
|
||
|
||
- 框架能力维护在 `AppDialog.vue`，基础尺寸、字号和间距维护在 `adminDensityTokens.css`，通用外观维护在 `adminDensity.css`。模块保留业务结构及已确认尺寸；不得通过修改公共默认值，批量去色、重排或重置所有弹框。
|
||
- `density-dialog-section` 及其 `data-tone="summary/source/work"` 是既有彩色分区实现能力，不是所有弹框的必选结构；仅在明确确认保留的场景使用。分区标题类为 `density-dialog-section__title`，容器类为 `density-dialog-sections`，存在公共类不构成采用理由。普通弹窗通过 `admin-density-dialog` 接入基础外观；抽屉按实际查看／编辑用途保留 `admin-density-drawer--detail`／`admin-density-drawer--editor` 等边界，不因此改成连续编辑表或复制测量分区。共用 `--admin-dialog-*` 令牌只统一基础能力。
|
||
- 确有必要且已确认的弹窗说明使用 `density-dialog-note`，由公共样式维护外观；是否展示遵循“提示文字与加载布局”，不因存在说明类就新增小字。
|
||
- JSON及原文快照显式使用 `density-code-block`，由公共样式维护代码字号、底色和边框；长内容完整换行，沿用外框正文滚动，不另设固定高度、内容截断或纵向滚动。快照属于诊断证据，不据此将数据库ID展示为业务编号。
|
||
- 连续信息表需要单元格编辑时，在 `density-table` 上显式添加 `density-table--editable`；数值与单位使用 `density-table-editor` 横排。输入的普通边框融入表格，保留悬停、键盘焦点及禁用反馈；页面只配置标签列宽和字段排列，不复制输入框外观。
|
||
- 小表单继续使用 `density-form`；末项已有明确紧凑尾距约定时显式添加 `density-form--flush-end`，不改变其他表单末项为校验错误保留的空间。
|
||
- Teleport 弹框自身显式使用 `admin-density-dialog`，原有 `ElMessageBox` 使用 `admin-density-confirm`；原生 `el-dialog` 的外观按同一规范接入，是否收敛到 `AppDialog` 按实际能力和消费者核对，避免一次替换全部弹窗。抽屉继续使用既有 `admin-density-drawer` 边界。
|
||
- 已改造弹框按原固定编号清单逐项复核，方法见 [前端验收规则](Admin-Client前端原型还原验收规则.md#执行与验收)。每项先核对改造记录、当前实现及实际截图，再决定保留或局部修正；一个样板通过不授权批量推广其业务布局和配色。共享弹框记录全部直接调用方，已有代码检查与历史截图不能替代本次视觉确认。
|
||
- 后续每个大模块按同一流程开展，进度和截图结论写入对应模块核对记录；本规范只维护稳定规则。页面字段、状态、权限、接口、计算口径、校验和提交逻辑继续按当前业务契约执行。
|
||
- 代码检查与人工视觉结论分别报告，逐项核对普通/全屏/关闭重开、长内容、空态、错误和权限状态；缺少截图时标记“待人工截图确认”。按模块汇总发布范围，部署继续沿用对应环境授权规则。
|
||
|
||
## 彩色图标
|
||
|
||
导航性质的详情页签采用与客户管理一致的彩色 Emoji，同一语义尽量复用同一图标：
|
||
|
||
| 语义 | 图标 |
|
||
|---|---|
|
||
| 基本信息 | 📋 |
|
||
| 货品、货物明细 | 📦 |
|
||
| 费用 | 💰 |
|
||
| 历史、日志 | 📝 |
|
||
| 测量、尺寸 | 📐 |
|
||
| 其他资料 | 🗂️ |
|
||
| 拆分履约 | 🧩 |
|
||
| 计费规则（客户管理已有） | ⚖️ |
|
||
|
||
图标只作辅助，保留文字标签；装饰图标设置 `aria-hidden="true"`。选中态通过文字色和底部横线表示，不把 Emoji 强制染成单色。采用系统彩色 Emoji 字体，不引入图片生成或外部图标下载依赖。
|
||
|
||
彩色图标用于详情页签。国内仓 7 个菜单的行内按钮与客户管理业务操作使用纯文字；返回箭头、顶部与弹框的既有功能图标可保留。不要给操作按钮、表头或字段添加 Emoji。
|
||
|
||
## 实现与验收
|
||
|
||
逐操作矩阵、人工截图与自动检查的证据要求统一见 [前端验收规则](Admin-Client前端原型还原验收规则.md)。本规范不记录通过状态；缺少截图保留“待人工截图确认”。实现前核对实际路由与直接消费者，保持字段、单位、排序、权限、提交及错误处理，测试不能锁定已废弃外观或删掉业务断言。
|
||
|
||
## 蓝白主题与图表
|
||
|
||
### 视觉基线与维护入口
|
||
|
||
| 维护内容 | 唯一实现入口 |
|
||
|---|---|
|
||
| DOM 配色、字号、间距、圆角、阴影与辅助色 | [`adminWorkbenchTokens.css`](../apps/admin-web/src/styles/adminWorkbenchTokens.css) |
|
||
| 标题、指标卡、列表外壳、页签、阶段、图表空态与弹窗外观 | [`adminWorkbench.css`](../apps/admin-web/src/styles/adminWorkbench.css) |
|
||
| Canvas 图表字体、颜色、坐标网格与提示框主题 | [`adminWorkbenchChartTheme.ts`](../apps/admin-web/src/styles/adminWorkbenchChartTheme.ts) |
|
||
| 显式接入范围、变量归属、公共类与浮层作用域合同 | [`adminWorkbench.test.ts`](../apps/admin-web/src/styles/adminWorkbench.test.ts) |
|
||
| 原有表格、控件和弹窗密度 | [`adminDensityTokens.css`](../apps/admin-web/src/styles/adminDensityTokens.css)、[`adminDensity.css`](../apps/admin-web/src/styles/adminDensity.css) |
|
||
| 弹框与抽屉的标题、正文滚动和底部操作 | [`AppDialog.vue`](../apps/admin-web/src/shared/components/AppDialog.vue)、[`AppDrawer.vue`](../apps/admin-web/src/shared/components/AppDrawer.vue)；真实 Element 挂载回归见 [`AppDialog.layout.test.ts`](../apps/admin-web/src/shared/components/AppDialog.layout.test.ts) |
|
||
|
||
下列取值只用于显式 `admin-workbench` 主题内的对应元素；业务表格、控件与表单继续沿用上文密度值。代码以对应令牌为准，修改数值只改唯一实现入口并同步本表，不在页面重新声明默认值。
|
||
|
||
| 项目 | 样板基线 |
|
||
|---|---|
|
||
| 主操作与链接 | `--workbench-primary`，`#3784FA`；悬停、按下与禁用使用配套令牌 |
|
||
| 重点数字 | `--workbench-number`，`#1890FF` |
|
||
| 正文与辅助文字 | `--workbench-text`，`#1F2937`；`--workbench-muted`，`#64748B` |
|
||
| 表面与边框 | 白色主体，浅灰蓝辅助区；`--workbench-border`，`#E5EAF2` |
|
||
| 卡片与图标底座 | 卡片圆角 16px、图标底座圆角 12px，低强度阴影；使用公共令牌 |
|
||
| 普通指标卡高度 | `--workbench-metric-min-height: 186px`；长内容可自然撑高，紧凑指标不继承此最小高度 |
|
||
| 空间 | 外壳内容区上／左右 12px、底部 16px；工作台根内边距 `--workbench-page-padding: 12px`；区块间距仍为 24px，普通卡片内边距 20px、紧凑卡片内边距 14px、同级网格间距 18px |
|
||
| 主列表顶部 | 工具栏最小高度 48px、上下内边距 6px；筛选区上下 8px；两区左右统一 12px，普通按钮与筛选控件 32px；内容多时自然换行，不截断或固定总高度 |
|
||
| 主列表底部分页 | 最小高度 48px（border-box）、上下内边距 6px、左右 12px，与筛选区对齐；保留 32px 翻页按钮和长统计换行，不沿用集成列表旧的 64px 高度、14px 上下留白 |
|
||
| 文字层级 | 页标题 24px、分区标题 18px、普通指标名称 15px、重点数字 34px、紧凑指标数字 26px |
|
||
| 辅助色 | 青、绿、紫、黄、红用于图标、分区与真实状态，不能代替状态文字 |
|
||
|
||
白色和细边框负责分层，不反复套大卡片；标题与数值形成重点，单位和补充说明降低权重。蓝色强调重点数据，不要求所有数字着色。红、黄继续表示风险、失败或警告；趋势是否改善由业务决定，不能仅凭上涨或下降设绿色。
|
||
|
||
原有 `--admin-*` 密度默认值继续有效。公共控件、表格行高、行内操作、弹窗尺寸和滚动由原组件与密度规范管理；蓝白外观只在显式主题范围内生效。
|
||
|
||
页面边缘采用紧凑双层留白：`.page-container` 与 `.admin-workbench.admin-page` 分别使用 12px，避免旧外壳 20px 再叠加工作台 24px 挤占内容。页边距与区块间距使用独立令牌，不通过缩小表格行高、控件或文字来换空间。
|
||
|
||
页面内复用另一个完整 `AdminPage` 时，仅在嵌入调用上显式加 `is-embedded`，去掉内层重复 padding；独立路由打开仍保留原页边距。订单内的测量审核分支是此用法的参考。不要在业务页重复声明公共间距变量，也不要全局清空所有面板内距。
|
||
|
||
整页主体是一块连续白底，不再额外套一圈边框、圆角和阴影。包住主要列表的 `workbench-table`／`workbench-toolbar` 或整页详情 `workbench-panel` 显式增加 `is-page-surface`；内部指标、图表、并列独立面板继续保留细边框，表格单元格、表头和操作分隔线也保留。不能通过清除全部 `border` 把卡片、控件和表格边界一起抹掉。
|
||
|
||
详情主容器的 `workbench-panel.is-page-surface` 在屏幕展示时不再叠加 padding，即使同时有 `is-compact` 也由外层页面或业务分区提供唯一一层留白。独立预装／装柜清单详情和货柜内的清单页签按此规则接入；内部独立紧凑卡片仍为 14px，普通卡片仍为 20px。该规则排除 `AdminPage` 页根并仅用于屏幕，不覆盖页面原有 12px 或打印内距。
|
||
|
||
### 公共样式接入
|
||
|
||
页面直接导入 `@/styles/adminWorkbench.css`，保留原有密度入口，并在实际页面根容器增加 `admin-workbench`。不依赖先打开样板页后残留的 CSS，不将主题放入全局入口，不修改 `:root`。导航、顶栏、页签由总控在各自容器显式接入，不给包含业务页面的 `.app-shell` 或 `.app-main` 添加主题类；业务页和 Teleport 浮层仍须自己接入。
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import '@/styles/adminDensity.css'
|
||
import '@/styles/adminWorkbench.css'
|
||
// 继续使用该页面原有数据、筛选、权限与事件。
|
||
</script>
|
||
|
||
<template>
|
||
<AdminPage class="admin-density admin-workbench">
|
||
<ListPageLayout>
|
||
<div class="workbench-table is-page-surface">
|
||
<DataTable :data="rows" :columns="columns">
|
||
<!-- 原有工具栏、查询和操作插槽 -->
|
||
</DataTable>
|
||
</div>
|
||
</ListPageLayout>
|
||
<AppDialog
|
||
v-model="detailOpen"
|
||
class="admin-density-dialog admin-workbench is-dialog"
|
||
>
|
||
<!-- 原有内容与尺寸配置 -->
|
||
</AppDialog>
|
||
</AdminPage>
|
||
</template>
|
||
```
|
||
|
||
这个片段只说明主题作用域。`rows`、`columns`、弹窗宽高、事件与组件导入仍按目标页原实现补齐，不代表需要新建弹窗或更换承载方式。
|
||
|
||
| 场景 | 公共类与用法 |
|
||
|---|---|
|
||
| 页头与分区 | `workbench-heading`、`workbench-title`、`workbench-meta`、`workbench-section`、`workbench-section-heading`、`workbench-section-title`、`workbench-badge` |
|
||
| 普通指标卡 | `workbench-metric`、`workbench-metric-heading`、`workbench-icon`、`workbench-metric-label`、`workbench-metric-value`、`workbench-status`、`workbench-note` |
|
||
| 紧凑指标 | 在指标卡和图标上增加 `is-compact`；不继承总览卡片的最小高度 |
|
||
| 面板与提示 | `workbench-panel`、`workbench-notice`、`workbench-skeleton`；紧凑／自带头部面板使用 `is-compact`／`is-flush` |
|
||
| 图表与空态 | `workbench-chart`、`workbench-chart-heading`、`workbench-chart-title`、`workbench-chart-actions`、`workbench-chart-canvas`、`workbench-chart-empty`、`workbench-chart-empty-icon` |
|
||
| 标准列表 | **外层 `div.workbench-table` 包裹 DataTable**，统一外框、表头、边框、行悬停和分页强调；不修改业务列宽或行密度 |
|
||
| 整页主要内容 | 主要列表的 `workbench-table`／`workbench-toolbar`、整页详情的 `workbench-panel` 增加 `is-page-surface`，去掉整页外框、圆角和阴影；详情主容器的屏幕 padding 为 0，保留页面根及内部卡片内距；主表顶部同时使用公共紧凑高度与左右边界，子表格不自动套用 |
|
||
| 嵌入完整页面 | 仅在嵌入调用上加 `is-embedded`，清除内层 AdminPage 的重复内距；独立路由不加 |
|
||
| 独立查询区 | QueryToolbar 自身添加 `workbench-query`，保留控件与换行；位于 DataTable 的筛选区时由外层提供独立搜索区的边框、底色及间距，内部不重复套卡片 |
|
||
| 列表页签与操作 | 页签放 `toolbar-start` 并加 `workbench-list-tabs`，按钮保留原操作插槽；标准主表统一 48px 最小工具栏、32px 控件，无需销量页专属紧凑类。保留自动换行与键盘切换，嵌套表格、详情和弹框不继承该布局 |
|
||
| 只有查询工具栏 | 外层 `div.workbench-toolbar` 包裹 DataTable，保留组件原有工具栏和筛选排列 |
|
||
| 原生页签与输入 | 页签父级 `workbench-tabs`，保留按钮的 `aria-pressed` 和点击事件；原生输入使用 `workbench-input`，页面只保留业务宽度 |
|
||
| 阶段节点 | `workbench-step`、`workbench-step-index`，从已确认的 `data-state` 选择状态，不从任务名或阶段顺序推断完成 |
|
||
| 证据内容 | 容器 `workbench-evidence`；已有 `density-table` 保留行密度 |
|
||
| 详情与表单 | 显式主题根保留原密度类，已有 `density-detail-*`、`density-fields`、`density-descriptions`、`density-form`、`density-form-section` 适配中性外观；字段列数、字号、业务色、校验及尺寸保持原契约 |
|
||
| 抽屉 | 实际根使用 `admin-density-drawer admin-workbench is-drawer`，保留原有详情／编辑 modifier、方向、宽度、贴边形态和正文滚动 |
|
||
| 白色品牌资源底座 | `workbench-brand-mark` 提供蓝底与公共圆角；图片比例、容器宽高由实际布局决定，不替换品牌图形 |
|
||
| 辅助色 | 元素增加 `workbench-tone`，按需选择 `data-tone` 为 `blue`、`teal`、`green`、`purple`、`amber` 或 `rose`；语义胶囊可加 `workbench-badge is-toned` |
|
||
|
||
DataTable 的属性透传目标是内部表格，不能只把 `workbench-table` 加到组件上就认为外框已接入。默认与 integrated 模式各保留原密度，不能为了外观切换模式。Teleport 弹框必须自身带 `admin-workbench is-dialog`，页面祖先不能替代；同时保留 `admin-density-dialog`、全屏、关闭、重开和正文滚动规则。抽屉使用 `is-drawer`，不能套用弹窗类改变承载。
|
||
|
||
业务页只保留列数、排列、业务宽度与高度；接入公共类后删除被接管的私有配色、边框和标题外观，不能保留两套 CSS 再叠加优先级或 `!important`。共享组件应明确接入模式并核对实际调用者，避免影响尚未推广的页面。
|
||
|
||
### 图表与数据表达
|
||
|
||
Canvas 图表显式导入 `adminWorkbenchChartTheme`，在 option 构建处组合字体、轴标签、网格、颜色与 tooltip；不注册全局 ECharts 主题。业务 option 入口分别为 [`skuTrendChart.ts`](../apps/admin-web/src/modules/self-operated/skuTrendChart.ts)、[`dashboardChartOptions.ts`](../apps/admin-web/src/modules/self-operated/dashboardChartOptions.ts)、[`turnoverPresentation.ts`](../apps/admin-web/src/modules/self-operated/turnoverPresentation.ts)。
|
||
|
||
- 趋势使用蓝色直线和轻面积。只有连续完整数据段可以填充，未知与缺失日期继续断线，未完整日继续以虚线／空心点表达。
|
||
- 柱图使用圆角、真实数值尺度和清晰单位；未知分类用灰色并显示文字，不把缺失量补成零。排名、tooltip 内容、精度和点击业务键由业务模块负责。
|
||
- 进度环只表达当前已知阶段；总量未知、分母为零或数量异常时保留未知状态。待机不等于全部完成，当前阶段 100% 不代表报表已发布。
|
||
- 普通、加载、空数据、错误和部分数据都保留已有语义。减少装饰不能删掉覆盖不足、过期、权限或操作阻断提示。
|
||
- 图表面积按用途选择。库存周转保留 360px 面板及内部伸缩画布，不机械套用固定画布类；体积图保留右侧数值标签空间。长标签、长数字及单位不得挤出可视区域。
|
||
|
||
- 同类指标统一千分位，保留业务小数精度和单位，不为排版缩写成“万”或先舍入再计算；筛选文案明确对象，不使用多个无上下文的“全部”。
|
||
- 运行看板区分主状态、阶段进度、发布结果及等待原因；已关闭／暂停与保留进度应同时可辨认，不把保留进度表达为正在续采。采集完整与修订核对未知分别表达。
|
||
- 横向宽表保留业务标识的可见性；只读库存表可固定 SKU 首列，有操作列的业务表仍将操作列放第一列。按钮按用户理解的结果命名，保留原行为、权限和禁用条件。
|
||
|
||
### 导航外壳
|
||
|
||
自营样板不包含导航外壳；后续 Admin 推广由总控统一维护公共样式、共享组件和外壳，各业务任务按实际消费者逐模块接入。外壳参考 `AppLayout.vue`、`WorkspaceTabs.vue` 和 `shell.css`：白色顶栏、蓝色激活态、轻分隔线，现有白色 Logo 保留蓝底承载；折叠菜单和页签下拉单独声明 `popper-class` 主题范围。保留菜单尺寸、彩色图标、未保存标记、权限与页签行为，不能通过全局注入主题或替换所有 Element 默认样式跳过验收。Client、PDA 不自动套用。
|
||
|
||
折叠侧栏保留 76px 宽度，展开仍为 240px。菜单宽度随纵向滚动条占用后的实际可用空间伸缩，折叠触发器去掉重复横向 padding 和图标右边距并居中；侧栏只允许纵向滚动，悬浮子菜单继续 Teleport 到侧栏滚动区之外，不能为去掉横向滚动条而裁切子菜单。
|
||
|
||
## 公共样式维护边界
|
||
|
||
<a id="国内仓客户管理的样式维护边界"></a>
|
||
|
||
密度、蓝白主题与基础组件分别维护各自能力；模块只提供字段、列数、跨列、业务宽高及已确认例外，不重复定义公共默认值。下表适用于本轮已明确接入的实际消费者。
|
||
|
||
| 要修改什么 | 唯一维护位置 | 页面需要做什么 |
|
||
|---|---|---|
|
||
| 正文/辅助/分区/页头字号 | `adminDensityTokens.css` 的 `--admin-font-*` | 引用变量，不重新写 13px 等普通字号 |
|
||
| 表格行高、输入高度、操作按钮高度、页签高度 | `--admin-row-height`、`--admin-control-height`、`--admin-action-height`、`--admin-tab-height` | 使用已有公共组件和公共类 |
|
||
| 常用间距、圆角、普通数据区底色 | `--admin-space-*`、`--admin-radius`、`--admin-surface` 等 | 业务布局引用变量；不可在页面重定义变量默认值 |
|
||
| 表头配色、独立搜索区圆角与间距 | `foundation.css` 的 `--cc-list-table-header-*`、`--cc-list-query-*` | 标准组件消费统一值，不在模块重定义 |
|
||
| 列表纯文字行操作 | `adminTextActions.css`，`RowActions` 的 `text-actions`／手写组的 `admin-text-actions` | 保留动作资格与显式危险语义，不复制旧描边行按钮 |
|
||
| 描边按钮外观、悬停/禁用/焦点状态 | `adminDensity.css` 的 `.density-action` | 只选择 `data-tone` 与业务事件 |
|
||
| 列表状态／分类页签（国内订单、尾程订单、车辆、供应商、整柜业务、国内／海外货柜工作台、退货库存） | `adminDensity.css` 的 `.density-status-tabs` | 原生按钮使用 `is-active`，Element 页签同时保留 `density-element-tabs`；保留业务分类、图标、数量、查询与切换，不在页面复制页签样式；详情页签继续使用原有详情规则 |
|
||
| 详情返回导航 | `.density-back` | 使用 `link`，保留返回事件和可访问名称；客户管理按纯文字约定保留返回文字 |
|
||
| 详情页头与业务摘要 | `.density-detail-header` / `.density-detail-heading` / `.density-detail-title` / `.density-detail-overview` | 与国内订单样板共用排版；页面提供实际业务编号、状态及摘要，不复制标题字号和摘要间距 |
|
||
| 连续白底独立详情容器 | `DetailPageLayout` 上的 `.density-detail-layout` | 显式接入统一页头分隔线、正文间距与零区块间隙；正文去掉重复面板，业务仅保留列数和长字段跨列 |
|
||
| 详情页签及彩色图标 | `.density-tabs`、`.density-tab-icon` | 保留标签、键盘事件和激活态；只配置业务内容 |
|
||
| 现有 Element 详情页签 | `.density-element-tabs` | 保留 `el-tabs` 的键盘处理、权限条件与切换事件，标签复用彩色图标 |
|
||
| 现有原生资料表、状态历史表 | `.density-table` | 保留字段、记录排序、业务列宽和固定操作列；不另写行高、边线和表头底色 |
|
||
| 分组页面与弹框表单 | `.density-form` | 显式接入统一标签字号和字段间距，模块只维护列数、跨列及字段顺序 |
|
||
| 既有 FormSection 分组 | `.density-form-section` | 在 `FormSection` 上显式添加，复用公共标题字号和分组间距，保留业务标题与分组顺序 |
|
||
| Element 描述表 | `.density-descriptions` | 页面显式接入统一标签/内容字号与行高；保留原字段及列数 |
|
||
| 连续信息表边框、标签底色、文字与内边距 | `.density-fields` | 只配置列数、跨列、字段顺序；特殊标签宽度使用局部 `--admin-field-label-width` |
|
||
| 弹框/抽屉标题、正文滚动、底部间距 | `.admin-density-dialog` / `.admin-density-drawer` | 容器显式接入，保留该业务已确认宽度与作业高度 |
|
||
| 客户资质列、测量对照列、预装信息布局 | 对应模块 CSS 或页面 `scoped` | 只保留业务列宽、列数、图片尺寸、定位与排列 |
|
||
|
||
### 使用约定
|
||
|
||
下列 `density-action` 是非列表行操作的描边按钮原语；标准列表行操作使用上文 `text-actions`／`admin-text-actions`，不照搬此描边示例。
|
||
|
||
```html
|
||
<!-- 业务按钮只选择语义，不复制尺寸、颜色及交互状态规则 -->
|
||
<el-button class="density-action" @click="edit">编辑</el-button>
|
||
<el-button class="density-action" data-tone="warning" @click="review">审核</el-button>
|
||
<el-button class="density-action" data-tone="danger" @click="remove">删除</el-button>
|
||
|
||
<!-- 更多入口仍是三点，必须保留可访问名称与悬停提示 -->
|
||
<el-button class="density-action" aria-label="更多操作" title="更多操作">
|
||
<MoreHorizontal :size="17" aria-hidden="true" />
|
||
</el-button>
|
||
```
|
||
|
||
`data-tone` 可用 `neutral`（默认）、`warning`、`purple`、`primary`、`success`、`danger`。每个页面仍按已确认的动作配色表选择；纯文字与图标策略不由 CSS 猜测。按钮组使用 `density-actions` 统一间距，业务布局可决定是否换行。
|
||
|
||
`density-actions` 使用 `gap` 管理间距，并将 `--cc-list-action-sibling-margin` 设为 0；`DataTable` 通过该变量保留未接入按钮的默认 8px 左边距。不得将两份间距叠加，也不以更强选择器在页面逐个覆盖。
|
||
|
||
纯文字行操作由 `adminTextActions.css` 统一将按钮横向内边距和组间距减半：每侧 5px、组间距 3px（随公共间距变量缩放），相邻文字间留白由 26px 收紧为 13px。描边操作继续使用原间距；页面不单独覆盖文字操作间距。
|
||
|
||
### 防止维护退化
|
||
|
||
1. **同一通用外观只有一个实现。** 已由公共类接管的按钮配色、页签高度、信息表边框或弹框内边距，删除原页面声明，不能保留两套后再增加优先级或 `!important`。
|
||
2. **新增通用尺寸先改变量。** 模块与页面只引用 `--admin-*`；禁止在页面重定义公共默认值。局部标签宽度是明确的业务参数，不改变全局标签宽度。
|
||
3. **不要把代码搬到模块 CSS 就称为公共化。** 多个业务共用的按钮、页签、信息表与弹框规则留在公共层；模块 CSS 不能依赖另一个业务模块的类名，也不引入第二套按钮颜色变量。
|
||
4. **保留显式接入边界。** 公共样式不能使用无范围的 `.el-button`、`.el-table`、`.el-dialog` 选择器。Teleport 的弹框、抽屉必须自己携带密度类；不能仅依赖页面父级。
|
||
5. **共用组件保留未接入消费者。** CSS 变量的兜底值用于独立渲染和未接入入口；已接入消费者始终由公共变量决定实际值，兜底值不是第二份密度配置。打印标签、PDF 尺寸、原图、画布和既有窄屏规则不能机械替换。
|
||
6. **公共调整按消费者回归。** `adminDensity.test.ts` 维护明确的页面/组件清单，不扫描全部后台。检查模板中公共按钮、页签和信息表的真实祖先是否带有密度入口，不能仅断言文件导入了 CSS 或出现过密度类；页面弹框带有 `admin-density-dialog` 不代表列表与详情已接入。新增接入时同步清单及逐操作矩阵，运行合同、受影响测试、类型检查、全量测试和构建。
|
||
7. **视觉与代码分开记录。** 本轮默认人工截图；代码通过不等于视觉验收通过。已确认业务宽度和工作区高度可以保留为例外，例外写入核对记录。
|
||
|
||
## 新模块接入规则
|
||
|
||
### 先确定范围，再选择公共能力
|
||
|
||
1. 用导航与实际路由列出全部菜单入口，以及新建、详情、编辑和深链页面；不能把文件夹数量当作页面覆盖数。为每个页面沿实际组件引用列出弹框、抽屉、消息确认、预览与打印入口，按逐操作矩阵记录承载方式。
|
||
2. 默认复用普通表格 36px 行高、正文 13px、辅助文字 12px、行内操作基准 28px、页签 38px、轻量返回和连续信息表。新模块的行内业务操作默认纯文字；顶部/提交保留 32px 主次按钮。动作语义色沿用本规范，不通过按钮文字自动猜测。
|
||
3. 模块只保留业务列宽、字段跨列、布局与图纸尺寸等参数。`density-fields` 的四列是默认值，不是固定业务要求；返回位置与大弹框尺寸也不能从订单整页复制。
|
||
4. 编辑表格、流程图、装柜模型、数据看板、图片、标签和 PDF 保留业务所需面积；指标卡和图表不得套用 `.density-fields`或其他详情表格样式，模型画布和打印尺寸不套普通行高。空态、错误、长内容、处理中、只读和无权限仍要可用。
|
||
5. 获准采用蓝白外观的页面按 [蓝白样板接入入口](界面参考/蓝白卡片式工作台风格参考.md#其他页面该参考哪个样板) 选择对应页面类型；列表参考销量分析，复杂分析参考库存分析，运行看板参考数据采集，不一律复制经营总览的大指标卡。保留现有密度根，显式接入主题根和公共类，浮层自行声明作用域；具体覆盖与截图结论回到目标模块现有矩阵。
|
||
|
||
### 密度类与浮层接入
|
||
|
||
页面直接导入 `@/styles/adminDensity.css`，实际根使用 `admin-density`；蓝白主题的组合示例见本文“蓝白主题与图表”。
|
||
|
||
样式接入不授权新增业务动作。详情复用页面根节点的 `admin-density`；原生详情页签用 `density-tabs` / `density-tab-icon`，连续信息表用 `density-fields`。既有 Element 页签使用 `density-element-tabs`；页签栏与正文分离时隐藏空内容容器。在 `el-tab-pane` 内承载正文的页面必须同时使用 `density-contained-tabs`，保留正文并由公共样式设置内容间距。不得依赖页面 CSS 覆盖隐藏规则。既有原生资料/历史表用 `density-table`，分组表单用 `density-form`。返回按钮使用 `link class="density-back"`，跟编号、状态排在同一行。
|
||
|
||
Teleport 弹框用 `admin-density-dialog`，抽屉框架用 `admin-density-drawer`，`ElMessageBox` 用 `customClass: 'admin-density-confirm'`；这些浮层必须各自声明，页面祖先不能替代。抽屉当前公共框架负责字号、标题和正文边距；其正文若复用页面级表格、信息表或按钮原语，在正文业务根节点显式接入 `admin-density`。不要把名为 Drawer 的嵌入组件当作实际抽屉，承载方式以模板和调用端为准。
|
||
|
||
### 共享组件与检查的扩展
|
||
|
||
- 对每个共享组件列出真实调用方及模式。现有 `dense` 参数由调用入口显式传递；`mode` / `workbench` 属于业务范围，不能为了样式变更其含义。新增消费者后，对开启和关闭密度、国内和海外等实际模式分别回归。
|
||
- `adminDensity.test.ts` 中菜单清单、`densityPages`、`consumers`、`moduleCss` 分别覆盖导航、独立入口、子组件和模块 CSS。接入时补充受影响清单，不移除国内仓和客户管理基线，也不通过递归扫描全后台推导范围。
|
||
- 动态类检查显式执行预装/已确认、`dense` 开/关，以及 DOMESTIC/OVERSEAS 入口；货柜已确认清单与船期浮层有独立开关断言。接入其他条件时补充真实上下文和对应开关用例，不能一律传 `preload`、强行把所有条件置真，或只断言出现过类名。
|
||
- 检查必须同时覆盖 CSS 独立导入、公共原语的实际祖先、Teleport 容器自己的类、变量定义与消费、按钮间距、普通/悬停/焦点/禁用，以及原有业务行为。源码合同只防止已知结构退化，不能证明最终 CSS 优先级或布局视觉正确。
|
||
- 发布前的代码门禁为密度合同、受影响业务测试、类型检查、全量测试和构建；维护指引后运行 AGENTS 索引合同。人工按 1920×1080、100% 缩放检查独立打开/刷新、列表到详情、浮层普通/全屏/重开、长数据和权限状态。缺少对应截图时保留“待人工截图确认”。
|