# 前端功能规格 — FE-02 用户管理（列表 + 新增 / 编辑）

> 关联 REQ：REQ-USR-002, REQ-USR-003, REQ-USR-004
> 关联原型：prototype/erp.html#screen-userlist, prototype/erp.html#screen-userdetail
> 日期：2026-05-15

## 一、功能概述

超级管理员管理用户账号的三大场景：
- **列表 / 筛选**（REQ-USR-004）：分页 + 多字段筛选 + 排序，路由 `/users`
- **新增用户**（REQ-USR-002）：独立表单页 `/users/new`，提交后跳回 `/users`
- **编辑用户**（REQ-USR-003）：独立表单页 `/users/:userId`，预填详情后允许部分字段更新

UI 模式：与 prototype 两个独立 section 对齐——userlist 是表格 + filter；userdetail 是表单页（toolbar + form-grid + Tabs + 权限分类）。新增 / 编辑共用同一 UserFormPage 组件（用 `:userId === undefined` 切模式）。

**本 FE 不含**：作废 / 取消作废、删除、重置密码、导出 Excel、客户查看 / 供应商查看 / 人员查看 / 工序查看 / 司机查看等多 Tab 权限（仅实现"权限组"主 Tab）。这些后续 FE 补。

## 二、组件树

基于 `prototype/erp.html` 中 `#screen-userlist` + `#screen-userdetail` 推导：

```
UsersListPage (pages/users/UsersListPage.tsx, route="/users", protected by RequireAuth)
├── PageToolbar
│   ├── RefreshButton (调 list query)
│   ├── AddNewButton (navigate to /users/new)
│   └── （导出 Excel 按钮：visually 保留但 disabled）
├── FilterBar (filter form)
│   ├── QueryFieldSelect  （username / employeeName / userCode / departmentName / userType / isDeleted / lastLoginDate / createdBy）
│   ├── MatchModeSelect   （contains / notContains / equals）
│   ├── QueryValueInput
│   ├── SearchButton
│   └── ResetButton
├── UsersTable (AntD Table)
│   ├── columns: 序号 / 用户名 / 员工名 / 用户号 / 部门 / 用户类型 / 语言 / 作废 / 登录日期 / 制单人 / 制单日期 / 操作（编辑链接）
│   ├── rowKey="userId"
│   ├── onRowClick → navigate to /users/{userId}
│   └── pagination footer
└── UsersPagination (AntD Pagination integrated with Table)

UserFormPage (pages/users/UserFormPage.tsx, route="/users/new" + "/users/:userId", protected by RequireAuth)
├── PageToolbar
│   ├── SaveButton
│   ├── CancelButton (navigate back to /users)
│   └── （新增按钮：仅编辑模式可见，跳 /users/new）
├── UserFormFieldsPanel (form-grid)
│   ├── CreatedTime (只读，仅编辑模式显示)
│   ├── CreatedBy (只读，仅编辑模式显示)
│   ├── EmployeeSelect (label "员工名"; 当前硬编码可选员工 fixture，等 HR REQ 后改 GET /api/v1/employees)
│   ├── UsernameInput (label "用户名"，编辑模式 readonly)
│   ├── UserCodeInput (label "用户号")
│   ├── UserTypeSelect (label "类型"，options: NORMAL / SUPER_ADMIN)
│   ├── LanguageSelect (label "语言"，options: zh-CN / en-US / zh-TW)
│   └── CanEditDocumentCheckbox (label "单据修改权限")
├── PermissionTabs (单一 Tab "权限组"，其他 Tab visually 保留但 disabled)
└── PermissionCategoryList (AntD List + Checkbox 行选)
    └── PermissionCategoryRow × N (当前硬编码 fixture {PUR, SAL}, 等运营 REQ 后改 GET /api/v1/permission-categories)
```

## 三、页面状态机

### UsersListPage 状态

| # | 状态 | 触发条件 | 视觉表现 | 用户可执行操作 |
|---|------|---------|---------|--------------|
| 1 | loading | 首次进入 / refresh / filter 提交 | Table loading=true 显 spinner | 等待 |
| 2 | empty | API 返 total=0 | Table 空态 + "暂无用户" | 点新增 / 清空筛选 |
| 3 | normal | 正常返回 records | Table 渲染数据；分页器显示 total / page / size | 点行编辑 / 翻页 / 排序 / 筛选 |
| 4 | error_network | 网络错（-1） | Table 顶部 Alert "网络异常，请重试" + 重试按钮 | 点重试 |
| 5 | error_forbidden | 403 / 40301 | 全屏 Result "权限不足" | 点退回 |

### UserFormPage 状态

| # | 状态 | 触发条件 | 视觉表现 | 用户可执行操作 |
|---|------|---------|---------|--------------|
| 1 | loading_initial | 编辑模式首次进入（new 模式跳过） | 表单 disabled + spinner | 等待 |
| 2 | error_load | GET /api/v1/users/{userId} 失败（404 / 40401） | 全屏 Result "用户不存在" + 返回按钮 | 点返回 |
| 3 | idle | 表单已加载完成 | 表单可编辑（编辑模式 username 只读） | 修改字段 |
| 4 | validating | 用户点 save → 前端字段校验 | submit 按钮 disabled | 等待 |
| 5 | submitting | 校验通过，调 POST/PUT | submit 显 loading 旋转 | 等待 |
| 6 | error_field | 后端返 40001/40901/40902/40004 | 对应字段下方红字 + Alert | 改字段重试 |
| 7 | error_global | 40101 / 40301 / 40302 / 网络 | 顶部 Alert 显文案 | 操作返回 |
| 8 | success | 后端返 200/201 | message.success "保存成功"；navigate(-1) 或 navigate('/users') | 自动跳转 |

## 四、消费的后端端点

| # | 方法 | 路径 | 触发时机 | 关联 REQ |
|---|------|------|---------|---------|
| 1 | GET | `/api/v1/users` | UsersListPage 加载 / refresh / filter 提交 / 翻页 / 排序 | REQ-USR-004 |
| 2 | GET | `/api/v1/users/{userId}` | UserFormPage 编辑模式挂载 | REQ-USR-003 |
| 3 | POST | `/api/v1/users` | UserFormPage 新增模式 submit | REQ-USR-002 |
| 4 | PUT | `/api/v1/users/{userId}` | UserFormPage 编辑模式 submit | REQ-USR-003 |

请求体 / 响应结构与 docs/05 一致；客户端 `usersApi.{list, get, create, update}` 包装函数。

## 五、业务规则前端复刻清单

| # | 规则描述 | 触发时机 | 报错文案 | 来源 REQ |
|---|---------|---------|---------|---------|
| 1 | 列表 size 上限 100 | 翻页器选项；默认 20 | （AntD pagination 内置） | REQ-USR-004 |
| 2 | 列表 page<1 / sortField 非白名单 / matchMode 非白名单 → 后端返 40001/40003，前端做 banner 提示 | filter submit | "请检查筛选参数" | REQ-USR-004 |
| 3 | 用户名（新增）必填 + 3-20 位字母数字下划线（正则 `^[A-Za-z0-9_]{3,20}$`） | submit 前 | "用户名必须为 3-20 位字母数字下划线" | REQ-USR-002 |
| 4 | 用户号必填 + 最大 50 字符 | submit 前 | "请输入用户号 / 不超过 50 字符" | REQ-USR-002 / 003 |
| 5 | 类型 / 语言必填且为枚举 | submit 前 | "请选择类型 / 语言" | REQ-USR-002 / 003 |
| 6 | 单据修改权限：boolean，默认 false | 字段渲染 | — | REQ-USR-002 / 003 |
| 7 | 员工 ID 可选；选 "无 / 解除关联" 时新增传 null，编辑传 0（spec § PATCH 三态） | submit | — | REQ-USR-003 |
| 8 | 编辑模式 username + 密码字段不允许修改（username readonly；表单不展示 password 字段） | 字段渲染 | — | REQ-USR-003 |
| 9 | 新增成功 → message + navigate('/users') | 响应处理 | "新增用户成功" | REQ-USR-002 |
| 10 | 编辑成功 → message + navigate('/users') | 响应处理 | "保存成功" | REQ-USR-003 |
| 11 | 40901 用户名冲突 → field-level "用户名已存在" | 响应处理 | "用户名已存在" | REQ-USR-002 |
| 12 | 40902 用户号冲突 → field-level "用户号已存在" | 响应处理 | "用户号已被占用" | REQ-USR-002 / 003 |
| 13 | 40004 员工 / 权限分类不存在 → field-level 错误 | 响应处理 | "员工或权限分类不存在或已删除" | REQ-USR-002 / 003 |
| 14 | 40301 非超级管理员 → 全屏 Result | 响应处理 | "权限不足，仅超级管理员可调用" | REQ-USR-002 / 003 / 004 |
| 15 | 40302 试图停用自己 → banner（FE-02 不含作废按钮，此分支只在意外触发时显示） | 响应处理 | "不允许停用当前登录用户自己" | REQ-USR-003 |
| 16 | 40401 用户不存在（编辑模式 GET / PUT 都可能命中） | 响应处理 | "用户不存在" → 跳回列表 | REQ-USR-003 |
| 17 | 网络错 → banner 重试 | 响应处理 | "网络异常，请检查连接后重试" | docs/04 § 2.4 |

> **要求**：每条规则必须在前端 form-level 校验中复刻（前端能预防的不依赖后端报错）。文案与后端语义一致。

## 六、Design Tokens 引用清单

```
--color-primary           （主按钮 / 链接 / Tab 激活下划线）
--color-primary-hover     （hover）
--color-primary-active    （按下）
--color-text              （表格行文字 / 标签）
--color-text-secondary    （表格表头辅助文字 / 占位）
--color-text-disabled     （只读字段文字）
--color-error             （错误字段 / 错误 Alert）
--color-success           （保存成功 message）
--color-warning           （列表网络错黄色 Alert）
--color-border            （表格 / 输入框边框）
--color-split             （列表行分割线）
--color-bg-page           （页面底色）
--color-bg-container      （Table / 表单 card bg）
--color-bg-disabled       （只读字段 bg）
```

均来自 docs/06 § 二。本 FE 不引入新 token。

## 七、交互流程关键路径

### 列表查询 + 翻页

```
[用户访问 /users]
  1. UsersListPage 挂载 → useEffect 调 usersApi.list({page:1, size:20, sortField:'tCreateDate', sortOrder:'desc'})
  2. Table loading=true → API 返回 → set records + total
  3. 用户改 filter 输入 → 点搜索 → 重新调 list
  4. 用户点列头排序 → set sortField/sortOrder → 重新调 list
  5. 用户翻页 → set page → 重新调 list

[用户点行]
  → navigate('/users/' + row.userId)
```

### 新增用户

```
[用户在 /users 点新增]
  → navigate('/users/new')
  → UserFormPage mode=create，空表单
  → 用户填字段 → 点保存
  → validateFields → submitting 态
  → usersApi.create(form) → 成功 → message.success → navigate('/users')
  → 失败：按错误码 setFieldErrors 或 banner
```

### 编辑用户

```
[用户在 /users 点行 或 访问 /users/:id]
  → UserFormPage mode=edit，挂载时调 usersApi.get(userId)
  → loading_initial → 收到 detail → 填入表单（username readonly）
  → 用户改字段 → 点保存
  → validateFields → submitting → usersApi.update(userId, patch) → 成功 → message.success → navigate('/users')
  → 40401 不存在 → error_load 全屏 Result
```

### filter 状态保留（推迟到 FE-03+）

本 FE：刷新页面 filter 清空；下一 FE 可引入 URL query string 同步。

## 八、备注与开放问题

- **GET /api/v1/employees + /api/v1/permission-categories 暂未实现**：员工 + 权限分类下拉用 fixture 数据（见 prototype，可硬编码 2-3 项；用户选择后传 ID）。spec § 一标记延后
- **导出 Excel / 删除 / 重置密码 / 作废切换 / 多 Tab 权限**：本 FE 不实现，prototype 按钮 visually 保留但 disabled / 不绑定点击事件。docs/08 § 三 中明确"FE-02 = 列表 + 新增 / 编辑"，其他能力推后
- **大表格性能**：当前默认 size=20，size 上限 100，无需虚拟滚动；docs/04 § 3.2 一致
- **i18n**：硬编码中文。后续 i18n 接入时统一替换
- **a11y**：表单字段必须有 label（与 FE-01 同样规则）；Table 行点击同时支持键盘 Enter 跳详情
- **后端 40001 data.field-level 信息**：当前接口未明示返回 detail；FE 接到 40001 暂统一 banner，待后端扩展
- **userType=NORMAL 用户调用列表 / 详情会被后端 40301**：FE 在用户进入路由前根据 LoginContext 已知 userType，可主动 RequireSuperAdmin 守卫减少不必要请求。本 FE 实现 `<RequireSuperAdmin>` 守卫包裹 `/users/**` 路由
- **PATCH 编辑模式 employeeId 三态**：null=不变；0=解除关联；正整数=更新。前端 form 把 "无" 选项 value=0 处理