# 商户入驻审核 — 前端技术方案

> **依据：** 《商户入驻审核功能需求.md》v1.0.2、《商户入驻审核技术方案.md》v1.0.2  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 平台管理端** 申请列表、详情、审核通过/驳回；C 端提交入驻 **不在 ruoyi-ui 实现**。  
> **实现状态：** 页面与 API 封装已落地，待后端 `/agri/merchantEntryApply` 联调。

---

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

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request` |
| 参考页面 | `ruoyi-ui/src/views/agri/content/banner/index.vue`（列表） |
| 详情参考 | `ruoyi-ui/src/views/system/user/view.vue`（抽屉 + 分区展示） |
| 申请状态 | `0` 待审核 / `1` 通过 / `2` 未通过 |

---

## 2. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 列表页 | `ruoyi-ui/src/views/agri/org/merchantEntryApply/index.vue` | 列表、Tab 筛选、待审角标 |
| 详情抽屉 | `ruoyi-ui/src/views/agri/org/merchantEntryApply/detail.vue` | 详情、通过/驳回 |
| API | `ruoyi-ui/src/api/agri/merchantEntryApply.js` | 列表、详情、待审数、审核 |

**组件 name：** `AgriMerchantEntryApply`

---

## 3. 菜单与路由

| 菜单名称 | 组件路径 | 路由 path（建议） | 权限标识 |
|----------|----------|-------------------|----------|
| 商户入驻审核 | `agri/org/merchantEntryApply/index` | `merchantEntryApply` | `agri:merchantEntryApply:list` |

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

| 按钮权限 | 标识 |
|----------|------|
| 查看详情 | `agri:merchantEntryApply:query` |
| 审核通过/驳回 | `agri:merchantEntryApply:audit` |

---

## 4. 页面结构

```text
商户入驻审核
├── 检索区（el-card）
│   ├── 关键词 keyword（申请会员名称）
│   └── 申请状态 applyStatus
├── 列表区（el-card）
│   ├── Tab：全部 / 待审核（角标） / 通过 / 未通过
│   ├── 表格：申请信息、会员名、联系人、状态、申请时间
│   └── 操作：查看详情
└── 详情抽屉（detail.vue · 72% 宽）
    ├── 基础信息（含驳回原因）
    ├── 主体资质（个人 / 企业）
    ├── 商户经营信息
    ├── 首家店铺信息
    └── 待审核操作区：审核通过、审核驳回（弹窗填原因）
```

**默认 Tab：** 待审核（`applyStatus=0`），便于审核工作台（EA9）。

---

## 5. 复用组件

| 组件 | 用途 |
|------|------|
| `ImagePreview` | 详情页证件照、店铺头像 |
| `el-descriptions` | 详情分区只读展示 |
| `Pagination` | 分页 |

---

## 6. API 对接

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

| 前端方法 | HTTP | 路径 | 调用场景 |
|----------|------|------|----------|
| `listMerchantEntryApply` | GET | `/list` | 列表、Tab、检索 |
| `getPendingCount` | GET | `/pendingCount` | 待审 Tab 角标 |
| `getMerchantEntryApply` | GET | `/{applyId}` | 详情 |
| `approveMerchantEntryApply` | PUT | `/approve/{applyId}` | 审核通过 |
| `rejectMerchantEntryApply` | PUT | `/reject` | 审核驳回 |

### 6.1 列表请求参数

| 字段 | 说明 |
|------|------|
| keyword | 模糊 member_code |
| applyStatus | `0` / `1` / `2`；不传查全部 |
| pageNum, pageSize | 分页 |

### 6.2 列表行字段

| 字段 | 展示 |
|------|------|
| subjectLabel | 个人/企业 + 姓名或企业名 |
| memberCode | 申请会员名称；空显示「—」 |
| applyStatus | Tag：待审 warning / 通过 success / 未通过 danger |

### 6.3 详情响应分区

后端 `EntryApplyDetailVO` 或解析 `formJson`：

| 分区 | 前端取值 |
|------|----------|
| subject | `data.subject` 或 `formJson.subject` |
| biz | `data.biz` 或 `formJson.biz` |
| shop | `data.shop` 或 `formJson.shop` |
| canApprove / canReject | 控制操作按钮 |

### 6.4 审核通过

```json
{ "confirmed": true }
```

前端 `$modal.confirm` 后提交；成功返回 `{ merchantId, shopId }`。

### 6.5 审核驳回

```json
{
  "applyId": 1,
  "rejectReason": "营业执照不清晰，请重新上传"
}
```

`rejectReason` 必填，maxlength 200。

---

## 7. 交互与校验

| 场景 | 前端行为 |
|------|----------|
| 进入页 | 默认 Tab「待审核」；加载 `pendingCount` |
| Tab 切换 | `statusTab` → `applyStatus`（全部传 undefined） |
| 重置检索 | Tab 回到「全部」 |
| 审核成功 | 关闭抽屉，刷新列表与角标 |
| 已审申请 | 详情只读；驳回原因红色展示 |
| 空待审 | 表格无数据（可后续加 empty 文案） |

---

## 8. 权限指令

```html
v-hasPermi="['agri:merchantEntryApply:query']"
v-hasPermi="['agri:merchantEntryApply:audit']"
```

---

## 9. 与关联模块边界

| 模块 | 关系 |
|------|------|
| 商城入驻协议 | C 端提交前勾选；本页 **不** 编辑协议 |
| 商户管理 | 通过后自动建档；平台代录入 **不在** 本列表 |
| 店铺管理 | 通过后自动创建首家店 |
| 会员管理 | 列表展示申请会员名称 |

**状态分离（EA2）：** 申请状态 ≠ 商户认证状态；详情 **不** 改商户冻结/注销。

---

## 10. 联调检查清单

- [ ] 待审 Tab 角标与 pendingCount 一致  
- [ ] 待审列表 sort 升序（后端）  
- [ ] 非待审详情无审核按钮  
- [ ] 驳回原因为空时前后端均拦截  
- [ ] 通过后商户/店铺可在对应模块查到  
- [ ] 重复审核后端阻断 msg  

---

## 11. 非本期（前端）

| 项 | 说明 |
|----|------|
| C 端入驻表单 | 另端 `POST /api/merchant/entry/apply` |
| 批量审核 | 不做 |
| 列表行快捷通过/驳回 | 仅详情内操作（对齐需求 §5.3） |

---

## 12. 修订记录

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-05 | 首版：列表 Tab、详情抽屉、通过/驳回；对齐功能需求 v1.0.2 |

---

*文档版本：v1.0 · ruoyi-ui · 关联《商户入驻审核功能需求.md》v1.0.2*
