# 商城入驻协议 — 前端技术方案

> **依据：** 《商城入驻协议功能需求.md》v1.0、《商城入驻协议技术方案.md》v1.0  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 平台管理端** 单页配置；C 端商家入驻勾选 **不在 ruoyi-ui 实现**。  
> **实现状态：** 页面与 API 封装已落地，待后端 `/agri/merchantEntryAgreement` 联调。

---

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

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI |
| 请求 | `@/utils/request` |
| 参考页面 | `ruoyi-ui/src/views/system/notice/index.vue`（富文本 `Editor` 用法） |
| 页面形态 | **单页卡片表单**（非列表）；全平台 **一条配置** |
| 启用字段 | `"0"` / `"1"` 单选，不用 Y/N 字典 |

---

## 2. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 页面 | `ruoyi-ui/src/views/agri/content/merchantEntryAgreement/index.vue` | 协议配置 + 预览 |
| API | `ruoyi-ui/src/api/agri/merchantEntryAgreement.js` | GET / PUT |

**组件 name：** `MerchantEntryAgreement`

---

## 3. 菜单与路由

| 菜单名称 | 组件路径 | 路由 path（建议） | 权限标识 |
|----------|----------|-------------------|----------|
| 商城入驻协议 | `agri/content/merchantEntryAgreement/index` | `merchantEntryAgreement` | `agri:merchantEntryAgreement:query` |

**上级菜单：** 农资管理 → **内容管理**

| 按钮权限 | 标识 |
|----------|------|
| 保存 | `agri:merchantEntryAgreement:edit` |

---

## 4. 页面结构

```text
商城入驻协议（单页 · el-card）
├── 卡片标题 + 说明文案
│   └── 「关闭启用后，C 端将无法提交新的商家入驻申请」
├── 表单
│   ├── 协议标题 agreementTitle（必填）
│   ├── 协议版本号 versionLabel（选填）
│   ├── 是否启用 enableFlag（必填）
│   ├── 最后更新 updateBy / updateTime（只读）
│   ├── 协议内容 content（富文本 Editor）
│   └── 预览按钮 + 保存按钮
└── 预览弹窗（el-dialog + v-html 渲染正文）
```

与原型差异说明：原型若为「启用开关 + 内容 + 提交」极简布局，本实现 **增加** 标题、版本号、最后更新、预览，以满足功能需求 §4～§5 全部字段。

---

## 5. 复用组件

| 组件 | 路径 | 用途 |
|------|------|------|
| `Editor` | `@/components/Editor`（全局注册） | 协议富文本编辑，`min-height="280"` |

预览区使用 `v-html` 展示保存后的 HTML（样式 scoped 于 `.preview-content`）。

---

## 6. API 对接

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

| 前端方法 | HTTP | 路径 | 说明 |
|----------|------|------|------|
| `getMerchantEntryAgreement` | GET | `/` | 进入页加载配置 |
| `saveMerchantEntryAgreement` | PUT | `/` | 保存配置 |

### 6.1 加载响应 `response.data`

| 字段 | 说明 |
|------|------|
| configId | 固定 1 |
| agreementTitle | 协议标题 |
| versionLabel | 版本号，可空 |
| content | HTML 正文 |
| enableFlag | `"0"` / `"1"` |
| updateBy, updateTime | 只读展示 |

无记录时后端返回空壳（标题空、`enableFlag=0`），前端 `Object.assign` 合并默认值。

### 6.2 保存请求体

```json
{
  "agreementTitle": "农资商城商家入驻协议",
  "versionLabel": "v1.0",
  "content": "<p>...</p>",
  "enableFlag": "1",
  "remark": ""
}
```

保存成功后 `msgSuccess`，再 `loadConfig()` 刷新更新人/时间。

---

## 7. 校验规则

| 规则 | 实现 |
|------|------|
| 标题必填 | `rules.agreementTitle` required |
| 启用必选 | `rules.enableFlag` required |
| 启用=是 时正文必填 | 自定义 `validateContent`：`enableFlag === '1'` 且 `isBlankHtml(content)` 则报错 |
| 空白 HTML | `isBlankHtml`：去标签、去 `&nbsp;` 后 trim 为空视为无内容 |

**`isBlankHtml` 逻辑（与后端 `AgreementContentSupport` 对齐）：**

```javascript
html.replace(/<[^>]+>/g, '').replace(/&nbsp;/g, ' ').trim()
```

监听 `form.enableFlag` 变化时 `validateField('content')` 重新校验。

---

## 8. 权限指令

```html
v-hasPermi="['agri:merchantEntryAgreement:edit']"
```

仅保存按钮需 edit 权限；查看页需菜单 `query` 权限。

---

## 9. 与 C 端的边界（前端分工）

| 端 | 接口 | 本方案 |
|----|------|--------|
| 平台 ruoyi-ui | `/agri/merchantEntryAgreement` | **本期实现** |
| C 端用户商城 | `GET /api/merchant/entry/agreement` | **非 ruoyi-ui**；展示 + checkboxLabel |
| C 端提交入驻 | `POST /api/merchant/entry` + `agreementAccepted` | **非本期前端** |

---

## 10. 联调检查清单

- [ ] `GET /` 正常回显或空壳  
- [ ] 启用且无内容时前后端均拦截  
- [ ] 保存后 `updateTime` 刷新  
- [ ] 禁用状态下 content 可为空  
- [ ] 富文本含列表/加粗等 Editor 支持格式  

---

## 11. 非本期（前端）

协议历史版本列表、勾选存证、强制阅读时长、PDF、多语言、C 端入驻表单页。

---

## 12. 修订记录

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-05 | 首版：单页配置、富文本、预览、启用校验 |

---

*文档版本：v1.0 · ruoyi-ui · 关联《商城入驻协议功能需求.md》v1.0*
