文档修改

2026-04-29 15:43:49 +08:00
parent c3f9de5f9f
commit b2aadf771a
28 changed files with 7502 additions and 109 deletions
--- a/Project/fonrey/UI_DESIGN/组织人事管理/组织人事_UI.md
+++ b/Project/fonrey/UI_DESIGN/组织人事管理/组织人事_UI.md
@@ -0,0 +1,219 @@
+# 组织人事 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）
+- 组织结构与员工数据将作为权限人员列表、角色分配的数据基础