docs/Client界面样式规范.md

Client 界面样式规范

范围与验收状态

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

公共入口与职责

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

入口（相对 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 把同一组联系人拆散重排。

两个样板的具体排列

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

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

代码参考：海外采购新增分支、本土卡页面外框、本土卡表单。新业务先确定字段分组与承载方式，再使用通用外观；若要调整上述排列或推广到其他共用分支，须在对应任务中明确范围，不顺手扩展。

尺寸与间距

以下数值分别适用，不将所有间距一律改为 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；菜单背景与部署前一致。四操作折叠分支仅自动化覆盖，缺少真实四操作数据；用户对视觉标准的最终确认待完成。