# 供应侧 UI/UX 设计规范（XR-003）

- 版本：v1.0
- 日期：2026-03-25
- 状态：生效（设计与验收基线）
- 目标：建立供应侧统一交互规范，补齐空态/异常态/权限态与可访问性基线
- 关联文档：
  - `supply_button_level_prd_v1_2026-03-25.md`
  - `supply_ui_test_cases_executable_v1_2026-03-25.md`
  - `supply_api_contract_openapi_draft_v1_2026-03-25.yaml`
  - `acceptance_gate_single_source_v1_2026-03-18.md`

---

## 1. 信息架构（IA）

## 1.1 导航结构

1. 一级导航：`供应账号`、`套餐管理`、`收益结算`。
2. 二级视图：
   1. 供应账号：账号列表、挂载弹窗、审计侧栏。
   2. 套餐管理：列表、编辑页、批量调价弹窗。
   3. 收益结算：收益卡片、提现弹窗、流水抽屉、对账单下载。
3. 全局辅助入口：帮助中心、操作日志、权限说明。

## 1.2 页面布局基线

1. 顶部固定：页面标题 + 关键 KPI + 最近更新时间。
2. 主体区域：筛选区、列表区、详情区（抽屉或侧栏）。
3. 底部区域：批量操作栏（仅在多选时显示）。

---

## 2. 交互规则（按钮级）

## 2.1 按钮等级与视觉规则

| 等级 | 用途 | 样式规则 | 示例 |
|---|---|---|---|
| Primary | 页面主动作（每屏最多 1 个） | 实色高对比 | 发布上架、发起提现 |
| Secondary | 常规辅助动作 | 描边/弱强调 | 保存草稿、刷新收益 |
| Tertiary | 次级动作 | 文本按钮 | 查看审计、查看流水 |
| Danger | 高风险动作 | 红色警示 + 二次确认 | 删除账号、立即下架 |

## 2.2 禁用态与提示规则

1. 禁用按钮必须可见禁用原因（tooltip 或内联提示），禁止“只灰不解释”。
2. 权限不足与状态不满足必须区分文案：
   1. 权限不足：`你没有执行该操作的权限`。
   2. 状态不满足：`当前状态不允许执行此操作`。
3. 按钮进入 loading 时，文案切换为进行时且禁止重复点击。

## 2.3 危险操作确认规则

1. `删除账号`、`立即下架`、`撤销提现`必须二次确认。
2. 二次确认弹窗必须包含：
   1. 操作对象名称与 ID。
   2. 影响范围说明。
   3. 不可逆后果说明。
3. 高风险动作需二次输入验证码或对象别名（可配置）。

---

## 3. 状态设计（闭环）

## 3.1 空态

1. 首次空态：展示引导文案 + 主按钮（如“立即挂载账号”）。
2. 过滤空态：展示“无匹配结果” + 清空筛选操作。
3. 异常空态：展示“加载失败” + 重试按钮 + 错误编号。

## 3.2 异常态

1. 表单错误：字段级错误 + 全局错误摘要。
2. 接口失败：保留用户输入，不自动清空。
3. 冲突错误（409）：提示“状态已变化，请刷新后重试”。
4. 系统错误（5xx）：提示可重试并记录 `request_id`。

## 3.3 权限态

1. `supplier_owner`：可执行所有业务按钮。
2. `supplier_viewer`：仅查看与导出，不可写操作。
3. `platform_admin`：可执行风控恢复、禁用解除。
4. UI 必须按权限前置控制，后端再做最终鉴权。

---

## 4. 可访问性（A11y）基线

## 4.1 键盘与焦点

1. 所有可交互控件支持 Tab/Shift+Tab 顺序访问。
2. 焦点可见：focus ring 对比度 >= 3:1。
3. 弹窗打开后焦点锁定在弹窗内，关闭后返回触发元素。

## 4.2 可读性

1. 正文最小字号 14px，行高 >= 1.5。
2. 文本与背景对比度：
   1. 常规文本 >= 4.5:1
   2. 大字号文本 >= 3:1
3. 错误提示不能仅靠颜色表达，需配合图标或文字标签。

## 4.3 可理解性

1. 表单字段必须有 label 与帮助文案。
2. 错误消息必须指向可操作修复方式。
3. 必填项统一使用 `*` 且配套说明“*为必填”。

---

## 5. 页面级规范补充

## 5.1 供应账号页（SUP-PAGE-001）

1. 凭证输入框默认掩码，粘贴后仅展示前后各 2 位。
2. 验证通过后展示摘要，不展示原始凭证。
3. 状态标签颜色统一：
   1. `pending`：中性黄
   2. `active`：绿色
   3. `suspended`：橙色
   4. `disabled`：红色

## 5.2 套餐管理页（SUP-PAGE-002）

1. 批量调价入口仅在多选>=2时出现。
2. 保护价未达标时禁用发布按钮并给出最低可填值。
3. 复制套餐后自动定位到新草稿并高亮 3 秒。

## 5.3 收益结算页（SUP-PAGE-003）

1. 发起提现前展示“可提现余额、预计到账时间、手续费”。
2. 处理中结算单必须固定在列表顶部并带进度状态。
3. 对账单下载失败时提供重试与工单入口。

---

## 6. 反馈与文案规范

1. 成功反馈：简短结果 + 下一步建议（如“可前往套餐页继续上架”）。
2. 失败反馈：失败原因 + 修复建议 + request_id。
3. 文案禁用词：避免“系统异常”这类无信息词，必须给可执行建议。
4. 安全文案：不得出现可复用凭证片段、真实账户号全量信息。

---

## 7. Design QA Checklist（验收清单）

| 编号 | 检查项 | 通过标准 | 严重级别 |
|---|---|---|---|
| DQA-001 | 按钮层级正确 | Primary/Secondary/Danger 使用符合规范 | P1 |
| DQA-002 | 禁用态可解释 | 所有禁用按钮有明确原因 | P1 |
| DQA-003 | 危险操作二次确认 | 所有高风险动作均有确认弹窗 | P0 |
| DQA-004 | 权限态一致 | viewer 不可触发写操作 | P0 |
| DQA-005 | 状态机可视一致 | 页面状态与后端状态一致，无跳态文案 | P0 |
| DQA-006 | 错误信息可操作 | 错误提示包含修复建议 | P1 |
| DQA-007 | 键盘可达性 | 全页面可纯键盘操作完成关键流程 | P1 |
| DQA-008 | 焦点可见性 | focus ring 清晰可见 | P1 |
| DQA-009 | 对比度达标 | 文本对比度满足 WCAG AA | P1 |
| DQA-010 | 表单可读性 | label/help/error 三要素完整 | P1 |
| DQA-011 | 空态完整 | 首次空态/过滤空态/异常空态均定义 | P2 |
| DQA-012 | 异常态完整 | 4xx/5xx/409 均有标准展示 | P1 |
| DQA-013 | 数据保留策略 | 提交失败后表单值保留 | P1 |
| DQA-014 | 审计可追溯提示 | 关键动作提示可追踪 request_id | P0 |
| DQA-015 | 敏感信息脱敏 | 界面与导出无可复用凭证片段 | P0 |
| DQA-016 | 组件复用一致 | 相同控件样式/交互一致 | P2 |
| DQA-017 | 响应式适配 | 1280/1024/768 宽度均可用 | P1 |
| DQA-018 | 文案一致性 | 同义动作命名一致，不混用 | P2 |
| DQA-019 | 加载反馈清晰 | loading/skeleton/spinner 使用统一 | P2 |
| DQA-020 | 业主验收可解释性 | SLA/申诉入口可见且流程清晰 | P1 |

判定规则：
1. 任一 P0 不通过则 UI Gate 不通过。
2. P1 通过率需 >=95%，低于阈值禁止发布。

---

## 8. 与测试和门禁对齐

1. DQA-001~020 对应测试集：`UI-DESIGN-QA-*`（纳入 SUP-003/SUP-008）。
2. 凭证脱敏相关 DQA-015 与 `SEC-SUP-001` 强绑定。
3. 权限态相关 DQA-004 与 `UI-SUP-ACC-005`、`UI-SUP-SET-*` 强绑定。
4. 业主可解释性 DQA-020 与申诉/赔付验收条款强绑定。

完成 DQA 全量执行并达标，即视为 XR-003 关闭。