# UI Review

- 审查目标：src/prototypes/customer-management
- 使用设计依据：DESIGN.md（项目默认 OneOS 设计规范）
- 生成时间：2026-07-01

## 总体点评

客户管理原型在信息架构上与 OneOS 中后台惯例高度一致：列表页采用「筛选区 + 工具栏 + 表格 + 分页」四段式，新增页采用分组卡片 + 底部 sticky 操作栏，并复用 `vehicle-management` 的 `vm-*` 样式与令牌桥接，整体视觉气质专业、数据密度适中，与 DESIGN.md 描述的 Emerald 主色、Inter 字体、32px 控件高度等基调基本吻合。

亮点方面：筛选区默认折叠为 4 项并支持「更多筛选」，有效控制了首屏认知负荷；表格对编号列与操作列做了 sticky 处理，在 17 列宽表场景下保留了关键操作可达性；新增页省-市、部门-负责人联动逻辑清晰，发票抬头随客户全称自动带入，符合业务心智模型。

主要风险集中在三类：一是部分组件（状态徽章、客户标签）仍使用硬编码色值，偏离 OneOS 语义色与 Emerald 主色体系；二是新增页表单错误反馈仅依赖 3 秒消失的 Toast，缺少字段级错误态与焦点引导；三是列表页面包屑信息不完整，与新增页及 DESIGN.md 约定的页面结构存在不一致。Impeccable detect 扫描未检出自动化规则违规，独立评估标记为 degraded（未使用浏览器预览/截图）。

## P0-P3 优先级问题

### P1 - 新增页校验失败仅 Toast 提示，缺少字段级错误反馈

- 证据：`index.tsx` 中 `validateCreateForm` 返回首条错误文案后，经 `showToast` 展示并在 3 秒后消失；`CreatePage.tsx` 各字段无 `aria-invalid`、错误文案或错误边框态。
- 影响：用户提交长表单后无法快速定位未填项，需记忆 Toast 内容或在多卡片间逐字段排查，显著增加完成新增任务的难度；不符合 Nielsen「错误识别与恢复」及 DESIGN.md 对校验失败使用错误色 `#ef4444` 的语义约定。
- 修复方向：提交时在首个无效字段旁展示 inline 错误，并为对应控件设置 `aria-invalid` + `aria-describedby`；校验失败后将焦点移至首个错误字段；保留 Toast 作为成功态补充即可。

### P1 - 必填标识对屏幕阅读器不可感知

- 证据：`CreatePage.tsx` 中 `FormField` 的必填星号使用 `aria-hidden`；关联的 `input`/`select` 未设置 `aria-required="true"`。
- 影响：依赖读屏或键盘的用户无法在进入字段前获知必填约束，提交失败后只能依赖 Toast 间接推断，构成 WCAG 可感知性缺口。
- 修复方向：移除星号上的 `aria-hidden`，在必填控件上添加 `aria-required="true"`；可选在标签文案中追加「（必填）」供读屏朗读；星号保留视觉样式并配合 `aria-hidden` 仅当标签已含文字说明时。

### P2 - 状态徽章与客户标签硬编码非 OneOS 语义色

- 证据：`StatusBadge.tsx` 内联 `#00b42a` / `#f53f3f` / `#86909c`；`LabelTags.tsx` 内联 `#f77234` 橙色描边与 `#1d2129` 文字色，未使用 `--oneos-*` 或 `--ln-*` 令牌。
- 影响：与 DESIGN.md「使用 CSS 变量 `--oneos-*`，不要硬编码色值」及「不要引入与 Emerald 主色冲突的第三方色板」冲突；列表中标签橙色与系统 Emerald 主色并置，削弱品牌一致性与状态色语义（成功/错误/警告）的可学习性。
- 修复方向：状态点改用 `var(--oneos-success)` / `var(--oneos-error)` / `var(--oneos-muted)` 或等效 `--ln-*` 桥接变量；标签样式复用 `oneos-app.css` 中已有 tag/chip 模式，或基于 `--oneos-primary-light` 背景 + `--oneos-primary` 描边统一视觉。

### P2 - 列表页面包屑未标示当前页「客户管理」

- 证据：列表视图 `index.tsx` 面包屑仅渲染 `<span className="cm-breadcrumb-muted">业务管理</span>`；新增页则完整展示「业务管理 / 客户管理 / 新增」且前两级可点击返回。
- 影响：用户在列表页无法从导航结构确认当前位置；与 DESIGN.md「列表页：面包屑 + 筛选区 + …」及 PRD 页面结构约定不一致，也弱化了「用户控制与自由」中的位置感知。
- 修复方向：列表页补全为「业务管理 / 客户管理」，当前级使用 `cm-breadcrumb-current` 高亮；「业务管理」在具备上级路由时可设为链接，与新增页交互保持一致。

### P3 - 17 列宽表首屏信息密度过高，缺少列管理能力

- 证据：`styles/index.css` 设定 `.cm-table { min-width: 2240px; }`，表格含 17 个数据列；虽有个别 sticky 列，但中间字段（信用代码、地址等）需大量横向滚动才能浏览。
- 影响：销售/运营在对比客户核心字段（名称、状态、负责人）时 extraneous cognitive load 偏高；存在可用绕行（横向滚动 + sticky），但不利于日常高频扫读。
- 修复方向：原型阶段可标注默认可见列集合并提供「列设置」入口；或将次要工商字段折叠进行内「详情」抽屉，列表保留 8–10 个高频列，与 DESIGN.md「数据密度适中」目标对齐。

## 核心元件

### 筛选区（FilterPanel）

符合 DESIGN.md 列表页「筛选区 + 工具栏 + 表格 + 分页」结构。标题 `h1.cm-page-title` 承担页面主标题职责，4 项默认展示 + 「更多筛选」折叠策略合理，查询/重置与 `pendingFilters` / `appliedFilters` 分离符合 PRD。保留点：部门-负责人联动、日期范围 `aria-label` 完整。调整点：筛选卡片与列表面包屑之间层级关系可再梳理（标题在筛选卡片内、面包屑在其外，略分散）。

### 工具栏与表格（CustomerTable + TablePagination）

主操作「新增客户」使用 `vm-btn-primary` 且带图标+文字，符合 DESIGN.md 主按钮约定；批量导入/导出为 secondary/ghost 层级清晰。表格空态文案「暂无符合条件的客户」存在，但缺少引导操作（如「新增客户」链接）。行内操作「详情 | 编辑 | 删除」链接化呈现符合中后台惯例；删除使用 `cm-link-danger` 指向错误色，语义正确。分页与「共 N 条」footer 布局清晰。宽表 sticky 左右列实现到位，但列数过多见 P3。

### 新增表单（CreatePage）

三组卡片（客户信息 / 联系人 / 开票）分组符合 PRD 与认知 chunking 原则；三列网格在 960px / 640px 有响应式断点。省-市、部门-负责人 disabled 联动、发票抬头只读同步逻辑正确。底部 sticky footer 固定「重置 / 提交」符合中后台表单模式。调整点：校验与必填可感知性见 P1；`cm-create-footer` 使用负 margin 对齐父级 padding，对 padding 变更较脆弱，后续可改为与 `.vm-page` 内边距一致的 layout token。

### 状态与标签（StatusBadge / LabelTags）

状态徽章圆点 + 文案结构清晰，但色值未走设计令牌（见 P2）。LabelTags「首标签 + +N 悬浮」符合 PRD；`+N` 支持 focus 展开 tooltip，键盘可达性优于纯 hover。标签橙色硬编码与 OneOS Emerald 体系脱节，建议统一为系统 tag 样式。

### 面包屑与全局反馈

新增页面包屑可点击返回、当前页高亮，表现良好。Toast 使用 `role="status"` + `aria-live="polite"`，成功/演示提示合适；但不宜作为表单校验的唯一错误通道。列表页面包屑不完整见 P2。

## 响应式与可访问性

- **响应式**：新增表单网格在 ≤960px / ≤640px 降为 2 列 / 1 列；列表表格依赖横向滚动，无移动端列精简方案，窄屏下操作成本较高（中后台可接受但需知晓）。
- **键盘**：`vm-btn`、分页、FilterPicker 等复用组件具备 `:focus-visible` 样式；MultiSelectField 的 `role="listbox"` 与 checkbox 组合非标准 listbox 模式，读屏语义可能混淆（未列入 TOP5，建议后续改为 `role="group"` + checkbox 或 Combobox 模式）。
- **对比度**：正文与背景通过 `--ln-*` 桥接，整体可读；LabelTags / StatusBadge 硬编码色未经验证对比度。
- **动效**：筛选 Chevron 旋转与 `prefers-reduced-motion: reduce` 降级已在模块 CSS 中处理。
- **检查结论**：未发现阻断级 a11y 缺陷，但表单必填感知与错误恢复需优先补强。

## 证据与评估说明

- **浏览器/截图**：未使用（当前会话无预览环境接入）。
- **Scanner**：已运行 `rules/references/impeccable/scripts/detect.mjs --json src/prototypes/customer-management`，结果为 `[]`（0 条自动化发现）。
- **独立评估**：degraded — 设计评估基于源码、DESIGN.md 与 PRD；证据评估仅含 CLI scanner，缺少浏览器可视化与响应式实测，结论以静态审查为主。
