# 商城首页 — 功能需求说明

> 本文档在《商城首页功能需求-草稿》基础上整理，并关联 **《关联需求分析.md》** v1.6、平台侧 **《首页banner设置功能需求》** v1.0.1、**《商品分类功能需求》** v1.5、**《商品审核功能需求》** v1.0、**《店铺管理功能需求》** v1.3.5、**《会员管理功能需求》** v1.0.1、**《商城服务协议功能需求》** v1.0 及 C 端 **《商品分类功能需求》** v1.0.1 做边界与流程对齐。  
> 范围：**C 端（消费者 APP / 用户商城）· 商城首页** 的信息展示与跳转；**不涉及** 数据库结构、接口定义及技术实现细节。  
> **说明：** 首页为 **全平台聚合入口**，展示 Banner、平台类目、热销商品等；**不** 按店铺维度拆分首页。  
> **v1.0：** 首版定稿；搜索栏、Banner、平台一级类目导航、热销 TOP6；与供给链/用户链边界对齐。  
> **v1.0.1：** 定稿一级分类落地页（二级 Tab + 商品列表）；热销零销量按上架时间降序；店铺名实时读档；不做下拉刷新；类目/热销加载失败空态。  
> **v1.0.2：** 一级导航可见口径与 C 端《商品分类》GC6 对齐；下游跳转引用 v1.0.1（A/B/C 页）。

---

## 1. 模块定位

### 1.1 业务目标

为 **C 端买家/访客** 提供农资商城 **默认落地页（商城首页）**，使其能够：

- 通过 **搜索入口** 进入全站检索（检索能力另册）；
- 浏览 **平台运营配置的 Banner 轮播**；
- 通过 **平台商品一级分类** 快捷进入分类浏览；
- 浏览 **全平台热销商品** 推荐位并进入商品详情。

**不包含（本期或与它模块分工）：**

| 能力 | 说明 |
|------|------|
| **搜索执行与结果页** | 首页仅提供 **搜索入口**；关键词检索、结果排序等见 **搜索模块**（待建设） |
| **Banner 维护** | 见平台 **首页 Banner 设置**；C 端 **只读展示** |
| **平台/店铺分类维护** | 见平台 **商品分类**、商家 **店铺商品分类**；首页 **只消费** 平台一级分类 |
| **商品发品/审核/上下架** | 见商家 **商品列表**、平台 **商品审核** |
| **购物车、下单、支付** | 见 **购物车**、**订单管理** 等模块；首页 **不直接** 完成交易 |
| **会员注册/登录页** | 见 **会员管理**、**商城服务协议**；首页可提供入口跳转，**不在本模块定义** 注册表单 |
| **底部 Tab、个人中心** | 见 **我的** 等 C 端模块 |

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

```text
【供给链】商户 → 店铺 → 分类 → 商品（出售中）
                              ↓
【内容】平台 Banner 设置 ──────┐
                              ↓
【C 端】商城首页（本模块）── 展示 Banner / 平台类目 / 热销商品
            ↓
      商品详情 / 分类页 / 搜索页 / 店铺页（跳转，另册）
            ↓
【用户链】会员登录 → 加购 → 下单（须满足可购条件，见 §8）

【用户链 · 并行】访客可浏览首页与多数内容；下单须登录且会员启用
```

| 关联模块 | 关系 | 边界说明 |
|----------|------|----------|
| **首页 Banner 设置** v1.0.1 | **内容来源** | C 端轮播 **完全遵循** BN1～BN14；首页 **不维护** Banner |
| **商品分类** v1.5 | **类目来源** | 快捷导航使用 **平台一级分类**（`shop_id` 为空）；**非** 店铺商品分类 |
| **商品审核 / 商品管理** | **商品来源** | 热销区仅展示 **出售中** 商品；销量字段由订单履约 **回写**（只读） |
| **店铺管理** v1.3.5 | **间接** | 停业店铺商品 **可出现在** 浏览层；**下单** 在详情/结算拦截（S13） |
| **会员管理** v1.0.1 | **用户链** | 访客与会员 **均可** 进入首页；禁用会员 **不影响** 首页 Banner/类目展示 |
| **商城服务协议** v1.0 | 并列 | 注册/登录协议勾选 **不在** 首页完成 |
| **关联需求分析** v1.6 §11 | **可购规则** | 首页 **展示 ≠ 可下单**；点击商品后按四条件校验 |

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

| 关联分析要点 | 本模块 |
|--------------|--------|
| C 端浏览与下单分离 | 首页属 **浏览层**；不加购、不结算 |
| 双业务链账号不混用 | 首页 **不校验** 店铺经营账号 |
| 平台分类 vs 店铺分类 | 首页类目 **仅用平台分类**（G1） |
| C 端可售四条件 | 首页 **不校验** 库存/店态；详情/下单模块校验 |
| 状态不级联 | Banner/分类/商品后台变更 **不触发** 首页单独「发布」动作，刷新即生效 |

### 1.4 使用端与角色

| 端 | 角色 | 能力 |
|----|------|------|
| **C 端（消费者 APP）** | **访客** | 浏览首页全部 **展示型** 区块 |
| **C 端** | **已登录会员** | 同访客；后续加购/下单在其它页面 |
| 平台管理端 | 平台管理员 | **不操作** 本页面；维护 Banner、分类、审核商品 |
| 店铺经营管理端 | 商家 | **不操作** 本页面 |

---

## 2. 页面结构（自上而下）

```text
商城首页
├── ① 顶部搜索栏（固定）
├── ② Banner 轮播区（有数据时展示，无数据时不占位）
├── ③ 平台类目快捷导航（一级 + 「更多」）
└── ④ 热销商品区（标题 + 商品卡片列表，最多 6 条）
```

> **定稿：** 区块 **顺序固定** 为 ① → ② → ③ → ④；与草稿条目顺序一致。草稿第 5 条「商城类目展示平台商品分类」定稿为：**首页所有类目展示均使用平台商品分类体系**，**不使用** 店铺商品分类（见 §5）。

---

## 3. 顶部搜索栏

### 3.1 展示规则

| 项 | 定稿 |
|----|------|
| 位置 | 页面 **顶部固定**（滚动时保持可见，具体吸顶样式以前台 UI 为准） |
| 默认文案 | 占位提示：**「搜索兽药、饲料、店铺」** |
| 可输入性 | 首页搜索栏本身 **可为只读样式**；点击整栏进入 **搜索输入页** |

### 3.2 交互流程

```text
用户在首页
    → 点击搜索栏
        → 进入「搜索输入页」（关键词输入、历史记录等 **另册**）
        → 用户在搜索页执行检索 **不在本模块定义**
```

### 3.3 边界

| 规则 | 说明 |
|------|------|
| HM-S1 | 首页 **不承担** 搜索逻辑与结果展示 |
| HM-S2 | 占位文案 **固定** 为草稿约定文案（运营 **不可** 在平台后台配置，若需可配置另版本） |

---

## 4. Banner 轮播区

### 4.1 数据来源与展示

C 端 **完全遵循** 《首页banner设置功能需求》v1.0.1 **§2.2 C 端展示规则** 及规则 **BN5、BN13、BN14**：

| 项 | 定稿 |
|----|------|
| 展示集合 | **已启用 + 未删除 + 图片有效** 的 Banner |
| 顺序 | 排序值 **升序**；同序按创建时间 **升序** |
| 零条可展示 | **不展示轮播区域**（不占位、不展示默认图） |
| 单条 | 仍用轮播组件展示；**不** 自动切换 |
| 点击 | **无跳转**；**仅预览大图** |

### 4.2 与会员/访客

| 场景 | 行为 |
|------|------|
| 未登录访客 | **可** 查看 Banner |
| 已登录会员 | 同访客 |
| 会员禁用 | **不** 单独隐藏 Banner（与 BN 模块 §8.2 一致） |

### 4.3 异常与局部失败

| 情形 | 首页行为 |
|------|----------|
| Banner 接口失败 / 超时 | **不阻塞** 整页；轮播区按空态处理（不展示轮播区）；其余模块照常加载 |
| 部分图片无效 | 按 BN 规则 **跳过** 无效项 |

---

## 5. 平台类目快捷导航

### 5.1 业务口径（对应草稿 §3、§5）

| 项 | 定稿 |
|----|------|
| 分类体系 | **平台商品分类**（全平台一份，平台管理员在 **商品分类** 模块维护） |
| 展示层级 | 仅 **一级分类** |
| 不展示 | **店铺商品分类**、二级分类 **不在** 本导航区平铺 |
| 可见条件 | 一级分类 **是否显示 = 是**、**未逻辑删除**，且其下 **至少存在一个** 可见的 **二级分类**（与 C 端《商品分类》GC6 一致；**无可见二级的空壳一级不出现在导航**） |
| 排序 | 同层 **排序值升序**；相同则 **创建时间升序**（与商品分类模块一致） |

### 5.2 展示与布局

| 项 | 定稿 |
|----|------|
| 展示内容 | 分类 **名称** + **分类图片**（缩略图） |
| 布局 | 横向排列；条目过多时 **横向滑动** 浏览 |
| 末尾入口 | 导航区 **最后一个固定为「更多」**（非分类数据，为功能入口） |

### 5.3 交互流程

```text
点击某一一级分类
    → 进入「一级分类商品页」（C 端《商品分类功能需求》v1.0.1 · **B 页**）
        → 页顶/页内展示该一级下 **平台二级分类 Tab**（仅「是否显示=是」的二级）
        → Tab 下方展示 **当前 Tab 对应二级分类下的可浏览商品列表**
        → 默认选中 **排序最靠前** 的第一个二级 Tab（同层排序升序，同序按创建时间升序）
        → 切换 Tab → 列表 **回顶** 并重新加载（C 端 **C1**）

点击「更多」
    → 进入 C 端「全部分类」页（《商品分类功能需求》v1.0.1 · **A 页**）
        → 展示完整 **平台商品分类** 树（一级 + 二级）
        → 点击二级 → **C 独立商品列表页**（A1）
```

### 5.4 空态

| 情形 | 首页行为 |
|------|----------|
| 无任何「显示=是」的一级分类 | 仍展示导航区；仅显示 **「更多」** 入口；或展示引导文案「暂无分类」（以前台 UI 为准） |
| 分类图片缺失 | 展示 **默认占位图** + 分类名称（以前台 UI 为准） |

### 5.5 加载失败

| 情形 | 首页行为 |
|------|----------|
| 类目数据接口失败 / 超时 | **不阻塞** 整页；导航区按 **空态** 处理（可不展示类目条目，**仍保留「更多」** 或整块隐藏，以前台 UI 为准）；**不提供** 模块内重试 |

---

## 6. 热销商品区

### 6.1 区块说明

| 项 | 定稿 |
|----|------|
| 区块标题 | 建议文案 **「热销商品」**（以前台 UI 为准，运营 **不可** 在后台配置标题，若需可配置另版本） |
| 数量上限 | **最多展示 6 条**（Top 6，对应草稿） |
| 数据范围 | **全平台** 跨店铺聚合；**非** 单店首页 |

### 6.2 入选规则

参与热销排行的商品须 **同时满足**：

| # | 条件 | 来源 |
|---|------|------|
| 1 | 商品状态 = **出售中** | 商品管理 / 商品审核 |
| 2 | 商品 **未逻辑删除** | 商品管理 |
| 3 | 所属店铺 **未逻辑删除** | 店铺管理 |
| 4 | 商品已挂 **平台二级商品分类**（发品必选字段已填） | 商品分类 C5 |

> **定稿：** **不要求** 店铺 **开业** 才可 **出现在** 热销列表（与《关联需求分析》「浏览层与下单层分离」一致）；**不要求** 库存 > 0 才可 **展示**（库存为 0 时可展示，详情/加购时按商品规则提示）。

**不要求：** 店铺商品分类已填、商品服务项已选 — **不影响** 是否进入热销榜。

### 6.3 排序规则

| 优先级 | 规则 |
|--------|------|
| 1 | **销量（累计销量）降序** |
| 2 | 销量相同 → **上架时间降序**（以商品 **出售中** 态对应的上架时间为准；免审店为提交上架成功时间，经审核店为审核通过时间，与商品状态机一致） |
| 3 | 仍相同 → **商品编号升序**（保证顺序稳定） |

> **说明：** 销量由 **订单履约** 回写至商品档案；首页 **只读** 该字段。若平台尚无订单、销量均为 0，按 **上架时间降序** 取 Top6。

### 6.4 单条展示字段

| 字段 | 说明 |
|------|------|
| 商品主图 | 列表主图 |
| 商品名称 | 单行或双行截断以前台为准 |
| 售价 | 当前 **出售中** 售价 |
| 店铺名称 | 所属 **店铺名称**；**实时读取** 店铺档案（店改名后刷新首页即更新） |

**不展示（本期列表卡片）：** 库存、销量数字、服务标签、规格 — 若需展示销量另版本。

### 6.5 交互流程

```text
用户在首页热销区
    → 点击某一商品卡片
        → 进入「商品详情页」（C 端另册）
            → 详情页展示完整信息、加购/立即购买等
            → 下单须满足 §8 可购条件

用户在首页热销区
    → 上下滑动 / 仅浏览
        → 停留首页，无额外提交
```

### 6.6 空态与不足 6 条

| 情形 | 首页行为 |
|------|----------|
| 符合条件的商品 **0 条** | 展示热销区 **空态**（如「暂无热销商品」）；**不** 用非出售中商品补齐 |
| 符合条件的商品 **1～5 条** | **按实际条数展示**，**不** 凑满 6 条 |
| 恰好 **6 条及以上** | 展示销量最高的 **6 条** |

### 6.7 加载失败

| 情形 | 首页行为 |
|------|----------|
| 热销数据接口失败 / 超时 | **不阻塞** 整页；热销区按 **空态** 处理（如「暂无热销商品」或隐藏区块，以前台 UI 为准）；**不提供** 模块内重试 |

---

## 7. 首页整体加载与刷新

### 7.1 首次进入

```text
用户打开 APP / 进入商城 Tab
    → 展示首页骨架或加载态（以前台 UI 为准）
    → 并行加载：Banner、平台一级分类、热销商品
    → 各模块独立渲染；某模块失败 **不导致** 整页白屏（见 §4.3、§5.4、§6.6）
    → 全部模块就绪或超时后结束全局 Loading
```

### 7.2 刷新

| 项 | 定稿 |
|----|------|
| 下拉刷新 | **不做** |
| 数据更新时机 | 用户 **重新进入** 首页、从其它 Tab 切回商城 Tab、或从子页 **返回** 首页时，按各模块 **重新加载**（是否每次回顶刷新以前台 UX 为准，见 §7.3） |

### 7.3 从其它页返回

从商品详情、分类页 **返回** 首页：默认 **保留** 离开前滚动位置（以前台 UX 为准）；若需每次回顶另版本说明。

---

## 8. 与下单、会员的协作（浏览 vs 可购）

首页 **仅浏览与跳转**，**不在此页** 完成加购或支付。用户从首页进入商品详情后，须满足 **《关联需求分析》§11 C 端可售条件** 方可下单：

| # | 条件 |
|---|------|
| 1 | 商品 = **出售中** |
| 2 | 店铺 = **开业** |
| 3 | 商品所属 **平台分类可见**（一级、二级 **是否显示** 均为是，且路径有效） |
| 4 | 库存 **> 0** |

| 场景 | 行为 |
|------|------|
| 访客点击热销商品 | 可进 **详情浏览**；加购/下单时引导 **登录/注册** |
| 会员禁用 | 首页 **仍可浏览**（与 Banner 策略一致）；登录/下单被会员模块拦截 |
| 停业店铺商品出现在热销区 | 可 **浏览** 详情；发起下单时提示 **店铺已停业**（S13） |
| 库存为 0 | 可 **浏览** 详情；加购/下单提示 **库存不足** |

---

## 9. 与平台后台配置的协作流程

```text
【平台 · 可选，与供给链并行】
    首页 Banner 设置 → 启用 Banner → C 端首页轮播即时生效

【平台 · 供给链前置】
    商品分类（平台）→ 维护一级/二级、是否显示
    商户 → 店铺 → 商家发品 → 审核/出售中

【C 端 · 本模块】
    打开商城首页
        → 读 Banner（内容管理）
        → 读平台一级分类（商品分类 · 平台侧）
        → 读出售中商品按销量 Top6（商品 + 店铺档案）

【C 端 · 下游】
    分类/搜索/详情 → 购物车 → 下单（用户链）
```

| 平台操作 | 对首页的影响 |
|----------|--------------|
| Banner 启停/改序/删除 | 轮播区 **即时** 变化（BN6） |
| 平台分类改「是否显示」 | 快捷导航 **即时** 增删条目 |
| 商品上架为出售中 / 下架 | 可能影响 **热销榜** 成员与排序 |
| 订单完成增加销量 | 可能影响 **热销榜** 排序 |
| 店铺停业 | **不** 自动从热销区移除商品；下单在详情拦截 |

---

## 10. 业务规则汇总

| 编号 | 规则 |
|------|------|
| **HM1** | 商城首页为 C 端 **全平台聚合** 落地页，**非** 店铺维度首页 |
| **HM2** | 访客与已登录会员 **均可** 浏览首页展示内容 |
| **HM3** | 搜索栏占位文案为 **「搜索兽药、饲料、店铺」**；点击进 **搜索输入页** |
| **HM4** | Banner 展示 **完全遵循** 《首页banner设置》C 端规则；首页 **不维护** Banner |
| **HM5** | 类目快捷导航使用 **平台一级分类**（显示=是 **且下有可见二级**）；**末尾固定「更多」** |
| **HM6** | 首页类目 **不使用** 店铺商品分类 |
| **HM7** | 点击一级 → **B 页**（Tab+列表）；「更多」→ **A 页**；详见 C 端《商品分类》v1.0.1 |
| **HM8** | 热销区 **最多 6 条**；范围 **全平台** |
| **HM9** | 热销入选须 **出售中** 且商品/店铺 **未删** |
| **HM10** | 热销排序：**销量降序** → 同销量 **上架时间降序** → 仍同 **商品编号升序** |
| **HM11** | 热销卡片展示：**主图、名称、售价、店铺名称**（店铺名 **实时读档**） |
| **HM12** | 点击热销卡片 → **商品详情页** |
| **HM13** | 首页 **展示 ≠ 可下单**；可购四条件在 **详情/结算** 校验 |
| **HM14** | 某模块加载失败 **不阻塞** 整页；Banner/类目/热销 **模块级空态**（**不提供** 模块内重试） |
| **HM15** | 首页 **不提供** Banner/分类/商品的 **商家或平台编辑** 能力 |

---

## 11. 页面与交互要点

| 场景 | 要求 |
|------|------|
| 首屏 | 搜索栏 + Banner（若有）+ 类目导航 **尽量首屏可见**（以前台 UI 为准） |
| Banner 空 | **无轮播占位**（BN13） |
| 类目横滑 | 末尾 **「更多」** 始终可达 |
| 热销列表 | 6 条以内 **纵向或网格** 展示；超过 1 条宜统一卡片高度 |
| 加载失败 | Banner/类目/热销 **空态**；**不提供** 模块内重试 |
| 网络离线 | 统一 C 端网络提示（不在本模块单独定义） |

---

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

| 草稿条目 | 本文档处理 |
|----------|------------|
| §1 首页搜索栏、占位、进搜索页 | §3 |
| §2 banner 轮播 | §4；对齐平台 Banner 定稿 |
| §3 一级分类 + 「更多」 | §5 |
| §4 热销：销量排序、字段、Top6、进详情 | §6 |
| §5 商城类目展示平台商品分类 | §5.1 定稿为 **平台分类口径**；与 §3 合并阐述，不重复建设第二套类目 UI |
| §6 异常返回 code/msg/data | **不纳入** |
| §7 技术栈 RuoYi/MySQL | **不纳入** |
| 未写：访客/会员、可购边界、Banner 细则、空态 | §1、§4、§6、§8 补充 |
| 未写：搜索具体逻辑 | **另册**；§3 仅入口 |

---

## 13. 非本期范围

| 项 | 说明 |
|----|------|
| 搜索输入页、搜索结果、搜索历史 | 待建设搜索模块 |
| C 端 **商品详情** 正式需求 | 首页、分类页仅跳转 |
| Banner 点击跳转活动/商品/外链 | 平台 Banner BN14：**仅预览大图** |
| 首页运营位（广告位、弹窗、公告） | — |
| 按店铺/地区/会员等级 **差异化首页** | — |
| 首页展示 **店铺商品分类**、**热门店铺** | — |
| 首页 **加购、领券、秒杀** | — |
| 热销标题/数量/占位文案 **后台可配置** | 本期固定；若需配置另版本 |
| 展示销量数字、库存标签 | 本期热销卡片 **不展示** |

---

## 14. 修订记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版定稿：搜索栏、Banner、平台一级类目导航、热销 Top6；关联平台 Banner/分类/商品/店铺/会员及《关联需求分析》v1.6 |
| **v1.0.1** | A 一级分类落地页=二级 Tab+商品列表；B 热销同销量按上架时间降序；C 店铺名实时读档；D 不做下拉刷新；E 类目/热销失败空态 |
| **v1.0.2** | 一级导航可见口径对齐 GC6；§5.3 引用 C 端《商品分类》v1.0.1 A/B/C 页 |

---

*文档版本：v1.0.2（定稿）· 关联《关联需求分析.md》v1.6、《首页banner设置功能需求.md》v1.0.1、《商品分类功能需求.md》v1.5、《商品分类功能需求.md》（C 端）v1.0.1、《商品审核功能需求.md》v1.0、《店铺管理功能需求.md》v1.3.5、《会员管理功能需求.md》v1.0.1 · 草稿《商城首页功能需求-草稿.md》保持不变。*
