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

> 本文档在《店铺商品分类功能需求-草稿》基础上整理，并关联 **《关联需求分析.md》**、**《店铺管理功能需求》**、**《店铺设置功能需求》**、平台侧 **《商品分类功能需求》** 及商家侧 **《商品列表功能需求-草稿》** 做边界对齐。  
> 范围：**店铺经营管理端 · 商品管理** 对 **当前店铺下店铺商品分类** 的列表、创建、编辑与删除。  
> **说明：** 本文档 **仅描述功能需求与业务规则**；不涉及数据库结构、接口定义及技术实现细节。  
> **v1.0：** 首版定稿；对齐草稿 §1～§7；补全店铺上下文、与平台商品分类及商品列表的协作链。  
> **v1.1：** **店铺商品分类** 由单层调整为 **两级**（一级 + 二级），与当前实现及平台《商品分类》层级规则一致；共用 `biz_goods_category`（`shop_id` 非空），数据与平台「商品分类」隔离。

---

## 1. 模块定位

### 1.1 业务目标

在农资商城 **店铺经营管理端（Web）· 商品管理** 提供 **店铺商品分类** 管理能力，使 **店铺管理员**（商户经营账号及已授权子管理员）能够：

- 浏览 **当前店铺** 下全部有效分类（**一级 + 二级**）；
- **添加一级分类**、**添加子分类（二级）**，配置 **分类名称、分类图片、排序、是否显示、是否热门**；
- **编辑**、**删除** 分类（支持 **单独 / 批量** 删除）；
- 为 **商家端 · 商品列表** 发品时的 **「店铺商品分类」** 字段提供可选数据源。

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

| 能力 | 说明 |
|------|------|
| **平台 · 商品分类** | 见 **平台 · 商品管理 · 商品分类**；维护 **全平台二级分类树**（含图片、热门等）；**非** 本模块 |
| **平台 · 商品监管** | 平台按店铺检索商品时引用商家数据；**不** 在本模块维护分类 |
| **商品 CRUD / 上下架** | 见 **店铺后台 · 商品列表**（待建设） |
| **C 端会员账号** | **无关**；商家端操作 **不校验** C 端会员注册 |

### 1.2 与草稿的对应关系

| 草稿条目 | 定稿规则 |
|----------|----------|
| §1 列表 | 分类名称、是否显示；操作：编辑、删除 |
| §2 数据范围 | 当前登录账号 **所属店铺 ID** 下该店铺的 **全部有效** 店铺商品分类 |
| §3 店铺上下文 | 登录解析所属店铺 ID 写入 header；商户管理员默认 **最早店铺**；切换店铺后更新 header |
| §4 添加分类 | 扩展为 **一级 / 二级**；含分类图片、是否热门（对齐平台分类交互） |
| §5 修改分类 | 一级、二级均可编辑；二级可更换上级一级 |
| §6 删除分类 | 分类下 **有商品** 则 **不允许删除** |
| §7 异常返回 | 统一 `code`、`msg`、`data` |
| §8 技术栈 | **不纳入** 本文档 |

### 1.3 在供给链中的位置

依据 **《关联需求分析.md》§5.1、§6.3**：

```text
【平台】商户管理 → 店铺管理 → 开店 + 经营账号
            ↓
【商家】登录 → 选择当前店铺（X-Shop-Id）
            ↓
【商家】店铺商品分类（本模块）── 维护本店 **两级** 分类树
            ↓
【商家】商品列表 ── 发品时选择「店铺商品分类」（与「商品分类」并列字段，见商品列表草稿）
            ↓
【平台】商品管理 ── 按店铺检索与审核（只读引用，不维护本模块数据）
```

| 分类类型 | 维护端 | 结构 | 与本模块关系 |
|----------|--------|------|--------------|
| **平台商品分类** | 平台 · 商品分类 | 一级 + 二级；图片、热门 | **并列、数据隔离**；发品时「商品分类」字段 |
| **店铺商品分类** | **本模块** | **两级**（一级 + 二级；与平台分类同层级规则） | **本模块维护对象**；发品时「店铺商品分类」字段（**仅挂二级**） |

> **命名区分：** 产品口语「商品分类」在平台端指 **平台/店铺二级树**；本模块定稿名 **「店铺商品分类」**，与商品列表草稿中 **「店铺商品分类」** 字段一致，避免与平台二级分类混淆。

### 1.4 使用端与角色

| 端 | 可操作角色 | 能力 |
|----|------------|------|
| **店铺经营管理端** | **商户经营账号** | 本模块全部能力 |
| **店铺经营管理端** | 员工（子管理员） | 是否可访问由 **角色管理** 中商家端菜单权限决定 |
| **平台管理端** | 平台管理员 | **不** 使用本模块；**不** 代维商家店铺商品分类 |
| **C 端** | — | **不可** 直接访问本模块 |

### 1.5 数据范围

- **纳入：** 当前 **所属店铺**（`X-Shop-Id`）下全部 **未删除** 的店铺商品分类；
- **排除：** 其他店铺分类；已逻辑删除分类；
- **上下文：** 页头展示 **当前店铺名称**（只读）；切换店铺后列表 **整页刷新**。

---

## 2. 关联需求分析

### 2.1 与《关联需求分析》— 供给链

| 关联点 | 定稿 |
|--------|------|
| **§3 模块职责** | 商家维护 **本店** 分类数据；平台 **商品分类** 另维护平台树 + 商家二级树（平台文档）；**本模块** 为商家端 **店铺商品分类** 专册 |
| **§5.1 开业流程** | 开店后商家须 **先选当前店铺**，再维护分类并发品 |
| **§9.1 经营账号** | 一商户一套登录、多店共用；登录后 **切换当前店铺** 再操作本模块 |
| **§9.2 子管理员** | 已授权子管理员 **可** 操作（须角色含本菜单）；人数上限在 **店铺设置**，与本模块 **无** 分类数量上限 |
| **硬前置** | **无有效店铺** → 无法进入本模块；**无店** → 无分类数据 |

### 2.2 与《店铺管理功能需求》

| 项 | 定稿 |
|----|------|
| 店铺创建 | 平台开店后，商家端 **本店** 分类初始为空；**不** 在开店流程中预置分类 |
| 店铺停业 | 与平台 §5.3 一致：商家端 **仍可** 维护分类与商品资料；C 端该店 **禁止下单**（**不自动** 删改分类） |
| 店铺逻辑删除 | 本店分类 **不可再维护**；进入功能时提示店铺不可用；已关联商品按 **商品/删店** 规则处理 |
| 多店 | 每店分类 **相互独立**；须 **切换当前店铺** 后操作对应数据 |

### 2.3 与平台《商品分类功能需求》— 边界

| 维度 | 平台 · 商品分类 | 本模块 · 店铺商品分类 |
|------|-----------------|----------------------|
| 使用端 | 平台端 + 商家端（二级树） | **仅** 商家端 |
| 结构 | **两级**（一级 + 二级） | **两级**（一级 + 二级；`shop_id` 非空，与平台分类 **数据隔离**） |
| 列表字段 | 名称、图片、显示、热门、排序 | 名称、图片、是否显示、是否热门（排序见表单） |
| 商品挂载 | 商品 **须挂二级** 平台分类（规则 C5） | 商品 **仅挂本店店铺商品二级**；与「商品分类」字段 **并列、独立** |
| 删除规则 | 二级有商品不可删；一级级联删二级 | **同左**（二级有商品不可删；删一级级联删二级） |
| 批量删除 | 平台文档支持；**整批失败** | **支持**；任一条不通过则 **整批失败** |

### 2.4 与商家侧《商品列表功能需求-草稿》— 消费方

| 项 | 定稿 |
|----|------|
| 发品字段 | 添加商品含 **「商品分类」** 与 **「店铺商品分类」**；后者数据源 **来自本模块** |
| 可选范围 | 下拉 **仅展示当前店铺**、**未删除** 的 **二级** 分类（展示「一级 > 二级」路径）；**建议** 仅展示 **是否显示 = 是** 的项 |
| 删除协作 | 本模块删除 **二级** 前须校验 **无关联商品**；删 **一级** 须校验 **全部下属二级** 均无商品；商品侧改分类后本模块方可删 |
| 列表检索 | 商品高级检索含「商品分类」；**店铺商品分类** 是否纳入检索以商品列表定稿为准 |

### 2.5 与《角色管理》《员工管理》— 权限

| 项 | 定稿 |
|----|------|
| 菜单权限 | 本模块对应商家端菜单（如「店铺商品分类」）；由 **角色管理** 配置 |
| 经营账号 | 默认具备商家端全部菜单（含本模块） |
| 子管理员 | 无权限则 **不可** 见菜单；直接访问须拒绝 |

---

## 3. 业务概念

| 概念 | 说明 |
|------|------|
| **当前店铺** | 登录后 `X-Shop-Id` 标识的店铺；本模块全部操作均限定于此 |
| **店铺商品分类** | 本店自定义的 **两级** 商品分组（一级 + 二级），用于商家内部组织与发品字段 |
| **一级分类** | 分类树根级节点，无上级 |
| **二级分类（子分类）** | 挂在某一一级分类下，**不能再设下级** |
| **分类名称** | 展示名称；**同一店铺、同一上级下** 不可重复 |
| **分类图片** | 分类展示图；添加/编辑 **必填** |
| **排序** | **同层级内** 列表展示顺序；**数值越小越靠前**；默认可为 **0** |
| **是否显示** | **是** / **否**；控制该分类是否在 **需要展示「可见分类」** 的场景中出现 |
| **是否热门** | **是** / **否**；用于 C 端店铺内 **热门分类** 展示位（若前台支持） |
| **关联商品** | 商品档案中 **店铺商品分类** 字段指向该 **二级** 分类的 **未删除** 商品 |

---

## 4. 功能结构

```text
店铺商品分类（店铺 · 商品管理）
├── 分类列表（当前店铺；树形或分级列表展示一级 + 二级）
├── 添加一级分类（名称、图片、排序、是否显示、是否热门）
├── 添加子分类（二级）
├── 编辑分类（一级 / 二级）
└── 删除分类（单独 / 批量；有关联商品则阻断；删一级级联删二级）
```

---

## 5. 分类列表

### 5.1 列表范围

- **纳入：** 当前店铺下全部 **有效** 一级、二级店铺商品分类；
- **排序：** 默认按 **一级分组**；同层内按 **排序值升序**；相同排序值按 **创建时间升序**；
- **展示：** 二级宜 **缩进或层级标识** 展示所属一级；
- **上下文：** 展示 **当前店铺名称**（只读）。
- 支持 **单独删除** 与 **批量删除**（勾选多条，见 §9）。

### 5.2 列表字段

| 字段 | 说明 |
|------|------|
| 分类名称 | 一级或二级名称；二级展示所属一级 |
| 分类图片 | 缩略图 |
| 是否显示 | **是** / **否** |
| 是否热门 | **是** / **否** |
| 排序 | 同层排序用（列表可不展示，表单维护） |
| 操作 | **编辑**、**删除**；一级分类额外提供 **添加子分类** |

> **与草稿差异：** 草稿列表仅含名称、是否显示；v1.1 对齐平台分类交互，补充 **图片、热门、两级结构**。

### 5.3 列表操作

| 操作 | 说明 |
|------|------|
| **编辑** | 见 §8 |
| **删除** | 见 §9 |

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

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

---

## 6. 店铺上下文（协作规则，对齐草稿 §3）

```text
商户经营账号 / 员工 ── 登录商家端
            ↓
      解析所属店铺 ID → 写入请求头 X-Shop-Id
      （商户管理员：默认该商户最先创建的店铺；
       多店时可切换店铺，更新 header）
            ↓
      店铺商品分类等模块按 X-Shop-Id 读写当前店铺数据
```

| 规则 | 说明 |
|------|------|
| 未选店铺 | 访问本模块接口 **拒绝**；提示 **请先选择当前店铺** |
| 切换店铺 | 列表与 CRUD **立即** 切换为新店数据；**不可** 跨店操作 |
| 员工账号 | 须为当前商户有效绑定；店铺 ID 须 **属于** 当前商户 |

---

## 7. 添加分类

### 7.1 结构规则

| 规则 | 说明 |
|------|------|
| SC2-1 | 仅支持 **两级**：一级、二级，**禁止三级及以上** |
| SC2-2 | 添加一级：上级为空（顶级） |
| SC2-3 | 添加二级：上级 **必须** 选择本店某一 **一级分类** |
| SC2-4 | 同一店铺、**同一上级下**，分类名称 **不可重复** |

### 7.2 添加一级分类

| 字段 | 必填 | 规则 |
|------|:----:|------|
| 分类名称 | 是 | 非空；本店 **一级** 名称不可重复 |
| 分类图片 | 是 | 符合平台图片格式与大小 |
| 排序 | 是 | 非负整数；默认 **0** |
| 是否显示 | 是 | 默认 **是** |
| 是否热门 | 是 | 默认 **否** |

### 7.3 添加子分类（二级）

**入口：** 列表行 **「添加子分类」**（仅一级行）；或添加时上级选择某一一级。

| 字段 | 必填 | 规则 |
|------|:----:|------|
| 上级分类 | 是 | 必选本店 **一级** 分类 |
| 分类名称 | 是 | 非空；在 **同一一级下** 不可重复 |
| 分类图片 | 是 | 同 §7.2 |
| 排序 | 是 | 非负整数；默认 **0** |
| 是否显示 | 是 | 默认 **是** |
| 是否热门 | 是 | 默认 **否** |

### 7.4 添加流程

```text
店铺管理员进入「店铺商品分类」（已携带 X-Shop-Id）
    → 点击「添加分类」或某一级行「添加子分类」
    → 填写名称、图片、排序、是否显示、是否热门（二级须选上级）
    → 校验（名称非空、同级唯一、排序合法、图片已传）
    → 保存成功 → 列表刷新
    → 二级分类可在「商品列表 · 添加商品」的「店铺商品分类」中被选用
```

---

## 8. 编辑分类

### 8.1 可编辑字段

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

### 8.2 编辑约束

- **仅当前店铺** 下分类可编辑；他店分类 **不可** 操作；
- 名称唯一性：**同级** 内校验，**排除自身**；
- 修改名称、图片、显示、热门、排序 **不自动** 改变已关联商品的 **上下架/审核状态**（与平台分类 G8 原则一致）；
- 将 **是否显示** 改为 **否**：**不自动** 下架已关联商品；仅影响依赖「可见分类」的 **展示/下拉** 行为。

---

## 9. 删除分类

### 9.1 删除方式

- **单独删除**：行操作删除；
- **批量删除**：勾选多条后批量删除；**任一条不通过则整批失败**，不删除任何一条，并 **汇总提示** 失败原因。

### 9.2 删除一级分类

```text
删除一级分类
    → 校验该一级下 **全部二级** 是否存在「已关联商品」
    ├── 任二级有商品 → 阻断
    └── 均无商品 → 二次确认：「将同时删除其下全部二级分类，是否继续？」
            ├── 取消 → 结束
            └── 确认 → 逻辑删除该一级及下属全部二级
```

### 9.3 删除二级分类

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

### 9.4 关联商品校验

| 场景 | 规则 |
|------|------|
| 何谓「有关联商品」 | 存在 **未删除** 且 **店铺商品分类** 指向该 **二级** 的商品 |
| 删除二级 | 该二级有关联商品 → **禁止删除** |
| 删除一级 | **任一下属二级** 有关联商品 → **禁止删除** |
| 批量删除 | 对每条选中记录分别校验；**整批失败** |

### 9.5 规则汇总

| 项 | 规则 |
|----|------|
| 可删对象 | **当前店铺** 下、**无关联商品** 的分类（删一级须子级均无商品） |
| 删除方式 | **逻辑删除**；列表不再展示 |
| 确认 | **二次确认**；删一级须 **级联提示** |

### 9.6 删除后影响

- 商品列表 **不可再选** 该分类；
- 已关联商品须 **先改分类** 或 **删除/处理商品** 后，方可删除本分类；
- 历史订单等 **不** 在本模块追溯修改。

---

### 10.1 商品列表（商家端 · 下游）

```text
添加/编辑商品（待上架、已下架、审核失败等可编辑态）
    → 「店铺商品分类」下拉（**仅二级**；展示「一级 > 二级」）
    → 仅列当前店铺有效 **二级** 分类
    → 保存后商品档案记录所选分类
    → 本模块删除前须确认无商品引用
```

| 场景 | 行为 |
|------|------|
| 分类被删 | 商品侧该字段 **失效**；须商家重新编辑商品 |
| 分类改名 | 商品 **仍关联** 同一分类 ID；列表展示新名称 |
| 分类隐藏 | **不自动** 改商品状态 |

### 10.2 C 端（间接）

| 项 | 定稿 |
|----|------|
| 本模块职责 | **不** 定义 C 端页面；若前台按店铺商品分类导航，则 **是否显示 = 是** 的分类 **可参与** 展示 |
| 店铺停业 | C 端 **禁止下单**；分类数据 **保留**，与《店铺管理》一致 |
| 可售条件 | C 端下单仍受 **商品状态、店铺开业、库存** 等约束（《关联需求分析》§11）；**店铺商品分类显示与否不单独作为下单硬条件**（除非商品/C 端专册另行规定） |

---

## 11. 业务流程总览

### 11.1 端到端协作

```text
【平台】店铺管理 ── 开店
            ↓
【商家】登录 → X-Shop-Id → 店铺商品分类 ── 添加一级 → 添加二级
            ↓
【商家】商品列表 ── 发品时选择店铺商品分类
            ↓
【平台】商品管理 ── 监管、检索（只读）
```

### 11.2 单模块内主流程

```text
列表浏览 ──┬── （可选）按名称检索
           ├── 添加一级 / 添加子分类
           ├── 编辑分类
           └── 删除（单独 / 批量；无商品关联）
```

---

## 12. 校验与提示

| 场景 | 提示要点 |
|------|----------|
| 未选店铺 | 请先选择当前店铺 |
| 同级名称重复 | 同级分类名称已存在 |
| 名称为空 | 请输入分类名称 |
| 图片为空 | 请上传分类图片 |
| 二级上级无效 | 二级分类的上级必须是一级分类 |
| 删除有商品 | 该分类下存在商品，请先修改商品分类或处理商品 |
| 批量删失败 | 部分分类不满足删除条件，整批操作已取消 |
| 跨店操作 | 分类不存在 / 无权限 |
| 响应格式 | 统一 **code、msg、data**（草稿 §7） |

---

## 13. 业务规则汇总

| 编号 | 规则 |
|------|------|
| SC1 | 列表 = **当前店铺**（`X-Shop-Id`）下全部 **有效** 一级、二级店铺商品分类 |
| SC2 | 分类为 **两级** 结构（一级 + 二级；与平台 **商品分类** **数据隔离**、**层级规则一致**） |
| SC3 | **同店铺、同上级下** 分类名称 **不可重复** |
| SC4 | 添加/编辑须填写 **名称、图片、排序、是否显示、是否热门**；二级须指定 **一级上级** |
| SC5 | 排序 **越小越靠前**（同层内）；默认 0 |
| SC6 | **有关联未删除商品** 的 **二级** 分类 **不可删除**；删 **一级** 须 **全部下属二级** 均无商品 |
| SC7 | 修改显示/热门/排序/名称 **不自动** 改变商品上下架状态 |
| SC8 | 平台 **不** 维护本模块数据；店间分类 **相互独立** |
| SC9 | 须 **切换当前店铺** 后再操作；切换后数据范围随之变化 |
| SC10 | 为 **商品列表 · 店铺商品分类** 字段提供 **二级** 数据源 |
| SC11 | 响应格式：**code、msg、data** |
| SC12 | 商品 **仅挂本店店铺商品二级**；一级 **不直接** 挂商品 |
| SC13 | 删除支持 **批量**；**整批失败** 策略 |

---

## 14. 修订记录

| 版本 | 说明 |
|------|------|
| **v1.0** | 首版定稿：对齐草稿 §1～§7；关联平台《关联需求分析》《商品分类》《店铺管理》及商品列表草稿 |
| **v1.1** | **两级结构**：一级 + 二级；商品仅挂二级；级联删除与批量删除；对齐当前实现（`biz_goods_category`，`shop_id` 非空） |

---

*文档版本：v1.1 · 关联《店铺商品分类功能需求-草稿》· 平台侧见《关联需求分析.md》《商品分类功能需求.md》《店铺管理功能需求.md》*
