# 员工管理 — 前端技术方案

> **依据：** 《员工管理功能需求.md》v1.2、《员工管理技术方案.md》v1.1  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 商家端（店铺经营管理端）** 当前店铺员工 CRUD、改资料、改密；经营账号 **不在列表**。  
> **实现状态：** 页面与 API 封装已落地，待后端 `/agri/seller/employee` 及 `X-Shop-Id` 联调。

---

## 1. 技术栈与写法约定

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request` + `sellerShopHeaders()` 携带 **`X-Shop-Id`** |
| 参考页面 | `agri/seller/role/index.vue`（店铺上下文）、`agri/accountManage/index.vue`（改密弹窗） |
| 布局 | 检索区 `el-card` + `<br/>` + 列表区 `el-card` + 表格 `border` |
| 状态字典 | `sys_normal_disable`（0 正常 / 1 停用） |
| 密码规则 | `@/utils/passwordRule` 混入 |

---

## 2. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 列表页 | `ruoyi-ui/src/views/agri/seller/employee/index.vue` | 列表、创建/编辑、修改账号/密码 |
| 员工 API | `ruoyi-ui/src/api/agri/seller/employee.js` | CRUD、配额、角色下拉 |
| 店铺上下文 | `ruoyi-ui/src/api/agri/seller/context.js` | 已有，复用 |
| 店铺工具 | `ruoyi-ui/src/utils/sellerShop.js` | 已有，复用 |

**组件 name（keep-alive）：** `AgriSellerEmployee`

---

## 3. 菜单与路由

| 菜单名称 | 组件路径 | 路由 path（建议） | 权限标识 |
|----------|----------|-------------------|----------|
| 员工管理 | `agri/seller/employee/index` | `seller/employee` | `agri:seller:employee:list` |

**上级菜单：** 店铺经营管理端 → **账号管理**

| 按钮权限 | 标识 |
|----------|------|
| 详情回显 | `agri:seller:employee:query` |
| 创建员工 | `agri:seller:employee:add` |
| 编辑 / 修改账号 | `agri:seller:employee:edit` |
| 修改密码 | `agri:seller:employee:resetPwd` |
| 删除员工 | `agri:seller:employee:remove` |

---

## 4. 页面结构

```text
员工管理
├── 检索区（el-card）
│   └── 员工名称 employeeName（模糊，仅此一项）
├── 列表区（el-card + border 表格）
│   ├── 卡片头：商户名称、员工配额 usedCount/maxCount
│   ├── 配额已满 warning
│   ├── 工具栏：创建员工（配额满 disabled）
│   ├── 列：员工账号、员工名称、手机号（脱敏）、邮箱、状态
│   └── 操作：编辑、修改账号、修改密码、删除
├── 创建/编辑弹窗（600px）
│   ├── 员工名称、手机号（编辑 disabled）、邮箱、头像、状态
│   ├── 绑定角色（多选，至少 1 个）
│   └── 创建 **不含密码**；提示创建后须改密
├── 修改账号弹窗（520px）
│   └── 员工名称、手机号、邮箱 → PUT /profile
└── 修改密码弹窗（520px）
    └── 新密码 + 确认新密码 → PUT /resetPwd
```

---

## 5. 复用组件

| 组件 | 用途 |
|------|------|
| `ImageUpload` | 头像上传 limit=1, 5MB |
| `dict-tag` | 状态展示 |
| `Pagination` / `RightToolbar` | 分页、检索显隐 |
| `el-alert` | 配额已满提示 |

---

## 6. API 对接

**基路径：** `/agri/seller/employee`

| 前端方法 | HTTP | 路径 | 说明 |
|----------|------|------|------|
| `listSellerEmployee` | GET | `/list` | 分页列表 |
| `sellerEmployeeQuota` | GET | `/quota` | 配额与店铺/商户展示 |
| `sellerEmployeeRoleOptions` | GET | `/roleOptions` | 当前店铺可选角色 |
| `getSellerEmployee` | GET | `/{userId}` | 详情（含 roleIds、完整手机号） |
| `addSellerEmployee` | POST | `/` | 创建（**无 password**） |
| `updateSellerEmployee` | PUT | `/` | 编辑（含头像、状态、角色） |
| `updateSellerEmployeeProfile` | PUT | `/profile` | 修改账号 |
| `resetSellerEmployeePassword` | PUT | `/resetPwd` | 修改密码 |
| `delSellerEmployee` | DELETE | `/{userIds}` | 删除 |

### 6.1 列表 Query

| 字段 | 说明 |
|------|------|
| pageNum, pageSize | 分页 |
| employeeName | 员工名称模糊 |

### 6.2 配额 VO

| 字段 | 展示 |
|------|------|
| shopName / merchantName | quota 接口返回；页头 **仅展示商户名称**（店铺切换见 Navbar） |
| usedCount / maxCount | 「员工 3/5」；**商户级**计数 |
| quotaFull | `usedCount >= maxCount` 时禁用创建、展示 warning |

### 6.3 创建 Body

| 字段 | 说明 |
|------|------|
| employeeName, mobile | 必填；mobile=登录账号 |
| email, avatar | 选填 |
| status | 默认 `"0"` |
| roleIds | 至少 1 个；来自 roleOptions |
| shopId | **不传**（后端取 X-Shop-Id） |
| password | **不传**（EM10） |

创建成功：`msgSuccess` + 可选 `$modal.confirm` 引导立即改密；响应 `userId` 用于打开改密弹窗。

### 6.4 编辑 vs 修改账号

| 入口 | 接口 | 字段 |
|------|------|------|
| **编辑** | PUT `/` | 名称、手机、邮箱、头像、状态、roleIds |
| **修改账号** | PUT `/profile` | 仅名称、手机、邮箱 |

编辑时手机号 **disabled**（与创建后账号稳定策略一致；改手机走修改账号入口）。

### 6.5 修改密码

| 字段 | 说明 |
|------|------|
| userId | 必填 |
| password / confirmPassword | pwdValidator + 一致校验 |

---

## 7. 交互与校验

| 场景 | 前端行为 |
|------|----------|
| 店铺上下文 | `loadShopContext` 写 X-Shop-Id；切换店铺 **仅 Navbar** reload |
| 创建 | 配额满拦截；角色至少 1 个 |
| 创建成功 | 提示须改密；可选立即打开改密弹窗 |
| 启用员工 | 编辑 status=0；超配额由后端 msg |
| 删除 | 二次确认「无法登录商家端」 |
| 角色下拉 | 仅当前店铺正常角色（后端过滤停用） |

---

## 8. 权限指令

```html
v-hasPermi="['agri:seller:employee:add']"
v-hasPermi="['agri:seller:employee:edit']"
v-hasPermi="['agri:seller:employee:resetPwd']"
v-hasPermi="['agri:seller:employee:remove']"
```

---

## 9. 与关联模块边界

| 模块 | 关系 |
|------|------|
| 角色管理 | roleOptions 数据源；须先建角色再绑员工 |
| 店铺设置 | maxCount 全局配额；前端只展示与禁用创建 |
| 平台账号管理 | 员工作为 sys_user 可被平台检索；CRUD 在本模块 |
| 经营账号 | **不出现在列表**；不可在本模块创建/删除 |

---

## 10. 联调检查清单

- [ ] 菜单 `agri/seller/employee/index` 可打开  
- [ ] X-Shop-Id 正确；列表仅当前店铺员工  
- [ ] 配额展示 usedCount/maxCount  
- [ ] employeeName 检索  
- [ ] 创建不含密码；成功后引导改密  
- [ ] 角色多选至少 1 个；仅当前店铺角色  
- [ ] 编辑 / 修改账号 / 改密 / 删除各接口正常  
- [ ] 超配额创建/启用后端 msg  
- [ ] 手机号重复后端 msg  
- [ ] 切换店铺后列表变化（Navbar reload）  

---

## 11. 非本期（前端）

| 项 | 说明 |
|----|------|
| 批量删除 | 需求未列 |
| 经营账号行 | 列表不含 |
| 创建表单密码项 | EM10 禁止 |

---

## 12. 修订记录

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-06 | 首版：员工 CRUD、配额、改密、X-Shop-Id、前端技术方案 |

---

*文档版本：v1.0 · ruoyi-ui · 关联《员工管理功能需求.md》v1.2 / 《员工管理技术方案.md》v1.1*
