06-UI交互规范.md 7.06 KB

Edit Raw Blame History



06-UI交互规范


本项目所有页面布局以项目根 prototype/ 目录下的静态 HTML mockup 为权威。前端阶段（fe-feature-*）实现时直接以 prototype/ HTML 推导组件树与样式。本文件仅承载跨页面通用规则与 Design Tokens。


一、通用交互规则


1.1 操作反馈


成功提示：使用 Ant Design message.success，3 秒自动消失；不阻塞操作。

失败提示：使用 message.error 显示后端 Result.message；4.5 秒消失；保留可复制。

危险操作（删除 / 停用 / 重置密码）：必须 Modal.confirm 二次确认，标题写明动作，正文写明影响对象 + 不可逆性。

长耗时按钮（>300ms）：按钮 loading 态 + 禁用，避免重复提交；提交完成后恢复。

表单校验失败：字段下方红字提示；首个错误字段自动聚焦并滚入视口。


1.2 数据展示


空状态：使用 Empty 组件，图标 + 一句话说明（如 暂无用户）+ 主操作按钮（如 新增用户）。

加载中：列表用 Skeleton；单组件用 Spin；全屏首次加载允许使用 Spin 覆盖。

异常态：网络 / 5xx 错误使用 Result status="error" 显示，附 重试 按钮。

分页：默认 20 条 / 页，可选 10 / 20 / 50 / 100；显示总数 + 当前页 / 总页数。

表格列：必显列固定在左侧；操作列固定在右侧；时间列统一格式 YYYY-MM-DD HH:mm。


1.3 权限控制（前端）


菜单级：Redux auth.user.permissions 驱动；菜单项无权限直接不渲染。

路由级：router/index.tsx 用 RequireAuth + RequireRole 高阶守卫；未授权重定向到登录或 403 页。

按钮级：<Permission code="..."> 包裹按钮，无权限时不渲染（不显示 disabled 灰按钮）。

后端 RBAC 同源：前端权限码与后端 Permission 表严格对齐（codename 一致）；前端只做展示控制，最终鉴权由后端兜底。


二、Design Tokens


所有色值统一以 CSS 变量定义于 frontend/src/styles/tokens.css；命名规范见 docs/04 § 2.5。组件样式只引用 var(--color-xxx)，禁止硬编码 hex / rgba。


2.1 全局调色板

与 Ant Design 5 默认主题对齐，按语义分组。


语义
变量名
默认值
用途


主色
--color-primary
#1677ff
主按钮、链接、激活态边框


主色-悬浮
--color-primary-hover
#4096ff
主色控件 hover


主色-激活
--color-primary-active
#0958d9
主色控件 active / pressed


成功
--color-success
#52c41a
成功提示、积极状态标签


警告
--color-warning
#faad14
警告提示、需注意状态


错误
--color-error
#ff4d4f
错误提示、危险按钮


信息
--color-info
#1677ff
普通信息提示


主文字
--color-text
rgba(0,0,0,0.88)
标题、正文


次文字
--color-text-secondary
rgba(0,0,0,0.65)
辅助说明


禁用文字
--color-text-disabled
rgba(0,0,0,0.25)
禁用态


边框
--color-border
#d9d9d9
输入框 / 卡片边框


分割线
--color-split
#f0f0f0
列表分割线


背景-页面
--color-bg-page
#f5f5f5
页面底色


背景-容器
--color-bg-container
#ffffff
卡片 / 表单 / Modal


背景-禁用
--color-bg-disabled
#f5f5f5
禁用控件


2.2 组件级状态色

按场景 × 状态映射，单元格写 token 引用形式（var(--color-xxx)）。— 表示该状态不适用。


#
组件
编辑bg
只读bg
悬浮bg
编辑fg
只读fg
悬浮fg
备注


1
Input
var(--color-bg-container)
var(--color-bg-disabled)
var(--color-bg-container)
var(--color-text)
var(--color-text-secondary)
var(--color-text)
只读用 readOnly，禁用用 disabled


2
Select
var(--color-bg-container)
var(--color-bg-disabled)
var(--color-bg-container)
var(--color-text)
var(--color-text-secondary)
var(--color-text)
同 Input


3
Button-Primary
var(--color-primary)
—
var(--color-primary-hover)
#fff
—
#fff
主操作


4
Button-Default
var(--color-bg-container)
—
var(--color-bg-container)
var(--color-text)
—
var(--color-primary)
次操作


5
Button-Danger
var(--color-error)
—
#ff7875
#fff
—
#fff
删除 / 停用


6
Table-Row
var(--color-bg-container)
—
#fafafa
var(--color-text)
—
var(--color-text)
斑马纹关闭


7
Tag-Success
#f6ffed
—
—
var(--color-success)
—
—
正常 / 启用状态


8
Tag-Error
#fff2f0
—
—
var(--color-error)
—
—
停用 / 失败状态


Token 默认值（与 § 2.1 完整一致；新增 token 时此表与 tokens.css 同步更新）。


2.3 引用约定


组件样式只用 var(--color-xxx)，禁止直接写 hex / rgb / rgba。
新增 token 必须先登记到 § 2.1 / 2.2，再写入 tokens.css。
修改色值只改 tokens.css 一处；组件层不允许覆盖（如 .ant-btn-primary { background: ... } 之类禁止）。


三、页面清单

（由 downstream-gen 按模块追加段落）


module_usr 用户管理


登录页 (/login)


类型: 表单页
对应 REQ: REQ-USR-001
入口菜单: 未登录访问任何路径均重定向至此
主要交互: 公司/版本下拉（页面加载时拉取 GET /api/v1/companies）→ 输入用户名 / 密码（密码星号显示）→ 提交按钮带 loading 态防重复提交；连续 5 次失败显示锁定剩余时间；成功后写 access token 到内存并跳转默认主页


用户列表 (/users)


类型: 列表页
对应 REQ: REQ-USR-002（"新增"入口）、REQ-USR-003（"编辑"行内按钮）、REQ-USR-004（列表分页 + 筛选）
入口菜单: 系统管理 → 用户管理
主要交互: 顶部筛选区（查询字段下拉 / 匹配方式下拉 / 查询值输入框 / 查询按钮）+ 右上"新增用户"按钮 + Ant Design Table（含序号 / 用户名 / 员工名 / 用户号 / 部门 / 用户类型 / 语言 / 作废标签 / 登录日期 / 制单人 / 制单日期 / 操作列）+ 分页器（10/20/50/100）；编辑按钮打开 Modal 复用新增表单组件（按 REQ-USR-003 字段差异置只读 / 禁用）；不允许停用当前登录账号自己（按钮 disabled + tooltip 解释）


用户表单（嵌入式 Modal，无独立路由）


类型: 表单页（Modal）
对应 REQ: REQ-USR-002 / REQ-USR-003
入口菜单: 由用户列表的"新增" / "编辑"按钮触发
主要交互: 左侧基础信息区（员工名下拉 / 用户号 / 用户名 / 类型下拉 / 语言下拉 / 单据修改权限复选框 / 作废复选框（仅编辑））+ 右侧权限组区（按 sys_permission_category 渲染勾选列表）+ 底部"保存"/"取消"；保存调 POST /api/v1/users（新增）或 PUT /api/v1/users/{userId}（编辑），成功后关闭 Modal 并刷新列表