lijiaoqiao/docs/supply_uiux_design_spec_v1_2026-03-25.md

供应侧 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 关闭。