ccdi/openspec/changes/add-employee-info-ui/specs/employee-info-ui/spec.md

# Spec: 员工信息管理前端用户界面

## ADDED Requirements

### Requirement: 前端SHALL提供员工信息列表页面

前端MUST提供员工信息列表页面，允许用户查看、搜索和管理员工信息。

#### Scenario: 页面加载时显示员工列表

**Given** 用户已登录系统且具有 `dpc:employee:list` 权限
**When** 用户访问员工信息管理页面
**Then** 页面应显示员工列表
**And** 列表应默认显示第1页，每页10条记录
**And** 页面应显示搜索筛选区和操作按钮

#### Scenario: 列表显示正确的员工信息

**Given** 用户已登录系统且具有 `dpc:employee:list` 权限
**When** 系统返回员工列表数据
**Then** 列表应显示以下列：姓名、柜员号、身份证号、所属部门、电话、状态、操作
**And** 状态列应显示"在职"或"离职"的文字描述
**And** 操作列应显示"详情"、"编辑"、"删除"按钮

#### Scenario: 列表支持分页

**Given** 用户已登录系统且具有 `dpc:employee:list` 权限
**And** 系统中存在25条员工记录
**When** 用户访问员工信息管理页面
**Then** 页面应显示分页控件
**And** 默认显示第1页的10条记录
**When** 用户点击第2页
**Then** 页面应显示第11-20条记录

#### Scenario: 搜索筛选区默认展开

**Given** 用户已登录系统且具有 `dpc:employee:list` 权限
**When** 用户访问员工信息管理页面
**Then** 搜索筛选区应默认显示
**And** 搜索筛选区应包含：姓名输入框、柜员号输入框、所属部门选择器、身份证号输入框、状态下拉框

---

### Requirement: 前端SHALL支持多条件搜索员工

前端MUST支持用户通过多种条件组合搜索员工信息。

#### Scenario: 按姓名模糊搜索

**Given** 用户已登录系统且具有 `dpc:employee:list` 权限
**And** 系统中存在姓名为"张三"的员工
**When** 用户在姓名输入框输入"张"
**And** 点击"搜索"按钮
**Then** 列表应仅显示姓名中包含"张"的员工记录
**And** 分页控件应显示匹配的记录总数

#### Scenario: 按柜员号精确搜索

**Given** 用户已登录系统且具有 `dpc:employee:list` 权限
**And** 系统中存在柜员号为"001"的员工
**When** 用户在柜员号输入框输入"001"
**And** 点击"搜索"按钮
**Then** 列表应仅显示柜员号为"001"的员工记录

#### Scenario: 按状态筛选

**Given** 用户已登录系统且具有 `dpc:employee:list` 权限
**And** 系统中存在在职和离职两种状态的员工
**When** 用户在状态下拉框选择"在职"
**And** 点击"搜索"按钮
**Then** 列表应仅显示状态为"在职"的员工记录

#### Scenario: 按所属部门筛选

**Given** 用户已登录系统且具有 `dpc:employee:list` 权限
**And** 系统中存在多个部门的员工
**When** 用户在所属部门选择器中选择"研发部门"
**And** 点击"搜索"按钮
**Then** 列表应仅显示该部门的员工记录

#### Scenario: 组合条件搜索

**Given** 用户已登录系统且具有 `dpc:employee:list` 权限
**When** 用户同时输入姓名"张"、柜员号"001"
**And** 点击"搜索"按钮
**Then** 列表应仅显示同时满足所有条件的记录

#### Scenario: 重置搜索条件

**Given** 用户已输入多个搜索条件并执行了搜索
**When** 用户点击"重置"按钮
**Then** 所有搜索条件输入框应清空
**And** 列表应显示所有员工记录（恢复默认）

---

### Requirement: 前端SHALL提供新增员工弹窗

前端MUST提供新增员工弹窗，允许用户输入员工基本信息并添加亲属信息。

#### Scenario: 点击新增按钮打开弹窗

**Given** 用户已登录系统且具有 `dpc:employee:add` 权限
**When** 用户点击"新增"按钮
**Then** 应打开新增员工弹窗
**And** 弹窗标题为"添加员工"
**And** 所有表单字段应为空
**And** 亲属列表应为空

#### Scenario: 填写员工基本信息

**Given** 新增员工弹窗已打开
**When** 用户填写姓名为"张三"
**And** 填写柜员号为"001"
**And** 在所属部门选择器中选择"研发部门"
**And** 填写身份证号为"110101199001011234"
**And** 填写电话为"13800138000"
**And** 选择入职时间为"2020-01-01"
**And** 选择状态为"在职"
**Then** 表单应正确显示填写的信息

#### Scenario: 添加单个亲属

**Given** 新增员工弹窗已打开
**And** 用户已填写员工基本信息
**When** 用户点击"+ 添加亲属"按钮
**Then** 亲属列表应新增一个空行
**When** 用户填写亲属姓名为"李四"
**And** 填写亲属身份证号为"110101199001011235"
**And** 填写亲属电话为"13800138001"
**And** 选择关系为"配偶"
**Then** 亲属列表应显示该亲属信息

#### Scenario: 添加多个亲属

**Given** 新增员工弹窗已打开
**And** 用户已填写员工基本信息
**When** 用户点击3次"+ 添加亲属"按钮
**And** 填写3个亲属的信息
**Then** 亲属列表应显示3个亲属
**And** 每个亲属应有独立的删除按钮

#### Scenario: 删除亲属

**Given** 新增员工弹窗已打开
**And** 亲属列表中存在2个亲属
**When** 用户点击第一个亲属的"删除"按钮
**Then** 亲属列表应仅显示1个亲属
**And** 被删除的亲属应从列表中移除

#### Scenario: 提交成功

**Given** 新增员工弹窗已打开
**And** 用户已填写所有必填信息
**When** 用户点击"确定"按钮
**Then** 系统应发送请求到后端
**And** 弹窗应关闭
**And** 应显示"新增成功"的提示消息
**And** 列表应刷新并显示新增的记录

#### Scenario: 表单验证-姓名为空

**Given** 新增员工弹窗已打开
**When** 用户不填写姓名
**And** 点击"确定"按钮
**Then** 系统应显示"姓名不能为空"的错误提示
**And** 弹窗应保持打开状态
**And** 不发送请求到后端

#### Scenario: 表单验证-身份证号格式错误

**Given** 新增员工弹窗已打开
**When** 用户填写身份证号为"123"
**And** 点击"确定"按钮
**Then** 系统应显示"身份证号格式不正确"的错误提示
**And** 弹窗应保持打开状态

#### Scenario: 亲属姓名为空验证

**Given** 新增员工弹窗已打开
**And** 用户已添加一个亲属但未填写亲属姓名
**When** 用户点击"确定"按钮
**Then** 系统应显示"亲属姓名不能为空"的错误提示

#### Scenario: 取消新增

**Given** 新增员工弹窗已打开
**And** 用户已填写部分信息
**When** 用户点击"取消"按钮
**Then** 弹窗应关闭
**And** 不保存任何数据
**And** 列表应保持原状态

---

### Requirement: 前端SHALL提供编辑员工弹窗

前端MUST提供编辑员工弹窗，允许用户修改员工信息和亲属信息。

#### Scenario: 点击编辑按钮打开弹窗

**Given** 用户已登录系统且具有 `dpc:employee:edit` 权限
**And** 列表中存在一条员工记录
**When** 用户点击该记录的"编辑"按钮
**Then** 应打开编辑员工弹窗
**And** 弹窗标题为"修改员工"
**And** 表单应显示该员工的现有信息
**And** 亲属列表应显示该员工的所有亲属

#### Scenario: 修改员工基本信息

**Given** 编辑员工弹窗已打开
**When** 用户修改姓名为"李四"
**And** 点击"确定"按钮
**Then** 系统应发送更新请求到后端
**And** 弹窗应关闭
**And** 应显示"修改成功"的提示消息
**And** 列表应刷新并显示更新后的姓名

#### Scenario: 编辑时新增亲属

**Given** 编辑员工弹窗已打开
**And** 该员工当前有1个亲属
**When** 用户点击"+ 添加亲属"按钮
**And** 填写新亲属信息
**And** 点击"确定"按钮
**Then** 系统应发送更新请求到后端
**And** 再次打开编辑弹窗时应显示2个亲属

#### Scenario: 编辑时删除亲属

**Given** 编辑员工弹窗已打开
**And** 该员工当前有2个亲属
**When** 用户点击其中一个亲属的"删除"按钮
**And** 点击"确定"按钮
**Then** 系统应发送更新请求到后端
**And** 再次打开编辑弹窗时应仅显示1个亲属

#### Scenario: 编辑时修改亲属信息

**Given** 编辑员工弹窗已打开
**And** 该员工有亲属"李四"
**When** 用户修改亲属姓名为"王五"
**And** 点击"确定"按钮
**Then** 系统应发送更新请求到后端
**And** 再次打开编辑弹窗时应显示亲属姓名为"王五"

#### Scenario: 编辑时清除所有亲属

**Given** 编辑员工弹窗已打开
**And** 该员工有亲属信息
**When** 用户逐个删除所有亲属
**And** 点击"确定"按钮
**Then** 系统应发送更新请求到后端
**And** 再次打开编辑弹窗时亲属列表应为空

---

### Requirement: 前端SHALL提供员工详情弹窗

前端MUST提供员工详情弹窗，以只读方式展示员工完整信息和亲属列表。

#### Scenario: 点击详情按钮打开弹窗

**Given** 用户已登录系统且具有 `dpc:employee:query` 权限
**And** 列表中存在一条员工记录
**When** 用户点击该记录的"详情"按钮
**Then** 应打开员工详情弹窗
**And** 弹窗标题为"员工详情"
**And** 所有字段应为只读状态

#### Scenario: 显示员工基本信息

**Given** 员工详情弹窗已打开
**Then** 应显示以下信息：姓名、柜员号、所属部门、身份证号、电话、入职时间、状态、创建时间
**And** 状态应显示为"在职"或"离职"的文字描述
**And** 所有字段应不可编辑

#### Scenario: 显示亲属列表

**Given** 员工详情弹窗已打开
**And** 该员工有2个亲属
**Then** 亲属列表应显示2个亲属
**And** 每个亲属应显示：亲属姓名、亲属身份证号、亲属电话、与员工关系
**And** 亲属列表应不可编辑

#### Scenario: 无亲属时显示提示

**Given** 员工详情弹窗已打开
**And** 该员工无亲属信息
**Then** 亲属列表区域应显示"暂无亲属信息"的提示

---

### Requirement: 前端SHALL支持删除员工

前端MUST支持删除员工操作，包括单个删除和批量删除。

#### Scenario: 删除单条记录

**Given** 用户已登录系统且具有 `dpc:employee:remove` 权限
**And** 列表中存在一条员工记录
**When** 用户点击该记录的"删除"按钮
**Then** 应弹出确认对话框，提示是否确认删除
**When** 用户确认删除
**Then** 系统应发送删除请求到后端
**And** 应显示"删除成功"的提示消息
**And** 列表应刷新，该记录应从列表中移除

#### Scenario: 取消删除

**Given** 用户已点击"删除"按钮
**And** 确认对话框已显示
**When** 用户点击"取消"按钮
**Then** 对话框应关闭
**And** 不发送删除请求
**And** 记录应保留在列表中

#### Scenario: 批量删除

**Given** 用户已登录系统且具有 `dpc:employee:remove` 权限
**And** 列表中存在多条员工记录
**When** 用户勾选3条记录
**And** 点击"删除"按钮
**And** 确认删除
**Then** 系统应发送批量删除请求到后端
**And** 应显示"删除成功"的提示消息
**And** 列表应刷新，被删除的记录应从列表中移除

---

### Requirement: 前端SHALL支持导入员工数据

前端MUST支持通过 Excel 文件批量导入员工数据。

#### Scenario: 点击导入按钮打开导入弹窗

**Given** 用户已登录系统且具有 `dpc:employee:import` 权限
**When** 用户点击"导入"按钮
**Then** 应打开导入数据弹窗
**And** 弹窗标题为"员工数据导入"
**And** 应显示文件上传区域

#### Scenario: 上传Excel文件

**Given** 导入弹窗已打开
**When** 用户选择一个 Excel 文件
**And** 点击"确定"按钮
**Then** 系统应上传文件到后端
**And** 应显示上传进度
**And** 上传完成后应显示导入结果消息

#### Scenario: 导入成功提示

**Given** 用户上传了一个包含有效数据的 Excel 文件
**When** 文件上传完成
**Then** 应显示导入成功消息，包含成功导入的记录数
**And** 弹窗应自动关闭
**And** 列表应刷新，显示新导入的记录

#### Scenario: 导入部分失败提示

**Given** 用户上传了一个包含10条数据的 Excel 文件
**And** 其中2条数据格式错误
**When** 文件上传完成
**Then** 应显示导入结果消息，说明成功8条，失败2条
**And** 消息中应包含失败行的错误详情

#### Scenario: 更新已存在数据选项

**Given** 导入弹窗已打开
**When** 用户勾选"是否更新已经存在的员工数据"选项
**And** 上传文件
**Then** 请求应携带 `updateSupport=true` 参数

#### Scenario: 下载导入模板

**Given** 导入弹窗已打开
**When** 用户点击"下载模板"链接
**Then** 浏览器应下载 Excel 模板文件
**And** 导入弹窗应保持打开

#### Scenario: 支持拖拽上传

**Given** 导入弹窗已打开
**When** 用户将 Excel 文件拖拽到上传区域
**Then** 文件应自动添加到上传队列

---

### Requirement: 前端SHALL根据权限控制按钮显示

前端MUST根据用户权限显示或隐藏相应的操作按钮。

#### Scenario: 无新增权限时隐藏新增按钮

**Given** 用户已登录系统
**And** 该用户不具有 `dpc:employee:add` 权限
**When** 用户访问员工信息管理页面
**Then** "新增"按钮应隐藏或禁用

#### Scenario: 无编辑权限时隐藏编辑按钮

**Given** 用户已登录系统
**And** 该用户不具有 `dpc:employee:edit` 权限
**When** 用户访问员工信息管理页面
**Then** 列表操作列中的"编辑"按钮应隐藏或禁用

#### Scenario: 无删除权限时隐藏删除按钮

**Given** 用户已登录系统
**And** 该用户不具有 `dpc:employee:remove` 权限
**When** 用户访问员工信息管理页面
**Then** 列表操作列中的"删除"按钮应隐藏或禁用

#### Scenario: 无导入权限时隐藏导入按钮

**Given** 用户已登录系统
**And** 该用户不具有 `dpc:employee:import` 权限
**When** 用户访问员工信息管理页面
**Then** "导入"按钮应隐藏或禁用

---

### Requirement: 前端SHALL提供友好的用户反馈

前端MUST在各种操作中提供适当的用户反馈。

#### Scenario: 加载状态显示

**Given** 用户执行任何需要请求后端的操作
**When** 请求正在处理中
**Then** 列表或弹窗应显示加载状态（如 loading 遮罩）

#### Scenario: 操作成功提示

**Given** 用户执行新增、修改或删除操作
**When** 操作成功
**Then** 应显示成功提示消息
**And** 提示消息应在几秒后自动消失

#### Scenario: 操作失败提示

**Given** 用户执行新增、修改或删除操作
**When** 操作失败
**Then** 应显示错误提示消息
**And** 错误消息应说明失败原因

#### Scenario: 网络错误处理

**Given** 用户执行任何需要请求后端的操作
**When** 网络请求失败
**Then** 应显示网络错误提示消息
**And** 弹窗应保持打开状态（如果是新增/编辑操作）

---

### Requirement: 前端SHALL支持响应式布局

前端MUST确保页面在不同屏幕尺寸下正常显示。

#### Scenario: 小屏幕适配

**Given** 用户使用小屏幕设备访问页面
**When** 页面加载完成
**Then** 搜索筛选区应合理布局
**And** 表格应支持横向滚动
**And** 弹窗应适配屏幕尺寸

#### Scenario: 大屏幕优化

**Given** 用户使用大屏幕设备访问页面
**When** 页面加载完成
**Then** 搜索筛选区应在一行内显示
**And** 表格应充分利用屏幕宽度