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

> **依据：** 《会员管理功能需求.md》v1.1、《会员管理技术方案.md》v1.1  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 平台管理端** 会员列表、详情、订单只读查看；C 端注册/登录 **不在 ruoyi-ui 实现**。  
> **实现状态：** 列表/详情/订单只读、**添加会员** 弹窗与 `addMember` API 已落地；待后端 `/agri/member` 联调。

---

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

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request` |
| 参考页面 | `ruoyi-ui/src/views/agri/org/merchant/index.vue`（列表 + 抽屉） |
| 状态字段 | `status`：`0` 启用 / `1` 禁用 |
| 日期区间 | 会员订单检索下单时间用 `el-date-picker type="daterange"` + `addDateRange` |

---

## 2. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 列表页 | `ruoyi-ui/src/views/agri/member/index.vue` | 会员列表、添加弹窗、启用开关 |
| 详情抽屉 | `ruoyi-ui/src/views/agri/member/detail.vue` | 基本资料 + 收货地址 |
| 订单抽屉 | `ruoyi-ui/src/views/agri/member/orders.vue` | 该会员订单列表（只读） |
| 订单详情 | `ruoyi-ui/src/views/agri/member/orderDetail.vue` | 订单详情（只读） |
| API | `ruoyi-ui/src/api/agri/member.js` | 会员与会员订单接口 |

**组件 name：** `AgriMember`

---

## 3. 菜单与路由

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

**上级菜单：** 农资管理 → **会员管理**（或用户与交易分组）

| 按钮权限 | 标识 |
|----------|------|
| 查看详情/订单 | `agri:member:query` |
| 添加会员 | `agri:member:add` |
| 启用/禁用 | `agri:member:edit` |

> 菜单需配置 **添加会员** 按钮权限 `agri:member:add`（类型 F）。

---

## 4. 页面结构

```text
会员管理
├── 检索：keyword（会员名称/昵称/手机号）、status
├── 工具栏：添加会员（弹窗）
├── 列表：名称+脱敏手机、等级、启用开关、消费次数/金额、注册日期
│   └── 操作：查看详情、查看订单
├── 详情抽屉（detail.vue）
│   ├── 基本信息
│   ├── 收货地址列表（默认标「默认」）
│   └── 按钮：查看订单
├── 订单抽屉（orders.vue · 85% 宽）
│   ├── 高级检索（编号、商品、支付/订单状态、收货人、下单日期区间）
│   ├── 订单表格（只读，操作列仅「详情」）
│   └── 嵌套订单详情抽屉（orderDetail.vue）
└── 订单详情：订单信息、商品明细、收货、物流、轨迹时间轴
```

---

## 5. 复用组件

| 组件 | 用途 |
|------|------|
| `ImagePreview` | 订单商品图 |
| `Pagination` / `RightToolbar` | 分页 |
| `el-switch` | 列表启用开关 |
| `el-timeline` | 物流轨迹 |

---

## 6. API 对接

**基路径：** `/agri/member`

| 前端方法 | HTTP | 路径 |
|----------|------|------|
| `listMember` | GET | `/list` |
| `addMember` | POST | `/` |
| `getMember` | GET | `/{memberId}` |
| `updateMemberStatus` | PUT | `/{memberId}/status` |
| `listMemberOrders` | GET | `/{memberId}/orders` |
| `getMemberOrder` | GET | `/{memberId}/orders/{orderId}` |

### 6.0 添加会员 Body

| 字段 | 表单 | 说明 |
|------|:----:|------|
| mobile | 必填 | 11 位手机号；校验 `/^1[3-9]\d{9}$/` |
| password | 必填 | 复用 `@/utils/passwordRule`（6～20 位） |
| memberCode | 选填 | 会员名称；不填后端随机 8 位 |
| nickName | 选填 | 不填同会员名称 |
| avatar | 选填 | `ImageUpload`，limit=1，5MB |
| memberLevel | 选填 | 字典 `biz_member_level` |
| status | 选填 | 默认 `"0"` 启用 |
| remark | 选填 | 备注 |

**弹窗：** 560px；工具栏「添加会员」`v-hasPermi="['agri:member:add']"`；提交 `addMember(form)`，成功刷新列表。

成功返回 `data` = `memberId`（= `user_id`）。

### 6.1 列表 Query

| 字段 | 说明 |
|------|------|
| keyword | 会员名称、昵称、手机号模糊 |
| status | `0` / `1` |
| pageNum, pageSize | 分页 |

### 6.2 启用/禁用 Body

```json
{ "status": "1" }
```

禁用前 `$modal.confirm`：「禁用后该会员将无法登录 C 端并无法下单」。

### 6.3 会员订单 Query

对齐需求 §6.3：`orderNo`、`goodsName`、`payStatus`、`shipStatus`、`consigneeName`、`beginTime`/`endTime`（由 `addDateRange` 注入）等。

### 6.4 订单状态展示

| 值 | 文案 |
|----|------|
| 0 | 待支付 |
| 1 | 待发货 |
| 2 | 已发货 |
| 3 | 已完成 |
| 4 | 已关闭 |
| 5 | 已删除 |

---

## 7. 交互要点

| 场景 | 行为 |
|------|------|
| 添加会员 | 弹窗表单；手机号+密码必填；禁用无需 confirm |
| 列表手机号 | 后端脱敏展示（如 `177****9136`） |
| 详情手机号 | query 权限可看完整号 |
| 启用开关 | 禁用二次确认；失败回滚 switch |
| 会员订单 | **只读**；无发货/关闭/删除按钮（M6） |
| 累计消费 | 列表 `orderCount` / `totalAmount` 只读（O11） |

---

## 8. 与关联模块边界

| 模块 | 关系 |
|------|------|
| 订单管理 | 履约写操作在订单模块；本模块仅只读 |
| 商户/店铺 | 会员与经营账号 **无关联**（M1/M7） |
| C 端 | 注册/登录接口 `/api/member/*` 非 ruoyi-ui |

---

## 9. 联调检查清单

- [ ] 添加会员：手机号重复、密码校验、成功后列表刷新  
- [ ] 列表 keyword 三字段模糊  
- [ ] 禁用 confirm + status 持久化  
- [ ] 详情 addressList 与默认标签  
- [ ] 订单列表仅当前 memberId  
- [ ] 订单详情校验归属（403 msg）  
- [ ] 下单日期 daterange → beginTime/endTime  

---

## 10. 非本期（前端）

余额/积分/标签、导入、批量改等级、商家端查会员。

## 11. 修订记录

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-05 | 首版：列表、详情、会员订单只读 |
| v1.1 | 2026-05 | 对齐 sys_user 复用、member 角色列表过滤；补充 addMember 接口说明 |
| v1.2 | 2026-05 | 落地添加会员弹窗、`member.js` 的 `addMember`、字典等级下拉 |

---

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