# 首页 Banner 设置 — 前端技术方案

> **依据：** 《首页banner设置功能需求.md》v1.0.1、《首页banner设置技术方案.md》v1.0  
> **前端规范：** `doc/前端设计/前端设计.md`  
> **范围：** 仅 **ruoyi-ui 平台管理端** 列表维护页；C 端首页轮播 **不在本仓库 ruoyi-ui 实现**（另端或后续）。  
> **实现状态：** 页面与 API 封装已落地，待后端 `/agri/banner` 联调。

---

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

| 项 | 说明 |
|----|------|
| 框架 | Vue 2 + Element UI（与 RuoYi-Vue 一致） |
| 请求 | `@/utils/request` 封装的 axios |
| 参考页面 | `ruoyi-ui/src/views/system/notice/index.vue`（列表 + 弹窗 CRUD） |
| 风格 | 缩进、命名、表格/分页/权限指令与若依老页面 **完全一致** |
| 启用字段 | 使用 `"0"` / `"1"`，**不用** `sys_yes_no` 的 Y/N |

---

## 2. 文件清单

| 类型 | 路径 | 说明 |
|------|------|------|
| 页面 | `ruoyi-ui/src/views/agri/content/banner/index.vue` | Banner 列表 + 添加/编辑弹窗 |
| API | `ruoyi-ui/src/api/agri/banner.js` | 列表、详情、增删改、行内改序 |

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

---

## 3. 菜单与路由

若依路由由 **后端菜单** 动态加载，前端需配置：

| 菜单名称 | 组件路径 | 路由 path（建议） | 权限标识 |
|----------|----------|-------------------|----------|
| 首页 Banner 设置 | `agri/content/banner/index` | `banner` | `agri:banner:list` |

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

| 按钮权限 | 标识 |
|----------|------|
| 添加 | `agri:banner:add` |
| 编辑（含行内改序） | `agri:banner:edit` |
| 删除 | `agri:banner:remove` |

---

## 4. 页面结构

```text
首页 Banner 设置（单页）
├── 高级检索区（v-show 可折叠）
│   ├── 图片名称 bannerName（模糊）
│   └── 是否启用 enableFlag（全部/是/否）
├── 工具栏
│   ├── 添加
│   ├── 批量删除
│   └── RightToolbar（显隐检索）
├── 表格 + 分页
│   ├── 多选
│   ├── 图片名称、缩略图、启用标签、排序（行内）、创建时间
│   └── 操作：编辑、删除
└── 添加/编辑弹窗
    ├── 图片名称、图片上传、是否启用、排序
    └── 确定 / 取消
```

---

## 5. 复用组件

| 组件 | 路径 | 用途 |
|------|------|------|
| `Pagination` | 全局注册 | 分页 |
| `RightToolbar` | 全局注册 | 检索区显隐 |
| `ImagePreview` | `@/components/ImagePreview` | 列表缩略图 + 点击预览 |
| `ImageUpload` | `@/components/ImageUpload` | 弹窗内单图上传 |

**图片上传参数（对齐 BN11）：**

| 属性 | 值 |
|------|-----|
| `limit` | `1` |
| `file-size` | `5`（MB） |
| `file-type` | `['png','jpg','jpeg']` |
| 上传地址 | 默认 `/common/upload`（RuoYi 公共上传） |

表单下方提示文案：「建议宽高比 2:1（如 750×375），单张不超过 5MB；禁用后 C 端不展示」。

---

## 6. API 对接

**基路径：** `/agri/banner`（见 `src/api/agri/banner.js`）

| 前端方法 | HTTP | 路径 | 调用场景 |
|----------|------|------|----------|
| `listBanner` | GET | `/list` | 进入页、检索、分页 |
| `getBanner` | GET | `/{bannerId}` | 编辑回显 |
| `addBanner` | POST | `/` | 添加提交 |
| `updateBanner` | PUT | `/` | 编辑提交 |
| `updateBannerSortNo` | PUT | `/sortNo` | 行内改排序 |
| `delBanner` | DELETE | `/{bannerIds}` | 单独/批量删除（逗号分隔 id） |

### 6.1 列表请求参数 `queryParams`

| 字段 | 类型 | 说明 |
|------|------|------|
| pageNum | number | 页码 |
| pageSize | number | 每页条数 |
| bannerName | string | 可选，模糊 |
| enableFlag | string | 可选，`"0"` / `"1"`，不传查全部 |

### 6.2 列表响应

使用 RuoYi 标准 `TableDataInfo`：`response.rows`、`response.total`。

### 6.3 表单字段（添加/编辑）

| 前端字段 | 后端字段 | 必填 | 说明 |
|----------|----------|:----:|------|
| bannerName | bannerName | 是 | 未删除记录内唯一 |
| bannerImage | bannerImage | 是 | 上传返回相对路径 |
| enableFlag | enableFlag | 是 | 默认 `"1"` |
| sortNo | sortNo | 是 | 非负整数，默认 `0` |
| bannerId | bannerId | 编辑必填 | 新增不传 |

### 6.4 行内改序

请求体：

```json
{ "bannerId": 1, "sortNo": 10 }
```

- 失焦或点击行内 ✓ 按钮触发 `updateBannerSortNo`。
- 与原始值相同则不请求；失败时还原为改前排序。
- **不提供** 拖拽排序（BN12）。

### 6.5 保存成功扩展

若 `response.data.warnAspectRatio === true`，前端 `msgWarning`：「建议使用 2:1 比例，以免 C 端裁切变形」（不阻断保存）。

---

## 7. 交互与校验

| 场景 | 前端行为 |
|------|----------|
| 检索 | 点搜索 `pageNum=1` 再请求；重置清空 queryForm |
| 启用展示 | `enableFlag === '1'` → 绿色 tag「是」，否则灰色「否」 |
| 删除 | `$modal.confirm` 二次确认；文案含「删除后不可恢复」 |
| 批量删除 | 未勾选时按钮 disabled |
| 表单校验 | 名称、图片、启用、排序必填；消息对齐功能需求 §5.2 |
| 空列表 | 表格无数据，依赖运营点「添加」（无单独空态组件） |

---

## 8. 权限指令

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

行内改序按钮使用 `agri:banner:edit`。

---

## 9. 联调检查清单

- [ ] 菜单组件路径与权限配置正确，页面可打开  
- [ ] `GET /agri/banner/list` 分页与检索生效  
- [ ] 图片上传 `/common/upload` 返回路径可预览  
- [ ] 名称重复、未上传图片等后端 msg 正常弹出  
- [ ] `PUT /sortNo` 保存后列表顺序与 C 端一致（C 端另验）  
- [ ] 批量删除传多个 id 逗号分隔  

---

## 10. 非本期（前端）

| 项 | 说明 |
|----|------|
| C 端首页轮播 | 读 `GET /api/home/banners`，Invalid 图跳过、零条隐藏轮播区 |
| 拖拽排序 | 不做 |
| Banner 点击跳转 | 不做 |

---

## 11. 修订记录

| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-05 | 首版：列表 CRUD、行内改序、检索；对齐功能需求 v1.0.1 与已落地代码 |

---

*文档版本：v1.0 · ruoyi-ui · 关联《首页banner设置功能需求.md》v1.0.1*
