会员管理代码

doc/店铺后台/商品管理/商品列表/商品列表功能需求.md

@@ -0,0 +1,667 @@
+# 店铺商品列表 — 功能需求说明
+
+> 本文档在《商品列表功能需求-草稿》基础上整理，并关联 **《关联需求分析.md》**、平台侧 **《商品审核功能需求》**、**《商品分类功能需求》**、**《商品服务管理功能需求》**、**《店铺管理功能需求》** 及商家侧 **《店铺商品分类功能需求》** 做边界与流程对齐。  
+> 范围：**店铺经营管理端 · 商品管理** 对 **当前店铺下商品** 的列表、检索、发品、编辑、提交上架、下架与删除。  
+> **说明：** 本文档 **仅描述功能需求与业务规则**；不涉及数据库结构、接口定义及技术实现细节。  
+> **v1.0：** 首版定稿；对齐草稿 §1～§7；补全五态状态机、店铺上下文、与平台审核/分类/服务的协作链。
+
+---
+
+## 1. 模块定位
+
+### 1.1 业务目标
+
+在农资商城 **店铺经营管理端（Web）· 商品管理** 提供 **商品列表** 能力，使 **店铺管理员**（商户经营账号及已授权子管理员）能够：
+
+- 浏览 **当前店铺** 下全部商品；
+- **添加、编辑** 商品资料；
+- **提交上架**、**下架**、**删除** 商品（单独 / 批量）；
+- 按编号、名称、分类等 **检索** 商品；
+- 查看各状态商品的 **详情** 及平台 **驳回原因**。
+
+**不包含（本期或与它模块分工）：**
+
+| 能力 | 说明 |
+|------|------|
+| **平台 · 商品审核** | 见平台 **商品审核**；平台对待审核商品通过/驳回、对出售中商品下架 |
+| **平台 · 商品分类 / 服务目录维护** | 见平台 **商品分类**、**商品服务管理**；商家 **只选** 不维护目录 |
+| **店铺商品分类维护** | 见 **店铺商品分类**；本模块 **消费** 其数据 |
+| **属性模版维护** | 模版配置 **非本期**（若后续单独立项）；发品时 **选用** 已有模版 |
+| **C 端下单 / 订单履约** | 见 **订单管理**；本模块不处理发货、退款 |
+
+### 1.2 与草稿的对应关系
+
+| 草稿条目 | 定稿处理 |
+|----------|----------|
+| §1 列表字段 | §5.1 |
+| §2 添加商品 | §8 |
+| §3 高级检索 | §6 |
+| §4 商品状态 | §4、§12（「待上架」定稿称 **未上架**） |
+| §5 操作（详情/上下架/编辑/删除） | §7、§9～§11 |
+| §6 按当前店铺查列表 | §5.2、§13 |
+| §7 店铺上下文 | §13 |
+| §8 异常返回 | **不纳入** |
+| §9 技术栈 | **不纳入** |
+
+### 1.3 在供给链中的位置
+
+依据 **《关联需求分析.md》§5.1、§5.4**：
+
+```text
+【平台】商户管理 → 店铺管理 → 商品服务目录 / 商品分类（平台树）
+            ↓
+【商家】登录 → 选择当前店铺
+            ↓
+【商家】店铺商品分类（可选）── 维护本店店铺商品分类
+            ↓
+【商家】商品列表（本模块）── 发品 / 提交上架 / 下架 / 删除
+            ↓
+    ┌─ 店铺「默认审核通过」= 关 ─► 待审核 ──【平台】审核──► 出售中 / 审核失败
+    └─ 店铺「默认审核通过」= 开 ─► 直接出售中
+            ↓
+【C 端】出售中 + 店铺开业 + 库存等 → 可下单
+```
+
+| 关联模块 | 关系 | 边界说明 |
+|----------|------|----------|
+| **店铺管理** | 上游 | 商品 **归属当前店铺**，创建后 **不可换店** |
+| **店铺设置** | 策略 | **商品默认审核通过** 决定提交上架后进入 **待审核** 或 **出售中** |
+| **商品分类（平台文档）** | 发品必选 | 商品须挂 **本店二级「商品分类」** |
+| **店铺商品分类** | 发品可选/并列字段 | 发品时 **「店铺商品分类」** 数据源来自该模块 |
+| **商品服务管理** | 发品多选 | 勾选平台服务目录项；保存时生成 **展示快照** |
+| **商品审核（平台）** | 下游协作 | 待审核 → 平台审；出售中 → 平台/商家均可下架 |
+| **订单管理** | 下架约束 | 草稿要求下架前订单须完结；见 §10.2 |
+
+### 1.4 使用端与角色
+
+| 端 | 可操作角色 | 能力 |
+|----|------------|------|
+| **店铺经营管理端** | **商户经营账号** | 本模块全部能力（含切换店铺后操作对应店商品） |
+| **店铺经营管理端** | 员工（子管理员） | 是否可访问由 **角色管理** 中商家端菜单权限决定 |
+| **平台管理端** | 平台管理员 | **不使用** 本模块；在 **商品审核/商品管理** 监管 |
+| **C 端** | 买家/访客 | **不可** 直接访问；仅消费 **出售中** 等可售结果 |
+
+### 1.5 数据范围
+
+- **纳入：** 当前 **所属店铺** 下全部 **未逻辑删除** 的商品；
+- **排除：** 其他店铺商品；已逻辑删除商品；
+- **上下文：** 页头展示 **当前店铺名称**（只读）；切换店铺后列表 **整页刷新**。
+
+---
+
+## 2. 关联需求分析
+
+### 2.1 与《关联需求分析》— 供给链
+
+| 关联点 | 定稿 |
+|--------|------|
+| **§3 模块职责** | 商家在本模块 **发品与状态流转**；平台在 **商品审核** **监管** |
+| **§5.1 开业流程** | 须 **先选当前店铺**，再维护分类并发品 |
+| **§5.4 五态** | 本模块与平台 **共用** 同一套状态机，**不得** 另立规则 |
+| **§6.2 S-P1～S-P5** | 默认审核策略、停业不自动下架、删店前置、商品不可换店 |
+| **§6.3 C-P1** | 商品 **仅挂本店二级商品分类** |
+| **§6.5 GS-P1～P9** | 服务目录全平台共用；保存写快照；改目录不追溯 |
+| **§8 不级联** | 店铺停业、分类隐藏、服务目录变更 **不自动** 改商品状态 |
+| **§9.1 经营账号** | 登录后 **切换当前店铺** 再操作本模块 |
+
+### 2.2 与平台《商品审核功能需求》
+
+| 项 | 商家端（本模块） | 平台端 |
+|----|------------------|--------|
+| 列表可见 **未上架** | **是**（草稿） | **否** |
+| **待审核** 编辑 | **允许**（P14；草稿 §5(2) 与之冲突，以 **P14** 为准） | 只读详情 + 审核 |
+| **出售中** 编辑 | **允许**（关联分析 §8；资料可变、状态不变） | 只读 + 下架 |
+| 审核驳回原因 | **详情可见**，便于修改后重提 | 必填 |
+| 批量审核/下架 | **不涉及** | 整批失败策略 |
+
+### 2.3 与平台《商品分类功能需求》
+
+| 项 | 定稿 |
+|----|------|
+| 发品字段「商品分类」 | 必选 **本店二级分类**；不可挂一级 |
+| 分类下拉范围 | 仅 **当前店铺**、**未删除** 分类 |
+| 删分类 | 有关联商品则 **不可删**（分类模块规则）；商家须先改商品分类 |
+
+### 2.4 与《店铺商品分类功能需求》
+
+| 项 | 定稿 |
+|----|------|
+| 发品字段「店铺商品分类」 | 数据源来自 **店铺商品分类** 模块；**仅可选本店二级**（展示「一级 > 二级」） |
+| 与「商品分类」关系 | **并列、独立** 字段；互不影响校验 |
+| 删除协作 | **二级** 下有商品则 **不可删**；删 **一级** 须全部下属二级均无商品 |
+
+### 2.5 与《商品服务管理功能需求》
+
+| 项 | 定稿 |
+|----|------|
+| 发品勾选 | 多选平台 **未删除** 服务项；「默认显示 = 是」的项 **默认勾选**，可取消 |
+| 展示快照 | **保存商品** 时写入名称、简介、图标快照 |
+| 平台删服务 | C 端不展示已删项；商家 **再次保存** 时自动剔除 |
+| 改服务文案 | **不自动** 更新已保存商品的展示 |
+
+### 2.6 与《店铺管理》《店铺设置》
+
+| 项 | 定稿 |
+|----|------|
+| 店铺停业 | 商家端 **仍可** 维护商品；C 端该店 **禁止下单** |
+| 默认审核通过 | **全局** 配置（店铺设置）；**关闭**（默认）→ 提交上架进 **待审核**；**开启** → 直接 **出售中** |
+| 修改审核开关 | **不追溯** 已有商品；仅影响 **此后** 新提交上架 |
+
+### 2.7 与《角色管理》《员工管理》— 权限
+
+| 项 | 定稿 |
+|----|------|
+| 菜单权限 | 本模块对应商家端「商品列表」等菜单；由 **角色管理** 配置 |
+| 经营账号 | 默认具备商家端全部菜单 |
+| 无权限 | 不可见菜单；直接访问须拒绝 |
+
+---
+
+## 3. 业务概念
+
+| 概念 | 说明 |
+|------|------|
+| **当前店铺** | 登录会话内选定的店铺；本模块全部操作均限定于此 |
+| **商品编号** | 系统生成、**全平台唯一**；列表与检索主键之一 |
+| **未上架** | 草稿称「待上架」；保存商品后的 **草稿态**，仅商家端可见 |
+| **待审核** | 商家 **提交上架** 后、平台未处理；须等平台审核（免审店除外） |
+| **出售中** | 审核通过或免审直达；C 端在满足其他条件时可售 |
+| **审核失败** | 平台驳回；须查看 **驳回原因** 后修改重提 |
+| **已下架** | 商家或平台将 **出售中** 商品下架后的状态 |
+| **提交上架** | 将未上架/审核失败/已下架商品 **送入** 审核或直接出售流程的 **独立动作**（非编辑保存） |
+| **商品分类** | 平台文档中的 **本店二级分类**；发品 **必选** |
+| **店铺商品分类** | 本店 **店铺商品分类** 模块 **二级** 数据；发品 **可选**（是否必填以原型为准） |
+| **展示快照** | 商品已选 **商品服务** 项在保存时的名称、简介、图标副本 |
+
+### 3.1 术语对照（草稿 → 定稿）
+
+| 草稿用语 | 定稿用语 | 说明 |
+|----------|----------|------|
+| 待上架 | **未上架** | 与平台、关联分析一致 |
+| 上架 | **提交上架** | 强调是状态流转动作，非简单保存 |
+
+---
+
+## 4. 功能结构
+
+```text
+商品列表（店铺 · 商品管理）
+├── 商品列表（当前店铺、分页）
+├── 高级检索
+├── 查看详情（全状态）
+├── 添加商品
+├── 编辑商品
+├── 提交上架（单独 / 批量）
+├── 下架商品（单独 / 批量）
+└── 删除商品（单独 / 批量）
+```
+
+---
+
+## 5. 商品列表
+
+### 5.1 列表字段（对齐草稿 §1）
+
+| 字段 | 说明 |
+|------|------|
+| 商品编号 | 系统生成，全平台唯一 |
+| 商品主图 | 缩略图 |
+| 商品名称 | — |
+| 售价 | 首期 **单规格** 销售价 |
+| 销量 | 累计销量 |
+| 商品状态 | 未上架 / 待审核 / 出售中 / 审核失败 / 已下架 |
+| 操作 | 见 §5.3 |
+
+**建议扩展列（非草稿必列）：** 库存、商品分类（一级 > 二级）、店铺商品分类（一级 > 二级）、提交上架时间。
+
+### 5.2 列表行为
+
+| 规则 | 说明 |
+|------|------|
+| 数据范围 | **仅当前店铺** 下未删除商品 |
+| 分页 | 支持 |
+| 默认排序 | 建议按 **更新时间降序**；**待审核** Tab 可按 **提交上架时间升序**（先报先审） |
+| 状态筛选 | 支持按状态 Tab 或下拉筛选 **五种状态** |
+| 店铺上下文 | 页头展示 **当前店铺名称**；切换店铺后 **整页刷新** |
+
+### 5.3 行操作（按状态）
+
+| 商品状态 | 可用操作 |
+|----------|----------|
+| 未上架 | 查看详情、编辑、**提交上架**、删除 |
+| 待审核 | 查看详情、**编辑**（P14）、— |
+| 出售中 | 查看详情、编辑、**下架** |
+| 审核失败 | 查看详情、编辑、**提交上架**、删除 |
+| 已下架 | 查看详情、编辑、**提交上架**、删除 |
+
+支持 **多选** 以触发批量 **提交上架**、**下架**、**删除**（须满足各节状态与校验规则）。
+
+---
+
+## 6. 高级检索
+
+> 对齐草稿 §3。
+
+| 检索项 | 规则 |
+|--------|------|
+| 商品编号 | 精确或模糊（与平台统一） |
+| 商品名称 | 模糊匹配 |
+| 商品分类 | 选择 **二级分类** 或展示「一级 > 二级」路径 |
+
+| 行为 | 说明 |
+|------|------|
+| 查询 | 条件 **与** 组合；结果分页；范围仍限定 **当前店铺** |
+| 重置 | 清空条件并恢复默认列表 |
+
+**可选扩展：** 按 **店铺商品分类**、商品状态筛选（列表 Tab 已覆盖状态时可不再重复）。
+
+---
+
+## 7. 查看详情
+
+> 对齐草稿：全部商品均可查看详情。
+
+### 7.1 展示内容
+
+| 类别 | 内容 |
+|------|------|
+| 基础信息 | 编号、名称、主图/详情图、售价、库存、销量、重量、条码、关键词、简述等 |
+| 分类 | **商品分类**（一级 > 二级）、**店铺商品分类**（一级 > 二级，若有） |
+| 规格与运费 | 销售规格（统一/多规格）、规格明细（市场价、库存）；快递运费（固定/模版） |
+| 属性 | 基于 **属性模版** 扩展的属性项、规格项及其值 |
+| 详情内容 | 图文详情（图片块 + 文本块） |
+| 服务快照 | 已勾选 **商品服务** 项的快照（只读） |
+| 状态信息 | 当前状态；**待审核/审核失败** 展示提交时间、审核时间（若有）、**驳回原因** |
+| 操作区 | 与列表行操作 **一致**（按状态启用） |
+
+### 7.2 边界
+
+- 详情 **不提供** 直接修改状态（须通过 **提交上架 / 下架** 等专用动作）。
+- 详情 **不维护** 平台服务目录、平台分类树。
+
+---
+
+## 8. 添加商品
+
+> 对齐草稿 §2。
+
+### 8.1 填写项概览
+
+| 分组 | 字段 | 必填 | 说明 |
+|------|------|:----:|------|
+| 基础 | 商品编号 | — | **系统生成**，创建后展示 |
+| 基础 | 商品图片 | 是 | **多张**；首张或指定一张为主图 |
+| 基础 | 商品名称 | 是 | — |
+| 分类 | 商品分类 | 是 | **本店二级分类** |
+| 分类 | 店铺商品分类 | 视产品 | **本店二级**；来自 **店铺商品分类** 模块 |
+| 基础 | 商品重量 | 视产品 | — |
+| 基础 | 商品条码 | 否 | — |
+| 基础 | 搜索关键词 | 否 | — |
+| 基础 | 商品简述 | 视产品 | — |
+| 属性 | 属性模版 | 视产品 | 在模版基础上 **可增删** 属性项、属性值、规格项、规格值 |
+| 销售 | 销售规格 | 是 | **统一规格 / 多规格** |
+| 销售 | 规格明细 | 是 | 每种规格：**市场价、库存**（首期单规格时一行） |
+| 物流 | 快递运费 | 是 | **固定运费 / 运费模版** |
+| 详情 | 商品详情 | 是 | **添加图片 / 添加文本** 组合 |
+| 服务 | 服务说明 | 否 | 多选平台服务项（如 24 小时发货、7 天无理由退换货等） |
+
+### 8.2 保存后状态
+
+```text
+填写表单 → 保存
+    → 校验通过
+    → 商品状态 = 【未上架】
+    → 返回列表，可继续编辑或提交上架
+```
+
+### 8.3 前置依赖
+
+| 前置 | 说明 |
+|------|------|
+| 当前店铺有效 | 停业店仍可发品；**已逻辑删除** 店铺不可用 |
+| 商品分类 | 须已维护 **本店二级分类**（至少一条可选） |
+| 商品服务 | 平台已配置目录则可选；无目录时服务区域为空 |
+| 属性模版 | 若启用模版能力，须已有可选模版（**非本期** 则手工维护属性） |
+
+---
+
+## 9. 编辑商品
+
+> 对齐草稿 §5(4)；与平台 P14、关联分析 §8 对齐。
+
+### 9.1 可编辑状态
+
+| 状态 | 是否可编辑 | 说明 |
+|------|:----------:|------|
+| 未上架 | ✓ | 草稿编辑 |
+| 待审核 | ✓ | 保存后 **仍为待审核**，不自动通过（P14） |
+| 出售中 | ✓ | 资料可变，**状态仍为出售中** |
+| 审核失败 | ✓ | 可改后 **提交上架** |
+| 已下架 | ✓ | 可改后 **提交上架** |
+
+> **定稿说明：** 草稿 §5(2)「上架后不支持编辑」以 **平台 P14** 及 **关联分析** 为准调整为：**待审核、出售中均可编辑**；**删除** 仍按 §11 状态限制。
+
+### 9.2 不可通过编辑变更的内容
+
+| 项 | 说明 |
+|----|------|
+| 商品编号 | 系统生成，**不可改** |
+| 归属店铺 | **不可换店**（S-P5） |
+| 商品状态 | **不可** 在编辑保存中直接改为出售中/未上架等；须走 **提交上架 / 下架** |
+
+### 9.3 保存后对服务快照
+
+- 修改服务勾选后 **再次保存** → 刷新 **展示快照**；
+- 已逻辑删除的平台服务项 → **自动剔除**（P21）。
+
+---
+
+## 10. 提交上架
+
+> 对齐草稿 §5(2)；对应关联分析「提交上架」动作。
+
+### 10.1 方式
+
+| 方式 | 说明 |
+|------|------|
+| 单独提交 | 列表行或详情 |
+| 批量提交 | 勾选多条 **未上架 / 审核失败 / 已下架** |
+
+### 10.2 前置与校验
+
+| 校验 | 失败提示（示例） |
+|------|------------------|
+| 含 **待审核 / 出售中** | 所选商品含不可提交状态，请重新选择（**整批失败**） |
+| 资料不完整 | 请完善必填项后再提交上架 |
+| 未勾选任何行 | 请选择要提交的商品 |
+
+### 10.3 提交后状态流转
+
+```text
+商家：提交上架
+    │
+    ├── 店铺「默认审核通过」= 开启 ──►【出售中】
+    │
+    └── 店铺「默认审核通过」= 关闭 ──►【待审核】
+                │
+                ├── 平台：审核通过 ──►【出售中】
+                └── 平台：审核驳回 ──►【审核失败】（须驳回原因）
+```
+
+| 项 | 说明 |
+|----|------|
+| 首次提交时间 | 记录 **提交上架时间**；待审核排序可参考该时间 |
+| 再次提交 | 审核失败/已下架修改后 **重新提交**，仍受 **免审策略** 约束 |
+| 待审核期间编辑 | 允许；保存后 **仍为待审核**（P14） |
+
+### 10.4 提交上架流程
+
+```text
+选择未上架 / 审核失败 / 已下架商品
+    → 点击「提交上架」（单独或批量）
+    → 校验状态与资料完整性
+    ├── 含非法状态 → 整批失败
+    └── 通过 → 按店铺审核策略进入「待审核」或「出售中」
+```
+
+---
+
+## 11. 下架商品
+
+> 对齐草稿 §5(3)。
+
+### 11.1 方式
+
+| 方式 | 说明 |
+|------|------|
+| 单独下架 | 列表行或详情 |
+| 批量下架 | 勾选多条 **出售中** |
+
+### 11.2 规则
+
+| 规则 | 说明 |
+|------|------|
+| 前置状态 | 仅 **出售中** |
+| 结果状态 | **已下架** |
+| 订单约束（草稿） | 该商品 **相关订单全部完成后** 方可下架；存在 **未完成订单** 时 **阻断** 并提示 |
+| 平台权限 | 平台亦可在 **商品审核** 模块下架；下架后商家可编辑、重新提交上架 |
+| 批量含非法状态 | **整批失败** |
+| 确认 | 建议二次确认：「下架后 C 端不可购买」 |
+
+> **未完成订单** 语义与 **《订单管理功能需求》O10** 一致：待支付、待发货、已发货；**已关闭、已完成** 不属于阻塞下架的未完成订单（若产品确认草稿「全部完成」指 **无 O10 订单**，则与此一致）。
+
+### 11.3 下架后
+
+| 项 | 说明 |
+|----|------|
+| 商家 | 可 **编辑**；可 **重新提交上架** |
+| 已有订单 | **不自动** 关闭（订单模块规则） |
+| C 端 | 不可新下单该商品 |
+
+### 11.4 下架流程
+
+```text
+选择「出售中」商品 → 下架
+    → 校验是否存在未完成订单（草稿）
+    → 校验状态
+    ├── 含非出售中 / 有未完成订单 → 整批失败或单独阻断
+    └── 通过 → 二次确认 → 已下架
+```
+
+---
+
+## 12. 删除商品
+
+> 对齐草稿 §5(5)。
+
+### 12.1 可删除状态
+
+| 状态 | 可删除 |
+|------|:------:|
+| 未上架 | ✓ |
+| 待审核 | **否**（须等平台审完或 **平台驳回** 后再删；或产品改为须先撤回——**非草稿**，本期 **不可删**） |
+| 出售中 | **否** |
+| 审核失败 | ✓ |
+| 已下架 | ✓ |
+
+> **定稿说明：** 草稿未明确 **待审核** 可否删；与平台监管衔接，**待审核、出售中不可删**；须先 **驳回/下架** 再处理。
+
+### 12.2 方式与校验
+
+| 方式 | 说明 |
+|------|------|
+| 单独删除 | 行操作 |
+| 批量删除 | 勾选多条；含 **不可删状态** → **整批失败** |
+
+```text
+选择可删状态商品 → 删除
+    → 校验状态
+    ├── 含待审核/出售中等 → 整批失败
+    └── 通过 → 二次确认 → 逻辑删除
+```
+
+---
+
+## 13. 商品状态与流转（定稿）
+
+> 与 **《关联需求分析》§5.4**、**《商品审核功能需求》§3** **一致**。
+
+```text
+【保存商品】────────────────────────────►【未上架】
+                                              │
+                                    【提交上架】
+                                              │
+                    ┌─────────────────────────┴─────────────────────────┐
+                    │                                                   │
+         默认审核 = 开                                         默认审核 = 关
+                    │                                                   │
+                    ▼                                                   ▼
+              【出售中】◄──── 平台审核通过 ────【待审核】──── 平台驳回 ────►【审核失败】
+                    │                              ▲                           │
+                    │         商家编辑(P14)          │                           │
+                    │         仍为待审核             │                           │
+                    │                              │                           │
+                    └──── 商家/平台：下架 ────►【已下架】◄──────────────────────┘
+                                                      │
+                                              【编辑 + 提交上架】
+```
+
+| 操作 | 前置状态 | 结果状态 | 执行方 |
+|------|----------|----------|--------|
+| 保存商品（新建） | — | 未上架 | 商家 |
+| 提交上架 | 未上架 / 审核失败 / 已下架 | 待审核 或 出售中 | 商家 |
+| 审核通过 | 待审核 | 出售中 | **平台** |
+| 审核驳回 | 待审核 | 审核失败 | **平台** |
+| 下架 | 出售中 | 已下架 | 商家 / 平台 |
+| 编辑保存 | 见 §9.1 | **状态不变** | 商家 |
+| 删除 | 未上架 / 审核失败 / 已下架 | 逻辑删除 | 商家 |
+
+**刚性约束（P17）：** 状态 **只能** 通过「提交上架、平台审核、下架」变更；编辑保存 **不得** 直接改为出售中，也 **不得** 改回未上架。
+
+---
+
+## 14. 店铺上下文（协作规则，对齐草稿 §6、§7）
+
+```text
+商户经营账号 / 员工 ── 登录商家端
+            ↓
+    解析当前店铺（会话内记住上次所选店铺）
+            ↓
+    页头展示当前店铺名称；后续请求携带当前店铺标识
+            ↓
+    商品列表 / 发品 / 操作 ── 仅作用于当前店铺商品
+            ↓
+    切换店铺 → 更新当前店铺 → 列表整页刷新
+```
+
+| 规则 | 说明 |
+|------|------|
+| 员工账号 | 绑定 **单一店铺**，**不可** 切换 |
+| 经营账号 | 可管理 **同商户多店**；须 **先选店** 再操作 |
+| 默认店铺 | 经营账号登录后默认 **该商户最早创建的店铺** |
+| 记住选择 | **同一会话** 内记住上次所选店铺；刷新后 **仍为所选店** |
+| 未选店铺 | **不可** 操作商品列表（须先完成店铺上下文初始化） |
+
+---
+
+## 15. 与关联模块的协作流程
+
+### 15.1 发品完整链路
+
+```text
+【平台】配置商品服务目录（可选，建议先发品前完成）
+【平台】维护平台商品分类树；商家维护本店二级「商品分类」
+【商家】维护「店铺商品分类」（可选）
+            ↓
+【商家】商品列表 → 添加商品 → 保存（未上架）
+            ↓
+【商家】提交上架
+            ↓
+【平台】商品审核（待审核时）→ 通过/驳回
+            ↓
+【C 端】出售中且满足可购条件 → 展示商品与服务快照
+```
+
+### 15.2 删店与商品
+
+| 条件 | 说明 |
+|------|------|
+| 阻塞删店 | 存在 **出售中** 或 **待审核** 商品（关联分析 §7.2） |
+| 不阻塞 | **未上架、已下架、审核失败** 可不挡删店 |
+| 对本模块 | 商家须先 **下架/处理待审** 后再由平台删店 |
+
+### 15.3 店铺停业
+
+| 项 | 行为 |
+|----|------|
+| 商家端 | **仍可** 维护商品、提交上架 |
+| C 端 | 该店 **禁止下单**；商品状态 **不变** |
+
+---
+
+## 16. 业务规则汇总
+
+| 编号 | 规则 |
+|------|------|
+| **GL1** | 列表与全部操作范围 = **当前店铺** 下未删除商品 |
+| **GL2** | 商品 **五态**：未上架、待审核、出售中、审核失败、已下架；与平台 **同源** |
+| **GL3** | 新建保存 → **未上架**；**提交上架** 方进入审核/出售流程 |
+| **GL4** | 提交上架：仅 **未上架 / 审核失败 / 已下架**；批量含非法状态 → **整批失败** |
+| **GL5** | 店铺「默认审核通过」= **开** → 提交后直接 **出售中**；= **关** → **待审核** |
+| **GL6** | **待审核** 期间允许 **编辑**，保存后 **仍为待审核**（P14） |
+| **GL7** | **出售中** 允许 **编辑** 资料，状态 **不变** |
+| **GL8** | 下架：仅 **出售中**；草稿要求 **无未完成订单**（O10）方可下架 |
+| **GL9** | 删除：仅 **未上架 / 审核失败 / 已下架**；**待审核、出售中不可删** |
+| **GL10** | 批量提交上架 / 下架 / 删除：**整批失败** 策略与平台一致 |
+| **GL11** | 商品 **仅挂本店二级商品分类**；**店铺商品分类** 为并列字段，**仅挂本店店铺商品二级** |
+| **GL12** | 保存商品时写入 **服务展示快照**；改平台目录 **不追溯** |
+| **GL13** | 状态 **仅** 经提交上架、平台审核、下架变更（P17） |
+| **GL14** | 商户/店铺/分类/服务目录变更 **不自动** 改商品状态 |
+| **GL15** | 须携带 **当前店铺上下文**；切换店铺后数据范围随之变化 |
+| **GL16** | 商品创建后 **不可换店** |
+| **GL17** | **任意状态** 均可 **查看详情**；审核失败须展示 **驳回原因** |
+
+---
+
+## 17. 页面与交互要点
+
+| 场景 | 要求 |
+|------|------|
+| 页头 | 固定展示 **当前店铺名称**；经营账号可 **切换店铺** |
+| 状态 Tab | 建议 Tab：全部 / 未上架 / 待审核 / 出售中 / 审核失败 / 已下架 |
+| 待审核角标 | 可选展示待审数量 |
+| 批量操作栏 | 勾选后按状态启用「批量提交上架」「批量下架」「批量删除」 |
+| 提交上架 | 与「保存」区分按钮；成功提示目标状态（待审核/出售中） |
+| 下架确认 | 二次确认；若有未完成订单则 **明确提示** |
+| 删除确认 | 二次确认 |
+| 驳回原因 | 审核失败详情 **醒目展示** |
+| 空态 | 无商品时引导「添加商品」 |
+| 权限 | 无菜单权限 **不可** 见入口 |
+
+---
+
+## 18. 非本期范围
+
+| 项 | 说明 |
+|----|------|
+| 属性模版 **维护** | 仅 **选用**；模版 CRUD 单独立项 |
+| 运费模版 **维护** | 假定平台或它模块已提供可选模版 |
+| 多规格 SKU 完整能力 | 草稿含多规格字段；复杂 SKU 以商品管理全模块为准 |
+| 平台代商家改价/改库存 | 平台侧能力 |
+| 会员价、营销活动 | 全项目不考虑会员体系 |
+| 评价管理 | 见 **评价管理**（待建设） |
+| 异常返回 code/msg/data | 实现层 |
+| 技术栈 | 实现层 |
+
+---
+
+## 19. 草稿对照与修订说明
+
+| 草稿条目 | 本文档处理 |
+|----------|------------|
+| §1 列表五字段 | §5.1；补 **状态** 列 |
+| §2 添加商品大表单 | §8 结构化；服务/分类/快照协作见 §2 |
+| §3 检索三项 | §6 |
+| §4 五状态 | §3、§12、§13；「待上架」→ **未上架** |
+| §5(1) 查看详情 | §7 |
+| §5(2) 上下架与审核 | §10、§11；**待审核可编辑** 依 P14 修正草稿 |
+| §5(3) 下架订单约束 | §11.2 |
+| §5(4) 编辑范围 | §9；**扩展出售中可编辑** |
+| §5(5) 删除范围 | §12；**补充待审核/出售中不可删** |
+| §6～§7 店铺范围与上下文 | §5.2、§13、§14 |
+| §8～§9 | **不纳入** |
+| 未写：平台免审、服务快照、分类边界 | §2、§8、§10 |
+| 未写：与商品审核分工 | §1、§2.2、§12 |
+
+---
+
+## 20. 修订记录
+
+| 版本 | 说明 |
+|------|------|
+| **v1.0** | 首版定稿：店铺商品列表/检索/发品/状态流转；对齐平台五态与关联分析；补店铺上下文与服务/分类协作 |
+| **v1.1** | 对齐《店铺商品分类功能需求》v1.1：店铺商品分类为 **两级**，发品 **仅挂二级** |
+
+---
+
+*文档版本：v1.1 · 关联《关联需求分析.md》v1.5、《商品审核功能需求.md》v1.0、《商品分类功能需求.md》v1.4、《商品服务管理功能需求.md》v1.0.1、《店铺商品分类功能需求.md》v1.1 · 草稿《商品列表功能需求-草稿.md》保持不变。*

doc/店铺后台/商品管理/商品列表/店铺商品列表技术方案.md

@@ -0,0 +1,515 @@
+# 店铺商品列表 — 技术方案
+
+> **依据：** 《商品列表功能需求.md》v1.0  
+> **关联：** 《关联需求分析.md》v1.5；平台《商品审核技术方案》v1.0、《商品分类技术方案》v1.2、《商品服务管理技术方案》v1.0.1；商家《店铺商品分类技术方案》（`biz_goods_category` 本店二级）  
+> **范围：** 商家端 **当前店铺** 商品列表、检索、发品、编辑、提交上架、下架、删除；**复用** 平台商品主表与状态机，**不另建** 商家商品表。  
+> **原则：** `goods_status` 仅经 submit / audit / offShelf 变更（P17）；`X-Shop-Id` 店铺上下文；批量含非法状态 **整批失败**。
+
+---
+
+## 1. 技术架构
+
+| 项 | 选型 |
+|----|------|
+| 基础框架 | RuoYi **v3.9.2**（`springboot2` 分支） |
+| 数据库 | **MySQL 5.7.39** |
+| ORM / 权限 | MyBatis；`@PreAuthorize`；`AjaxResult` / `TableDataInfo` |
+| 店铺上下文 | `SellerShopContextInterceptor` + 请求头 **`X-Shop-Id`**；会话内记住所选店铺（Redis token） |
+| 编号 | Redis 自增 `agri:goods:sn:{yyyyMMdd}` |
+| 日志 | 增删改、提交上架、下架 `@Log` |
+
+### 1.1 与平台侧边界
+
+| 维度 | 平台 · 商品审核/管理 | 本模块 · 商家商品列表 |
+|------|----------------------|----------------------|
+| 表 | **`biz_goods` 同源** | 同表，`shop_id` 限定当前店 |
+| 状态机 | `IGoodsService.auditGoods` / `offShelfPlatform` | `submitGoods` / `offShelfSeller` |
+| 列表范围 | `goods_status <> '0'` | **含未上架（0）** 五态全展示 |
+| 路径 | `/agri/goods` | **`/agri/seller/goods`** |
+| 权限前缀 | `agri:goods:*` | **`agri:seller:goods:*`** |
+
+> **定稿：** 商家端与平台 **同一套** `IGoodsService` 实现，避免双轨状态逻辑（对齐《商品审核技术方案》§1）。
+
+### 1.2 业务链
+
+```text
+GET /agri/seller/context          → 前端缓存 shopId（X-Shop-Id）
+        ↓
+biz_shop_global_config.default_audit_pass
+        ↓
+biz_goods（shop_id = 当前店铺）
+        ├── 保存 POST/PUT           → status=0 未上架
+        ├── 提交上架 PUT .../submit → status=1 或 2
+        ├── 平台 audit（/agri/goods/audit）→ 1→2|3
+        └── 下架 PUT .../offShelf     → 2→4
+        ↓
+biz_goods_service_snapshot（保存商品时写快照）
+        ↓
+biz_goods_category
+        ├── category_id      → shop_id IS NULL 的二级（平台「商品分类」）
+        └── shop_category_id → shop_id = 当前店 的二级（「店铺商品分类」）
+```
+
+| 关联模块 | 协作 |
+|----------|------|
+| **商品审核** | 商家 submit 后进入平台待审队列；驳回原因商家详情可读 |
+| **商品分类** | `category_id` ← `ICategoryFacade.listPlatformLevel2Options()` |
+| **店铺商品分类** | `shop_category_id` ← `IShopGoodsCategoryFacade.listOptionsByShopId()` |
+| **商品服务** | 发品多选 ← `IGoodsServiceFacade`；保存写快照 |
+| **店铺设置** | `IShopGlobalConfigFacade.getDefaultAuditPass()` 决定 submit 目标态 |
+| **订单管理** | 下架前校验 **O10 未完成订单**（待实现，`IOrderFacade`） |
+| **店铺管理** | `IGoodsFacade.hasBlockingGoodsForShopDelete` 删店前置 |
+
+### 1.3 模块落位
+
+```text
+baqing-shop/src/main/java/com/ruoyi/web/modules/goods/
+├── controller/SellerGoodsController.java      # /agri/seller/goods（本方案）
+├── controller/GoodsController.java            # 平台监管（已实现）
+├── controller/GoodsAuditController.java       # 平台审核菜单（可选薄封装）
+├── service/IGoodsService.java
+├── service/impl/GoodsServiceImpl.java
+├── domain/BizGoods.java
+├── dto/GoodsSaveDTO.java
+├── dto/GoodsSubmitBatchDTO.java               # 待实现 · 批量提交
+├── dto/GoodsOffShelfDTO.java                  # 复用 · 批量下架
+├── dto/GoodsDeleteDTO.java                    # 待实现 · 批量删除
+├── mapper/BizGoodsMapper.java
+├── support/GoodsSnGenerator.java
+├── support/GoodsStatusUtils.java
+├── facade/IGoodsFacade.java                   # 删店/分类删校验
+└── constant/GoodsConstants.java
+
+resources/mapper/goods/BizGoodsMapper.xml
+sql/biz_goods.sql
+sql/biz_goods_service_snapshot.sql
+sql/biz_goods_shop_category_id.sql             # shop_category_id 增量 DDL
+sql/agri_seller_goods_menu.sql                 # 商家菜单
+```
+
+**店铺上下文（已有）：** `com.ruoyi.web.modules.store` → `SellerShopContextController`（`/agri/seller/context`）。
+
+---
+
+## 2. 数据库设计
+
+### 2.1 表复用与分工
+
+| 表名 | 本模块用途 |
+|------|------------|
+| **`biz_goods`** | 商品主表；商家 CRUD + 状态字段 |
+| **`biz_goods_service_snapshot`** | 发品勾选服务的 **展示快照** |
+| `biz_goods_category` | join 分类路径；**不** 由本模块维护 |
+| `biz_shop` | 店铺上下文、删店 join |
+| `biz_shop_global_config` | 全局默认审核开关 |
+
+**无商家独立商品表。**
+
+### 2.2 `biz_goods` 字段（本模块相关）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| goods_id | bigint PK | |
+| shop_id | bigint NOT NULL | **创建时写入当前店铺**；不可 UPDATE 换店 |
+| category_id | bigint NOT NULL | **平台二级分类**（`biz_goods_category`，`shop_id IS NULL`） |
+| shop_category_id | bigint NULL | **店铺商品分类**（`biz_goods_category` 本店二级）；可空 |
+| goods_sn | varchar(32) UK | Redis 生成，全平台唯一 |
+| goods_name | varchar(200) | |
+| main_pic | varchar(512) | 主图 URL |
+| detail_content | text | 详情（首期 JSON/HTML 字符串） |
+| sale_price | decimal(10,2) | **首期单规格** 售价 |
+| stock | int | **首期单规格** 库存 |
+| sales_count | int DEFAULT 0 | 销量（订单模块回写，本模块只读） |
+| goods_status | char(1) | **0** 未上架 **1** 待审核 **2** 出售中 **3** 审核失败 **4** 已下架 |
+| reject_reason | varchar(500) | 平台驳回原因 |
+| submit_time | datetime | 首次 submit 时间 |
+| audit_time | datetime | 审核时间 |
+| off_shelf_time | datetime | 下架时间 |
+| del_flag | char(1) | 0 存在 2 逻辑删除 |
+| create_by / create_time / update_by / update_time | | 审计 |
+
+**首期未落库、后续扩展（需求 §8 完整表单）：** 多图、重量、条码、关键词、简述、多规格 SKU、运费模版、属性项等 → 见 §2.5，**不阻塞 v1.0 列表/单规格发品**。
+
+### 2.3 增量 DDL
+
+```sql
+-- sql/biz_goods_shop_category_id.sql
+ALTER TABLE `biz_goods`
+  ADD COLUMN `shop_category_id` bigint(20) DEFAULT NULL COMMENT '店铺商品分类ID（本店二级 biz_goods_category）' AFTER `category_id`,
+  ADD KEY `idx_shop_category_id` (`shop_category_id`, `del_flag`);
+```
+
+完整建表见 `sql/biz_goods.sql`。
+
+### 2.4 `biz_goods_service_snapshot`
+
+| 字段 | 说明 |
+|------|------|
+| goods_id | FK 逻辑 |
+| service_id | 来源 `biz_goods_service` |
+| service_name / service_intro / service_icon | **快照** |
+| sort_no | 展示顺序 |
+
+保存商品时 **先删后插** 该商品全部快照行。
+
+### 2.5 扩展表（非 v1.0 · 概要）
+
+| 表（规划） | 用途 |
+|------------|------|
+| `biz_goods_pic` | 多图 gallery |
+| `biz_goods_sku` | 多规格 SKU（市场价、库存） |
+| `biz_goods_freight` | 固定运费 / 运费模版 ID |
+| `biz_goods_attr` | 属性项/规格项键值 |
+
+v1.0 **仅** 使用主表 `sale_price`/`stock`/`main_pic`/`detail_content`。
+
+### 2.6 索引
+
+| 索引 | 字段 | 用途 |
+|------|------|------|
+| uk_goods_sn | goods_sn | 编号唯一 |
+| idx_shop_status | shop_id, goods_status, del_flag | 商家列表 + 状态 Tab |
+| idx_category_id | category_id, del_flag | 分类检索 |
+| idx_shop_category_id | shop_category_id, del_flag | 店铺分类删校验 |
+| idx_submit_time | submit_time | 待审核排序（平台侧） |
+
+### 2.7 商家列表 SQL 约定
+
+```sql
+WHERE g.del_flag = '0'
+  AND g.shop_id = #{shopId}          -- 强制当前店铺（GL1）
+  -- 含 goods_status='0'，与平台列表不同
+```
+
+### 2.8 字典
+
+| dict_type | 说明 |
+|-----------|------|
+| goods_status | 0～4 状态展示 |
+
+---
+
+## 3. 状态机（Service）
+
+> 与《商品审核技术方案》§3、《关联需求分析》§5.4 **同源**。
+
+| 操作 | 方法 | 执行方 | 前置 status | 结果 status |
+|------|------|--------|-------------|-------------|
+| 保存（新建） | `insertSellerGoods` | 商家 | — | **0** |
+| 保存（编辑） | `updateSellerGoods` | 商家 | 0/1/2/3/4 | **不变** |
+| 提交上架 | `submitGoods` | 商家 | 0/3/4 | **1** 或 **2**¹ |
+| 审核通过 | `auditGoods` | 平台 | 1 | 2 |
+| 审核驳回 | `auditGoods` | 平台 | 1 | 3 |
+| 下架 | `offShelfSeller` / `offShelfPlatform` | 商家/平台 | 2 | 4 |
+| 删除 | `deleteSellerGoods`² | 商家 | 0/3/4 | del_flag=2 |
+
+¹ `default_audit_pass='1'` → **2**，否则 **1**。  
+² **待实现**；出售中/待审核 **阻断**。
+
+**禁止：** 请求体携带 `goodsStatus` 直接改态（`rejectGoodsStatusInBody`）。
+
+**批量策略：** `submit` / `offShelf` / `delete` 均 **先全量校验** → 任一失败 `GoodsBatchOperationException`，**零行** 更新。
+
+---
+
+## 4. 跨模块 Facade
+
+| 接口 | 提供方 | 本模块用法 |
+|------|--------|------------|
+| `ICategoryFacade` | 分类 | `listPlatformLevel2Options()` — 发品「商品分类」 |
+| `IShopGoodsCategoryFacade` | 店铺商品分类 | `listOptionsByShopId(shopId, visibleOnly)` — 「店铺商品分类」 |
+| `IGoodsServiceFacade` | 商品服务 | `listAllEnabled` / `listDefaultShow`；删服务前 `existsByServiceId` |
+| `IShopGlobalConfigFacade` | 店铺设置 | `getDefaultAuditPass()` |
+| `IShopFacade` | 店铺 | 删店时 `assertShopMaintable` |
+| `IGoodsFacade` | 商品 | `hasBlockingGoodsForShopDelete`；`existsByShopCategoryId` |
+| `IOrderFacade`³ | 订单 | `hasUnfinishedOrderByGoodsId(goodsId)` — 下架前置 |
+
+³ 订单模块 Facade，下架 O10 校验 **待对接**。
+
+---
+
+## 5. 接口设计
+
+**公共约定**
+
+| 项 | 说明 |
+|----|------|
+| 基路径 | `/agri/seller/goods` |
+| 请求头 | **`X-Shop-Id`**：当前店铺 ID（除 `/agri/seller/context` 外 `/agri/seller/**` 必传） |
+| 分页 | `pageNum` / `pageSize` → `TableDataInfo` |
+| 权限 | `@PreAuthorize("@ss.hasPermi('agri:seller:goods:…')")` |
+| 批量失败 | `code!=200`，`data.reasons[]` 明细 |
+
+---
+
+### 5.1 商品列表 `GET /agri/seller/goods/list`
+
+| 项 | 说明 |
+|----|------|
+| 权限 | `agri:seller:goods:list` |
+| 店铺 | `SellerShopContext.getShopId()`，与 header 一致 |
+
+**Query：**
+
+| 参数 | 说明 |
+|------|------|
+| goodsSn | 编号模糊 |
+| goodsName | 名称模糊 |
+| categoryId | **平台** 二级分类 ID |
+| goodsStatusQuery | 0/1/2/3/4；不传查全部 |
+| keyword | 可选；sn+name 组合模糊 |
+
+**`rows`（GoodsListVO）：**
+
+| 字段 | 说明 |
+|------|------|
+| goodsId, goodsSn, goodsName, mainPic | |
+| salePrice, salesCount | 售价、销量 |
+| stock | 可选列 |
+| goodsStatus, goodsStatusLabel | 字典 goods_status |
+| categoryPath | 一级 > 二级（平台分类） |
+| shopCategoryName | 可选；店铺商品分类名 |
+
+**排序：** 默认 `create_time DESC`（待审核 Tab 可前端传参或扩展 `orderBy=submitTime`）。
+
+---
+
+### 5.2 商品详情 `GET /agri/seller/goods/{goodsId}`
+
+| 项 | 说明 |
+|----|------|
+| 权限 | `agri:seller:goods:query` |
+| 校验 | `goods_id` 须属 **当前 shop_id** |
+
+**`data`（GoodsDetailVO）：**
+
+| 字段 | 说明 |
+|------|------|
+| 列表字段 | 同 §5.1 |
+| shopId, categoryId, shopCategoryId | |
+| detailContent, stock | |
+| rejectReason, submitTime, auditTime, offShelfTime | |
+| services[] | 服务快照列表 |
+| canSubmit, canOffShelf, canDelete, canEdit | 前端按钮态（可选） |
+
+---
+
+### 5.3 添加商品 `POST /agri/seller/goods`
+
+| 项 | 说明 |
+|----|------|
+| 权限 | `agri:seller:goods:add` |
+| 日志 | title=商家商品 |
+
+**Body（GoodsSaveDTO · v1.0）：**
+
+```json
+{
+  "categoryId": 1002,
+  "shopCategoryId": 2005,
+  "goodsName": "复合肥 50kg",
+  "mainPic": "/profile/upload/2026/05/01/a.jpg",
+  "detailContent": "<p>详情</p>",
+  "salePrice": 128.00,
+  "stock": 500,
+  "serviceIds": [1, 3]
+}
+```
+
+| 校验 | 说明 |
+|------|------|
+| categoryId | 须为 **平台二级** 有效分类 |
+| shopCategoryId | 若传，须属 **当前店** 二级分类 |
+| serviceIds | 须全部存在于未删除服务目录 |
+| goodsStatus | **禁止** 传入 |
+
+**响应：** `{ "goodsId": 10001 }`；落库 `goods_status='0'`，生成 `goods_sn`。
+
+---
+
+### 5.4 编辑商品 `PUT /agri/seller/goods`
+
+| 项 | 说明 |
+|----|------|
+| 权限 | `agri:seller:goods:edit` |
+| Body | 同 §5.3 + **goodsId** 必填 |
+
+- **不修改** `goods_status`、`shop_id`、`goods_sn`。  
+- 各状态均可编辑（P14）；保存后刷新服务快照。
+
+---
+
+### 5.5 提交上架
+
+#### 5.5.1 单独 `PUT /agri/seller/goods/{goodsId}/submit`
+
+| 项 | 说明 |
+|----|------|
+| 权限 | `agri:seller:goods:edit` |
+| 前置 | status ∈ {0, 3, 4} |
+
+**响应 data：**
+
+```json
+{
+  "goodsId": 10001,
+  "goodsStatus": "1",
+  "goodsStatusLabel": "待审核"
+}
+```
+
+#### 5.5.2 批量 `PUT /agri/seller/goods/submit`（待实现）
+
+**Body：** `{ "goodsIds": [10001, 10002] }`  
+规则：含非 {0,3,4} → **整批失败**。
+
+---
+
+### 5.6 下架
+
+#### 5.6.1 单独 `PUT /agri/seller/goods/{goodsId}/offShelf`
+
+| 项 | 说明 |
+|----|------|
+| 权限 | `agri:seller:goods:offshelf` |
+| 前置 | status=2；**无 O10 未完成订单**（待实现） |
+
+#### 5.6.2 批量 `PUT /agri/seller/goods/offShelf`
+
+| 项 | 说明 |
+|----|------|
+| 权限 | `agri:seller:goods:offshelf` |
+| Body | 复用 `GoodsOffShelfDTO`：`{ "goodsIds": [10001] }` |
+
+失败：`GoodsBatchOperationException` → `{ "reasons": ["仅出售中商品可下架：G20260501001"] }`。
+
+---
+
+### 5.7 删除
+
+#### 5.7.1 单独 `DELETE /agri/seller/goods/{goodsId}`（待实现）
+
+| 项 | 说明 |
+|----|------|
+| 权限 | `agri:seller:goods:remove` |
+| 前置 | status ∈ {0, 3, 4} |
+
+逻辑删除：`del_flag='2'`；同步删快照（可选保留历史）。
+
+#### 5.7.2 批量 `DELETE /agri/seller/goods/{goodsIds}`（待实现）
+
+路径：`goodsIds=1,2,3`；含不可删状态 → **整批失败**。
+
+---
+
+### 5.8 发品辅助下拉
+
+| 方法 | 路径 | 权限 | 说明 |
+|------|------|------|------|
+| GET | `/agri/seller/goods/categoryOptions` | `list` | 平台二级「商品分类」`ICategoryFacade.listPlatformLevel2Options()` |
+| GET | `/agri/seller/goods/shopCategoryOptions` | `list` | 本店二级「店铺商品分类」`IShopGoodsCategoryFacade.listOptionsByShopId(shopId, false)` **待加** |
+| GET | `/agri/seller/goods/serviceOptions` | `list` | `{ all: [], defaultShow: [] }` |
+
+---
+
+### 5.9 与平台接口对照
+
+| 能力 | 商家（本方案） | 平台 |
+|------|----------------|------|
+| 列表 | `GET /agri/seller/goods/list`（含 status=0） | `GET /agri/goods/list`（status≠0） |
+| 详情 | `GET /agri/seller/goods/{id}` | `GET /agri/goods/{id}` |
+| 保存 | POST/PUT `/agri/seller/goods` | — |
+| 提交上架 | PUT `.../submit` | — |
+| 审核 | — | PUT `/agri/goods/audit` |
+| 下架 | PUT `.../offShelf` | PUT `/agri/goods/offShelf` |
+| 删除 | DELETE `.../{id}` | — |
+
+---
+
+## 6. Service 核心逻辑摘要
+
+```text
+insertSellerGoods
+  → requireShopId
+  → validateSaveFields + assertPlatformCategoryLevel2(categoryId)
+  → assertShopCategoryIfPresent(shopCategoryId)
+  → goodsSn = GoodsSnGenerator.next()
+  → insert status=0
+  → saveServiceSnapshots
+
+submitGoods
+  → status in (0,3,4)
+  → target = defaultAuditPass ? 2 : 1
+  → updateSubmitStatus（首次写 submit_time）
+
+offShelfSeller
+  → offShelfBatch（shopId 限定）
+  → [待] orderFacade 校验 O10
+  → status 2 → 4，写 off_shelf_time
+
+deleteSellerGoods [待]
+  → status in (0,3,4)
+  → logic delete
+```
+
+**分类校验口径：**
+
+| 字段 | SQL 条件 |
+|------|----------|
+| category_id | `biz_goods_category.category_id`，`shop_id IS NULL`，`parent_id > 0` |
+| shop_category_id | `biz_goods_category.category_id`，`shop_id = #{shopId}`，`parent_id > 0` |
+
+---
+
+## 7. 权限与菜单
+
+| 权限标识 | 说明 |
+|----------|------|
+| agri:seller:goods:list | 列表、下拉 |
+| agri:seller:goods:query | 详情 |
+| agri:seller:goods:add | 新增 |
+| agri:seller:goods:edit | 编辑、提交上架 |
+| agri:seller:goods:offshelf | 下架 |
+| agri:seller:goods:remove | 删除 |
+
+**菜单 SQL：** `sql/agri_seller_goods_menu.sql`  
+**组件路径：** `agri/seller/goods/index`（发品/编辑可 `goods/form`）。
+
+---
+
+## 8. 实现分期
+
+| 阶段 | 内容 | 状态 |
+|------|------|------|
+| **v1.0** | 列表/详情/单规格 CRUD/单独 submit·offShelf/服务快照/平台分类与服务下拉 | **已实现** |
+| **v1.0 补全** | `shop_category_id` 字段 + 店铺分类下拉 + 删除 + 批量 submit/offShelf/delete + 下架 O10 校验 | **待实现** |
+| **v1.x** | 多图、多规格 SKU、运费、属性模版引用、关键词检索扩展 | 规划 |
+
+---
+
+## 9. 测试要点
+
+| 编号 | 场景 |
+|------|------|
+| T1 | 未传 `X-Shop-Id` → 业务失败 |
+| T2 | 列表仅返回当前店商品 |
+| T3 | 保存 → status=0；body 带 goodsStatus → 拒收 |
+| T4 | submit：免审关→1，免审开→2 |
+| T5 | 待审核/出售中 edit 保存 → 状态不变 |
+| T6 | 批量 submit 含 status=2 → 整批失败 |
+| T7 | 下架非出售中 → 失败 |
+| T8 | 删除出售中 → 失败 |
+| T9 | 跨店 goodsId → MSG_NOT_OWNER |
+| T10 | 服务快照：保存后详情与目录变更隔离 |
+
+---
+
+## 10. 修订记录
+
+| 版本 | 说明 |
+|------|------|
+| **v1.0** | 首版：商家商品列表技术方案；复用 biz_goods 与平台状态机；接口/DDL 与实现对齐并标注待办 |
+
+---
+
+*文档版本：v1.0 · 关联《商品列表功能需求.md》v1.1、《商品审核技术方案.md》、《商品分类技术方案.md》v1.2、《商品服务管理技术方案.md》v1.0.1、《店铺商品分类技术方案.md》v1.1 · 技术栈 RuoYi v3.9.2-springboot2 + MySQL 5.7.39。*