# 组织人事 UI 设计文档

> **任务编号**：07（P0-C）  
> **覆盖范围**：`US-ORG-001 ~ US-ORG-003`（组织结构维护 / 员工列表维护 / 员工入职账号创建）  
> **输出文件**：`UI_DESIGN/组织人事_UI.html`  
> **设计基线**：`UI_SYSTEM/UI_SYSTEM.md`（后台壳层、表格、分页、Modal/Drawer、树形选择器）  
> **需求依据**：
> - `PRD/TASK.md`（US-ORG-001~003）
> - `PRD/组织人事管理/组织人事管理模块PRD.md`
> - `DATA_MODEL/DATA_MODEL_ORG.md`
> **竞品截图参考**：
> - `screenshots/组织人事/组织结构/公司组织结构.png`
> - `screenshots/组织人事/组织结构/部门新增.png`
> - `screenshots/组织人事/组织结构/部门编辑.png`
> - `screenshots/组织人事/组织结构/部门详情.png`
> - `screenshots/组织人事/组织结构/部门架构图.png`
> - `screenshots/组织人事/组织结构/员工信息编辑.png`
> - `screenshots/组织人事/组织结构/员工离职.png`
> - `screenshots/组织人事/组织结构/员工调动.png`
> - `screenshots/组织人事/组织结构/员工通讯录.png`
> - `screenshots/组织人事/职务管理/职务管理.png`

---

## 1. 目标与范围

### 1.1 页面目标

组织人事页面用于承载 3 个 P0 核心能力：

1. **组织结构维护（US-ORG-001）**
   - 左侧组织树支持新增/编辑/删除部门
   - 删除有员工部门时阻断并提示
2. **员工列表维护（US-ORG-002）**
   - 支持姓名/工号/手机号关键词检索
   - 支持部门/状态筛选
   - 员工姓名可进入员工详情
3. **员工入职与账号创建（US-ORG-003）**
   - 入职表单必填校验（姓名/手机号/所属门店/职位）
   - 创建后自动生成初始密码并给出发送提示
   - 新员工立即进入组织数据并可用于后续选择器

### 1.2 本任务边界

- ✅ 包含：壳层、组织树、员工表格、架构图视图、通讯录视图、部门弹窗、入职抽屉、离职弹窗、调动抽屉、员工详情抽屉、异动记录弹窗
- ✅ 包含：关键必填校验、批量操作启用态、分页演示、Toast 反馈
- ⛔ 不包含：真实后端接口、真实地图服务、真实短信发送、真实权限系统

---

## 2. 信息架构

### 2.1 统一壳层

- **Top Bar（56px）**：品牌 + 一级导航 + 用户区
- **Sidebar（240px）**：组织人事二级导航
- **Main Content（`ml-60 pt-[72px]`）**：
  1. 面包屑 + 页面标题
  2. 主 Tab（组织结构 / 部门架构图 / 员工通讯录）
  3. 各视图内容

### 2.2 组织结构视图（默认）

#### 左栏：组织树
- 新增部门按钮
- 部门搜索
- 显示已关闭部门复选
- 树节点（名称 + 在职人数）
- 行内操作：编辑 / 删除

#### 右栏：员工管理
1. 顶部预警条（账号上限、证件不匹配）
2. 筛选区（关键词、职务、状态、审批状态、入职时间、部门级别等）
3. 操作区（新增员工、导出员工、批量调动、批量设置上级、更多、员工异动记录）
4. 员工表格（姓名、工号、职务、部门、上级、电话、入职时间、审批状态、操作）
5. 分页区

### 2.3 部门架构图视图

- 顶部筛选：部门下拉、显示已关闭部门
- 说明文案：最多 8 层，支持拖拽缩放
- 工具栏：放大、缩小、导出、适配、重置
- 树状节点卡片：部门名、级别标签、负责人、人数、直属下级

### 2.4 员工通讯录视图

- 筛选：部门、职务、生日、关键字
- 表格：部门、姓名、职务、性别、生日、电话、分机、邮箱
- 电话操作：拨打 / 查看号码
- 分页演示

---

## 3. 关键交互设计

### 3.1 组织树维护

- 点击节点切换右侧员工列表范围
- 新增部门弹窗：保存后实时加入树
- 编辑部门弹窗：字段预填并支持状态/属性调整
- 删除部门：
  - 若该部门（含下级）仍有员工，阻断并提示
  - 无员工时删除成功
- 组织树变更后，部门下拉/调动选择器实时更新（同页数据源）

### 3.2 员工列表筛选与批量

- 关键词支持：姓名 / 工号 / 手机号
- 部门筛选 + “显示下属部门员工”开关
- 状态筛选（正式/试用/冻结/离职）
- 批量按钮在未勾选时禁用，勾选后启用

### 3.3 新增员工（入职）抽屉

#### 必填字段
- 姓名
- 手机号
- 所属门店/店组
- 职务

#### 联动逻辑
- 选择职务后自动带出：职务类别、默认角色
- 仅允许选择门店/店组作为所属部门

#### 提交结果
- 自动生成初始密码
- 弹窗展示账号与密码（模拟发送）
- 新员工立即进入列表，审批状态置为“入职审”

### 3.4 员工离职弹窗

- 顶部展示业务统计（房源数/客源数/营销客数）
- 必填：离职日期、离职类型
- 可选：备注
- 成功后：员工状态改为“离职”，并写入异动记录

### 3.5 员工调动抽屉

- “调动前 / 调动后”双列对照
- 必填：调动日期、部门、职务、角色、直属上级（或勾选无直属上级）
- 备注最多 30 字
- 调动成功后更新员工归属并写入异动记录

### 3.6 员工详情抽屉

- 左侧：头像、姓名、部门、职务、工号
- 右侧 Tab：员工基本信息 / 异动记录 / 账号信息
- 列表点击姓名触发打开

---

## 4. 状态矩阵

| 状态 | 触发 | 页面反馈 |
|---|---|---|
| 默认态 | 首次进入 | 展示组织结构视图 + 默认部门员工 |
| 树节点切换 | 点击部门节点 | 右侧员工列表按节点刷新 |
| 查询态 | 输入条件并查询 | 列表过滤结果更新 |
| 空结果态 | 条件过严 | 表格空状态“暂无匹配数据” |
| 批量勾选态 | 勾选复选框 | 批量按钮启用 + 已选计数 |
| 新增员工校验失败 | 缺失必填 | 字段红字错误提示，不提交 |
| 部门删除拦截 | 部门有员工 | Toast 提示并阻断删除 |
| 离职/调动成功 | 表单校验通过 | 更新列表 + 写异动日志 + Toast |
| 主题策略 | 后台统一视觉 | 页面内不包含 Light/Dark/System 切换控件 |

---

## 5. 字段与数据模型映射（DATA_MODEL_ORG）

| UI 字段 | 数据模型字段 |
|---|---|
| 部门名称 | `org_units.name` |
| 部门级别 | `org_units.type` |
| 上级部门 | `org_units.parent_id` |
| 部门属性 | `org_units.attribute` |
| 部门状态 | `org_units.is_active` |
| 员工姓名 | `staff.name` |
| 员工工号 | `staff.employee_no` |
| 职务 | `staff.job_title` |
| 职务类别 | `staff.job_category` |
| 所属部门 | `staff.org_unit_id` |
| 员工状态 | `staff.status` |
| 手机号（脱敏显示） | `staff.phone_enc` + 展示脱敏规则 |
| 入职日期 | `staff.first_joined_at` |
| 离职日期 | `staff.resigned_at` |
| 异动类型 | `staff_transfer_logs.transfer_type` |
| 异动时间 | `staff_transfer_logs.transfer_date` |
| 操作人 | `staff_transfer_logs.operator_id` |
| 账号平台绑定 | `staff_accounts.platform / is_bound` |

---

## 6. 可访问性与实现规范

- 表格列头使用 `<th scope="col">`
- 图标按钮补充 `aria-label`
- Modal/Drawer 支持 `Esc` 关闭
- 必填错误信息使用文本提示，不仅靠颜色
- 焦点统一 `focus-visible:ring-2 focus-visible:ring-primary-600/40`
- 所有关键操作给出 Toast 反馈
- 页面遵循既有后台浅色视觉，不加入主题切换控件

---

## 7. 验收清单（本轮）

- [x] 覆盖 US-ORG-001：组织树增改删 + 删除拦截
- [x] 覆盖 US-ORG-002：员工关键词/部门/状态筛选 + 姓名详情入口
- [x] 覆盖 US-ORG-003：入职必填校验 + 自动密码 + 成功入列
- [x] 竞品关键结构已映射：组织树、架构图、离职弹窗、调动抽屉、通讯录
- [x] 页面不含 Light/Dark/System 切换控件
- [ ] 控制台 0 报错（待本地预览验证）

---

## 8. 后续衔接

- 本任务评审通过后进入任务 08：权限管理（US-PERMISSION-001~005）
- 组织结构与员工数据将作为权限人员列表、角色分配的数据基础