# 商品分类 — 功能需求说明

> 本文档在《商品分类功能需求-草稿》基础上整理，并关联《农资商城web》目录下商户管理、店铺管理、商品管理等模块需求做边界与流程对齐。  
> 范围：**平台 + 店铺** 的商品分类（一级 + 二级）维护能力；不涉及数据库结构、接口定义及技术实现细节。  
> **说明：** **平台** 维护全平台统一分类（`shop_id` 为空）；**商家** 维护本店分类；平台 **商品管理** 按店铺引用商家分类做检索。  
> **v1.1：** 商品仅挂二级分类、批量删除整批失败、店铺停业 C 端禁止下单已产品定稿。  
> **v1.3：** **不考虑会员体系**；商家端使用 **店铺经营账号** 登录。  
> **v1.4：** 平台端提供分类 CRUD；列表 **分页**；`shop_id` 可空区分平台/店铺分类。  
> **v1.5：** 发品 **商品分类**（`category_id`）挂 **平台二级**；**店铺商品分类**（`shop_category_id`）为并列字段，见《店铺商品分类功能需求》。

---

## 1. 模块定位

### 1.1 业务目标

为 **平台** 与每个 **店铺** 提供商品分类体系（最多 **二级**），支撑：

- 平台维护 **全平台分类**（与店铺分类数据隔离）；
- 店铺内商品的分类挂载与组织；
- 平台 **商品管理** 按 **店铺** 分类筛选；
- **C 端（用户商城）** 按店铺展示可见分类（受「是否显示」「是否热门」控制）。

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

```text
商品分类（平台 + 店铺 · 最多二级）
    ├── 平台端：全平台分类树（shop_id 为空）
    └── 商家端：本店分类树（归属店铺）
            └── 商品管理 ── 商品挂 **本店** 二级分类
```

| 关联模块 | 关系 | 边界说明 |
|----------|------|----------|
| 商户管理 v1.3.1 | 无直接操作 | 不维护分类 |
| 店铺管理 v1.3.2 | 上游 | 分类 **归属店铺**；商家端 **店铺经营账号** 在开店时由平台配置 |
| 商品管理 | 下游消费 | 商品 **category_id** 须挂 **平台二级分类**；**shop_category_id** 可选挂本店店铺商品二级；平台检索可按店铺名称 + 分类筛选 |

### 1.3 使用端与角色

| 项目 | 说明 |
|------|------|
| **平台端** | 平台管理员维护 **全平台分类**（一级 + 二级） |
| **商家端** | **店铺经营管理端** — 店铺管理员维护 **本店** 分类 |
| 店铺管理员 | **店铺经营账号**（平台配置）及已授权 **子管理员** |
| 商户/店铺管理 | **不** 在入驻/开店流程中代建分类；分类在商品分类模块维护 |

### 1.4 数据范围

- **平台分类：** 全平台共用，`shop_id` 为空；平台端菜单「平台商品 → 商品分类」维护。
- **店铺分类：** 使用 **店铺经营账号** 登录商家端后，在 **当前店铺** 下操作（须切换店铺上下文）。
- 平台分类与店铺分类 **相互独立**；店铺之间分类亦相互独立。

---

## 2. 业务概念

| 概念 | 说明 |
|------|------|
| 一级分类 | 分类树的根级节点，无上级分类 |
| 二级分类（子分类） | 挂在某一一级分类下，**不能再设下级** |
| 是否显示 | 控制 C 端是否展示该分类；平台商品管理仍可看到全部分类 |
| 是否热门 | 用于 C 端店铺内 **热门分类** 展示位（具体展位以前台为准） |
| 排序 | 同层级内的展示顺序，**数值越小越靠前** |
| 逻辑删除店铺 | 店铺被平台逻辑删除后，本店分类不可再维护，已关联商品按商品/店铺删除规则处理 |

---

## 3. 分类结构规则（定稿）

| 规则 | 说明 |
|------|------|
| C1 | 仅支持 **两级**：一级、二级，**禁止三级及以上** |
| C2 | 添加一级：上级分类为空（或选择「无 / 顶级」） |
| C3 | 添加二级：上级分类 **必须** 选择本店某一 **一级分类** |
| C4 | 同一店铺、同一上级下，**分类名称不可重复** |
| C5 | 发品 **商品分类**（`category_id`）**须且仅能关联平台二级分类**（`shop_id IS NULL`）；**不可** 关联一级 |
| C6 | **店铺商品分类**（`shop_category_id`）为并列可选字段，规则见 **《店铺商品分类功能需求》** |

---

## 4. 功能结构

```text
商品分类（当前店铺）
├── 分类列表（树形或分级列表展示一级 + 二级）
├── 添加一级分类
├── 添加子分类（二级）
├── 编辑分类（一级 / 二级）
└── 删除分类（单独 / 批量）
```

---

## 5. 分类列表

### 5.1 列表字段

| 字段 | 说明 |
|------|------|
| 分类名称 | 一级或二级名称；二级宜 **缩进或层级标识** 展示所属一级 |
| 分类图片 | 缩略图 |
| 是否显示 | 是 / 否 |
| 是否热门 | 是 / 否 |
| 排序 | 数字，同层排序用 |
| 操作 | 编辑、删除；一级分类额外提供 **添加子分类** |

### 5.2 列表行为

- 默认展示 **当前店铺** 下全部未删除的一级、二级分类。
- 默认按 **一级分组**，同层内按 **排序值升序**，排序相同则按 **创建时间升序**。
- 支持 **单独删除** 与 **批量删除**（勾选多条，见第 9 节）。
- 列表顶部展示 **当前店铺名称**（只读），避免误操作他店数据。

### 5.3 高级检索（可选）

草稿未要求；若实现，支持按 **分类名称** 模糊匹配，命中一级或二级均展示其层级关系。

---

## 6. 添加一级分类

### 6.1 填写项

| 字段 | 必填 | 说明 |
|------|:----:|------|
| 分类名称 | 是 | 本店一级分类名称唯一 |
| 上级分类 | — | 固定为顶级，不可选二级作上级 |
| 分类图片 | 是 | 符合平台图片格式与大小 |
| 排序 | 是 | 非负整数，默认 **0** |
| 是否热门 | 是 | 默认 **否** |
| 是否显示 | 是 | 默认 **是** |

### 6.2 流程

```text
点击「添加分类」
    → 填写表单（上级为顶级）
    → 提交校验
    ├── 失败 → 逐项提示
    └── 成功 → 列表刷新，展示新的一级分类
```

---

## 7. 添加子分类（二级）

### 7.1 入口

- 列表行操作 **「添加子分类」**（仅 **一级分类** 行展示）；
- 或添加分类时上级分类选择某一一级。

### 7.2 填写项

与第 6.1 节相同，但 **上级分类** 必选为 **某一个一级分类**（下拉仅列本店一级）。

| 字段 | 说明 |
|------|------|
| 分类名称 | 在同一一级下的二级名称不可重复 |
| 上级分类 | 必选，且必须为一级 |

### 7.3 限制

- 不允许以 **二级分类** 作为上级。
- 每个一级下二级数量不设上限（若后续需限额，单独版本补充）。

---

## 8. 编辑商品分类

### 8.1 范围

- **一级、二级分类均可编辑**（草稿第 3 条）。

### 8.2 可编辑字段

| 字段 | 一级 | 二级 |
|------|:----:|:----:|
| 分类名称 | ✓ | ✓ |
| 上级分类 | ✗ 固定顶级 | ✓ 可更换为本店其他 **一级**（更换后须仍满足名称唯一） |
| 分类图片 | ✓ | ✓ |
| 排序 | ✓ | ✓ |
| 是否热门 | ✓ | ✓ |
| 是否显示 | ✓ | ✓ |

### 8.3 校验

与添加时一致；名称唯一性校验 **排除自身**。

### 8.4 保存后对商品的影响

- 修改名称、图片、显示、热门、排序：**不自动** 改变已挂该分类的商品状态（出售中/待审核等）。
- 将 **是否显示** 改为 **否**：C 端不再展示该分类入口，已挂在该分类下的商品 **不自动下架**；用户仍可能通过店铺内其他入口进入商品页，但须受商品自身状态及 **店铺是否停业可下单** 规则约束（见 10.3）。

---

## 9. 删除商品分类（定稿）

### 9.1 删除方式

- **单独删除**：行操作删除；
- **批量删除**：勾选多条后批量删除。

### 9.2 删除一级分类（草稿第 4、5 条对齐）

```text
删除一级分类
    → 校验该一级下是否存在「已关联商品」的分类（见 9.4）
    ├── 存在 → 阻断，提示先调整商品分类或下架商品
    └── 不存在 → 二次确认：「将同时删除其下全部二级分类，是否继续？」
            ├── 取消 → 结束
            └── 确认 → 删除该一级及下属全部二级
```

**定稿：** 删除一级 **级联删除** 其下全部二级（与草稿一致）；级联前须通过 9.4 校验（任一层有关联商品则整棵子树不可删）。

### 9.3 删除二级分类

```text
删除二级分类
    → 校验该二级是否有关联商品（9.4）
    ├── 有 → 阻断，提示「该分类下存在商品，请先修改商品分类或处理商品」
    └── 无 → 二次确认 → 删除成功
```

### 9.4 关联商品校验（定稿）

| 场景 | 规则 |
|------|------|
| 何谓「有关联商品」 | 存在 **未删除** 且商品档案中 **分类字段指向该二级分类** 的商品（商品 **仅挂二级**，一级不直接挂商品） |
| 删除二级 | 该二级有关联商品 → **禁止删除** |
| 删除一级 | **任一下属二级** 有关联商品 → **禁止删除**（一级不直接挂商品，仅校验子级） |
| 批量删除（定稿） | 对每条选中记录分别校验；**任一条不通过则整批失败**，不删除任何一条，并 **汇总提示** 失败原因（如「分类 A 下存在商品，整批操作已取消」） |

### 9.5 删除后影响

- 已删除分类从列表消失。
- 商品管理、C 端不再可选该分类；历史数据查询是否展示分类名以平台规范为准。

---

## 10. 与商品管理、C 端的协作

### 10.1 商品管理（平台）

| 场景 | 行为 |
|------|------|
| 商品列表检索 | 可按 **商品分类**（展示分类全路径，如「一级 > 二级」）、店铺名称等筛选 |
| 商品数据来源 | **商品分类** 读平台二级（`shop_id IS NULL`）；**店铺商品分类** 读各店维护的店铺分类；两字段并列展示 |

### 10.2 商品发布（商家端 / 与商品管理衔接）

```text
商家在当前店铺发布/编辑商品
    → 「商品分类」下拉：平台二级（`GET /agri/seller/goods/categoryOptions`）
    → 「店铺商品分类」下拉：本店二级（`GET /agri/seller/goods/shopCategoryOptions`）
    → 商品分类必选（规则 C5）；店铺商品分类视产品是否必填
    → 保存后平台商品管理可按分类、店铺检索
```

### 10.3 C 端展示与下单（定稿）

| 配置 | C 端行为 |
|------|----------|
| 是否显示 = 是 | 店铺内分类导航/筛选项 **可展示**（店铺非停业或停业但仅浏览时，展示策略与前台 UI 一致） |
| 是否显示 = 否 | **不展示** 该分类入口 |
| 是否热门 = 是 | 参与店铺内 **热门分类** 区域（具体 UI 以前台为准） |
| 店铺 **停业** | 与《店铺管理功能需求》v1.3.2 一致：用户 **禁止下单**；商家端仍可维护分类 |

```text
用户进入停业店铺 / 分类页
    → 可浏览分类与商品信息（是否展示停业店由前台 UI 决定）
    → 发起下单 / 结算 → 拦截，禁止下单
```

---

## 11. 业务规则汇总

| 编号 | 规则 |
|------|------|
| G1 | **平台分类**（`shop_id` 为空）与 **店铺分类** 数据隔离；店铺分类归属店铺 |
| G2 | 仅 **两级** 分类；二级的上级必须是一级 |
| G3 | 同 **数据范围**、同上级下分类名称 **不可重复** |
| G4 | 删除一级 **级联删除** 全部二级（须先通过商品关联校验） |
| G5 | 有关联 **未删除商品** 的分类 **不可删除** |
| G6 | **平台管理员** 维护平台分类；**店铺管理员**（含授权子管理员）维护本店分类 |
| G7 | 商品 **仅可关联二级分类**（与商品管理模块衔接） |
| G8 | 修改显示/热门/排序 **不自动** 改变商品上下架状态 |
| G9 | 批量删除：**任一条校验失败则整批失败**，不部分删除 |
| G10 | 店铺 **停业** 时 C 端 **禁止下单**，与店铺管理 v1.3.2 一致 |
| G11 | 商家端使用 **店铺经营账号** 登录；**不考虑会员体系** |

---

## 12. 页面与交互要点

| 场景 | 要求 |
|------|------|
| 列表 | 扁平分页列表；二级展示上级名称；一级行可「添加子分类」 |
| 添加/编辑 | 选择二级时上级仅一级；图片支持预览 |
| 删一级 | 二次确认 + 级联说明 |
| 删二级 / 批量删 | 二次确认；有关联商品时明确提示；批量 **整批失败** 并汇总原因 |
| 多店铺 | 页头固定展示当前店铺，切换店铺后列表整页刷新 |

---

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

### 13.1 入驻 → 开店 → 维护分类

```text
平台：商户管理 → 主体入驻 → 编辑补全经营信息
    ↓
平台：店铺管理 → 添加店铺（选商户 + 配置经营账号）→ 开业
    ↓
商家：经营账号登录 → 选择当前店铺 → 商品分类 → 添加一级 / 二级
    ↓
商家：商品管理 → 选平台二级「商品分类」发品（可选本店「店铺商品分类」）
    ↓
平台：商品管理 → 按店铺、分类检索与审核
```

### 13.2 删店与分类

```text
平台：店铺管理 → 逻辑删除店铺（满足删店条件）
    ↓
本店分类：不可再维护；商家端进入该店分类功能不可用或提示店铺已关闭
    ↓
商品：按商品管理 / 删店规则处理，不在本模块重复删商品
```

---

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

| 草稿条目 | 本文档处理 |
|----------|------------|
| 列表字段、添加、编辑、删一级级联、子分类 | 结构化展开 |
| 店铺管理员维护 | 商家维护 **本店** 分类；**平台** 另维护全平台分类 |
| 批量/单独删除 | 补充商品关联校验、批量失败策略、确认流程 |
| 异常返回、技术栈 | **不纳入** |
| 未写：店铺维度、二级挂商品、C 端显示 | 已定稿补充，与商户/店铺/商品边界对齐 |
| 商品管理草稿首条误贴分类列表 | 以本模块为准；商品管理列表以商品字段为准 |
| v1.1 商品挂类 | 定稿：**仅二级**，一级不挂商品 |
| v1.1 批量删除 | 定稿：**整批失败** + 汇总提示 |
| v1.1 停业 C 端 | 定稿：**禁止下单** |
| v1.3 | **不考虑会员**；店铺经营账号 |
| v1.3.1 | 同步取消单商户 **3 店** 上限表述 |
| v1.4 | 平台端分类 CRUD；`shop_id` 可空；列表分页 |
| v1.5 | 统一发品口径：`category_id` = 平台二级；`shop_category_id` = 本店店铺商品二级 |

---

*文档版本：v1.5（定稿）· 关联《商品分类技术方案.md》v1.2、《商品分类测试用例.md》v1.0、《店铺商品分类功能需求.md》v1.1 · 草稿保持不变。*
