商品列表 — 前端技术方案
依据： 《商品列表功能需求.md》v1.1、《店铺商品列表技术方案.md》v1.0
前端规范： doc/前端设计/前端设计.md
范围： 仅 ruoyi-ui 商家端（店铺经营管理端） 当前店铺商品列表、检索、发品（v1.0 单规格）、编辑、提交上架、下架、删除；平台审核 不在本页。
实现状态： 页面与 API 封装已落地，待菜单配置及 /agri/seller/goods 联调。
1. 技术栈与写法约定
| 项 |
说明 |
| 框架 |
Vue 2 + Element UI（与 RuoYi-Vue 一致） |
| 请求 |
@/utils/request；商家端接口携带 X-Shop-Id |
| 参考页面 |
ruoyi-ui/src/views/agri/goods/audit/index.vue（列表 Tab、批量操作） |
| 商家端参考 |
ruoyi-ui/src/views/agri/seller/employee/index.vue（loadShopContext） |
| 布局 |
检索区 el-card + <br/> + 列表区 el-card + 表格 border |
| 店铺切换 |
仅 Navbar；业务页禁止展示店铺选择器（§5 商家端店铺上下文） |
2. 文件清单
| 类型 |
路径 |
说明 |
| 列表页 |
ruoyi-ui/src/views/agri/seller/goods/index.vue |
检索、Tab、列表、批量操作、发品/编辑弹窗 |
| 详情抽屉 |
ruoyi-ui/src/views/agri/seller/goods/detail.vue |
详情展示、行内操作 |
| 商品 API |
ruoyi-ui/src/api/agri/seller/goods.js |
列表、下拉、CRUD、submit、offShelf、delete |
| 店铺上下文 |
ruoyi-ui/src/api/agri/seller/context.js + utils/sellerShop.js |
X-Shop-Id |
组件 name（keep-alive）： AgriSellerGoods
3. 菜单与路由
| 菜单名称 |
组件路径 |
路由 path（建议） |
权限标识 |
| 商品列表 |
agri/seller/goods/index |
seller/goods |
agri:seller:goods:list |
上级菜单： 店铺经营管理端 → 商品管理
| 按钮权限 |
标识 |
| 详情 |
agri:seller:goods:query |
| 添加 / 编辑 / 提交上架 |
agri:seller:goods:edit |
| 添加 |
agri:seller:goods:add |
| 下架 |
agri:seller:goods:offshelf |
| 删除 |
agri:seller:goods:remove |
4. 页面结构
商品列表
├── 检索区（el-card）
│ ├── 商品编号 goodsSn（模糊）
│ ├── 商品名称 goodsName（模糊）
│ └── 商品分类 categoryId（平台二级下拉）
├── 列表区（el-card + border 表格）
│ ├── 状态 Tab：全部 / 未上架 / 待审核 / 出售中 / 审核失败 / 已下架
│ ├── 工具栏：添加商品、批量提交上架、批量下架、批量删除
│ ├── 列：编号、主图、名称、售价、库存、销量、商品分类、店铺分类、状态
│ └── 行操作（按状态）：详情、编辑、提交上架、下架、删除
├── 详情抽屉 detail.vue（72% 宽）
│ ├── 基础 / 分类 / 状态 / 服务快照 / 详情 HTML
│ └── 操作：编辑、提交上架、下架、删除（can* 或状态驱动）
└── 添加/编辑弹窗（720px · v1.0 单规格）
├── 商品分类 categoryId（必填，平台二级）
├── 店铺商品分类 shopCategoryId（选填，本店二级）
├── 属性模版 attrTemplateId（选填）
│ ├── 下拉 GET /agri/seller/goods/attrTemplateOptions
│ ├── 选用预填 GET /agri/seller/goods/attrTemplate/{templateId}
│ └── 属性 attributes[] / 规格 specs[]（itemName + values[]，可增删改）
├── 商品名称、主图、销售价、库存
├── 商品详情 detailContent（Editor 富文本）
└── 服务说明 serviceIds（多选；新建默认勾选 defaultShow）
v1.0 未实现（后续扩展）： 多图 gallery、多规格 SKU、运费模版、独立 form 路由页。
已实现（后端）： attrTemplateId + attributes/specs 保存与详情回显（biz_goods_attr）；前端发品表单待接入。
5. 店铺上下文（X-Shop-Id）
| 步骤 |
说明 |
页面 created |
getSellerContext() → setSellerShopContext |
| 每次 API |
sellerShopHeaders() 注入 X-Shop-Id |
| 切换店铺 |
仅 Navbar → location.reload() |
6. 接口封装
Base URL： /agri/seller/goods
| 前端方法 |
HTTP |
路径 |
用途 |
listSellerGoods |
GET |
/list |
分页列表 |
sellerGoodsCategoryOptions |
GET |
/categoryOptions |
平台二级分类 |
sellerGoodsShopCategoryOptions |
GET |
/shopCategoryOptions |
本店二级店铺分类 |
sellerAttrTemplateOptions |
GET |
/attrTemplateOptions |
本店属性模版下拉 |
getSellerAttrTemplateDetail |
GET |
/attrTemplate/{templateId} |
选用模版预填 attributes/specs |
sellerGoodsServiceOptions |
GET |
/serviceOptions |
{ all, defaultShow } |
getSellerGoods |
GET |
/{goodsId} |
详情 |
addSellerGoods |
POST |
/ |
新增 → status=0 |
updateSellerGoods |
PUT |
/ |
编辑（不改状态） |
submitSellerGoods |
PUT |
/{goodsId}/submit |
单条提交上架 |
submitSellerGoodsBatch |
PUT |
/submit |
批量提交 |
offShelfSellerGoods |
PUT |
/{goodsId}/offShelf |
单条下架 |
offShelfSellerGoodsBatch |
PUT |
/offShelf |
批量下架 |
delSellerGoods |
DELETE |
/{goodsIds} |
删除（逗号分隔批量） |
6.1 列表 Query
| 字段 |
说明 |
| pageNum, pageSize |
分页 |
| goodsSn, goodsName |
模糊 |
| categoryId |
平台二级分类 ID |
| goodsStatusQuery |
0～4；Tab 切换写入；不传查全部 |
注意：商家列表用 goodsStatusQuery，与平台 /agri/goods/list 的 goodsStatus 字段名不同。
6.2 商品状态（goods_status）
| 值 |
标签 |
行操作 |
| 0 |
未上架 |
详情、编辑、提交上架、删除 |
| 1 |
待审核 |
详情、编辑 |
| 2 |
出售中 |
详情、编辑、下架 |
| 3 |
审核失败 |
详情、编辑、提交上架、删除 |
| 4 |
已下架 |
详情、编辑、提交上架、删除 |
6.3 保存体（GoodsSaveDTO · v1.0）
| 字段 |
新增 |
编辑 |
说明 |
| categoryId |
必填 |
必填 |
平台二级 |
| shopCategoryId |
选填 |
选填 |
本店二级 |
| attrTemplateId |
选填 |
选填 |
本店有效属性模版 |
| attributes |
选填 |
选填 |
[{ itemName, values[] }] 属性项 |
| specs |
选填 |
选填 |
[{ itemName, values[] }] 规格项 |
| goodsName |
必填 |
必填 |
max 200 |
| mainPic |
必填 |
必填 |
image-upload |
| detailContent |
必填 |
必填 |
富文本 |
| salePrice |
必填 |
必填 |
≥0 |
| stock |
必填 |
必填 |
整数 ≥0 |
| serviceIds |
选填 |
选填 |
数组 |
| goodsId |
— |
必填 |
编辑 |
| goodsStatus |
禁止 |
禁止 |
后端拒收 |
保存后状态 不变（新建为 0）；须单独调用 submit 接口上架。
6.4 批量操作规则
| 操作 |
允许状态 |
失败策略 |
| 批量提交 |
0、3、4 |
含其他状态 → 整批失败，data.reasons |
| 批量下架 |
2 |
同上 |
| 批量删除 |
0、3、4 |
同上 |
前端通过 selection.every(...) 预禁用按钮；最终以服务端校验为准。
6.5 详情 VO 扩展字段
| 字段 |
用途 |
| canSubmit / canOffShelf / canDelete / canEdit |
按钮显隐 |
| rejectReason |
审核失败展示 |
| services[] |
服务快照；编辑时回显 serviceIds |
| shopCategoryPath |
店铺分类路径 |
| attrTemplateId / attrTemplateName |
属性模版引用与名称 |
| attributes / specs |
属性/规格快照（同保存体结构） |
7. 交互要点
| 场景 |
行为 |
| 添加成功 |
提示「未上架」；不自动提交 |
| 提交成功 |
展示返回的 goodsStatusLabel（待审核 / 出售中） |
| 下架 |
二次确认「C 端不可购买」 |
| 删除 |
二次确认；待审核/出售中不可删 |
| 审核失败 |
详情抽屉红色展示 rejectReason |
| 服务默认勾选 |
serviceOptions.defaultShow → 新建表单 serviceIds |
8. 联调检查清单
9. 修订记录
| 版本 |
说明 |
| v1.0 |
首版：列表 + v1.0 单规格发品弹窗 + 详情抽屉 + 状态流转操作 |
| v1.1 |
对齐后端 attrTemplateId：保存体/详情字段；下拉走属性模版模块 |
| v1.2 |
对齐 biz_goods_attr：attributes/specs 保存体；goods 侧预填/下拉 API |
文档版本：v1.2 · 关联《商品列表功能需求.md》v1.4、《店铺商品列表技术方案.md》v1.4
