# 首页 Banner 设置 — 功能需求说明

> 本文档在《首页banner设置功能需求-草稿》基础上整理，并关联《农资商城web》目录下 **商户管理 v1.4**、**店铺管理 v1.3.2**、**商品管理 v1.3.3**、**会员管理 v1.0**、**订单管理 v1.0.1**、**商品服务管理 v1.0.1**、《关联需求分析.md》v1.2 及同目录 **商城入驻协议**、**商城服务协议** 草稿做边界与流程对齐。  
> 范围：平台侧 **C 端用户商城首页轮播图（Banner）** 的配置与维护；不涉及数据库结构、接口定义及技术实现细节。  
> **说明：** Banner 为 **全平台一份** 运营素材，在 C 端首页展示；**不** 按商户、店铺、商品维度拆分。  
> **v1.0：** 列表维护、启用控制、排序、检索、单独/批量删除；C 端仅展示 **已启用** 项并按排序展示。  
> **v1.0.1：** 定稿 Banner **图片规格**、列表 **排序交互**（改排序值保存）；C 端 **无效图跳过**、**零启用不展示轮播区**；修正章节引用与会员/访客表述。

---

## 1. 模块定位

### 1.1 业务目标

在农资商城 **平台管理端（Web）** 维护用户商城 **首页顶部轮播 Banner**，使运营可：

- 配置多张轮播图及其展示顺序；
- 通过 **是否启用** 控制是否在 C 端露出；
- 按 **图片名称** 检索与管理历史素材。

**不包含：** Banner 点击跳转链接/落地页配置（草稿未要求，见 §13）；商家端维护 Banner；按店铺/商品差异化 Banner。

### 1.2 在业务链中的位置

```text
平台运营
    └── 内容管理
            ├── 首页 Banner 设置（本模块）──► C 端首页轮播
            ├── 商城服务协议（草稿）──────► C 端注册/登录勾选
            └── 商城入驻协议（草稿）──────► C 端商家入驻勾选

【供给链】商户 → 店铺 → 商品 → C 端可购          （与 Banner 无数据依赖）
【用户链】会员注册 → 下单/订单                    （与 Banner 无账号依赖）
```

| 关联模块 | 关系 | 边界说明 |
|----------|------|----------|
| 商户 / 店铺 / 商品 / 分类 | **无直接操作** | 发品、审核、上下架 **不依赖** Banner；Banner 变更 **不自动** 改商品/店铺状态 |
| 商品服务管理 v1.0.1 | 并列 | 均属平台 **内容/主数据**；商品服务作用于 **商品详情**，Banner 作用于 **首页** |
| 会员管理 v1.0 | 间接 | **用户商城首页为公开浏览入口**：未登录访客与已登录会员均可看 Banner；会员 **禁用** 仅限制登录/下单，**不隐藏** 首页 Banner（见 §8.2） |
| 订单管理 v1.0.1 | **无** | 下单、履约 **不读取** Banner 配置 |
| 商城服务协议（草稿） | 同目录 | 协议类为 **文本+启用**；本模块为 **图片+启用+排序** |
| 商城入驻协议（草稿） | 同目录 | 面向 **商家入驻** 场景；与首页营销 Banner **入口不同** |

### 1.3 与《关联需求分析》的对应

| 关联分析要点 | 本模块 |
|--------------|--------|
| 平台端：商户、店铺、商品监管 | 本模块属 **平台内容运营**，不在 §3 核心模块表中，与供给链 **并行** |
| C 端浏览与下单分离 | 店铺停业可浏览商品（关联分析 §11）；Banner 为 **浏览层** 内容，**不参与** 可下单校验 |
| 状态不级联 | 改 Banner **不自动** 改商户/店铺/商品/订单状态 |
| 用户链与供给链账号不混用 | Banner **不绑定** 会员/经营账号 |

### 1.4 使用端与角色

| 端 | 角色 | 能力 |
|----|------|------|
| **平台管理端** | 平台管理员（及被授予内容管理权限的角色） | 列表、检索、添加、编辑、删除（单独/批量）、调整排序 |
| **C 端（用户商城）** | 访客、会员 | **只读** 展示已启用 Banner；**不可** 配置 |
| 店铺经营管理端 | 商家 | **不使用** 本模块 |

---

## 2. 业务概念

| 概念 | 说明 |
|------|------|
| Banner / 轮播图 | 一条首页轮播素材记录，含管理用名称、图片、启用状态、排序 |
| 图片名称 | **后台管理用** 名称，便于运营识别；**不要求** 与 C 端展示文案一致 |
| 图片 | Banner 展示图；规格见 §2.3 |
| 图片有效 | 图片 URL 可访问、格式合规且文件未损坏；无效时 C 端 **跳过** 该条（见 §2.2、§2.4） |
| 是否启用 | 控制该条是否在 C 端首页轮播中 **参与展示** |
| 排序 | 多条 Banner 的先后顺序，**数值越小越靠前**（与商品服务管理排序语义一致） |
| 逻辑删除 | 删除后平台列表不再展示，C 端不再展示；**本期不提供** 恢复入口 |

### 2.1 「是否启用」语义（定稿）

| 是否启用 | 平台列表 | C 端首页轮播 |
|----------|----------|----------------|
| **是** | 展示 | **参与** 轮播（仍须满足：未逻辑删除、图片有效） |
| **否** | 展示 | **不参与** 轮播（配置保留，可随时改回启用） |

> **定稿：** 禁用 **立即** 从 C 端轮播中消失（无须额外「发布」动作）；启用后 **立即** 按排序参与展示。

### 2.2 C 端展示规则（定稿）

| 规则 | 说明 |
|------|------|
| 展示集合 | 全部 **已启用** 且 **未逻辑删除** 且 **图片有效** 的 Banner |
| 展示顺序 | 按 **排序值升序**；相同排序值按 **创建时间升序** |
| **零条可展示** | **不展示轮播区域**（不占位、不展示默认图）；页面其余模块正常加载，**不报错** |
| 部分图片无效 | 仅展示有效项；若过滤后 **零条**，同「零条可展示」 |
| 仅 1 条可展示 | 仍使用轮播组件展示单张；**不** 自动轮播切换（无下一张）；是否显示指示点以前台 UI 为准，默认 **1 个点** 或不显示指示点 |
| 点击行为 | **无跳转**；点击仅 **预览大图**（全屏/弹层，以前台 UI 为准） |

### 2.3 Banner 图片规格（定稿 · v1.0.1）

与农资商城其他运营图片（商户证照、分类图、商品主图等）对齐 **格式与体积**；另约定 **首页轮播展示比例**：

| 项 | 定稿 |
|----|------|
| 文件格式 | **jpg / jpeg / png** |
| 单张体积 | ≤ **5MB**（与 RuoYi 平台上传配置及《商户管理技术方案》§9.4 等一致） |
| 建议宽高比 | **2 : 1**（宽 : 高），例如 **750×375** px |
| 最小宽度建议 | 宽度 ≥ **750** px，避免 C 端模糊拉伸 |
| 上传校验 | 不符合格式或超体积 **拒绝上传**；比例非 2:1 时 **允许上传** 但后台 **提示**「建议使用 2:1 比例，以免 C 端裁切变形」 |
| C 端适配 | 轮播容器按 **2:1** 展示；非标准比例图片 **等比裁剪居中**（以前台实现为准） |

### 2.4 「图片无效」判定（定稿 · v1.0.1）

| 情形 | 平台侧 | C 端 |
|------|--------|------|
| 未上传 / URL 为空 | 添加/编辑 **校验不通过** | — |
| 文件已删、404、无法解码 | 列表仍可看到记录（运营须编辑换图） | **跳过**，不展示该条 |
| 上传中 / 临时失败 | 保存前拦截 | 不展示 |

> **定稿：** C 端 **不因** 单条无效图导致整页报错或隐藏其他有效 Banner。

---

## 3. 功能结构

```text
首页 Banner 设置（平台）
├── Banner 列表（含高级检索、排序操作）
├── 添加 Banner
├── 编辑 Banner
└── 删除 Banner（单独 / 批量）
```

---

## 4. Banner 列表

### 4.1 列表字段

| 字段 | 说明 |
|------|------|
| 图片名称 | 文本 |
| 图片 | 缩略图预览 |
| 是否启用 | 是 / 否（建议用标签区分状态） |
| 排序 | 展示当前排序值；支持 **行内修改排序值并保存**（见 4.2） |
| 操作 | 编辑、删除 |

### 4.2 列表行为

- 默认展示全部 **未逻辑删除** 的 Banner。
- 默认按 **排序值升序**，相同则按 **创建时间升序**。
- 支持 **勾选多条** 后批量删除（见第 8 节）。
- 支持行内 **单独删除**。
- **排序操作（定稿 · v1.0.1）：** 在列表 **行内编辑「排序」数值 → 失焦或点保存 → 单条保存成功**；**不提供** 拖拽排序、不提供批量改序。保存后 C 端顺序 **即时** 按新排序生效。添加/编辑弹窗内也可改排序，与行内改序规则相同。

### 4.3 高级检索

| 检索项 | 规则 |
|--------|------|
| 图片名称 | 模糊匹配 |
| 是否启用 | 精确筛选：是 / 否 / 全部（全部可不选或选「全部」） |

- 支持检索条件 **重置**。
- 检索后分页从第 1 页开始（与平台其他列表一致）。

---

## 5. 添加 Banner

### 5.1 填写项

| 字段 | 必填 | 说明 |
|------|:----:|------|
| 图片名称 | 是 | 未删除记录中 **不可重复**；建议长度由产品/原型约定 |
| 图片 | 是 | 符合 §2.3；上传成功后方允许提交 |
| 是否启用 | 是 | 是 / 否；新建默认建议为 **是** |
| 排序 | 是 | 非负整数；默认 **0** |

### 5.2 提交校验

| 校验 | 失败提示（示例） |
|------|------------------|
| 图片名称为空 | 请输入图片名称 |
| 图片名称与未删除记录重复 | 图片名称已存在 |
| 未上传图片 | 请上传图片 |
| 图片格式/大小不合规 | 仅支持 jpg/png/jpeg，单张不超过 5MB |
| 图片比例非 2:1 | **允许保存**；提示建议使用 2:1（见 §2.3） |
| 排序非合法非负整数 | 排序须为非负整数 |

### 5.3 提交成功

- 返回列表，新记录按排序规则出现在相应位置。
- 若 **是否启用 = 是**，C 端首页 **立即** 可按规则展示该图。

---

## 6. 编辑 Banner

### 6.1 可编辑项

与「添加 Banner」相同：**图片名称、图片、是否启用、排序**。

### 6.2 规则

| 规则 | 说明 |
|------|------|
| 名称唯一 | 修改后仍须在 **未删除** 记录中唯一（排除自身） |
| 更换图片 | 保存成功后 C 端展示 **新图** |
| 启用 → 禁用 | C 端 **立即** 不再展示该条 |
| 禁用 → 启用 | C 端 **立即** 按排序参与展示 |
| 修改排序 | C 端顺序 **立即** 更新 |

### 6.3 只读项（若有）

| 项 | 说明 |
|----|------|
| 内部标识 / 创建时间 | 系统字段，只读展示（若有） |

---

## 7. 删除 Banner

### 7.1 单独删除

```text
点击删除
    → 二次确认「确认删除该 Banner？删除后不可恢复」
    ├── 取消 → 结束
    └── 确认 → 逻辑删除成功，列表不再展示
```

### 7.2 批量删除

```text
勾选一条或多条 → 批量删除
    → 二次确认（提示将删除 N 条）
    ├── 取消 → 结束
    └── 确认 → 对所选记录执行逻辑删除
```

**定稿：** Banner **无** 商品/订单类「关联阻断」；批量删除 **不需** 因某条失败而整批取消（与商品服务「有关联则整批失败」不同）。若所选包含已删或不存在记录，按平台统一批量策略提示即可。

### 7.3 删除后影响

| 对象 | 影响 |
|------|------|
| 平台列表 | 不再展示 |
| C 端 | **立即** 不再展示该图；若已无 **可展示** Banner，按 §2.2 **不展示轮播区域** |
| 商户/店铺/商品/订单 | **无影响** |

---

## 8. 与 C 端、会员、供给链的协作

### 8.1 推荐配置顺序（运营）

```text
【平台】首页 Banner 设置 → 配置首页轮播（可与供给链开业并行）
【平台】商城服务协议 / 入驻协议 → 配置协议文案（内容管理其他子模块）
【C 端】用户打开商城首页 → 展示已启用 Banner
【C 端】用户浏览商品 → 受商品/店铺可售规则约束（与 Banner 无关）
```

### 8.2 C 端与会员（定稿 · v1.0.1）

| 场景 | 行为 |
|------|------|
| 未登录访客 | 进入 **用户商城首页** 即可查看 Banner（首页为公开浏览入口） |
| 已登录会员 | 同访客，按 §2.2 展示 Banner |
| 会员 **禁用** | **不可** 登录、**不可** 下单；**不** 单独屏蔽首页 Banner（禁用前已登录会话是否强制登出，按 C 端会话策略，**不在本模块定义**） |
| 店铺 **停业** | 不影响 Banner；商品浏览/下单按店铺、商品规则 |

### 8.3 状态联动（不级联）

| 平台操作 | 商户/店铺/商品/订单 |
|----------|---------------------|
| 新增/编辑/删除/启停 Banner | **不变** |
| 商户冻结/注销、店铺停业 | **不变** Banner 配置 |
| 商品下架、订单关闭 | **不变** Banner 配置 |

---

## 9. 业务规则汇总

| 编号 | 规则 |
|------|------|
| **BN1** | Banner 配置为 **全平台一份**，**非** 店铺/商品维度 |
| **BN2** | 仅 **平台管理端** 在本模块维护；商家端 **不可** 维护 |
| **BN3** | 未逻辑删除的 **图片名称** 不可重复 |
| **BN4** | 列表与 C 端展示均按 **排序升序**，同序按 **创建时间升序** |
| **BN5** | C 端 **仅展示**「已启用 + 未删除 + 图片有效」的 Banner |
| **BN6** | 启停、排序、删改对 C 端 **即时生效**（无单独发布步骤） |
| **BN7** | 删除为 **逻辑删除**；**本期不提供** 恢复 |
| **BN8** | Banner 变更 **不自动** 改变商户/店铺/商品/订单/会员状态 |
| **BN9** | Banner **不参与** 商品可购、库存、下单校验 |
| **BN10** | 与会员账号 **无绑定**；与店铺经营账号 **无绑定** |
| **BN11** | 图片须满足 §2.3（格式、5MB）；建议 2:1，非 2:1 可保存并提示 |
| **BN12** | 排序 **仅** 通过维护排序数值保存调整；**不用** 拖拽 |
| **BN13** | C 端：无效图 **跳过**；零条可展示时 **不展示轮播区** |
| **BN14** | C 端点击 Banner **无跳转**，仅预览大图 |

---

## 10. 页面与交互要点

| 场景 | 要求 |
|------|------|
| 列表 | 图片缩略清晰；启用状态一目了然 |
| 添加/编辑 | 图片支持预览；说明「禁用后 C 端不展示」 |
| 排序 | 列表行内改排序值 → 保存；成功 Toast；非 2:1 上传时展示建议提示 |
| C 端空态 | 无启用/全部无效时首页 **无轮播区块**（验收对照 §2.2） |
| 删除 | 单独/批量均需二次确认 |
| 高级检索 | 名称 + 启用状态；支持重置 |
| 空列表 | 引导运营「添加」首张 Banner |

---

## 11. 与关联模块的协作流程

### 11.1 与内容管理其他子模块

| 子模块 | C 端触点 | 与本模块关系 |
|--------|----------|--------------|
| **首页 Banner 设置** | 商城 **首页** 轮播 | — |
| 商城服务协议（草稿） | 注册/登录 **协议勾选** | 同属内容管理；**无数据依赖** |
| 商城入驻协议（草稿） | **商家入驻** 协议勾选 | 同上；与首页 Banner **入口不同** |

### 11.2 与供给链、用户链（摘要）

```text
供给链：商户入驻 → 开店 → 发品 → C 端购买
         （不要求先配 Banner；Banner 可随时维护）

用户链：会员注册 → 下单
         （下单不依赖 Banner；Banner 不写入订单）
```

---

## 12. 草稿对照与修订说明

| 草稿条目 | 本文档处理 |
|----------|------------|
| 列表：图片名称、图片、是否启用、排序操作 | §4 结构化；明确排序语义与 C 端顺序 |
| 添加：图片名称、图片、是否启用、排序 | §5；补充名称唯一、图片校验 |
| 高级检索：图片名称、是否启用 | §4.3 |
| 编辑；单独/批量删除 | §6、§7；补充逻辑删除与 C 端即时生效 |
| 异常返回 code/msg/data | **不纳入**（属实现层） |
| 技术栈 RuoYi/MySQL | **不纳入** |
| 未写：C 端展示规则、全平台维度、与其他模块边界 | §1、§2、§8、§9 定稿补充 |
| 未写：点击跳转 | **非本期**（§13）；v1.0.1 定稿点击仅预览大图 |
| v1.0.1 | §2.3 图片规格；§2.4 无效图；§4.2 行内改序；§2.2 零条不展示轮播区；BN11～BN14 |

---

## 13. 非本期范围

| 项 | 说明 |
|----|------|
| Banner 点击跳转（商品/活动/H5/外链） | 草稿未要求；v1.0.1 仅预览大图 |
| 列表拖拽排序、批量改序 | v1.0.1 明确 **不做** |
| 分端/分渠道 Banner（APP 与 H5 不同图） | — |
| 定时上下线（ scheduled 启停） | — |
| 商家端、按店铺配置 Banner | — |
| 恢复已逻辑删除的 Banner | — |
| 浏览/点击统计 | — |
| 视频 Banner、多语言 | — |

---

## 14. 修订记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版定稿：列表/增删改/检索/排序/启停；C 端展示规则；与农资商城各模块及内容管理兄弟模块边界 |
| **v1.0.1** | 图片 2:1/5MB；行内改排序值；C 端无效图跳过、零条不展示轮播区、点击仅预览；修正 §8.2 引用 |

---

*文档版本：v1.0.1（定稿）· 关联《关联需求分析.md》v1.2、《商户管理功能需求.md》v1.4、《店铺管理功能需求.md》v1.3.2、《商品管理功能需求.md》v1.3.3、《会员管理功能需求.md》v1.0、《订单管理功能需求.md》v1.0.1、《商品服务管理功能需求.md》v1.0.1 · 草稿《首页banner设置功能需求-草稿.md》保持不变。*
