会员管理代码

doc/消费者APP/商品分类/商品分类功能需求.md

@@ -0,0 +1,496 @@
+# 商品分类 — 功能需求说明（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》保持不变。*

doc/消费者APP/商品分类/商品分类技术方案.md

@@ -0,0 +1,372 @@
+# 商品分类 — 技术方案（C 端）
+
+> **依据：** 《商品分类功能需求.md》v1.0.1  
+> **关联：** 平台《商品分类技术方案.md》v1.2、《商品管理技术方案.md》v1.3、《店铺管理技术方案.md》v1.2.6、《商城首页技术方案.md》v1.1、《关联需求分析.md》v1.6  
+> **范围：** C 端 **`/api/category/**`** 只读（全部分类树、一级下二级 Tab、二级下商品分页列表）；**无** 平台/店铺分类 CRUD、**无** 搜索执行、**无** 新建业务主表。  
+> **原则：** **无新建表**；复用 `biz_goods_category`、`biz_goods`、`biz_shop`；全部 **`@Anonymous`**；搜索栏 **无接口**（GC-S1）。
+
+---
+
+## 1. 技术架构
+
+| 项 | 选型 |
+|----|------|
+| 基础框架 | RuoYi **v3.9.2**（`springboot2` 分支） |
+| 数据库 | **MySQL 5.7.39** |
+| ORM / 响应 | MyBatis；分类树 `AjaxResult`；商品列表 `TableDataInfo`（分页） |
+| 鉴权 | C 端 **`@Anonymous`**（访客/会员均可读） |
+| 分页 | RuoYi **`PageHelper`** + `startPage()`（`/goods`） |
+| 缓存 | **本期不做** Redis；读库即时生效 |
+
+### 1.1 模块落位
+
+```text
+baqing-shop/src/main/java/com/ruoyi/web/modules/home/
+├── controller/CategoryAppController.java     # /api/category/**
+├── service/ICategoryAppService.java
+├── service/impl/CategoryAppServiceImpl.java
+├── mapper/CategoryAppMapper.java             # 二级 Tab、分类商品 SQL
+├── dto/CategoryGoodsQuery.java
+├── constant/CategoryAppConstants.java        # sortBy 枚举值
+└── vo/HomeHotGoodsVO.java                    # 商品卡片（与首页热销共用）
+
+已有（category 模块 · Facade）：
+└── com.ruoyi.web.modules.category.facade.ICategoryFacade
+        listVisibleByShopId(null)               # 平台可见分类树（A 页 / tree）
+        isCategoryVisible(categoryId)         # 二级校验（/goods）
+
+已有（home 模块 · 首页一级导航，勿混用）：
+└── HomeAppController GET /api/home/categories
+        仅一级扁平列表，供首页横向导航；**不含** children
+
+resources/mapper/home/
+└── CategoryAppMapper.xml
+```
+
+> **说明：** C 端分类与 C 端首页 **同属 `home` 包**、**不同基路径**（`/api/category` vs `/api/home`）。平台分类 CRUD 仍在 `/agri/category`（`PlatformCategoryController`）。
+
+### 1.2 协作链
+
+```text
+biz_goods_category（shop_id IS NULL）
+    ├── GET /api/category/tree              → A 页 · 一级+二级树
+    ├── GET /api/category/{level1Id}/level2-tabs → B 页 · 二级 Tab
+    └── （校验）isCategoryVisible
+
+biz_goods + biz_shop
+    └── GET /api/category/goods?categoryId=&sortBy=&pageNum=&pageSize=
+            → B 内嵌列表 / C 独立列表（共用）
+
+【页面与接口】
+    首页 HM7 ──一级──► B：level2-tabs + goods（默认首 Tab）
+    首页「更多」──► A：tree ──点二级──► C：goods（同 goods 接口）
+    搜索栏：纯前端 GC-S1（无接口）
+```
+
+| 关联模块 | 协作 |
+|----------|------|
+| **平台 · 商品分类** | 维护 `biz_goods_category`；C 端只读 `show_flag` / 排序 |
+| **商品分类 Facade** | `listVisibleByShopId(null)` 过滤空壳一级、父隐子隐（GC6） |
+| **商城首页** | `/api/home/categories` 一级快捷导航；点击进入本模块 B 页 |
+| **商品 / 审核** | 列表 `goods_status=2`（出售中） |
+| **店铺管理** | JOIN `shop_name` 实时；**不过滤** 停业/库存（GC13） |
+| **会员管理** | **不校验** Token |
+| **商品详情** | 列表点击跳转；可购四条件在详情/Facade 校验（GC12） |
+
+### 1.3 跨模块 Facade
+
+| 接口 | 本模块用法 |
+|------|------------|
+| **`ICategoryFacade.listVisibleByShopId(null)`** | `/tree` 平台全量可见树（含 children） |
+| **`ICategoryFacade.isCategoryVisible`** | `/goods` 校验二级 `categoryId` |
+| **`IPlatformCategoryService`** | **不直接** 暴露 C 端 HTTP |
+| **`IGoodsPurchaseFacade` / 详情** | 本模块 **不调用**；下单层校验 |
+
+---
+
+## 2. 数据库设计
+
+### 2.1 原则
+
+**无新建表。** 只读下列已有表；DDL 见 `sql/`。
+
+| 表 | 本模块用途 | 权威 DDL |
+|----|------------|----------|
+| `biz_goods_category` | 平台一/二级导航 | `sql/biz_goods_category.sql` |
+| `biz_goods` | 二级下商品列表 | `sql/biz_goods.sql` |
+| `biz_shop` | 商品卡片店铺名 | `sql/biz_shop.sql` |
+
+### 2.2 本模块读字段与条件
+
+**`biz_goods_category`** — 平台分类（`shop_id IS NULL`）
+
+| 场景 | 条件 | 输出字段 |
+|------|------|----------|
+| **tree**（Facade 内存组装） | 一级 `show=1` 且下有可见二级；二级 `isCategoryVisible` | `categoryId, categoryName, categoryPic, sortNo, hotFlag` + `children[]` |
+| **level2-tabs** | `level=2`, `parent_id=#{level1Id}`, `show=1`, `del=0`；且一级可见 | 同上（无 children） |
+
+**`biz_goods` + `biz_shop`** — 分类商品列表
+
+| 字段 | 条件 / 说明 |
+|------|-------------|
+| g.category_id | **=** 所选二级 ID |
+| g.goods_status | **`2`** 出售中（GC8） |
+| g.del_flag | **`0`** |
+| s.del_flag | **`0`**（JOIN） |
+| g.sales_count, g.sale_price, g.goods_sn | 排序键（GC9） |
+| g.goods_id, g.goods_sn, g.goods_name, g.main_pic, g.sale_price | 输出 |
+| s.shop_id, s.shop_name | JOIN；**实时**（GC10） |
+
+> **浏览层：** SQL **不过滤** `shop_status`、**不过滤** `stock`（GC13）。
+
+### 2.3 与首页 `/api/home/categories` 差异
+
+| 项 | `/api/home/categories` | `/api/category/tree` |
+|----|------------------------|----------------------|
+| 层级 | 仅 **一级** 扁平 | **一级 + 二级** 树 |
+| 空壳一级 | SQL 仅 `show=1`（首页导航宜与 GC6 对齐：无可见二级的不展示） | Facade **排除** 无可见二级的一级 |
+| 用途 | 首页横向导航 +「更多」 | A 全部分类页 |
+
+### 2.4 建议索引（可选）
+
+```sql
+-- 可选：与首页热销共用
+-- idx_category_id on biz_goods(category_id)
+-- idx_shop_status 等现有索引一般够用
+```
+
+---
+
+## 3. C 端接口设计
+
+**基路径：** `/api/category`  
+**鉴权：** 全部 **`@Anonymous`**
+
+### 3.1 接口一览
+
+| 方法 | 路径 | 页面 | 说明 |
+|------|------|------|------|
+| GET | `/tree` | **A** 全部分类 | 平台可见分类树 |
+| GET | `/{level1Id}/level2-tabs` | **B** Tab 区 | 指定一级下二级列表 |
+| GET | `/goods` | **B/C** 商品列表 | 二级下出售中商品 **分页** |
+
+**本期不提供：** 搜索 API、聚合 `/api/category/index`、店铺分类读接口。
+
+### 3.2 可见分类树 `GET /api/category/tree`
+
+| 项 | 说明 |
+|----|------|
+| Query | **无** |
+| 实现 | `ICategoryFacade.listVisibleByShopId(null)` |
+
+**`data`：** `CategoryVisibleVO[]`（`category` 模块已有 VO）
+
+| 字段 | 说明 |
+|------|------|
+| categoryId | 一级 ID |
+| categoryName | 名称 |
+| categoryPic | 图片 |
+| sortNo | 排序 |
+| hotFlag | 是否热门 |
+| children | `CategoryVisibleChildVO[]`（二级） |
+
+**children 元素：** `categoryId, categoryName, categoryPic, sortNo, hotFlag`
+
+**前端（A 页）：** 左列 = `data`；右列 = 当前选中一级的 `children`；点 child → 路由 C 页并带 `categoryId`。
+
+### 3.3 一级下二级 Tab `GET /api/category/{level1Id}/level2-tabs`
+
+| 项 | 说明 |
+|----|------|
+| Path | `level1Id` — 平台一级 ID |
+| 校验 | 一级存在、`shop_id IS NULL`、`level=1`、`show=1`；否则 `ServiceException` |
+
+**`data`：** `CategoryVisibleChildVO[]`（按 `sort_no, create_time` 升序）
+
+**SQL 片段：**
+
+```sql
+SELECT category_id, category_name, category_pic, hot_flag, sort_no
+FROM biz_goods_category
+WHERE shop_id IS NULL
+  AND category_level = '2'
+  AND parent_id = #{level1Id}
+  AND show_flag = '1'
+  AND del_flag = '0'
+ORDER BY sort_no ASC, create_time ASC
+```
+
+**前端（B 页）：** 首页带入 `level1Id` → 本接口渲染 Tab → 默认首 Tab 调 `/goods`；切换 Tab（**C1**）仅改 `categoryId` 重新请求 `/goods`。
+
+### 3.4 分类商品列表 `GET /api/category/goods`
+
+| 项 | 说明 |
+|----|------|
+| Query | 见下表 |
+| 分页 | `pageNum`、`pageSize`（RuoYi 默认） |
+| 响应 | **`TableDataInfo`**：`{ code, msg, rows, total }` |
+
+**Query：**
+
+| 参数 | 必填 | 说明 |
+|------|:----:|------|
+| categoryId | 是 | **平台二级** 分类 ID |
+| sortBy | 否 | 默认 `sales_desc`（`CategoryAppConstants.DEFAULT_SORT`） |
+| pageNum | 否 | 页码 |
+| pageSize | 否 | 每页条数 |
+
+**sortBy 合法值：**
+
+| 值 | 排序 |
+|----|------|
+| `sales_desc` | 销量降序 → `goods_sn` 升序 |
+| `sales_asc` | 销量升序 → `goods_sn` 升序 |
+| `price_desc` | 售价降序 → `goods_sn` 升序 |
+| `price_asc` | 售价升序 → `goods_sn` 升序 |
+
+**校验：**
+
+1. `categoryId` 非空  
+2. `categoryFacade.isCategoryVisible(categoryId)` 为 true，否则「分类不存在或不可见」  
+3. `sortBy` 非法 →「排序参数无效」
+
+**`rows` 元素：** `HomeHotGoodsVO`（与 `/api/home/hot-goods` 同结构）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| goodsId | long | |
+| goodsSn | string | |
+| goodsName | string | |
+| mainPic | string | |
+| salePrice | decimal | |
+| shopId | long | |
+| shopName | string | 实时 |
+
+**SQL 片段：**
+
+```sql
+SELECT g.goods_id, g.goods_sn, g.goods_name, g.main_pic, g.sale_price,
+       s.shop_id, s.shop_name
+FROM biz_goods g
+INNER JOIN biz_shop s ON g.shop_id = s.shop_id AND s.del_flag = '0'
+WHERE g.goods_status = '2'
+  AND g.del_flag = '0'
+  AND g.category_id = #{categoryId}
+ORDER BY
+  -- 动态 sortBy，同键 goods_sn ASC
+```
+
+### 3.5 搜索栏
+
+| 项 | 说明 |
+|----|------|
+| 占位 | 前端写死「搜索兽药、饲料、店铺」（GC3） |
+| 接口 | **无** |
+
+---
+
+## 4. Service 分层
+
+```text
+CategoryAppController
+    → ICategoryAppService.listCategoryTree()
+    → ICategoryAppService.listLevel2Tabs(level1Id)
+    → ICategoryAppService.listCategoryGoods(query)   # 分页由 Controller startPage
+
+CategoryAppServiceImpl
+    → ICategoryFacade.listVisibleByShopId(null)
+    → ICategoryFacade.isCategoryVisible(categoryId)
+    → BizGoodsCategoryMapper.selectById(level1Id, null)   # 一级校验
+    → CategoryAppMapper.selectPlatformLevel2Tabs(level1Id)
+    → CategoryAppMapper.selectGoodsByCategory(categoryId, sortBy)
+```
+
+| 方法 | 说明 |
+|------|------|
+| `listCategoryTree()` | 透传 Facade；`shopId=null` → 平台树 |
+| `listLevel2Tabs()` | 校验一级可见 → Mapper 查二级 |
+| `listCategoryGoods()` | 校验二级可见 + sortBy → Mapper；**不** 校验可购四条件 |
+
+---
+
+## 5. 与平台后台对照
+
+| 平台操作 | 影响的 C 端接口 |
+|----------|-----------------|
+| 平台分类改 show/排序/名称/图 | `/tree`、`/level2-tabs` |
+| 平台分类改 show=0 | 树/Tab 即时隐藏；`/goods` 校验失败 |
+| 商品上下架 | `/goods` 增删行 |
+| 店铺改名 | `/goods` 的 `shopName` |
+| 店铺停业 | **仍出现在** `/goods`；下单在详情拦截 |
+| 会员禁用 | **不影响** 三接口 |
+
+---
+
+## 6. 业务规则映射
+
+| 规则 | 实现 |
+|------|------|
+| GC1 | 仅 `shop_id IS NULL` / Facade 平台树 |
+| GC2 | `@Anonymous` |
+| GC3～GC-S2 | 无搜索 API |
+| GC4 | `/tree` + 前端 A→C 路由 |
+| GC5 | `/level2-tabs` + `/goods`；Tab 切换前端 C1 |
+| GC5a | `/goods` + 前端面包屑（路径非接口字段） |
+| GC6 | Facade `listVisibleByShopId` + `isCategoryVisible` |
+| GC7 | SQL / Facade 排序 |
+| GC8～GC10 | `/goods` SQL + `HomeHotGoodsVO` |
+| GC9 | `sortBy` 四档 + 默认 `sales_desc` |
+| GC12 | Service **不** 调可购 Facade |
+| GC13 | SQL 不过滤店态/库存 |
+| GC14 | 三接口 **独立**；前端模块级空态 |
+| GC15 | 无写接口 |
+
+---
+
+## 7. 前端接口调用建议
+
+| 页面 | 调用顺序 |
+|------|----------|
+| **A** 全部分类 | `GET /tree` → 点二级 → `GET /goods?categoryId=` |
+| **B** 一级分类 | `GET /{level1Id}/level2-tabs` → `GET /goods?categoryId=首Tab` → 切换 Tab 仅重调 `/goods` |
+| **C** 独立列表 | `GET /goods?categoryId=`（`level1Id` 由路由/状态展示面包屑） |
+
+> **C1：** Tab 切换时前端 **列表回顶** 后再请求 `/goods`（产品层，非后端字段）。
+
+---
+
+## 8. 实现状态
+
+| 项 | 状态 |
+|----|------|
+| `GET /api/category/tree` | **待实现** |
+| `GET /api/category/{level1Id}/level2-tabs` | **待实现** |
+| `GET /api/category/goods` | **待实现** |
+| `CategoryAppController` / `CategoryAppServiceImpl` | **待创建** |
+| `CategoryAppMapper.xml` | **待创建** |
+| C 端分类前端 | **未实现** |
+
+---
+
+## 9. 非本期
+
+| 项 | 说明 |
+|------|------|
+| `GET /api/category/index` 聚合 | 前端分调三接口即可 |
+| Redis 缓存 | — |
+| `/api/search/**` | 搜索模块 |
+| 店铺商品分类 C 端读 | GC1 排除 |
+| 列表返回销量/库存字段 | GC10 卡片不展示 |
+| 商品详情 API | 商品详情模块 |
+
+---
+
+## 10. 修订记录
+
+| 版本 | 说明 |
+|------|------|
+| **v1.0** | 首版；无新建表；`/api/category` 三读接口；关联平台分类 Facade、商城首页 v1.1 |
+
+---
+
+*文档版本：v1.0 · MySQL 5.7.39 · RuoYi v3.9.2-springboot2 · 关联《商品分类功能需求.md》v1.0.1、《商品分类技术方案.md》v1.2（平台）、《商城首页技术方案.md》v1.1*

doc/消费者APP/商品分类/商品分类测试用例.md

@@ -0,0 +1,774 @@
+# 商品分类 — 测试用例（C 端）
+
+> **依据：** 《商品分类功能需求.md》v1.0.1、《商品分类技术方案.md》v1.0  
+> **关联：** 平台《商品分类测试用例.md》CAT-UT-013/014（同源 `isCategoryVisible`）、C 端《商城首页测试用例.md》MHP-UI-008/009（HM7 入口）、《关联需求分析.md》§11  
+> **范围：** C 端 `/api/category/tree`、`/api/category/{level1Id}/level2-tabs`、`/api/category/goods`；`CategoryAppServiceImpl` / `CategoryAppController`  
+> **代码落位：** `baqing-shop/src/main/java/com/ruoyi/web/modules/home/`  
+> **排除：** 搜索执行与结果页、商品详情可购四条件校验、平台/店铺分类 CRUD、店铺商品分类 C 端导航、聚合 `/api/category/index`  
+> **环境：** RuoYi v3.9.2-springboot2；MySQL 5.7.39；C 端 **无需 Token**（`@Anonymous`）；UI 使用 Playwright **`channel: 'chrome'`**
+
+---
+
+## 用例编号说明
+
+| 前缀 | 类型 | 工具 |
+|------|------|------|
+| CGC-UT-xxx | 单元测试 | JUnit 5 + Mockito |
+| CGC-API-xxx | 接口测试 | MockMvc / Apifox |
+| CGC-UI-xxx | 界面测试 | Playwright（Google Chrome） |
+
+> **命名：** **CGC** = Consumer Goods Category（C 端商品分类）；与平台 **CAT-** 区分。
+
+---
+
+## 测试数据约定
+
+| 实体 | 说明 |
+|------|------|
+| 平台一级 | L1-A「兽药」show=1 sort=0；L1-B「饲料」show=1 sort=1；L1-H **隐藏** show=0；L1-E **空壳**（无可见二级）；L1-S 店铺101一级（**不应出现**） |
+| 平台二级 | L1-A 下 L2-A1「抗生素」、L2-A2「驱虫药」show=1；L2-H **隐藏** show=0；L2-P 父级 L1-H（**不可见**） |
+| 店铺 | S101 开业；S102 **停业**；S103 已删 |
+| 出售中商品 | G-A1@L2-A1 销量100 价88；G-A2 销量100 价99（同销量测排序）；G-A3 销量50；G-B1@S102 停业；G-Z1 stock=0；G-O1 已下架/待审核（**不进列表**） |
+| 会员 | M1 正常；M2 **禁用**（分类仍可读） |
+
+---
+
+## 一、单元测试
+
+### CGC-UT-001 分类树委托平台 Facade
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-001 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | listCategoryTree |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证 GC1、GC6 |
+| **前置条件** | Mock `ICategoryFacade.listVisibleByShopId(null)` 返回含 L1-A 树 |
+| **测试步骤** | 调用 `listCategoryTree()` |
+| **预期结果** | 调用 `listVisibleByShopId(null)`；返回与 Facade 一致 |
+
+### CGC-UT-002 分类树空列表
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-002 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | listCategoryTree 空态 |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证 §5.3 边界 |
+| **前置条件** | Facade 返回 empty |
+| **测试步骤** | `listCategoryTree()` |
+| **预期结果** | 空 List；**不** 抛异常 |
+
+### CGC-UT-003 二级 Tab 一级可见时返回
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-003 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | listLevel2Tabs |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证 GC5、GC7 |
+| **前置条件** | L1-A 一级 show=1；Mapper 返回 L2-A1、L2-A2 |
+| **测试步骤** | `listLevel2Tabs(L1-A.id)` |
+| **预期结果** | 返回 2 条二级；顺序与 Mapper 一致 |
+
+### CGC-UT-004 二级 Tab 一级隐藏拒绝
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-004 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | listLevel2Tabs 校验 |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证 GC6 |
+| **前置条件** | L1-H show=0 |
+| **测试步骤** | `listLevel2Tabs(L1-H.id)` |
+| **预期结果** | 抛 `ServiceException`；msg 含「不可见」或「不存在」 |
+
+### CGC-UT-005 商品列表缺 categoryId
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-005 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | listCategoryGoods 必填 |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证 §3.4 校验 |
+| **前置条件** | query.categoryId 为空 |
+| **测试步骤** | `listCategoryGoods(query)` |
+| **预期结果** | 抛 `ServiceException`；「请选择商品分类」类提示 |
+
+### CGC-UT-006 商品列表分类不可见拒绝
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-006 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | isCategoryVisible |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证 GC6 |
+| **前置条件** | `isCategoryVisible(L2-H)=false` |
+| **测试步骤** | `listCategoryGoods({categoryId:L2-H})` |
+| **预期结果** | 抛 `ServiceException`；「分类不存在或不可见」 |
+
+### CGC-UT-007 商品列表默认销量降序
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-007 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | sortBy 默认 |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证 GC9 |
+| **前置条件** | L2-A1 可见；sortBy 未传 |
+| **测试步骤** | `listCategoryGoods(query)` |
+| **预期结果** | Mapper 调用 `sortBy=sales_desc` |
+
+### CGC-UT-008 商品列表价格升序排序
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-008 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | sortBy price_asc |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证 GC9 |
+| **前置条件** | query.sortBy=`price_asc` |
+| **测试步骤** | `listCategoryGoods(query)` |
+| **预期结果** | Mapper 入参 `price_asc` |
+
+### CGC-UT-009 非法 sortBy 拒绝
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-009 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | sortBy 校验 |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证 §3.4 |
+| **前置条件** | sortBy=`invalid`；分类可见 |
+| **测试步骤** | `listCategoryGoods(query)` |
+| **预期结果** | 抛 `ServiceException`；「排序参数无效」 |
+
+### CGC-UT-010 商品列表透传 Mapper 顺序
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-010 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 列表顺序 |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证 GC8 |
+| **前置条件** | Mapper 返回 G-A1 在 G-A3 前 |
+| **测试步骤** | `listCategoryGoods(query)` |
+| **预期结果** | 结果顺序与 Mapper 一致 |
+
+### CGC-UT-011 商品列表零条
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-011 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 列表空态 |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证 §7.4 |
+| **前置条件** | Mapper 返回 empty |
+| **测试步骤** | `listCategoryGoods(query)` |
+| **预期结果** | 空 List |
+
+### CGC-UT-012 Facade null 树返回空
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UT-012 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | listCategoryTree null |
+| **测试类型** | 单元测试 |
+| **测试工具** | JUnit 5 + Mockito |
+| **测试目的** | 验证健壮性 |
+| **前置条件** | Facade 返回 null |
+| **测试步骤** | `listCategoryTree()` |
+| **预期结果** | 空 List；**不** NPE |
+
+---
+
+## 二、接口测试
+
+### CGC-API-001 分类树无需 Token
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-001 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | GET /tree 匿名 |
+| **测试类型** | 接口测试 |
+| **测试工具** | MockMvc / Apifox |
+| **测试目的** | 验证 GC2 |
+| **前置条件** | 不传 Authorization |
+| **测试步骤** | GET `/api/category/tree` |
+| **预期结果** | `code=200`；`data` 为数组 |
+
+### CGC-API-002 分类树含 children 契约
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-002 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | tree VO |
+| **测试类型** | 接口测试 |
+| **测试工具** | MockMvc |
+| **测试目的** | 验证 §3.2 |
+| **前置条件** | 存在 L1-A 含 L2-A1 |
+| **测试步骤** | GET `/tree` |
+| **预期结果** | 含 `categoryId/categoryName/children`；child 含 `categoryId/categoryName` |
+
+### CGC-API-003 分类树不含 show=0 一级
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-003 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | tree 过滤 |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 GC6 |
+| **前置条件** | 库中 L1-H show=0 |
+| **测试步骤** | GET `/tree` |
+| **预期结果** | **不含** L1-H |
+
+### CGC-API-004 分类树不含空壳一级
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-004 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 空壳一级 |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 GC6、§4.2 |
+| **前置条件** | L1-E show=1 但无可见二级 |
+| **测试步骤** | GET `/tree` |
+| **预期结果** | **不含** L1-E |
+
+### CGC-API-005 分类树不含店铺分类
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-005 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 平台隔离 |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 GC1 |
+| **前置条件** | 存在 L1-S（shop_id=101） |
+| **测试步骤** | GET `/tree` |
+| **预期结果** | **不含** L1-S |
+
+### CGC-API-006 二级 Tab 正常返回
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-006 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | GET level2-tabs |
+| **测试类型** | 接口测试 |
+| **测试工具** | MockMvc |
+| **测试目的** | 验证 GC5 |
+| **前置条件** | L1-A 可见；下有 L2-A1、L2-A2 |
+| **测试步骤** | GET `/api/category/{L1-A}/level2-tabs` |
+| **预期结果** | `code=200`；`data.length=2` |
+
+### CGC-API-007 二级 Tab 排序升序
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-007 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | Tab sort_no |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 GC7 |
+| **前置条件** | L2-A1 sort=0；L2-A2 sort=1 |
+| **测试步骤** | GET level2-tabs |
+| **预期结果** | 第一条 `categoryId=L2-A1` |
+
+### CGC-API-008 二级 Tab 一级不存在
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-008 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | level1 校验 |
+| **测试类型** | 接口测试 |
+| **测试工具** | MockMvc |
+| **测试目的** | 验证 §3.3 |
+| **前置条件** | level1Id=99999 |
+| **测试步骤** | GET `/api/category/99999/level2-tabs` |
+| **预期结果** | 业务失败；提示分类不存在/不可见 |
+
+### CGC-API-009 二级 Tab 一级隐藏
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-009 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | level1 show=0 |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 GC6 |
+| **前置条件** | L1-H show=0 |
+| **测试步骤** | GET `/api/category/{L1-H}/level2-tabs` |
+| **预期结果** | 业务失败 |
+
+### CGC-API-010 商品列表分页成功
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-010 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | GET /goods |
+| **测试类型** | 接口测试 |
+| **测试工具** | MockMvc |
+| **测试目的** | 验证 §3.4 |
+| **前置条件** | L2-A1 可见；≥1 出售中商品 |
+| **测试步骤** | GET `/api/category/goods?categoryId=&pageNum=1&pageSize=10` |
+| **预期结果** | `code=200`；含 `rows`、`total` |
+
+### CGC-API-011 商品列表字段契约
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-011 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | goods VO |
+| **测试类型** | 接口测试 |
+| **测试工具** | MockMvc |
+| **测试目的** | 验证 GC10 |
+| **前置条件** | G-A1 出售中 |
+| **测试步骤** | GET `/goods?categoryId=L2-A1` |
+| **预期结果** | row 含 `goodsId/goodsName/mainPic/salePrice/shopId/shopName` |
+
+### CGC-API-012 商品列表缺 categoryId
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-012 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | categoryId 必填 |
+| **测试类型** | 接口测试 |
+| **测试工具** | MockMvc |
+| **测试目的** | 验证 §3.4 |
+| **前置条件** | — |
+| **测试步骤** | GET `/api/category/goods` |
+| **预期结果** | 业务失败 |
+
+### CGC-API-013 商品列表分类不可见
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-013 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 隐藏二级 |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 GC6 |
+| **前置条件** | L2-H show=0 |
+| **测试步骤** | GET `/goods?categoryId=L2-H` |
+| **预期结果** | 业务失败；「分类不存在或不可见」 |
+
+### CGC-API-014 商品列表默认销量降序
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-014 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 默认排序 |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 GC9 |
+| **前置条件** | G-A1 销量100；G-A3 销量50 |
+| **测试步骤** | GET `/goods?categoryId=L2-A1`（无 sortBy） |
+| **预期结果** | 首条 `goodsId=G-A1` |
+
+### CGC-API-015 商品列表价格升序
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-015 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | sortBy price_asc |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 GC9 |
+| **前置条件** | G-A1 价88；G-A2 价99 |
+| **测试步骤** | GET `/goods?categoryId=L2-A1&sortBy=price_asc` |
+| **预期结果** | 首条价 **更低** 的商品 |
+
+### CGC-API-016 商品列表非法 sortBy
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-016 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | sortBy 校验 |
+| **测试类型** | 接口测试 |
+| **测试工具** | MockMvc |
+| **测试目的** | 验证 §3.4 |
+| **前置条件** | L2-A1 可见 |
+| **测试步骤** | GET `/goods?categoryId=L2-A1&sortBy=foo` |
+| **预期结果** | 业务失败；「排序参数无效」 |
+
+### CGC-API-017 商品列表仅出售中
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-017 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | goods_status |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 GC8 |
+| **前置条件** | G-O1 已下架同分类 |
+| **测试步骤** | GET `/goods?categoryId=L2-A1` |
+| **预期结果** | **不含** G-O1 |
+
+### CGC-API-018 商品列表含停业店商品
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-018 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 浏览层店态 |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 GC13 |
+| **前置条件** | G-B1@S102 停业、出售中 |
+| **测试步骤** | GET `/goods?categoryId=对应二级` |
+| **预期结果** | **含** G-B1 |
+
+### CGC-API-019 禁用会员仍可读
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-019 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 会员禁用 |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 GC2 |
+| **前置条件** | M2 禁用 Token |
+| **测试步骤** | 带 Token 调 `/tree`、`/goods` |
+| **预期结果** | 均 `code=200` |
+
+### CGC-API-020 平台改 show 后 goods 拒绝
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-API-020 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 分类联动 |
+| **测试类型** | 接口测试 |
+| **测试工具** | Apifox |
+| **测试目的** | 验证 §10 |
+| **前置条件** | 平台将 L2-A1 show 改为 0 |
+| **测试步骤** | GET `/goods?categoryId=L2-A1` |
+| **预期结果** | 业务失败 |
+
+---
+
+## 三、界面测试（Playwright · Chrome）
+
+> **路由建议：** A `/#/mall/category/all`；B `/#/mall/category/l1/{id}`；C `/#/mall/category/goods?categoryId=`（以实际为准）
+
+### CGC-UI-001 首页点一级进 B 页
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-001 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | HM7 入口 B |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC5、HM7 |
+| **前置条件** | 首页已加载；存在 L1-A |
+| **测试步骤** | 点击首页一级「兽药」 |
+| **预期结果** | 进入 B 页；可见二级 Tab 与商品列表区 |
+
+### CGC-UI-002 首页点更多进 A 页
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-002 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | HM7 入口 A |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC4 |
+| **前置条件** | 首页已加载 |
+| **测试步骤** | 点击类目区「更多」 |
+| **预期结果** | 进入 A 全部分类页；左右分栏可见 |
+
+### CGC-UI-003 A 页左切一级联动右侧
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-003 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | A 页联动 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC4、§5.1 |
+| **前置条件** | A 页已打开；有 L1-A、L1-B |
+| **测试步骤** | 点击左侧 L1-B |
+| **预期结果** | 右侧刷新为 L1-B 下二级列表；**不跳转** 新页 |
+
+### CGC-UI-004 A 页点二级进 C 独立页
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-004 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | A1 跳转 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC4、GC5a |
+| **前置条件** | A 页右侧有 L2-A1 |
+| **测试步骤** | 点击「抗生素」 |
+| **预期结果** | 进入 **C 独立列表页**；**无** Tab；可见路径「兽药 > 抗生素」 |
+
+### CGC-UI-005 B 页默认选中首 Tab
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-005 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 默认 Tab |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 §6.1 |
+| **前置条件** | 从首页进入 L1-A |
+| **测试步骤** | 观察 Tab 与列表 |
+| **预期结果** | **排序最靠前** 的二级 Tab 高亮；列表对应该 Tab |
+
+### CGC-UI-006 B 页切换 Tab 列表回顶
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-006 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | C1 回顶 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC5、C1 |
+| **前置条件** | B 页列表已下滚 |
+| **测试步骤** | 点击另一二级 Tab |
+| **预期结果** | 列表 **回顶**；展示新 Tab 商品 |
+
+### CGC-UI-007 搜索栏占位文案
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-007 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 搜索占位 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC3 |
+| **前置条件** | 打开 A 或 B 或 C 页 |
+| **测试步骤** | 读取搜索框 placeholder |
+| **预期结果** | **「搜索兽药、饲料、店铺」** |
+
+### CGC-UI-008 点击搜索栏进搜索页
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-008 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 搜索入口 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC-S1 |
+| **前置条件** | 分类页已加载 |
+| **测试步骤** | 点击搜索栏 |
+| **预期结果** | 路由至搜索输入页 |
+
+### CGC-UI-009 C 页含搜索栏无 Tab
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-009 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | C 页结构 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC5a |
+| **前置条件** | 从 A 进入 C 页 |
+| **测试步骤** | 检查页顶结构 |
+| **预期结果** | 有搜索栏+路径标题；**无** 二级 Tab |
+
+### CGC-UI-010 商品卡片字段展示
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-010 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 列表卡片 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC10 |
+| **前置条件** | 列表有 G-A1 |
+| **测试步骤** | 检查首卡 |
+| **预期结果** | 可见主图、名称、售价、店铺名；**不** 展示销量数字 |
+
+### CGC-UI-011 切换销量价格排序
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-011 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 排序 UI |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC9、§7.3 |
+| **前置条件** | 列表 ≥2 条不同价/销量 |
+| **测试步骤** | ① 选「价格升序」② 选「销量降序」 |
+| **预期结果** | 列表顺序 **随之变化** |
+
+### CGC-UI-012 点击商品进详情
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-012 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 进详情 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC11 |
+| **前置条件** | 列表有商品 |
+| **测试步骤** | 点击商品卡片 |
+| **预期结果** | 进入商品详情；URL 含 `goodsId` |
+
+### CGC-UI-013 访客与会员均可浏览
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-013 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 访客/会员 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC2 |
+| **前置条件** | ① 未登录 ② M1 登录 |
+| **测试步骤** | 分别打开 A/B 页 |
+| **预期结果** | 均可见分类与列表 |
+
+### CGC-UI-014 零商品空态
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-014 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | 列表空态 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 §7.4 |
+| **前置条件** | 某二级无出售中商品 |
+| **测试步骤** | 打开该二级列表 |
+| **预期结果** | 空态文案（如「该分类下暂无商品」） |
+
+### CGC-UI-015 分类树失败不白屏
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-015 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | tree 失败 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC14 |
+| **前置条件** | Mock `/tree` 500 |
+| **测试步骤** | 打开 A 页 |
+| **预期结果** | 空态/错误提示；**不** 整页白屏 |
+
+### CGC-UI-016 商品列表失败空态
+
+| 要素 | 内容 |
+|------|------|
+| **用例编号** | CGC-UI-016 |
+| **测试模块** | C 端商品分类 |
+| **测试项** | goods 失败 |
+| **测试类型** | 界面测试 |
+| **测试工具** | Playwright（Chrome） |
+| **测试目的** | 验证 GC14、§7.6 |
+| **前置条件** | Mock `/goods` 失败；Tab 仍可见 |
+| **测试步骤** | 打开 B 页 |
+| **预期结果** | 列表区空态；Tab 区 **仍展示** |
+
+---
+
+## 四、业务规则覆盖矩阵
+
+| 规则 | UT | API | UI |
+|------|:--:|:---:|:--:|
+| GC1 仅平台分类 | — | API-005 | — |
+| GC2 匿名可读 | — | API-001/019 | UI-013 |
+| GC3 搜索占位 | — | — | UI-007 |
+| GC4 A 页/A→C | UT-003 | API-002 | UI-002/003/004 |
+| GC5 B Tab+列表 | UT-003 | API-006/007 | UI-001/005/006 |
+| GC5a C 独立页 | — | — | UI-004/009 |
+| GC6 可见性 | UT-004/006 | API-003/004/008/009/013/020 | — |
+| GC7 排序 | — | API-007 | — |
+| GC8 出售中 | UT-010 | API-017 | — |
+| GC9 四档排序 | UT-007/008/009 | API-014/015/016 | UI-011 |
+| GC10 卡片字段 | — | API-011 | UI-010 |
+| GC11 进详情 | — | — | UI-012 |
+| GC12 展示≠可购 | — | — | — |
+| GC13 停业/零库存 | — | API-018 | — |
+| GC14 模块空态 | UT-011/012 | — | UI-015/016 |
+| GC15 无写接口 | — | — | — |
+
+---
+
+## 五、自动化映射
+
+| 用例 | 建议代码位置 |
+|------|--------------|
+| CGC-UT-001～012 | `CategoryAppServiceImplTest.java` |
+| CGC-API-001～020 | `CategoryAppControllerTest.java` |
+| CGC-UI-001～016 | `e2e/consumer/category.spec.ts`（Playwright `channel: 'chrome'`） |
+
+---
+
+## 六、用例统计
+
+| 类型 | 数量 |
+|------|------|
+| 单元测试 CGC-UT | 12 |
+| 接口测试 CGC-API | 20 |
+| 界面测试 CGC-UI | 16 |
+| **合计** | **48** |
+
+---
+
+## 七、修订记录
+
+| 版本 | 说明 |
+|------|------|
+| **v1.0** | 首版；48 用例；覆盖 GC1～GC15、A/B/C 三页、四档排序、HM7 入口 |
+
+---
+
+*文档版本：v1.0 · 关联《商品分类功能需求.md》v1.0.1、《商品分类技术方案.md》v1.0*