# 店铺管理 — 前端技术方案

> **依据：** 《店铺管理功能需求.md》v1.4、《店铺管理技术方案.md》v1.5  
> **实现状态：** 列表/添加/编辑/更换主账号/删除已对齐 v1.4。

---

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

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request` |
| 参考页面 | `ruoyi-ui/src/views/agri/content/banner/index.vue` |
| 选商户 | 复用 `selectMerchantList`、`openShopCheck`（`@/api/agri/merchant`） |
| 换绑搜索 | 复用 `adminUserOptions`、`memberOptions`（`@/api/agri/merchant`） |
| 店铺状态 | `0` 开业 / `1` 停业 |

---

## 2. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 页面 | `ruoyi-ui/src/views/agri/org/shop/index.vue` | 列表、开店/编辑弹窗、更换主账号弹窗 |
| API | `ruoyi-ui/src/api/agri/shop.js` | 店铺 CRUD、删店预检、主账号查询/换绑 |
| API | `ruoyi-ui/src/api/agri/merchant.js` | `selectMerchantList`、`openShopCheck`、账号搜索 |

**组件 name：** `AgriShop`

---

## 3. 菜单与路由

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

**上级菜单：** 农资管理 → **组织管理**

| 按钮权限 | 标识 |
|----------|------|
| 添加店铺 | `agri:shop:add` |
| 编辑店铺 | `agri:shop:edit` |
| 删除店铺 | `agri:shop:remove` |
| 更换主账号 | `agri:shop:account` |

> **店铺设置** 已独立菜单，见《店铺设置前端技术方案.md》；本页 **无** 逐店设置入口。

---

## 4. 页面结构

```text
店铺管理
├── 检索区（el-card）
│   ├── 关键词 keyword（店铺名/商户名/主账号）
│   ├── 店铺状态 shopStatus
│   └── 商户名称 merchantName（支持路由 query 带入）
├── 列表区（el-card + border 表格）
│   ├── 列：名称、头像、商户名、状态、评分、主账号
│   └── 操作：编辑、更换主账号、删除
├── 添加/编辑弹窗（640px）
│   ├── 公共：名称、头像、电话、描述
│   ├── 添加：选商户、主账号只读展示、店铺状态（选填，默认开业）
│   └── 编辑：所属商户/主账号只读、店铺状态（开业/停业）
└── 更换主账号弹窗（600px）
    ├── 提示：修改同步至该商户下全部店铺
    ├── 下属店铺标签列表
    ├── 当前主账号只读
    ├── 绑定方式：平台管理员 / 会员（二选一）
    └── 远程搜索选择 bindUserId 或 bindMemberId
```

---

## 5. v1.4 对齐要点

| 变更项 | 前端处理 |
|--------|----------|
| 列表列 **主账号** | `accountAdminName / accountLoginName`（后端脱敏） |
| 列表列 **评分** | `rating`；`formatRating` 无值显示 `—`，有值两位小数 |
| **更换主账号** | 替代原「账号管理」改登录名/密码；`bindType` + 远程 select |
| 添加店铺 **不再** 采集账号字段 | 选商户后 `getShopAccount` 只读展示 |
| `shop_phone` 添加/编辑 **均选填** | 有值时校验电话格式 |
| 停业 S12 | 仅 `0→1` 时 `confirm` 两步 |
| 换绑确认 | 提交前 `$modal.confirm`「更换后将同步至该商户下全部店铺」 |

---

## 6. 复用组件

| 组件 | 用途 |
|------|------|
| `ImageUpload` | 店铺头像，limit=1，5MB，png/jpg/jpeg |
| `ImagePreview` | 列表头像缩略图 |
| `Pagination` / `RightToolbar` | 分页与检索显隐 |

---

## 7. API 对接

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

| 前端方法 | HTTP | 路径 | 调用场景 |
|----------|------|------|----------|
| `listShop` | GET | `/list` | 列表（含 `rating`） |
| `getShop` | GET | `/{shopId}` | 编辑回显 |
| `addShop` | POST | `/` | 添加店铺 |
| `updateShop` | PUT | `/` | 编辑店铺 |
| `deleteShopCheck` | GET | `/{shopId}/deleteCheck` | 删除预检 |
| `delShop` | DELETE | `/{shopIds}` | 删除 |
| `getShopAccount` | GET | `/merchant/{merchantId}/account` | 添加展示、换绑回显 |
| `updateShopAccount` | PUT | `/merchant/{merchantId}/account` | 换绑主账号 |

**协作接口（merchant.js）：**

| 方法 | 路径 | 用途 |
|------|------|------|
| `selectMerchantList` | GET `/agri/merchant/selectList` | 添加店铺选商户 |
| `openShopCheck` | GET `/agri/merchant/{id}/openShopCheck` | 选商户后可开店校验 |
| `adminUserOptions` | GET `/agri/merchant/adminUserOptions` | 换绑-平台管理员搜索 |
| `memberOptions` | GET `/agri/merchant/memberOptions` | 换绑-会员搜索 |

### 7.1 换绑主账号请求体

```json
{
  "bindType": "SYS_USER",
  "bindUserId": 20
}
```

或 `{ "bindType": "MEMBER", "bindMemberId": 5 }`。

### 7.2 编辑店铺 · 停业二次确认（S12）

1. 首次 `PUT` 带 `shopStatus: "1"`，`confirm: false`
2. `needConfirm` 时弹窗确认后再 `confirm: true`

---

## 8. 交互与校验

| 场景 | 前端行为 |
|------|----------|
| 选商户变更 | `openShopCheck` + `getShopAccount`；无主账号则阻断 |
| 换绑 | `bindType` 切换清空已选；远程搜索 ≥1 字符 |
| 换绑提交 | 与 `currentAccountId` 相同则提示；确认后 PUT |
| 列表评分 | null/空 → `—` |
| 删除 | 先 `deleteShopCheck` |

---

## 9. 权限指令

```html
v-hasPermi="['agri:shop:add']"
v-hasPermi="['agri:shop:edit']"
v-hasPermi="['agri:shop:remove']"
v-hasPermi="['agri:shop:account']"
```

---

## 10. 联调检查清单

- [x] 列表展示 **评分**、**主账号** 列
- [x] 更换主账号：管理员/会员远程搜索可选
- [x] 换绑成功后同商户多店主账号列一致
- [ ] 添加店铺无账号输入项；无主账号商户被阻断
- [ ] 开业→停业 needConfirm 两步
- [ ] deleteCheck 阻断并展示 reasons

---

## 11. 修订记录

| 版本 | 日期 | 说明 |
|------|------|------|
| **v1.4** | 2026-05 | 主账号列名；评分列；更换主账号换绑 UI |
| v1.3 | 2026-06 | v1.3.6：编辑电话选填、停业 confirm |
| v1.0 | 2026-05 | 首版：列表 CRUD |

---

*文档版本：v1.4 · ruoyi-ui · 关联《店铺管理功能需求.md》v1.4、《店铺管理技术方案.md》v1.5*
