# 表单与数据录入 UX 最佳实践

> **doc_type**: Standard
> **status**: Active
> **owner**: FFOA Team
> **scope**: 项目内所有"业务信息管理"模块（CRM / ERP-like / 主数据 / 工单类）的录入 UI
> **last_verified**: 2026-05-17

## 1. 为什么有这份文档

业务系统 80% 的用户时间花在「填表 + 找数据 + 改数据」上。录入 UX 的小改进对总效率影响**线性**——一个员工每天填 10 个表，每个表省 5 秒，一天 50 秒，100 人 1.4 小时/天，一年 250+ 工时。

业内 Salesforce / SAP / NetSuite / Linear / Notion / Airtable / Stripe Dashboard 等成熟产品的共识沉淀如下，**做新模块时按这套清单逐项核对**。

## 2. 十条核心原则

### P0 — 必做（投入小、影响大）

#### 2.1 减少键盘输入

- **智能默认值**：从上下文推断（`country=CN → currencyCode=CNY`；当前用户作为 `createdBy`；上次输入值复用）
- **自动编码**：业务 code 自动生成（如 `C-{timestamp}`）— 用户能改但不必填
- **联动字段**：选了 model → SKU 下拉只显示该 model 的
- **扫码 / 条码 / 二维码**：现场录入首选，扫到的内容直接深链到目标页
- **粘贴导入**：从 Excel 复制粘贴 → 解析成多行

#### 2.2 渐进式披露

- **必填先行**：required 在表单顶部，optional 折叠
- **场景分层**：同一个表单按 stage / role 显示不同字段
- **"更多"展开**：高频字段默认显示，低频藏在"高级"展开后

#### 2.3 就地编辑（Inline Edit）

- **Airtable / Notion 风**：点列表里某格 → 直接编辑 → 失焦保存
- **不要"点行 → 弹窗 → 编辑 → 保存"4 步流程**，原子字段（boolean / 国家码 / enum 单选）适合 inline 编辑

#### 2.4 实时校验

- 边输边校验：code 重复立即提示，不等 submit
- 错误信息建设性：「code 至少 3 位」而不是「invalid」
- placeholder 提示格式：`FF-202605-NNNNN` 让用户照样子写

#### 2.5 草稿 / 自动保存

- 表单未提交时自动存 `localStorage`，崩了 / 关 tab 也能恢复
- 「未保存」红点提示
- 适合长表单（10+ 字段或包含 textarea）

### P1 — 应做（中等投入，明显价值）

#### 2.6 批量操作

- 多选 → 批量改 enabled / 批量删
- 从 Excel 粘贴 N 行 → 直接成 N 条记录
- 批量操作后的 toast 含"撤销"按钮

#### 2.7 跨上下文 Quick-Add

- 创建主表时发现引用实体不存在 → 表单里直接「+ 新建」侧抽屉打开，填完返回主表单自动选上
- 例：创建 SalesOrder 选客户发现没有 → quick-add 客户

#### 2.8 键盘优先

- Tab 流畅切换字段
- `Cmd+K` 命令面板（"创建客户" / "找机器人 FF-..."）
- `Esc` 关闭弹窗，`Enter` 提交
- `c` 创建，`e` 编辑，`/` 搜索（项目惯例热键）

### P2 — 可做（投入较大或场景特定）

#### 2.9 移动端 / 现场友好

- 触控目标 ≥ 44×44 px
- 底部抽屉（Bottom Sheet）替代右侧弹窗
- 语音输入（free-text 字段，浏览器原生 `SpeechRecognition`）
- 拍照上传
- 离线优先 + 后台同步（进阶）
- GPS 自动填位置

#### 2.10 乐观 UI + 撤销

- 改 enabled flag → 立即反应，不等服务器；失败 toast + 自动 revert
- 删除后 toast 带"撤销 (5s)"按钮（Gmail 模式）

## 3. 项目内实施清单

| 阶段 | 完成项 | 状态 |
|---|---|---|
| QR 扫码 | 详情页二维码 + 扫码 deep link + html5-qrcode 摄像头 | ✅ |
| 智能 code 默认 | `C-{ts}` / `S-{ts}` / `P-{ts}` / `L-{ts}` 自动生成 | ✅ |
| 全局热键 | `c` / `/` / `Cmd+K` 在 robot-manager 已有 | 🟡 部分 |
| Inline edit | 列表内 enabled toggle / enum 选择就地切换 | ⏳ P0 待做 |
| 草稿 autosave | localStorage + 表单恢复 | ⏳ P0 待做 |
| 实时校验 | code 重复 / 字段联动默认值 | ⏳ P0 待做 |
| 批量操作 | 多选 + 批量 enable / 删 | ⏳ P1 |
| Excel 粘贴导入 | 4 主数据页 + L3 业务表 | ⏳ P1 |
| Quick-Add | 表单内创建引用实体 | ⏳ P1 |
| 全局 Cmd+K | 全应用命令面板 | ⏳ P2 |
| 移动端响应式 | 现场扫码后 Action Panel | ⏳ P2 |
| 撤销 toast | 删除可撤销 | ⏳ P2 |
| 语音输入 | service ticket / inspection 自由文本 | ⏳ P2 |

## 4. 反模式（避免）

| 反模式 | 为什么不好 | 替代 |
|---|---|---|
| Save 按钮提交后才校验 | 用户填完 30 字段才发现 code 重复 | 边输边校验，错误就地显示 |
| 30 字段单一巨型表单 | 视觉过载 + 必填不明确 | 必填一组 + "更多"折叠 |
| 所有字段统一 modal 编辑 | 改一个 boolean 都要弹窗 | inline edit 原子字段 |
| 错误提示"invalid" | 用户不知怎么改 | 「至少 3 位 / 只允许字母数字」 |
| 删除即刻消失 | 误删无救 | 软删 + 5 秒撤销 toast |
| 单 PR 一次性补全所有 UX 改进 | 风险大，回滚成本高 | 按 P0/P1/P2 分批落地 |

## 5. 工程化复用

新模块开发 / 现有模块迭代时，**review 这份清单**：
1. 在 PR 描述里勾选已应用的条目
2. 故意跳过的项目写明理由
3. 通用组件（如 `CrudListPage` / `SimpleListPage`）持续吸收新模式，不要每模块自己重写

## 6. 关联文档

- 项目级前端规范：`.agents/skills/frontend-main/references/frontend-standards.md`
- 设计系统：复用 `frontend/src/styles/theme.ts` 颜色与 typography
- 模块文档模板：`docs/standards/06-documentation-system.md` 不强制 UX 清单段，但鼓励在 05-ui-interaction-spec.md 显式列出