docs/Client界面样式规范.md

# Client 界面样式规范

## 范围与验收状态

- 本文是客户端样式的现行维护正文，按新增页面和列表分别定义规则。后续客户端的新增、新建、下单操作统一采用下文“新增页面”的风格；列表沿用列表章节，不把两者的控件尺寸和间距混用。
- 新增页以“海外采购下单”和“美国本土卡车下单”在当前对话确认的外观与布局为样板：满宽、无阴影、精简说明、12px 模块间距、浅色 placeholder 和字段右上角校验提示。两页的不同字段排列见下文，不按整页截图机械复制。规范确定不等于所有新增页已改造或通过视觉验收。列表首个验收样板为“头程物流 → 订单列表”（`/orders/first-leg`），其验收状态见文末。
- 只维护 `apps/client-web/` 内的样式和公共组件，不与 Admin 跨应用链接依赖。
- 左侧菜单背景保持现状，不修改 `shell.css` 中的导航背景，也不通过全局品牌变量间接改变导航。
- 标准通过正文容器 `.client-ui` 接入；新增页在本页或新增表单容器内覆盖对应令牌，不将新增页尺寸写入全局默认值。创建、详情与其他模块需分别核对承载方式和字段，不以某个样板通过代替整模块验收。
- 按 1920×1080、浏览器缩放 100% 验收，保留现有窄屏能力。

## 公共入口与职责

按任务阅读：新增、新建、下单读“新增页面”；列表读“尺寸与布局”“颜色与按钮”及适用的列表样板条款。视觉核对方法只维护在 [Admin / Client 前端原型还原验收规则](Admin-Client前端原型还原验收规则.md)。

| 入口（相对 apps/client-web） | 职责 |
|---|---|
| `src/styles/client-ui.css` | `--client-*` 颜色、尺寸、间距；正文按钮和状态外观 |
| `src/components/common/QueryToolbar.vue` | 搜索栏；`layout="grid"` 为四列筛选布局 |
| `src/components/common/DataTable.vue` | 表格、工具栏、行操作、分页；工具栏内容用插槽提供 |
| `src/components/common/tableActions.ts` | 三个操作以内全部展示，超过三个折叠；禁用和加载状态执行保护 |
| `src/modules/first-leg/utils/firstLegOrder.ts` | 头程状态码 → 语义色，不在公共样式中判断业务状态码 |
| `src/modules/cross-border/views/ProcurementView.vue` 的新增分支 | 新增页外观样板；只参考当前新增分支，不跨模块导入该业务页面 |
| `src/modules/cross-border/components/BusinessOrdersView.vue` 与 `TransportDemandForm.vue` 的新增分支 | 本土卡与散板共用新增外观；参考三列短字段、两列详细地址和右上角校验。编辑分支及各业务的视觉验收分别核对，不从共用组件推定已通过 |

页面只提供字段、操作、业务状态与权限，不再覆盖公共工具栏 padding、表格行高及分页 padding。确有业务差异时增加明确的组件能力，避免重复页面 CSS。

## 新增页面

### 适用范围与设计依据

- 后续客户端新增、新建、下单操作按本章实施。既有页面在对应任务触及时按授权范围调整，不因规范更新批量改造其他页面。
- 本章替代最初海外采购 HTML / UI Redesign Spec 中的 1240px 内容宽度上限、26px 模块间距、24px 表单卡片内边距及重复说明文字；不采用带阴影的大圆角截图版本。桌面导出文件是参考材料，后续规则统一更新本文，不要求开发者依赖个人桌面文件或设计工具链接。
- 统一外观不统一业务表单：字段、顺序、分组、必填条件、默认值、权限、计算口径和提交行为仍按各业务契约及已确认原型。海外采购的采购方向、币种、收件资料等不自动成为其他新增页的字段。
- 独立页面、居中弹框、抽屉仍按对应操作的已确认承载方式；本规范不将所有新增操作改成独立页面。后续用户明确确认的外观例外优先于本章，其余通用外观不回退到旧原型的大留白、阴影或说明堆叠。
- 本章只约束新增内容区。复用现有侧边栏、顶栏、页签和面包屑，不复制设计稿中的静态用户名、菜单或页签，不因新增页改造修改公共外框。

### 页面组织与信息密度

1. 独立新增页使用一个清晰标题，右侧按现有列表访问权限提供返回入口；默认不增加标题下的解释性段落。
2. 摘要区按业务需要使用，展示数量、预算等真实表单派生值。已有三项摘要时等宽三列；没有必要摘要的表单直接进入业务区，不为套用样板硬凑三个指标。
3. 表单按业务分组呈现为独立白色卡片，标题位于卡片上方，以小圆点区分分组。常规短字段使用三列等宽网格；成对详细地址可使用两列，单个长地址、链接、长备注可占满整行。具体排列按下文样板及业务确认，不把所有区域强制设成相同列数。既有明确分组和摆放不得因凑满网格擅自重排。
4. 独立页底部操作靠右，返回列表在前、主提交按钮在后；返回资格沿用现有权限。弹框或抽屉保留其已确认的取消、关闭和提交语义，不硬加“返回列表”。
5. 内容填满所在容器的可用宽度，使用 `width: 100%`、`min-width: 0`；独立页不设置 1240px 等固定内容上限造成右侧空白。弹框和抽屉中的满宽指其正文容器，不是铺满浏览器视口；保留应用壳层或容器已有边距，不重复包一层大 padding。
6. 在 1920×1080、100% 缩放下优先减少无效留白和重复文案，使主要填写内容更集中。长表单允许正常滚动，不通过隐藏必要字段、缩小字号、裁切内容或未经确认拆步骤强行塞进一屏；一屏效果以人工截图为准。

### 字段列数与宽度

“内容区满宽”“字段单独一行”和“控件占满整行”是三个不同要求，实施前按下表区分。

| 场景 | 当前标准 | 样板 |
|---|---|---|
| 页面、表单卡片 | 铺满可用正文宽度，不留下固定宽度上限造成的右侧空白 | 两个新增页 |
| 常规短字段 | 一行三列等宽，横向间距 20px；输入框填满所在列 | 采购品类／商品名称／商品规格；本土卡取货地／联系人／电话 |
| 前置选择项独立一行 | 单独占一行位置，控件只占三列中的一列，与下一行第一列对齐，右侧留空 | 采购方向、车辆类型 |
| 成对详细地址 | 同一行两列等宽，分别放取货地址、送达地址 | 本土卡运输信息 |
| 单个长字段 | 按已确认分组占满该行，例如商品链接、完整收货地址、备注 | 海外采购及本土卡备注 |

- 前置选择项的一列宽度按正文网格计算：`calc((100% - 40px) / 3)`，其中 40px 是两个 20px 列间距。不得改成任意固定的 280px，也不得把“独立一行”理解成下拉框横跨整张卡片。
- 混合三列短字段与两列地址时，可以使用六列基础网格，短字段跨两格、详细地址跨三格；这只是实现方式，用户看到的仍是三列或两列。前置项独占整行位置，再将自身宽度限制为标准一列。
- 字段按实际阅读顺序写入模板，键盘 Tab 顺序与视觉顺序一致；不只用 CSS `order` 把同一组联系人拆散重排。

### 两个样板的具体排列

以下是后续页面可对照的布局依据，不是要求其他业务复制相同字段、默认值或摘要指标。

| 页面／区域 | 已确认排列 |
|---|---|
| 海外采购／摘要 | 数量、预算单价、币种三张等宽卡片，数值与当前表单联动 |
| 海外采购／商品与预算 | 采购方向独立一行、控件一列宽；其后采购品类／商品名称／商品规格三列，采购数量／预算单价／预算币种三列；商品链接整行，预算总上限用普通文本 |
| 海外采购／收件资料 | 收件人、联系电话各占三列网格的一列，第三列留空；完整收货地址、采购要求各占整行 |
| 本土卡／运输信息 | 车辆类型独立一行、控件一列宽；取货地／取货联系人／取货联系电话一行三列；送达地／送达联系人／送达联系电话一行三列；取货地址／送达地址一行两列 |
| 本土卡／货物信息 | 托数／总重量／总体积一行三列 |
| 本土卡／费用与时效 | 预算总价与币种组成同一字段，占两列网格的左列，右列留空；取货时间／送达时间一行两列；备注整行 |

代码参考：[海外采购新增分支](../apps/client-web/src/modules/cross-border/views/ProcurementView.vue)、[本土卡页面外框](../apps/client-web/src/modules/cross-border/components/BusinessOrdersView.vue)、[本土卡表单](../apps/client-web/src/modules/cross-border/components/TransportDemandForm.vue)。新业务先确定字段分组与承载方式，再使用通用外观；若要调整上述排列或推广到其他共用分支，须在对应任务中明确范围，不顺手扩展。

### 尺寸与间距

以下数值分别适用，不将所有间距一律改为 12px。

| 元素 | 新增页标准 |
|---|---|
| 页头、摘要区、表单模块底部间距 | `margin-bottom: 12px` |
| 摘要卡之间 | 横向 gap 16px |
| 摘要卡内部 | padding 12px 16px；纵向 gap 8px |
| 摘要标题行 | 图标与标题 gap 12px；图标底块 44×44px，圆角 8px；线性图标 20px |
| 表单卡片 | padding 16px；1px 边框；圆角 10px |
| 摘要卡片 | 1px 边框；圆角 10px |
| 分组标题 | 下方 margin 10px；圆点 9px；圆点与标题 gap 10px |
| 表单网格 | 常规三列等宽，两列／整行区域按上文布局；纵向 gap 12px、横向 gap 20px；单项不另叠加底部 margin |
| 标签与控件 | 间距 6px；标签行高 20px |
| 字段校验提示 | 字段右上角、标签同行，12px 字号、20px 行高；不增加底部占位和字段高度 |
| 输入框、选择框 | 最小高 44px；圆角 6px；padding 10px 14px |
| 多行输入 | 最小高 110px；padding 11px 14px；允许纵向调整；字数计数在下方右侧，间距 4px |
| 预算等必要汇总值 | 上方 margin 10px；字号 13px、行高 20px；普通文本，不做说明横幅 |
| 底部按钮间距 | gap 12px |
| 次按钮 | 最小高 44px；padding 10px 18px；圆角 6px |
| 主按钮 | 最小高 44px；padding 12px 28px；圆角 6px |

### 字体、颜色与状态

字体沿用中文无衬线栈：`"PingFang SC", "Microsoft YaHei", "Noto Sans SC", sans-serif`。

| 用途 | 标准 |
|---|---|
| 独立页标题 | 26px / 700；margin 0 |
| 分组标题 | 18px / 700 |
| 正文、输入内容 | 14px / 400 |
| 字段标签 | 14px / 600 |
| 摘要标题、数值、单位 | 15px / 600；30px / 700；14px / 500 |
| 内容底色、卡片及控件底色 | `#F4F7FC`、`#FFFFFF` |
| 主文字、标签、次要文字 | `#1F2937`、`#374151`、`#6B7280` |
| 占位文字 placeholder | `#B0B7C3`；输入框、多行输入和选择框的未填写提示统一使用，已填写内容保持正文色 |
| 卡片边框、控件及次按钮边框 | `#E3E8F0`、`#D5DCE8` |
| 主按钮 | `#2F7BFF` 背景、白字 |
| 次按钮、摘要数值 | `#1D5FE0`；次按钮白底描边 |
| 必填星号 | `#E5484D` |
| 焦点 | 2px `#2F7BFF` outline；无发光阴影 |

- 卡片、输入框、选择框及其弹出层、按钮均不使用装饰阴影、渐变、毛玻璃或位移动效；分隔依靠边框与底色。
- 主要操作以蓝色为强调色，其他颜色仅用于必要的业务状态、错误反馈和小面积分组标记。样板图标底块可使用蓝 `#EAF2FF / #2F7BFF`、绿 `#E8F8F0 / #16A34A`、橙 `#FFF5E0 / #D97706`；分组圆点使用蓝色或青色 `#0EA5A4`，不把整块表单染成状态色。
- 已确认的原型图标沿用对应资源；未定义的图标使用项目既有图标库，不引入第二套组件库或表情图标。无需要时不添加装饰图标。
- 保留清晰的禁用、提交中、焦点和错误状态，状态不只依赖颜色表达；不得为了“干净”删去校验、失败重试或权限说明。

### 文案与数据绑定

- 删除重复解释性提示：不恢复页头“一单一个商品及规格……”、摘要卡下的说明行，也不新增类似的常驻说明段落或黄色提示横幅。
- 字段标签与简短占位提示负责说明输入用途；校验错误、提交失败、无权限及必要业务提示按实际状态就近出现。保留影响客户正确操作的必要信息，不将“去提示”理解为关闭验证或隐藏错误。
- 未填写字段应提供简短 placeholder，例如“请选择车辆类型”“请输入取货联系人姓名”“请选择取货日期和时间”；不要通过 `placeholder=""` 将必要输入提示清空。按字段性质标明选填，不使用整段业务说明代替占位文字；已存在默认值时显示真实值，不为显示 placeholder 清除默认值，尤其不得把有效的 `0` 当作空值。
- 保留真实汇总数据，例如货款预算总上限；摘要和汇总跟随当前表单实时更新，不能保留设计稿中的静态 `1`、`USD` 或 `0 / 1000`。
- 空值显示“—”，合法零值按零展示；金额沿用现有精度处理，不因样式调整改变校验或金额口径。支持多个币种或方向的业务继续联动展示，不用原型示例缩减现有能力。

### 必填校验与稳定布局

- 字段错误提示统一放在输入框右上方，与字段标签同行、靠右对齐；保留必填星号与错误边框。提示出现、纠正或清空时，后续字段和整张卡片不得上下跳动。
- 错误不参与正常文档流，不在控件下面额外预留 16px 空行；标签区应能同时容纳标签与简短错误文案。对当前明确的单行标签，可相对 `.el-form-item__content` 使用 `bottom: calc(100% + 6px)`、`right: 0` 定位，宽度避开标签。更长标签或提示须单独核对，不截断必要错误或覆盖标签、输入内容。
- 必填星号必须配套字段级校验：Element Plus 表单绑定 `ref`、`model`、`rules`，校验项绑定对应 `prop`；文本失焦、选项变化时校验当前字段，提交时校验全部必填项。未通过时不发送创建请求，不用整页错误代替缺失字段提示。
- 填写正确并再次触发校验后清除该字段错误；重置表单时清除校验状态；提交中防重复点击，失败保留填写内容。采购预算单价 `0` 是有效值，不得误报必填。
- 已有金额、格式、权限和服务端校验继续保留；非字段级请求失败仍按原有页面错误反馈处理。本规范不改变业务规则，也不将两页未统一的所有校验逻辑推定为已统一。

### 接入与核对

- 使用现有 Vue、Element Plus 和 `.client-ui`；新增页所需 44px 控件、14px 字号、配色等在新增内容容器内覆盖。列表仍使用下文的 32px 控件，不修改全局 `:root` 使其他页面跟随变化。
- 同一组件同时承载列表、新增和详情时，新增样式必须限制在新增分支；不得扩大到列表、详情或侧边导航。跨模块稳定复用时按应用指引抽取通用能力，不跨模块导入采购页，也不复制设计工具的 React 运行时。
- 新增或整体重排页面时，按前端验收规则核对该操作的承载方式、满宽、字段分组和按钮；重点检查前置选择项是否与三列网格对齐、短字段和成对地址列数、placeholder、长值、摘要联动、空值与零值、校验出现／消失时的位置稳定及正常滚动。纯文案或小间距调整只核对差异，不重复建立完整矩阵。
- 自动检查按实际变更选择；文案和纯样式不自动升级为全量测试、类型检查或构建。真实视觉由人工提供截图确认，部署成功或静态资源命中不等于一屏布局通过；不开展当前阶段未要求的窄屏验收。

## 尺寸与布局

本节用于列表、查询栏和表格工具栏；新增表单使用上文“新增页面”的尺寸。

| 项目 | 标准 |
|---|---|
| 正文、表格、按钮字号 | 13px |
| 次要说明、状态字号 | 12px |
| 普通按钮、输入框 | 高 32px |
| 表格行操作按钮 | 高 28px，左右 padding 8px |
| 按钮间距 | 8px |
| 搜索栏 | padding 16px；四列；字段间距纵向 12px、横向 16px |
| 搜索操作区 | 顶部 margin 12px、padding 12px，分隔线与字段区区分 |
| 表格工具栏 | 最小高 48px；padding 8px 16px；实际高度随操作换行增长 |
| 表头 | 高 44px，浅灰底，600 字重 |
| 数据行 | 高 48px；白底与浅灰交替，悬停浅蓝 |
| 单元格 | 左右 padding 12px，行高 20px |
| 分页 | 最小高 58px；padding 12px 16px；页码按钮 32px |
| 内容分区间距、圆角 | 16px、6px |

长编号保持可辨认，普通长文本省略并提供完整内容提示；金额右对齐，状态居中。操作列在业务列最左侧并固定，批量选择框在其前方。列设置、排序与选择行为保持原有业务逻辑。

## 颜色与按钮

本节用于列表操作和状态语义；新增表单按钮的外观使用上文“新增页面”，业务危险语义和权限要求仍须保留。

| 用途 | 文字色 | 背景色 |
|---|---|---|
| 默认操作 | `#1777ff` | 白色 |
| 主要操作 | 白色 | `#1777ff` |
| 处理中 | `#175cd3` | `#eff8ff` |
| 成功 | `#067647` | `#ecfdf3` |
| 待处理、提醒 | `#b54708` | `#fffaeb` |
| 失败、危险 | `#b42318` | `#fef3f2` |
| 草稿、中性 | `#475467` | `#f2f4f7` |
| 禁用按钮 | `#98a2b3` | `#f9fafb` |

- 查询、创建等主要操作使用实心蓝色；行内详情、编辑等使用白底描边蓝字，统一使用纯文字，不显示装饰图标。加载中的进度指示保留。
- 行操作先按权限及业务条件过滤，再计算数量；1–3 个全部展示，4 个及以上显示前两个和 `…`。入口保留“更多操作”的可访问名称。
- 禁用操作不被隐藏，不因禁用改变位置；加载中不可重复执行。
- 表格顶部批量操作不套用行操作的三个阈值，保留明确的批量入口和创建入口。
- 危险操作仍需原有业务确认；样式不改变权限和提交条件。

## 头程状态映射

| 状态码 | 文案 | 语义色 |
|---|---|---|
| DRAFT | 草稿 | 中性灰 |
| PENDING_REVIEW | 待审核 | 提醒橙 |
| WAIT_MEASURE | 待测量数据 | 处理中蓝 |
| WAIT_PALLETIZE | 待组托 | 处理中蓝 |
| WAIT_SPLIT | 待分柜 | 处理中蓝 |
| LOADING | 装柜中 | 处理中蓝 |
| LOADED | 装柜完成 | 成功绿 |
| DELIVERED | 派送完成 | 成功绿 |
| COMPLETED | 已完成 | 成功绿 |

测试环境复验补充：服务端统一订单已正式返回 `COMPLETED`，列表、筛选和详情沿用该状态，不能再显示英文或映射成“装柜完成”。订单号列宽 240px，入仓码列宽 230px，状态默认紧随入仓码，保证首屏可识别。

标签包含状态文字，颜色为辅助识别。其他模块需按业务阶段单独列出状态映射，不以中文模糊匹配统一推断；未知状态不得伪装为处理中或完成。

## 样板逐操作验收矩阵

| 检查对象 | 首版目标 | 验收方式 |
|---|---|---|
| 左侧菜单 | 背景与修改前一致 | 同视口截图对照 |
| 列表首屏 | 筛选、工具栏、表格、分页层次一致 | 有数据的完整页面截图 |
| 搜索 | 查询和重置有效；输入框不遮挡、字段标签完整 | 查询前后、重置后 |
| 工具栏 | 列设置、下载、导出、批量提交、批量导入、创建入口保留 | 未选择/已选择/无写权限 |
| 行操作 | 1、2、3 个不折叠；4 个时前两个加省略入口 | 按权限与业务条件验证，不修改真实订单来凑状态 |
| 状态 | 草稿、待审核、处理中、装柜完成的语义颜色不同 | 对照多状态列表 |
| 表格 | 横向滚动时选择、操作、订单号可用；完整值可查看 | 长编号、长渠道、空值、列重排 |
| 分页 | 条数和页码完整；更换条数回到第 1 页 | 10/20/50 条、首尾页 |
| 加载/失败/空态 | 失败保留重试和工具栏；不把失败显示为无订单 | 加载、失败重试、空结果 |
| 关联操作 | 详情、费用、编辑、报关入口保持原有行为 | 只读打开核对；写入另按授权执行 |

自动化检查不代替真实页面截图。列表样板确认前，不将其他 21 个菜单标记为已统一或已验收。

2026-09-15 经用户明确授权完成内置浏览器验收：测试部署 `client-web-test #282`、提交 `7068f49` 成功；1920×1080、100% 缩放下检查首屏、筛选重置、全选、列设置、10/20/50 分页、横向固定列、详情入口以及灰/橙/蓝/绿状态。实测工具栏 padding 为 8px 16px，分页为 12px 16px，表头/行高为 44px/48px，行按钮 28px、#1777ff；菜单背景与部署前一致。四操作折叠分支仅自动化覆盖，缺少真实四操作数据；用户对视觉标准的最终确认待完成。