Skip to content

商品管理 PRD ​

文档信息 ​

项目内容
文档编号PRD-06-01
文档名称商品管理
产品名称PMForge 项目管理平台
所属模块mall
文档版本v2.2
最后更新2026-11-18
文档状态已更新
实施状态预留(已编译,未接入运行时)
优先级P0

1. 功能概述 ​

1.1 功能定位 ​

商品管理是 PMForge 商城模块的"地基"——就像线下超市需要先搭好货架、贴好标签、摆好商品,顾客才能找到并购买。本模块承担商品全生命周期管理能力,涵盖分类体系搭建 → 品牌库维护 → 属性/规格定义 → 商品录入(SPU+SKU) → 上下架管理 → 运费模板 → 评价管理完整链路。

通俗理解:如果把商城比作一家超市,商品管理就是"货架+商品标签+价签"的集合。分类是货架的分区(食品区、日用品区),品牌是厂商标签,SPU 是一个商品(如"可口可乐"),SKU 是具体规格(如"330ml 罐装")。

本模块为交易管理、营销管理、统计分析等上层业务提供标准化商品数据支撑,是商城运转的核心基础设施。

1.2 目标用户 ​

用户类型核心诉求使用频率
平台运营人员快速搭建分类/品牌/属性体系,为商品上架做好"基础设施"准备初期高频,日常中频
商品管理员高效录入商品、灵活配置 SKU 组合、批量操作提升效率每日高频
店铺运营快速上下架、设置推荐位、调整排序,配合营销活动每日高频
客服/售后人员查看商品信息解答用户疑问、处理评价回复每日中频
C 端消费者快速找到目标商品、清晰了解商品信息、顺畅地下单购买每日高频

1.3 业务价值 ​

价值维度具体收益衡量指标
降低录入成本属性模板 + SKU 矩阵自动生成,减少重复劳动单品录入时间 < 3 分钟
提升选购效率清晰的分类导航 + 精准搜索 + 多维筛选用户找到目标商品 < 30 秒
保障数据一致SPU/SKU 标准化管理,避免信息混乱商品信息完整度 > 95%
提升转化率推荐标签 + 评价展示 + 划线价对比商品详情页转化率提升 15%+
支撑营销玩法商品数据为优惠券、秒杀、拼团等提供基础活动商品配置 < 5 分钟

1.4 功能范围 ​

功能分类后台管理端前台用户端
商品分类管理✅❌
商品品牌管理✅❌
商品属性/规格管理✅❌
商品列表管理✅❌
商品详情编辑✅❌
商品状态管理(上下架/售罄/推荐)✅❌
运费模板管理✅❌
商品评价管理✅❌
分类导航❌✅
商品列表浏览/搜索❌✅
商品详情/规格选择❌✅
评价展示❌✅

2. 用户场景 ​

2.1 用户角色 ​

角色描述核心诉求
平台运营(李姐)负责商品体系顶层设计快速搭好分类/品牌/属性框架,让商品管理员能顺利录入
商品管理员(小王)负责商品数据录入与维护高效录入商品、灵活配 SKU、批量操作省时间
店铺运营(小张)负责商品日常运营快速上下架、设推荐位、配合活动调价格
客服(小陈)处理用户评价与售后查看评价、回复评价、管控不当内容
C 端消费者(小赵)浏览和购买商品快速找到商品、看清信息、顺畅下单

2.2 使用场景 ​

场景1:运营李姐搭建商品分类体系 ​

  • 背景:商城上线初期,需要搭建"项目管理书籍"品类的全部分类框架
  • 操作步骤:
    1. 李姐登录后台 → 进入"商品管理 > 分类管理"
    2. 点击"新增分类" → 填写"项目管理书籍" → 保存为一级分类
    3. 选中"项目管理书籍" → 新增子分类"PMP认证"、"PRINCE2"、"敏捷开发"
    4. 在"敏捷开发"下再新增"Scrum"、"看板"两个三级分类
    5. 拖拽调整排序 → 上传分类图标 → 启用所有分类
  • 期望:分类层级清晰、支持拖拽排序、图标可灵活配置
  • 验收标准:
AC编号验收条件
AC-01最多创建到三级分类,尝试创建四级时系统提示"最多支持三级分类"
AC-02同一父级下创建同名分类时,提示"分类名称已存在"
AC-03隐藏分类后,前台分类导航和列表均不展示该分类及其子分类
AC-04拖拽排序后前台展示顺序与后台设置一致

场景2:商品管理员小王批量创建多规格商品 ​

  • 背景:新到一批 T 恤商品,需要录入"颜色(红/蓝/黑)× 尺码(S/M/L)"共 9 个 SKU
  • 操作步骤:
    1. 小王进入"商品列表" → 点击"新增商品"
    2. 选择分类"服装>T恤" → 系统自动加载该分类的属性模板
    3. 填写商品名称、副标题、品牌等基本信息
    4. 在"销售规格"区域:勾选颜色(红/蓝/黑)和尺码(S/M/L)
    5. 系统自动生成 3×3=9 个 SKU 矩阵 → 逐一填写价格、库存、SKU 图片
    6. 上传商品主图 → 编辑商品详情(富文本) → 关联运费模板
    7. 点击"保存为草稿" → 检查无误后点击"上架"
  • 期望:SKU 矩阵自动生成、批量填充高效、支持模板复用
  • 验收标准:
AC编号验收条件
AC-01选择 3 个颜色 + 3 个尺码后,自动生成 9 行 SKU 矩阵
AC-02SKU 价格必须 > 0,输入 0 或负数时提示"售价必须大于 0"
AC-03库存输入非整数时提示"库存必须为整数"
AC-04市场价(划线价)低于售价时提示"市场价不能低于售价"
AC-05保存草稿后商品不出现在前台,上架后前台立即可见

场景3:店铺运营小张配合促销活动 ​

  • 背景:618 大促前,需要将 50 个商品设置"热卖"标签并批量调价
  • 操作步骤:
    1. 小张进入"商品列表" → 按分类筛选出目标商品
    2. 勾选 50 个商品 → 点击"批量操作 > 设置推荐" → 选择"热卖"
    3. 再次勾选 → "批量操作 > 修改价格" → 统一打 8 折
    4. 活动期间监控库存 → 某商品售罄后系统自动标记"售罄"
    5. 补货后小张将该商品恢复为"上架"状态
  • 期望:批量操作高效、状态变更即时生效、售罄自动处理
  • 验收标准:
AC编号验收条件
AC-01批量操作 50 条商品在 5 秒内完成
AC-02所有 SKU 库存为 0 时,商品状态自动变为"售罄"
AC-03售罄商品在前台列表不展示,直接访问 URL 显示"商品已下架"
AC-04补货后手动上架,前台立即恢复展示和购买

场景4:消费者小赵搜索并购买商品 ​

  • 背景:小赵想买一本 Scrum 相关的书
  • 操作步骤:
    1. 小赵进入商城 → 在搜索框输入"Scrum"
    2. 搜索结果列表展示相关商品 → 按"销量"排序
    3. 点击目标商品 → 进入详情页 → 看到主图、价格、划线价、销量、好评率
    4. 选择规格"精装版" → 价格和库存实时联动
    5. 查看评价区域 → 好评率 96%,翻看几条带图评价
    6. 点击"加入购物车" → 去购物车结算
  • 期望:搜索精准、加载快速、规格选择直观、评价真实可信
  • 验收标准:
AC编号验收条件
AC-01搜索"Scrum"在 800ms 内返回结果
AC-02选择规格后价格变化延迟 < 100ms
AC-03库存为 0 的规格选项置灰不可选
AC-04未选完所有规格时,"加入购物车"按钮不可点击
AC-05未登录用户点击"加入购物车"跳转登录页

场景5:客服小陈处理商品评价 ​

  • 背景:有用户给某商品打了 1 星差评并附带了图片
  • 操作步骤:
    1. 小陈收到"新差评待处理"通知 → 进入"评价管理"
    2. 筛选"差评" → 找到该条评价 → 查看评价内容和图片
    3. 点击"回复" → 输入回复内容 → 保存
    4. 如果评价包含不当内容(如广告/辱骂),点击"隐藏"
  • 期望:评价实时展示、回复便捷、可对不当评价进行管控
  • 验收标准:
AC编号验收条件
AC-01用户提交评价后,后台评价列表 1 秒内可见
AC-02每条评价只能回复一次,已回复后"回复"按钮置灰
AC-03隐藏评价后前台不展示,但后台仍可查看
AC-04好评率 = 好评数 / 总评价数 × 100%,实时更新

3. 功能需求 ​

3.1 后台管理端 ​

3.1.1 功能清单 ​

功能优先级说明
商品分类管理P0三级分类树维护,含增删改查、排序、状态管理
商品品牌管理P0品牌增删改查、排序、状态管理
商品属性管理P0属性/规格/属性模板管理
商品列表管理P0商品分页查询、多维度筛选、搜索
商品创建/编辑P0商品基本信息、SKU、详情、SEO 设置
商品状态管理P0上下架、售罄处理、推荐设置
批量操作P1批量上下架、批量修改分类、批量删除
商品导出P1导出商品数据为 Excel
运费模板管理P1运费模板增删改查、配送区域设置
商品评价管理P1评价列表、回复、显示/隐藏、统计

3.1.2 商品分类管理 ​

页面描述:

操作流程:

  1. 点击"新增分类"按钮
  2. 选择父级分类(新增一级分类时不选择)
  3. 填写分类名称、图标、排序值
  4. 设置是否显示
  5. 保存

业务规则:

规则编号规则描述设计原因
R-01最多支持三级分类,不允许创建四级分类过深的分类层级会增加用户浏览成本,三级已满足绝大多数电商品类需求
R-02分类名称在同一父级下唯一避免前台导航出现同名分类造成用户困惑
R-03删除分类时,若该分类下存在子分类则不允许删除防止误删导致子分类成为"孤儿"数据
R-04删除分类时,若该分类下关联了商品则不允许删除商品必须有分类归属,强制先迁移商品
R-05隐藏分类后,前台不展示该分类及其子分类,但后台仍可见支持临时隐藏(如季节性分类),不丢失配置数据
R-06分类排序值越小越靠前,默认值为 0提供灵活的排序能力,支持在任意两个分类之间插入
R-07分类图标支持 PNG/JPG 格式,建议尺寸 64×64统一前台分类导航的视觉规范
R-08一级分类支持配置首页展示大图用于首页分类入口的视觉展示

接口设计:

接口名称请求方式接口路径说明
获取分类树GET/admin-api/product/category/list获取完整分类树结构
获取分类详情GET/admin-api/product/category/get获取单个分类详情
创建分类POST/admin-api/product/category/create创建新分类
更新分类PUT/admin-api/product/category/update更新分类信息
删除分类DELETE/admin-api/product/category/delete删除分类
更新分类排序PUT/admin-api/product/category/update-sort批量更新排序值
获取分类下拉列表GET/admin-api/product/category/simple-list用于下拉选择(仅返回 id/name/parentId)

创建分类请求参数:

参数名类型必填说明
parentIdLong是父分类ID,一级分类传 0
nameString是分类名称,最多 20 字符
iconString否分类图标 URL
picUrlString否分类大图 URL
descriptionString否分类描述,最多 200 字符
sortInteger否排序值,默认 0
statusInteger是状态(0-显示 1-隐藏)

3.1.3 商品品牌管理 ​

页面描述:

业务规则:

规则编号规则描述设计原因
R-01品牌名称同一租户内唯一避免商品关联品牌时出现歧义
R-02删除品牌时,若该品牌下关联了商品则不允许删除已上架商品的品牌信息不能丢失
R-03隐藏品牌后,前台不展示该品牌,但不影响已关联商品的上架状态品牌和商品的上架状态独立管理
R-04Logo 支持 PNG/JPG 格式,建议尺寸 200×100统一前台品牌展示的视觉规范
R-05排序值越小越靠前常用品牌可排在前面

接口设计:

接口名称请求方式接口路径说明
获取品牌分页GET/admin-api/product/brand/page获取品牌分页列表
获取品牌详情GET/admin-api/product/brand/get获取单个品牌详情
创建品牌POST/admin-api/product/brand/create创建新品牌
更新品牌PUT/admin-api/product/brand/update更新品牌信息
删除品牌DELETE/admin-api/product/brand/delete删除品牌
获取品牌下拉列表GET/admin-api/product/brand/simple-list用于下拉选择

3.1.4 商品属性管理 ​

页面描述:

关键概念:属性分为"普通属性"和"销售属性"两类——

  • 普通属性(也叫商品参数):描述商品特性,如作者、ISBN、出版社。用户看到商品详情时,这些信息以"规格参数表"形式展示。
  • 销售属性(也叫规格):用于区分不同 SKU 的维度,如颜色、尺码。用户选择销售属性后,系统定位到具体的 SKU(价格、库存随之变化)。

业务规则:

规则编号规则描述设计原因
R-01属性分为普通属性和销售属性两种类型两种属性用途不同:普通属性展示参数,销售属性生成 SKU 矩阵
R-02普通属性关联分类后,该分类下的商品需填写对应属性值确保同类商品信息完整度一致
R-03销售属性用于生成 SKU 组合矩阵如"颜色3个×尺码4个=12个SKU",系统自动生成
R-04同一分类下属性名称唯一避免商品编辑时出现重复属性
R-05删除属性时,若已关联商品则不允许删除已录入的商品属性数据不能丢失
R-06属性模板关联分类,定义该分类下商品的默认属性组合同类商品属性大体相同,模板减少重复配置
R-07创建商品时选择属性模板可自动填充属性新品录入效率提升 50%+
R-08销售属性最多支持 3 个维度组合超过 3 维的 SKU 组合过于复杂,用户体验差

接口设计:

接口名称请求方式接口路径说明
获取属性分页GET/admin-api/product/property/page获取属性分页列表
获取属性详情GET/admin-api/product/property/get获取属性详情(含属性值列表)
创建属性POST/admin-api/product/property/create创建新属性
更新属性PUT/admin-api/product/property/update更新属性信息
删除属性DELETE/admin-api/product/property/delete删除属性
创建属性值POST/admin-api/product/property-value/create创建属性值
更新属性值PUT/admin-api/product/property-value/update更新属性值
删除属性值DELETE/admin-api/product/property-value/delete删除属性值
获取分类下的属性列表GET/admin-api/product/property/list-by-category根据分类 ID 获取属性列表
获取属性模板分页GET/admin-api/product/attr-template/page获取属性模板分页列表
创建属性模板POST/admin-api/product/attr-template/create创建属性模板
更新属性模板PUT/admin-api/product/attr-template/update更新属性模板
删除属性模板DELETE/admin-api/product/attr-template/delete删除属性模板

3.1.5 商品列表管理 ​

页面描述:

业务规则:

规则编号规则描述设计原因
R-01默认按创建时间倒序排列最新录入的商品优先展示,方便管理员确认
R-02商品售价取所有 SKU 中最低价格展示列表展示"起步价"吸引用户点击
R-03库存取所有 SKU 库存之和展示反映商品总可售数量
R-04销量取所有 SKU 销量之和展示反映商品总销售表现
R-05逻辑删除,商品删除后不物理删除保留历史数据,关联的订单/评价数据不断裂
R-06已参与进行中活动的商品不允许直接删除防止活动页面出现"商品不存在"的异常
R-07批量操作单次最多 100 条防止大批量操作导致数据库压力过大
R-08导出单次最多 10000 条,超过则异步导出大数据量导出改为异步任务,不阻塞用户操作

接口设计:

接口名称请求方式接口路径说明
获取商品分页GET/admin-api/product/spu/page获取商品分页列表
获取商品详情GET/admin-api/product/spu/get-detail获取商品完整详情
创建商品POST/admin-api/product/spu/create创建新商品
更新商品PUT/admin-api/product/spu/update更新商品信息
删除商品DELETE/admin-api/product/spu/delete删除商品
商品上架/下架PUT/admin-api/product/spu/update-status更新商品状态
批量上架/下架PUT/admin-api/product/spu/batch-update-status批量更新状态
批量删除DELETE/admin-api/product/spu/batch-delete批量删除
批量修改分类PUT/admin-api/product/spu/batch-update-category批量修改分类
导出商品GET/admin-api/product/spu/export导出商品 Excel
获取商品统计GET/admin-api/product/spu/get-count获取各状态商品数量

3.1.6 商品详情编辑 ​

页面描述:

业务规则:

规则编号规则描述设计原因
R-01商品名称必填,最多 120 字符过长的标题影响前台展示和搜索体验
R-02分类必选,支持选择到最末级分类商品必须有明确的分类归属
R-03商品主图至少 1 张,最多 10 张,第 1 张为默认主图主图是用户第一印象,至少要有 1 张
R-04商品视频选填,最多 1 个,MP4 格式,最大 50MB视频能提升转化率,但需控制存储成本
R-05SKU 至少 1 个;未配置销售规格时自动生成默认 SKU确保每个商品都有可购买的规格
R-06SKU 价格必须 > 0,最多 2 位小数价格精度控制,避免计算误差
R-07SKU 库存必须 >= 0,整数库存不能为负数是基本业务约束
R-08市场价(划线价)必须 >= 售价划线价高于售价才有"优惠感"的意义
R-09商品详情支持富文本编辑,可插入图片/表格/链接满足多样化的商品展示需求
R-10分类属性中必填属性必须填写保证同类商品信息完整度一致
R-11商品编码(SPU 级别)全局唯一商品编码是系统间交互的唯一标识
R-12支持保存为草稿状态商品录入可能需要分步完成,草稿避免数据丢失

接口设计:

接口名称请求方式接口路径说明
创建商品POST/admin-api/product/spu/create创建商品(含 SKU)
更新商品PUT/admin-api/product/spu/update更新商品(含 SKU)
获取商品详情GET/admin-api/product/spu/get-detail获取商品完整详情

创建/更新商品请求参数:

参数名类型必填说明
nameString是商品名称
subtitleString否副标题
categoryIdLong是分类 ID
brandIdLong否品牌 ID
keywordString否关键词,多个用逗号分隔
picUrlsString[]是商品图片 URL 列表
videoUrlString否商品视频 URL
descriptionString否商品详情(HTML)
sortInteger否排序值,默认 0
statusInteger否状态(0-草稿 1-上架 2-下架 3-售罄)
recommendTypesInteger[]否推荐类型列表
deliveryTemplateIdLong否运费模板 ID
seoTitleString否SEO 标题
seoDescriptionString否SEO 描述
seoKeywordsString否SEO 关键词
attrValuesList否商品属性值列表
skusList是SKU 列表

SKU 请求参数:

参数名类型必填说明
nameString是SKU 名称(规格组合描述,如"红色/XL")
picUrlString否SKU 图片 URL
priceDecimal是售价
marketPriceDecimal否市场价(划线价)
costPriceDecimal否成本价
stockInteger是库存
barCodeString否条形码
attrValuesList是规格属性值列表(属性 ID + 属性值 ID)

3.1.7 商品状态管理 ​

状态流转图:

业务规则:

规则编号规则描述设计原因
R-01商品状态:草稿(0)、上架(1)、下架(2)、售罄(3)四种状态覆盖商品从创建到售完的完整生命周期
R-02上架时校验:至少一个 SKU 库存 > 0,至少一张主图无库存或无图片的商品上架无意义
R-03下架即时生效,前台立即不可见/不可购买问题商品需要紧急下架能力
R-04所有 SKU 库存为 0 时自动标记为售罄自动化管理,避免"幽灵商品"(可看不可买)
R-05售罄商品补货后可手动恢复为上架补货是常见操作,需要便捷的恢复路径
R-06推荐类型:精品(1)、新品(2)、热卖(3)、推荐(4)多维度推荐标签,支持营销场景
R-07推荐类型为多选,一个商品可同时拥有多个标签一个商品可以同时是"新品"和"热卖"
R-08仅上架状态的商品支持设置推荐下架/售罄商品不应出现在推荐位

3.1.8 运费模板管理 ​

页面描述:

业务规则:

规则编号规则描述设计原因
R-01计费方式:按件(1)、按重量(2)、按体积(3)不同商品类型适用不同计费方式
R-02每个租户至少需要一个默认运费模板新商品必须能关联运费模板
R-03删除运费模板时,若有关联商品则不允许删除已关联商品的运费计算不能断裂
R-04配送区域支持按省/市/区选择,支持多选不同地区运费差异是常见业务需求
R-05运费设置:首件/首重/首体积费用 + 续件/续重/续体积费用阶梯计费是物流行业标准模式
R-06包邮条件支持:满额包邮、满件包邮包邮是常见促销手段,提升客单价
R-07未配置的区域默认使用"默认运费"规则避免新增区域时出现"无法计算运费"的问题
R-08支持指定区域不配送部分商品无法配送到偏远地区

接口设计:

接口名称请求方式接口路径说明
获取运费模板分页GET/admin-api/trade/delivery/express-template/page获取分页列表
获取运费模板详情GET/admin-api/trade/delivery/express-template/get获取详情
创建运费模板POST/admin-api/trade/delivery/express-template/create创建模板
更新运费模板PUT/admin-api/trade/delivery/express-template/update更新模板
删除运费模板DELETE/admin-api/trade/delivery/express-template/delete删除模板
获取模板下拉列表GET/admin-api/trade/delivery/express-template/simple-list用于下拉选择

3.1.9 商品评价管理 ​

页面描述:

业务规则:

规则编号规则描述设计原因
R-011-2 星为差评,3 星为中评,4-5 星为好评行业标准评分分级方式
R-02评价支持图片,最多 9 张带图评价更有说服力,提升购买转化率
R-03商家可对每条评价回复一次一次回复避免"刷回复"嫌疑
R-04隐藏评价后前台不展示,但后台仍可见不当评价需要管控,但保留审计记录
R-05评价统计实时更新好评率是用户购买决策的重要参考
R-06匿名评价时前台展示"匿名用户"保护用户隐私

接口设计:

接口名称请求方式接口路径说明
获取评价分页GET/admin-api/product/comment/page获取评价分页列表
获取评价详情GET/admin-api/product/comment/get获取评价详情
回复评价PUT/admin-api/product/comment/reply商家回复评价
隐藏/显示评价PUT/admin-api/product/comment/update-status更新展示状态
获取评价统计GET/admin-api/product/comment/statistics获取统计数据

3.2 前台用户端 ​

3.2.1 功能清单 ​

功能优先级说明
分类导航P0展示分类树,支持展开/收起
商品列表P0分类/搜索进入列表,支持筛选/排序
商品搜索P0关键词搜索,支持搜索建议
商品详情P0展示商品信息、规格选择、评价
规格选择P0多规格联动选择、价格联动
评价展示P1商品评价列表、好评率、图片评价

3.2.2 分类导航 ​

业务规则:

规则编号规则描述
R-01仅展示状态为"显示"的分类
R-02按排序值升序排列
R-03分类下无商品时仍展示分类入口(点击进入为空列表)
R-04一级分类支持展示配置的大图

接口设计:

接口名称请求方式接口路径说明
获取前台分类树GET/app-api/product/category/list获取前台可见分类树

3.2.3 商品列表与搜索 ​

业务规则:

规则编号规则描述
R-01仅展示上架状态的商品
R-02展示价格为该商品最低 SKU 价格
R-03默认按综合排序(考虑推荐权重 + 销量 + 时间)
R-04分页加载,每页 20 条
R-05推荐标签商品展示对应角标(精品/新品/热卖)

接口设计:

接口名称请求方式接口路径说明
获取商品分页GET/app-api/product/spu/page获取前台商品分页列表
搜索商品GET/app-api/product/spu/search关键词搜索商品
获取搜索建议GET/app-api/product/spu/get-suggest获取搜索关键词建议

3.2.4 商品详情 ​

业务规则:

规则编号规则描述
R-01选择规格后价格和库存实时联动变化
R-02库存为 0 的规格选项置灰不可选
R-03库存不足时展示"缺货"提示
R-04加入购物车需先选择完整规格(所有销售属性均已选择)
R-05未登录用户点击加购/购买跳转登录页
R-06商品详情图片采用懒加载
R-07市场价低于或等于售价时不展示市场价

接口设计:

接口名称请求方式接口路径说明
获取商品详情GET/app-api/product/spu/get-detail获取商品完整详情

3.2.5 评价展示 ​

业务规则:

规则编号规则描述
R-01仅展示状态为"显示"的评价
R-02匿名评价展示为"匿名用户"
R-03评价按时间倒序排列
R-04分页加载,每页 10 条

接口设计:

接口名称请求方式接口路径说明
获取评价分页GET/app-api/product/comment/page获取前台评价分页
获取评价统计GET/app-api/product/comment/statistics获取商品评价统计

4. 非功能需求 ​

4.1 性能要求 ​

指标目标值说明
商品列表查询< 500ms含分页、筛选条件
商品详情查询< 300ms含 SKU 列表、属性值
分类树查询< 200ms全量分类树
商品搜索< 800ms含关键词分析
搜索建议< 200ms用户输入即响应
商品创建/更新< 1000ms含 SKU 矩阵保存
批量操作(100 条)< 5s批量上下架/删除
导出 10000 条< 60s异步导出
SKU 规格联动< 100ms前端计算,无需后端请求
前台商品列表页< 2s含图片懒加载
前台商品详情页< 3s含图片懒加载

4.2 安全要求 ​

要求实现方式
权限控制后台所有操作校验 RBAC 操作权限
数据隔离多租户通过 tenant_id 字段严格隔离
图片安全上传时校验文件格式和大小,防止恶意文件上传
XSS 防护商品详情 HTML 内容经 XSS 过滤后存储
SQL 注入防护搜索接口使用参数化查询
价格安全价格和库存操作进行合理性校验(> 0、非负整数等)
操作审计上下架、删除、价格变更等关键操作记录操作日志
成本价保护成本价仅对特定角色可见,前台接口不返回

4.3 兼容性要求 ​

端要求
PC 后台Chrome 80+、Firefox 75+、Safari 13+、Edge 80+
PC 前台Chrome 80+、Firefox 75+、Safari 13+、Edge 80+
移动端前台iOS Safari 12+、Android Chrome 80+、微信内置浏览器
屏幕适配后台 ≥ 1280px;前台 375px-1920px 响应式
图片格式JPG、PNG、WebP;视频 MP4

5. 数据设计 ​

5.1 核心数据表 ​

5.1.1 商品分类表(product_category) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT分类 ID
parent_idBIGINTNOT NULL, DEFAULT 0父分类 ID,一级为 0
nameVARCHAR(100)NOT NULL分类名称
iconVARCHAR(512)分类图标 URL
pic_urlVARCHAR(512)分类大图 URL
descriptionVARCHAR(500)分类描述
sortINTDEFAULT 0排序值
statusTINYINTNOT NULL, DEFAULT 00-显示 1-隐藏
levelTINYINTNOT NULL层级(1/2/3)
creatorVARCHAR(64)创建者
create_timeDATETIMENOT NULL创建时间
updaterVARCHAR(64)更新者
update_timeDATETIMENOT NULL更新时间
deletedBIT(1)NOT NULL, DEFAULT 0删除标记
tenant_idBIGINTNOT NULL租户 ID

索引设计:idx_parent_id (parent_id)、uk_name_parent (parent_id, name, tenant_id) UNIQUE

5.1.2 商品品牌表(product_brand) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT品牌 ID
nameVARCHAR(100)NOT NULL品牌名称
pic_urlVARCHAR(512)品牌 Logo URL
descriptionVARCHAR(1000)品牌描述
sortINTDEFAULT 0排序值
statusTINYINTNOT NULL, DEFAULT 00-启用 1-禁用
creator / create_time / updater / update_time / deleted / tenant_id通用字段

索引设计:uk_name_tenant (name, tenant_id) UNIQUE

5.1.3 商品 SPU 表(product_spu) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT商品 ID
nameVARCHAR(200)NOT NULL商品名称
subtitleVARCHAR(300)副标题
category_idBIGINTNOT NULL分类 ID
brand_idBIGINT品牌 ID
keywordVARCHAR(500)关键词
descriptionTEXT商品详情(HTML)
pic_urlsVARCHAR(2000)商品图片 URL 列表(JSON 数组)
video_urlVARCHAR(512)商品视频 URL
statusTINYINTNOT NULL, DEFAULT 00-草稿 1-上架 2-下架 3-售罄
sortINTDEFAULT 0排序值
recommend_typesVARCHAR(100)推荐类型(JSON 数组)
priceDECIMAL(10,2)展示价格(最低 SKU 价格)
market_priceDECIMAL(10,2)市场价(划线价)
stockINTDEFAULT 0总库存
sales_countINTDEFAULT 0总销量
delivery_template_idBIGINT运费模板 ID
seo_titleVARCHAR(200)SEO 标题
seo_descriptionVARCHAR(500)SEO 描述
seo_keywordsVARCHAR(300)SEO 关键词
creator / create_time / updater / update_time / deleted / tenant_id通用字段

索引设计:idx_category_id (category_id)、idx_brand_id (brand_id)、idx_status (status, tenant_id)、idx_sort (sort, status)

5.1.4 商品 SKU 表(product_sku) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENTSKU ID
spu_idBIGINTNOT NULL商品 SPU ID
nameVARCHAR(200)NOT NULLSKU 名称(规格组合描述)
pic_urlVARCHAR(512)SKU 图片 URL
priceDECIMAL(10,2)NOT NULL售价
market_priceDECIMAL(10,2)市场价(划线价)
cost_priceDECIMAL(10,2)成本价
stockINTNOT NULL, DEFAULT 0库存
sales_countINTDEFAULT 0SKU 销量
bar_codeVARCHAR(100)条形码
attr_valuesVARCHAR(1000)规格属性值(JSON 数组)
creator / create_time / updater / update_time / deleted / tenant_id通用字段

索引设计:idx_spu_id (spu_id)、uk_bar_code (bar_code, tenant_id) UNIQUE

5.1.5 商品属性表(product_property) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT属性 ID
nameVARCHAR(100)NOT NULL属性名称
category_idBIGINTNOT NULL关联分类 ID
typeTINYINTNOT NULL1-普通属性 2-销售属性
sortINTDEFAULT 0排序值
statusTINYINTNOT NULL, DEFAULT 00-启用 1-禁用
requiredBIT(1)DEFAULT 0是否必填
creator / create_time / updater / update_time / deleted / tenant_id通用字段

5.1.6 商品属性值表(product_property_value) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT属性值 ID
property_idBIGINTNOT NULL属性 ID
nameVARCHAR(200)NOT NULL属性值内容
sortINTDEFAULT 0排序值
creator / create_time / updater / update_time / deleted / tenant_id通用字段

5.1.7 属性模板表(product_attr_template) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT模板 ID
nameVARCHAR(100)NOT NULL模板名称
category_idBIGINTNOT NULL关联分类 ID
property_idsVARCHAR(2000)关联属性 ID 列表(JSON 数组)
statusTINYINTNOT NULL, DEFAULT 00-启用 1-禁用
sortINTDEFAULT 0排序值
creator / create_time / updater / update_time / deleted / tenant_id通用字段

5.1.8 商品评价表(product_comment) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT评价 ID
user_idBIGINTNOT NULL评价用户 ID
spu_idBIGINTNOT NULL商品 SPU ID
sku_idBIGINTNOT NULLSKU ID
order_item_idBIGINTNOT NULL订单项 ID
description_scoresTINYINTNOT NULL描述评分(1-5)
benefit_scoresTINYINTNOT NULL性价比评分(1-5)
contentVARCHAR(1000)评价内容
pic_urlsVARCHAR(2000)评价图片 URL 列表(JSON 数组)
seller_replyVARCHAR(1000)商家回复
reply_timeDATETIME回复时间
statusTINYINTNOT NULL, DEFAULT 00-显示 1-隐藏
anonymousBIT(1)DEFAULT 0是否匿名
creator / create_time / updater / update_time / deleted / tenant_id通用字段

索引设计:idx_spu_id (spu_id, status)、idx_user_id (user_id)

5.1.9 运费模板表(trade_delivery_express_template) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT模板 ID
nameVARCHAR(100)NOT NULL模板名称
charge_modeTINYINTNOT NULL1-按件 2-按重量 3-按体积
is_defaultBIT(1)DEFAULT 0是否默认模板
sortINTDEFAULT 0排序值
statusTINYINTNOT NULL, DEFAULT 00-启用 1-禁用
creator / create_time / updater / update_time / deleted / tenant_id通用字段

5.1.10 运费模板区域计费表(trade_delivery_express_template_charge) ​

字段名类型约束说明
idBIGINTPK, AUTO_INCREMENT记录 ID
template_idBIGINTNOT NULL运费模板 ID
area_idsVARCHAR(2000)NOT NULL区域 ID 列表(JSON 数组)
is_freeBIT(1)DEFAULT 0是否包邮
start_countDECIMAL(10,2)NOT NULL首件/首重/首体积
start_priceDECIMAL(10,2)NOT NULL首费
extra_countDECIMAL(10,2)NOT NULL续件/续重/续体积
extra_priceDECIMAL(10,2)NOT NULL续费
free_countINT满件包邮数量
free_priceDECIMAL(10,2)满额包邮金额
creator / create_time / updater / update_time / deleted / tenant_id通用字段

5.2 数据字典 ​

字典类型字典值说明
product_spu_status0-草稿 1-上架 2-下架 3-售罄商品状态
product_category_status0-显示 1-隐藏分类状态
product_brand_status0-启用 1-禁用品牌状态
product_property_type1-普通属性 2-销售属性属性类型
product_recommend_type1-精品 2-新品 3-热卖 4-推荐推荐类型
product_delivery_charge_mode1-按件 2-按重量 3-按体积运费计费方式
product_comment_status0-显示 1-隐藏评价状态

6. 跨模块联动 ​

6.1 联动关系总览 ​

联动模块联动方式数据流向触发时机
交易管理(06-02)商品数据被订单引用商品 → 订单用户下单时,快照商品信息(名称、价格、图片)到订单项
营销管理(06-03)活动关联商品商品 ↔ 活动创建秒杀/拼团/砍价活动时选择参与商品
统计分析(06-04)商品数据作为统计维度商品 → 统计商品维度销售统计、品类分析
支付模块(04)间接关联-订单支付时涉及商品价格计算
会员模块(05)会员价会员 → 商品不同会员等级可享不同会员价
库存管理(08-03 WMS)库存同步WMS → 商品仓库出入库时同步更新 SKU 库存
系统管理(01)操作日志商品 → 日志商品上下架、删除等操作记录审计日志

6.2 关键联动流程 ​

6.2.1 商品 → 订单(下单快照) ​

设计要点:订单中保存商品快照而非实时引用,确保即使后续商品修改名称/价格,历史订单数据不受影响。

6.2.2 商品 ↔ 营销活动 ​

6.2.3 商品 → 统计 ​

6.3 数据一致性要求 ​

场景一致性策略
下单扣库存乐观锁(version 字段),失败重试
活动锁定库存独立活动库存字段,与日常库存隔离
商品删除逻辑删除,订单中快照数据不受影响
价格变更仅影响变更后新创建的订单,历史订单价格不变
库存归零自动触发售罄状态变更,发送通知给运营

7. 附录 ​

7.1 名词解释 ​

术语通俗解释类比
SPU (Standard Product Unit)标准化产品单元,代表"一个商品"比如"iPhone 16"就是一个 SPU
SKU (Stock Keeping Unit)库存量单位,代表商品的一个具体规格"iPhone 16 黑色 256GB"就是一个 SKU
商品属性描述商品特性的参数就像人的"姓名、年龄、性别"
销售属性(规格)区分不同 SKU 的维度买衣服时选的"颜色+尺码"就是销售属性
属性模板预设的属性组合,创建商品时一键填充就像"简历模板",填好基本信息就行
运费模板定义运费计算规则的配置就像快递公司的"收费标准表"
划线价商品市场价,与售价对比展示商场里的"原价¥999 → 现价¥599"
推荐类型商品的营销标签超市货架上的"店长推荐""新品上市"标签
逻辑删除不真正删除数据,只标记为"已删除"就像把文件放进"回收站"而非永久删除
租户隔离SaaS 模式下不同客户的数据完全隔离同一栋办公楼里不同公司的门禁卡互不相通
包邮条件满足特定条件后免除运费"满 99 元包邮""满 3 件包邮"
商品状态控制商品在前台的可见性和可购买性草稿=未发布,上架=在售,下架=停售,售罄=卖完了
分类树层级结构的分类体系超市的"食品区→饮料区→碳酸饮料"
富文本支持加粗、图片、表格等格式的文本不只是纯文字,可以有颜色、排版、插图
乐观锁通过版本号防止并发冲突的机制两个人同时编辑同一文档,后保存的会提示"已被他人修改"

7.2 权限标识 ​

权限标识说明所属菜单
product:category:list查看商品分类商品管理 > 分类管理
product:category:create创建商品分类商品管理 > 分类管理
product:category:update编辑商品分类商品管理 > 分类管理
product:category:delete删除商品分类商品管理 > 分类管理
product:brand:list查看商品品牌商品管理 > 品牌管理
product:brand:create创建商品品牌商品管理 > 品牌管理
product:brand:update编辑商品品牌商品管理 > 品牌管理
product:brand:delete删除商品品牌商品管理 > 品牌管理
product:property:list查看商品属性商品管理 > 属性管理
product:property:create创建商品属性商品管理 > 属性管理
product:property:update编辑商品属性商品管理 > 属性管理
product:property:delete删除商品属性商品管理 > 属性管理
product:attr-template:list查看属性模板商品管理 > 属性模板
product:attr-template:create创建属性模板商品管理 > 属性模板
product:spu:list查看商品列表商品管理 > 商品列表
product:spu:create创建商品商品管理 > 商品列表
product:spu:update编辑商品商品管理 > 商品列表
product:spu:delete删除商品商品管理 > 商品列表
product:spu:update-status上下架商品商品管理 > 商品列表
product:spu:batch-operate批量操作商品商品管理 > 商品列表
product:spu:export导出商品商品管理 > 商品列表
product:comment:list查看商品评价商品管理 > 评价管理
product:comment:reply回复评价商品管理 > 评价管理
product:comment:update-status显示/隐藏评价商品管理 > 评价管理
trade:delivery:express-template:*运费模板 CRUD交易管理 > 运费模板

7.3 接口汇总 ​

后台管理端(共 40+ 接口):

模块核心接口数量
分类管理树查询/CRUD/排序/下拉7
品牌管理分页/CRUD/下拉6
属性管理分页/CRUD/属性值/按分类查10
属性模板分页/CRUD4
商品 SPU分页/详情/创建/更新/删除/状态/批量/导出12
评价管理分页/详情/回复/状态/统计5
运费模板分页/详情/CRUD/下拉6

前台用户端(共 7 接口):

模块接口
分类获取前台分类树
商品分页/搜索/搜索建议/详情
评价分页/统计

7.4 错误码定义 ​

错误码说明
PRODUCT_CATEGORY_NOT_EXISTS商品分类不存在
PRODUCT_CATEGORY_EXISTS商品分类名称已存在
PRODUCT_CATEGORY_HAS_CHILDREN分类下存在子分类,无法删除
PRODUCT_CATEGORY_HAS_SPU分类下存在商品,无法删除
PRODUCT_BRAND_NOT_EXISTS商品品牌不存在
PRODUCT_BRAND_NAME_EXISTS品牌名称已存在
PRODUCT_BRAND_HAS_SPU品牌下存在商品,无法删除
PRODUCT_SPU_NOT_EXISTS商品不存在
PRODUCT_SPU_STATUS_ERROR商品状态不允许此操作
PRODUCT_SKU_STOCK_NOT_ENOUGHSKU 库存不足
PRODUCT_SKU_PRICE_INVALIDSKU 价格不合法
PRODUCT_PROPERTY_HAS_SPU属性已关联商品,无法删除
PRODUCT_COMMENT_REPLY_EXISTS评价已回复,不可重复回复
PRODUCT_DELIVERY_TEMPLATE_HAS_SPU运费模板已关联商品,无法删除

7.5 变更记录 ​

版本日期修改内容修改人
v1.02026-09-24初始版本PM Team
v2.02026-09-19增强业务场景与验收标准、增加 ASCII 页面原型、增加跨模块联动章节、增加名词解释与错误码PM Team

本文档为商品管理模块 PRD v2.0,如有问题请联系产品负责人。

代码对齐(自动生成) ​

本节由 tools/docs/prd-align.mjs 从源码与 SQL 解析生成,请勿手工编辑;重跑 npm run prd:align 会整体替换。

1. 模块规模 ​

控制器接口权限点数据表
13492110

2. 控制器清单 ​

控制器基础路径接口数权限点数代码位置
AppCategoryController/product/category20modules/mall/product/src/main/java/com/pmforge/module/product/controller/app/category/AppCategoryController.java
AppFavoriteController/product/favorite50modules/mall/product/src/main/java/com/pmforge/module/product/controller/app/favorite/AppFavoriteController.java
AppProductBrowseHistoryController/product/browse-history30modules/mall/product/src/main/java/com/pmforge/module/product/controller/app/history/AppProductBrowseHistoryController.java
AppProductCommentController/product/comment10modules/mall/product/src/main/java/com/pmforge/module/product/controller/app/comment/AppProductCommentController.java
AppProductSpuController/product/spu30modules/mall/product/src/main/java/com/pmforge/module/product/controller/app/spu/AppProductSpuController.java
ProductBrandController/product/brand74modules/mall/product/src/main/java/com/pmforge/module/product/controller/admin/brand/ProductBrandController.java
ProductBrowseHistoryController/product/browse-history11modules/mall/product/src/main/java/com/pmforge/module/product/controller/admin/history/ProductBrowseHistoryController.java
ProductCategoryController/product/category54modules/mall/product/src/main/java/com/pmforge/module/product/controller/admin/category/ProductCategoryController.java
ProductCommentController/product/comment52modules/mall/product/src/main/java/com/pmforge/module/product/controller/admin/comment/ProductCommentController.java
ProductFavoriteController/product/favorite11modules/mall/product/src/main/java/com/pmforge/module/product/controller/admin/favorite/ProductFavoriteController.java
ProductPropertyController/product/property64modules/mall/product/src/main/java/com/pmforge/module/product/controller/admin/property/ProductPropertyController.java
ProductPropertyValueController/product/property/value64modules/mall/product/src/main/java/com/pmforge/module/product/controller/admin/property/ProductPropertyValueController.java
ProductSpuController/product/spu105modules/mall/product/src/main/java/com/pmforge/module/product/controller/admin/spu/ProductSpuController.java

3. 接口对照 ​

本文引用 48 个接口,代码中存在 30 个(命中率 63%)。

本文接口代码中对应真实接口
/product/category/list✅
/product/category/get✅
/product/category/create✅
/product/category/update✅
/product/category/delete✅
/product/category/update-sort❌—
/product/category/simple-list❌/bpm/category/simple-list
/product/brand/page✅
/product/brand/get✅
/product/brand/create✅
/product/brand/update✅
/product/brand/delete✅
/product/brand/simple-list❌/product/property/simple-list
/product/property/page✅
/product/property/get✅
/product/property/create✅
/product/property/update✅
/product/property/delete✅
/product/property-value/create❌/product/favorite/create
/product/property-value/update❌/product/brand/update
/product/property-value/delete❌/product/favorite/delete
/product/property/list-by-category❌—
/product/attr-template/page❌/product/favorite/page
/product/attr-template/create❌/product/favorite/create
/product/attr-template/update❌/product/brand/update
/product/attr-template/delete❌/product/favorite/delete
/product/spu/page✅
/product/spu/get-detail✅
/product/spu/create✅
/product/spu/update✅
/product/spu/delete✅
/product/spu/update-status✅
/product/spu/batch-update-status❌—
/product/spu/batch-delete❌—
/product/spu/batch-update-category❌—
/product/spu/export❌—
/product/spu/get-count✅
/trade/delivery/express-template/page✅
/trade/delivery/express-template/get✅
/trade/delivery/express-template/create✅
/trade/delivery/express-template/update✅
/trade/delivery/express-template/delete✅
/trade/delivery/express-template/simple-list❌/trade/delivery/pick-up-store/simple-list
/product/comment/page✅
/product/comment/get✅
/product/comment/reply✅
/product/comment/update-status❌/product/spu/update-status
/product/comment/statistics❌—

❌ 记 18 个接口在代码中不存在:可能是尚未实现(应移入「规划」),也可能是命名与实现不一致(以「对应真实接口」列修正)。

4. 数据表 ​

表名说明
product_brandProductBrandDO
product_browse_historyProductBrowseHistoryDO
product_categoryProductCategoryDO
product_commentProductCommentDO
product_favoriteProductFavoriteDO
product_propertyProductPropertyDO
product_property_valueProductPropertyValueDO
product_skuProperty
product_spuProductSpuDO
product_statisticsProductStatisticsDO

5. 说明 ​

  • 模块码:mall(商城);PRD 编号:06-01。
  • 「接口对照」只统计本文用反引号显式写出的 /admin-api/... 路径;未写接口的章节不代表没有实现。
  • 代码位置为相对仓库根的路径,行号可在功能卡或 docs/code/api/ 中查到。