# 商品分类 — 功能需求说明（C 端）

> 本文档在《商品分类功能需求-草稿》基础上整理，并关联 **《关联需求分析.md》** v1.6、平台侧 **《商品分类功能需求》** v1.5、**《商品审核功能需求》** v1.0、**《店铺管理功能需求》** v1.3.5、**《会员管理功能需求》** v1.0.1 及 C 端兄弟模块 **《商城首页功能需求》** v1.0.1 做边界与流程对齐。  
> 范围：**C 端（消费者 APP / 用户商城）· 商品分类** 的浏览、导航与分类下商品列表；**不涉及** 数据库结构、接口定义及技术实现细节。  
> **说明：** 本模块 **只消费** 平台维护的 **平台商品分类**（全平台一份）；**不使用** 店铺商品分类。分类下商品为 **全平台跨店铺** 聚合展示。  
> **v1.0：** 首版定稿；搜索入口、全部分类页、一级分类落地页、分类商品列表与排序；与供给链/浏览层规则对齐。  
> **v1.0.1：** 定稿 A→独立列表页（A1）；B 切换 Tab 列表回顶（C1）；独立列表页含搜索栏；排序区 UI 说明；与商城首页一级可见口径对齐。

---

## 1. 模块定位

### 1.1 业务目标

为 **C 端买家/访客** 提供按 **平台商品分类** 浏览农资商品的能力，使其能够：

- 通过 **顶部搜索入口** 进入全站检索（检索能力另册）；
- 在 **全部分类页** 查看完整 **一级 + 二级** 平台分类，并快速切换大类与小类；
- 从 **商城首页** 进入 **一级分类商品页**，通过 **二级 Tab** 切换查看各小类下的商品；
- 在 **分类商品列表** 中按 **价格、销量** 排序浏览，并进入 **商品详情**。

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

| 能力 | 说明 |
|------|------|
| **搜索执行与结果页** | 本模块仅提供 **搜索入口**；关键词检索、结果排序等见 **搜索模块**（待建设） |
| **平台/店铺分类维护** | 见平台 **商品分类**、商家 **店铺商品分类**；C 端 **只读消费** |
| **商品发品/审核/上下架** | 见商家 **商品列表**、平台 **商品审核** |
| **购物车、下单、支付** | 见 **购物车**、**订单管理** 等；本模块 **不直接** 完成交易 |
| **按店铺商品分类导航** | 店铺商品分类为商家内部组织字段；**C 端分类浏览不走该体系** |
| **会员注册/登录页** | 见 **会员管理**；本模块可提供入口跳转，**不在此定义** 注册表单 |

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

```text
【供给链】平台维护平台分类 → 商家发品挂平台二级 → 审核/出售中
                              ↓
【C 端 · 商城首页】一级快捷导航、「更多」入口
                              ↓
【C 端 · 本模块】全部分类页 / 一级分类商品页 / 分类商品列表
                              ↓
                      商品详情 → 加购/下单（须满足可购条件，见 §9）

【用户链 · 并行】访客与会员均可浏览；下单须登录且会员启用
```

| 关联模块 | 关系 | 边界说明 |
|----------|------|----------|
| **商城首页** v1.0.1 | **上游入口** | 点击一级分类 → **一级分类商品页**；点击「更多」→ **全部分类页**（HM7） |
| **商品分类（平台）** v1.5 | **类目来源** | 仅 **平台分类**（一级 + 二级）；**是否显示** 控制 C 端可见性 |
| **商品审核 / 商品管理** | **商品来源** | 列表仅展示 **出售中** 商品 |
| **店铺管理** v1.3.5 | **间接** | 停业店铺商品 **可出现在** 浏览列表；**下单** 在详情/结算拦截 |
| **会员管理** v1.0.1 | **用户链** | 访客与会员 **均可** 浏览；禁用会员 **不影响** 分类页展示 |
| **关联需求分析** v1.6 §11 | **可购规则** | 本模块 **展示 ≠ 可下单**；详情/结算校验四条件 |

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

| 关联分析要点 | 本模块 |
|--------------|--------|
| C 端浏览与下单分离 | 分类页、商品列表属 **浏览层** |
| 平台分类 vs 店铺分类 | **仅用平台分类**（G1）；**不展示** 店铺商品分类 |
| C 端可售四条件 | 列表 **不校验** 店态/库存；详情/下单模块校验 |
| 分类「不显示」 | C 端 **无** 该分类入口；已挂商品 **不自动下架**（C-P5） |
| 店铺停业 | 商品 **可浏览**；**禁止下单**（S-P3、G10） |
| 状态不级联 | 平台改分类显示/排序 **即时** 影响 C 端展示，**无** 单独「发布」动作 |

### 1.4 使用端与角色

| 端 | 角色 | 能力 |
|----|------|------|
| **C 端** | **访客** | 浏览全部分类、分类下商品列表、进详情 |
| **C 端** | **已登录会员** | 同访客；加购/下单在其它页面 |
| 平台管理端 | 平台管理员 | **不操作** 本页面；维护 **平台** 分类树 |
| 店铺经营管理端 | 商家 | **不操作** 本页面；维护 **店铺商品分类**（与本模块无关） |

---

## 2. 页面与入口

本模块包含 **三个页面**；其中 **商品列表展示规则** 在 B 内嵌区与 C 独立页 **共用**（§7）：

```text
C 端商品分类
├── A. 全部分类页（左右分栏：一级 + 二级）
├── B. 一级分类商品页（二级 Tab + 同页下方商品列表）
└── C. 二级分类商品列表页（独立页；仅 A 路径进入）
```

| 入口 | 目标页面 | 说明 |
|------|----------|------|
| 商城首页 · 点击某一 **一级分类** | **B. 一级分类商品页** | 带入该 **一级分类**；默认选中排序最靠前的 **二级 Tab** |
| 商城首页 · 点击 **「更多」** | **A. 全部分类页** | 展示完整可见分类树 |
| A · 点击某一 **二级分类** | **C. 二级分类商品列表页** | **跳转独立页**；无 Tab；顶栏展示 **一级 > 二级** 路径 |
| B · 切换 **二级 Tab** | B 内 **同页** 商品列表区刷新 | **不跳转**；列表规则见 §7 |

> **定稿（v1.0.1）：**  
> - **A1：** A 点二级 → **C 独立商品列表页**（**非** 在 A 页右侧直接展示商品）。  
> - **B 与 C 区别：** B = Tab + 同页列表；C = 无 Tab 的独立列表页，带面包屑/路径标题。  
> - 草稿「点击小类进入商品列表」= **A→C**；B 内 Tab 切换 **共用 §7 列表规则**。

---

## 3. 顶部搜索栏

### 3.1 展示规则

| 项 | 定稿 |
|----|------|
| 出现页面 | **A. 全部分类页**、**B. 一级分类商品页**、**C. 二级分类商品列表页（独立）** 顶部 **固定**（滚动时保持可见，具体吸顶样式以前台 UI 为准） |
| 默认文案 | 占位提示：**「搜索兽药、饲料、店铺」**（与商城首页 HM3 **一致**） |
| 可输入性 | 可为 **只读样式**；点击整栏进入 **搜索输入页** |

### 3.2 交互流程

```text
用户在分类相关页面
    → 点击搜索栏
        → 进入「搜索输入页」（关键词、历史等 **另册**）
        → 检索逻辑 **不在本模块定义**
```

### 3.3 边界

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

---

## 4. 分类数据口径（只读）

### 4.1 分类体系

| 项 | 定稿 |
|----|------|
| 数据来源 | **平台商品分类**（平台管理员在 **平台 · 商品分类** 维护；全平台一份） |
| 层级 | **一级 + 二级**；商品 **仅挂二级**，一级 **不直接** 挂商品（对齐平台 C5、C7） |
| 不展示 | **店铺商品分类** 及任意 **店铺维度** 分类树 |

### 4.2 可见性

| 层级 | C 端展示条件 |
|------|--------------|
| **一级** | **是否显示 = 是**；**未删除**；且其下 **至少存在一个** 满足可见条件的 **二级**（避免空壳一级） |
| **二级** | **是否显示 = 是**；**未删除**；且其 **所属一级** **是否显示 = 是** |

> **说明：** 父级隐藏则子级 **一律不可见**，即使子级单独设为显示（对齐平台 §8.4、关联分析 C-P5）。

### 4.3 排序

| 层级 | 规则 |
|------|------|
| 一级、二级 | 同层 **排序值升序**；相同则 **创建时间升序**（与平台商品分类模块一致） |

### 4.4 展示字段

| 字段 | 说明 |
|------|------|
| 分类名称 | 必展示 |
| 分类图片 | 有则展示缩略图；**缺失时** 使用 **默认占位图**（以前台 UI 为准） |
| 是否热门 | 平台配置 **是否热门 = 是** 时，可在分类条目上展示 **热门标识**（样式以前台 UI 为准；**非必须**） |

---

## 5. 全部分类页（A）

### 5.1 布局（对应草稿 §2）

| 项 | 定稿 |
|----|------|
| 布局 | **左右分栏**：**左侧** 一级分类列表；**右侧** 当前选中一级下的 **二级分类** 列表 |
| 默认选中 | 进入页面时，左侧默认选中 **排序最靠前** 的第一个 **可见一级**；右侧展示其下二级 |
| 切换一级 | 点击左侧某一一级 → 右侧 **切换** 为对应二级列表（**不跳转** 新页） |

### 5.2 交互流程

```text
用户从首页「更多」进入全部分类页
    → 左侧展示全部可见一级
    → 右侧展示默认一级的二级列表
    → 用户点击左侧其他一级
        → 右侧刷新为对应二级列表
    → 用户点击右侧某一二级
        → **跳转** 至 **C. 二级分类商品列表页（独立）**（§7）
            → 页顶展示 **搜索栏** + **一级 > 二级** 路径（面包屑或标题栏，以前台 UI 为准）
            → **无** 二级 Tab（与 B 页区分）
```

### 5.3 空态

| 情形 | 行为 |
|------|------|
| 无任何可见一级（或均无可见二级） | 展示 **空态**（如「暂无分类」）；**不展示** 虚假分类条目 |
| 某一级下无可见二级 | 该一级 **不出现在** 左侧列表（见 §4.2 空壳过滤） |
| 分类图片缺失 | 占位图 + 名称 |

### 5.4 加载失败

| 情形 | 行为 |
|------|------|
| 分类数据加载失败 / 超时 | 页面展示 **空态或错误提示**；**不白屏**；是否提供 **整页重试** 以前台 UX 为准（**不提供** 模块内局部重试按钮为默认定稿，与首页 HM14 一致） |

---

## 6. 一级分类商品页（B）

承接 **商城首页** 点击某一 **一级分类** 的落地页（HM7、商城首页 §5.3）。

### 6.1 布局

| 项 | 定稿 |
|----|------|
| 页顶 | **顶部搜索栏**（§3） |
| 一级上下文 | 展示当前 **一级分类名称**（及可选图片/面包屑，以前台 UI 为准） |
| 二级导航 | 该一级下全部 **可见二级** 以 **Tab**（或等效横向标签）展示 |
| 默认 Tab | 进入时选中 **排序最靠前** 的第一个 **可见二级** |
| 列表区 | Tab 下方为 **分类商品列表**（§7） |

### 6.2 交互流程

```text
用户从首页点击一级分类「兽药」
    → 进入一级分类商品页，上下文 = 兽药
    → 展示其下二级 Tab（如 抗生素、驱虫药…）
    → 默认选中第一个 Tab，下方加载该二级商品列表
    → 用户切换 Tab
        → 下方列表 **回顶** 并 **重新加载** 对应二级商品（**C1**；Tab 条位置 **保持不变**）
    → 用户点击某一商品
        → 进入商品详情页
```

### 6.3 Tab 切换与滚动（定稿 C1）

| 项 | 定稿 |
|----|------|
| 切换 Tab | 商品列表区 **滚动回顶**；按新 Tab 对应二级 **重新加载** 列表 |
| Tab 条 | **保持** 当前横向位置（**不** 因切换 Tab 而重置 Tab 滚动位置） |
| 排序状态 | 切换 Tab 后 **保留** 用户已选排序方式（如仍为「销量降序」） |

### 6.4 边界

| 情形 | 行为 |
|------|------|
| 一级存在但 **无可见二级** | **不应** 从首页进入（首页一级已过滤）；若直达则展示 **空态** |
| 一级被平台改为 **不显示** | 用户 **刷新或再进入** 时该入口消失；已打开页按 **空态/失效提示** 处理 |

---

## 7. 商品列表规则（B 内嵌区 / C 独立页共用）

对应草稿 §3「对应商品列表」；**B 页 Tab 下方列表区** 与 **C 独立页** **共用** 下列规则。

### 7.0 C 独立页结构（A1）

| 项 | 定稿 |
|----|------|
| 进入方式 | 仅 **A. 全部分类页** 点击某一 **二级分类** |
| 页顶 | **搜索栏**（§3）+ **一级 > 二级** 路径展示 |
| 主体 | **商品列表**（本节 §7.1～§7.6） |
| 无 Tab | **不展示** 同级其它二级 Tab；返回 **A 页** 可再选其它二级 |

### 7.1 数据范围

列表展示 **当前所选平台二级分类** 下、**全平台跨店铺** 聚合的可浏览商品。

参与列表的商品须 **同时满足**：

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

> **定稿（浏览层）：** **不要求** 店铺 **开业** 才可 **出现在列表**；**不要求** 库存 > 0 才可 **展示**（与商城首页 §6.2、关联分析「浏览 vs 下单分离」一致）。

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

### 7.2 单条展示字段

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

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

### 7.3 排序（对应草稿 §3）

用户可在列表区切换排序方式：

| 排序项 | 规则 |
|--------|------|
| **销量** | 累计销量 **降序** 或 **升序**（用户二选一） |
| **价格** | 售价 **降序** 或 **升序**（用户二选一） |

| 项 | 定稿 |
|----|------|
| 默认排序 | 进入列表时默认 **销量降序**（以前台 UX 可标注「销量」为当前选中态） |
| 切换排序 | 用户切换后 **重新排序** 当前列表；**不切换** 分类上下文 |
| 稳定性 | 同排序值下，以 **商品编号升序** 保证顺序稳定 |
| 排序区 UI | 提供 **销量**、**价格** 两个维度及 **升序/降序**（共四种组合）；宜采用 **排序条 / 下拉面板** 等单一入口切换（具体样式以前台 UI 为准） |

### 7.4 分页与加载

| 项 | 定稿 |
|----|------|
| 加载方式 | 支持 **分页** 或 **上拉加载更多**（以前台 UX 选定一种或组合） |
| 空列表 | 展示 **空态**（如「该分类下暂无商品」）；**不** 用其它分类商品补齐 |

### 7.5 交互流程

```text
用户进入某二级分类的商品列表
    → 默认按销量降序展示出售中商品
    → 用户切换「价格升序/降序」或「销量升序/降序」
        → 列表重排/重新加载
    → 用户点击商品卡片
        → 进入商品详情页
    → 用户上拉/翻页
        → 加载更多（若有）
```

### 7.6 加载失败

| 情形 | 行为 |
|------|------|
| 商品列表加载失败 | 列表区 **空态或错误提示**；**不阻塞** 分类导航/Tab；是否整页重试以前台 UX 为准 |

---

## 8. 页面间导航关系

```text
                    ┌── 商城首页 ──┐
                    │  一级 / 更多  │
                    └──────┬───────┘
           ┌───────────────┼───────────────┐
           ▼                               ▼
   B. 一级分类商品页                  A. 全部分类页
   （Tab + 同页列表）                 （左一级 / 右二级）
           │                               │
           │ 切换 Tab（列表回顶 C1）          │ 点击二级
           │                               ▼
           │                       C. 二级分类商品列表页
           │                       （独立 · 面包屑 + 列表）
           └───────────┬───────────────────┘
                       │ 共用 §7 列表规则
                       ▼
                 点击商品 → 商品详情页（另册）
```

| 导航 | 定稿 |
|------|------|
| 返回 | 遵循系统 **返回栈**；从 B 返回首页 **保留** 首页滚动位置（对齐商城首页 §7.3） |
| 深度链接 | 若 APP 支持外链/分享进入某分类列表，须 **校验分类可见性**；不可见则 **空态或友好提示** |

---

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

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

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

| 场景 | 行为 |
|------|------|
| 访客浏览分类与列表 | **允许**；加购/下单引导 **登录/注册** |
| 会员禁用 | 分类页 **仍可浏览**；登录/下单被会员模块拦截 |
| 停业店铺商品出现在列表 | 可 **浏览** 详情；下单提示 **店铺已停业** |
| 库存为 0 | 可 **浏览** 详情；加购/下单提示 **库存不足** |
| 分类被改为 **不显示** | 入口消失；已收藏/历史链接进入时 **失效提示** |

---

## 10. 与平台后台配置的协作

```text
【平台 · 商品分类】
    维护一级/二级、图片、排序、是否显示、是否热门
        ↓ 即时生效（无 C 端单独发布）
【C 端 · 本模块】
    全部分类页 / 一级分类页 / 商品列表 只读展示
【平台 · 供给链】
    商户 → 店铺 → 发品挂平台二级 → 出售中
        ↓
    分类下列表仅展示出售中商品
```

| 平台操作 | 对本模块的影响 |
|----------|----------------|
| 新增/编辑分类名称、图片、排序 | 分类页 **即时** 更新展示 |
| 分类 **是否显示** 改为否 | C 端 **隐藏** 该分类入口；列表 **不再** 纳入新浏览（已打开页刷新后生效） |
| 商品上架为出售中 / 下架 | 分类列表 **增删** 可浏览商品 |
| 店铺改名 | 列表 **店铺名称** 即时更新 |
| 店铺停业 | **不** 自动从列表移除；下单在详情拦截 |
| 会员禁用 | **不影响** 分类浏览 |

---

## 11. 异常与提示（产品层）

| 场景 | 要求 |
|------|------|
| 网络异常 | 使用 C 端 **统一网络提示**；不在本模块单独定义文案体系 |
| 业务校验失败 | 提示语 **明确**（如「分类不存在或不可见」「排序方式无效」）；与 C 端其它模块 **体验一致** |
| 草稿 §4「code、msg、data」 | **不在本文定义**；属实现层约定 |

---

## 12. 业务规则汇总

| 编号 | 规则 |
|------|------|
| **GC1** | C 端分类浏览 **仅使用平台商品分类**；**不使用** 店铺商品分类 |
| **GC2** | 访客与已登录会员 **均可** 浏览本模块页面 |
| **GC3** | 搜索栏占位 **「搜索兽药、饲料、店铺」**；点击进 **搜索输入页**（GC-S1、GC-S2） |
| **GC4** | **全部分类页 A**：左一级、右二级；点二级 **跳转 C 独立列表页**（A1） |
| **GC5** | **一级分类商品页 B**：二级 **Tab** + 同页列表；切换 Tab **列表回顶重载**（C1） |
| **GC5a** | **C 独立页**：含 **搜索栏** + **一级>二级** 路径；**无 Tab** |
| **GC6** | 分类可见性：**显示=是** 且未删；二级须 **父级一级亦显示** |
| **GC7** | 分类排序：同层 **排序值升序** → **创建时间升序** |
| **GC8** | 商品列表范围：**当前二级** 下 **出售中** 且商品/店铺 **未删**；**全平台** 跨店 |
| **GC9** | 列表 **默认销量降序**；用户可切换 **价格/销量** 升序或降序 |
| **GC10** | 列表卡片：**主图、名称、售价、店铺名称**（店铺名 **实时读档**） |
| **GC11** | 点击商品 → **商品详情页** |
| **GC12** | 本模块 **展示 ≠ 可下单**；可购四条件在 **详情/结算** 校验 |
| **GC13** | 列表 **可含** 停业店、零库存商品（浏览层） |
| **GC14** | 分类/列表加载失败 **不白屏**；分类区与列表区 **可独立空态** |
| **GC15** | 本模块 **不提供** 分类或商品的 **编辑** 能力 |

---

## 13. 页面与交互要点

| 场景 | 要求 |
|------|------|
| 全部分类页 | 左右分栏 **一级联动二级**；点二级 **跳转 C 独立页** |
| 一级分类页 | Tab 多时可 **横向滑动**；切换 Tab **列表回顶**（C1） |
| C 独立列表页 | **搜索栏 + 路径标题 + 列表**；**无 Tab** |
| 商品列表 | 排序区含 **销量/价格 × 升/降**；切换排序 **即时反馈** |
| 图片缺失 | 分类/商品均可用 **占位图** |
| 空分类 / 空商品 | **明确空态文案** |
| 从首页进入 | 与 HM7 **路径一致**，无第二套交互 |

---

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

| 草稿条目 | 本文档处理 |
|----------|------------|
| §1 搜索栏、占位、进搜索页 | §3 |
| §2 二级分类、左右分栏、点大类切换小类 | §5（全部分类页） |
| §3 点小类进商品列表、价格销量排序 | §7；**B 页 Tab 切换** 同规则 |
| §4 异常返回 code/msg/data | §11 **不纳入** |
| §5 技术栈 RuoYi/MySQL | **不纳入** |
| 未写：首页入口、平台口径、可购边界 | §2、§4、§9 补充 |
| 未写：一级分类 Tab 落地页 | §6；对齐商城首页 v1.0.1 **定稿 A** |
| v1.0.1 | A1 独立列表页；C1 Tab 切换回顶；C 页搜索栏；排序 UI §7.3 |

---

## 15. 非本期范围

| 项 | 说明 |
|------|------|
| 搜索输入页、搜索结果、搜索历史 | 待建设搜索模块 |
| C 端 **商品详情** 正式需求 | 本模块仅跳转 |
| 按 **店铺商品分类** 浏览 | — |
| 按 **店铺** 维度的分类馆 / 店铺首页 | — |
| 列表展示 **销量数字、库存、服务标签** | 本期卡片 **不展示** |
| 三级及以上分类 | 平台 **禁止**（C1） |
| 分类页 **加购、领券、分享** | 在详情或另册 |
| 分类/排序 **后台可配置**（C 端默认排序、占位文案） | 本期产品定稿；若需配置另版本 |
| 下拉刷新 | 默认 **不做**（与商城首页 v1.0.1 一致）；若分类页单独需要另版本 |

---

## 16. 修订记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版定稿：搜索入口、全部分类页、一级分类 Tab 页、分类商品列表与排序；关联平台商品分类 v1.5、《关联需求分析》v1.6、商城首页 v1.0.1 |
| **v1.0.1** | A1 A→C 独立列表页；C1 B 切换 Tab 列表回顶；C 页含搜索栏；排序区 UI；与首页一级可见口径对齐 |

---

*文档版本：v1.0.1（定稿）· 关联《关联需求分析.md》v1.6、《商品分类功能需求.md》v1.5、《商城首页功能需求.md》v1.0.2 · 草稿《商品分类功能需求-草稿.md》保持不变。*
