当前位置：首页 > news >正文

【研究与学习】易订货商品模块设计分析文档字段级数据字典 + 表关系 + 单位换算 + 价格/库存/促销链路（一）---升鲜宝生鲜配送供应链管理系统

news 2026/5/9 10:45:21

文档信息

项目	说明
文档版本	V1.0
生成日期	2023-05-08
适用对象	升鲜宝研发团队、产品经理、架构师、数据库设计人员
文档性质	竞品功能推理 + 可落地数据结构参考，不代表易订货官方真实数据库
建议技术栈	Spring Boot + MyBatis-Plus + MySQL 8.0+ + Redis

1. 文档说明与边界

本文档对易订货类 B2B 订货系统的商品模块进行字段级结构分析，重点覆盖商品分类、单位、SPU、SKU、多规格、图片附件、客户级别价格、客户单独价格、库存、促销、导入导出及订单明细快照等关键结构。

本文档不是易订货官方数据库反编译结果，而是基于公开产品能力、B2B 订货系统共性流程和升鲜宝供应链系统落地经验推理形成的研发参考版。实际落库时可按升鲜宝现有命名规范、租户模型、组织权限、商品 SPU/SKU/单位模型进行调整。

设计边界

项目	说明
覆盖范围	商品主数据、商品单位、规格 SKU、价格、库存、促销、导入导出、订单快照关联。
不覆盖范围	完整订单、完整财务、完整 WMS、完整会员/分销商权限，仅说明商品模块相关引用字段。
命名约定	为便于竞品分析，表名前缀使用 ydh_；升鲜宝落地时可映射到 pms_、oms_、wms_ 等域。
主键类型	统一使用 bigint；建议使用雪花 ID 或数据库自增，需与现有系统统一。
多租户字段	所有业务表建议包含 tenant_id，用于 SaaS 数据隔离。
删除策略	商品、SKU、单位、分类等基础资料建议使用逻辑删除 deleted，避免影响历史单据。

2. 商品模块总体功能结构

易订货商品模块可理解为“B2B 订货商品中心”。它不仅维护商品档案，还负责客户可见范围、客户定价、起订限订、库存展示、促销适配和订单快照。

商品分类
  ↓
商品 SPU 主档
  ↓
商品 SKU / 多规格
  ↓
商品单位与换算
  ↓
客户级别价格 / 客户专属价格
  ↓
商品库存 / 库存展示
  ↓
商品促销规则
  ↓
订单明细商品快照

2.1 商品模块功能清单

功能域	核心功能	关键字段/表	研发注意点
商品分类	一级/多级分类、排序、启用禁用、置顶	ydh_goods_category	分类存在商品或子分类时不允许直接删除。
计量单位	维护件、箱、瓶、斤、公斤等单位	ydh_goods_unit	单位本身不保存商品换算率，换算必须按商品/SKU 定义。
商品主档	商品名称、编码、类别、单位、上下架、主图、关键字	ydh_goods	商品名称、分类、单位是核心必填字段。
多规格 SKU	颜色、尺码、规格组合、SKU 编码、条码、缩略图	ydh_goods_sku	即使无多规格，也建议生成默认 SKU。
价格体系	市场价、默认订货价、级别价、客户专属价	level_price/customer_price	客户专属价优先级最高。
库存管理	库存、锁定库存、可用库存、上下限、库存流水	ydh_goods_stock/flow	库存应按 SKU + 仓库维度管理。
促销管理	买赠、直降、打折、满减、满折、范围控制	promotion/rule/scope	促销要支持客户级别、区域、指定客户。
导入导出	商品资料、客户单独定价、商品图片导入	import_task/error	导入任务要记录失败行与错误字段。
订单引用	订单明细保存商品快照、单位快照、价格快照	ydh_order_item	不能只保存商品 ID，否则历史订单会被商品修改影响。

3. 商品模块数据域划分

3.1 数据域划分

数据域	包含表	职责	是否商品模块核心
基础资料域	ydh_goods_category、ydh_goods_unit、ydh_goods_brand、ydh_goods_tag	维护商品基础引用数据。	是
商品主档域	ydh_goods、ydh_goods_sku	维护 SPU/SKU 档案、规格、条码、上下架。	是
规格域	ydh_goods_spec_group、ydh_goods_spec_value、ydh_goods_sku_spec_rel	维护多规格组合关系。	是
单位换算域	ydh_goods_sku_unit、ydh_goods_unit_relation	维护不同商品/SKU 的可用单位和换算关系。	是
媒体资料域	ydh_goods_media、ydh_goods_attachment	维护主图、图册、SKU 缩略图、附件资料。	是
价格域	ydh_goods_level_price、ydh_goods_customer_price	维护客户级别价格和客户专属价格。	是
库存域	ydh_goods_stock、ydh_goods_stock_flow	维护库存数量、锁定数量、上下限和库存变动流水。	扩展核心
促销域	ydh_goods_promotion、ydh_goods_promotion_rule、ydh_goods_promotion_scope	维护商品促销、订单促销及适用范围。	扩展核心
导入域	ydh_goods_import_task、ydh_goods_import_error	维护导入过程、导入结果和失败明细。	辅助

4. 商品模块核心表清单

4.1 表清单

序号	表名	中文名称	主键	核心外键	说明
1	ydh_goods_category	商品分类表	id	parent_id	商品目录树。
2	ydh_goods_unit	计量单位表	id	-	全局单位基础资料。
3	ydh_goods_brand	商品品牌表	id	-	品牌基础资料，可选。
4	ydh_goods_tag	商品标签表	id	-	新品、热卖、清仓等标签。
5	ydh_goods	商品 SPU 主表	id	category_id、unit_id、brand_id、tag_id	商品主档。
6	ydh_goods_spec_group	规格组表	id	goods_id	如颜色、尺码。
7	ydh_goods_spec_value	规格值表	id	goods_id、spec_group_id	如红色、蓝色、S、M。
8	ydh_goods_sku	商品 SKU 表	id	goods_id、unit_id	具体可销售规格商品。
9	ydh_goods_sku_spec_rel	SKU 规格关系表	id	sku_id、spec_group_id、spec_value_id	SKU 与规格值组合关系。
10	ydh_goods_sku_unit	SKU 可用单位表	id	goods_id、sku_id、unit_id	定义单位可用于销售/采购/库存/订货。
11	ydh_goods_unit_relation	商品单位换算表	id	goods_id、sku_id、from_unit_id、to_unit_id	定义 1箱=24瓶、1只=1.3斤。
12	ydh_goods_media	商品图片表	id	goods_id、sku_id	主图、图册、规格图。
13	ydh_goods_attachment	商品附件表	id	goods_id	说明书、资料文件。
14	ydh_goods_level_price	客户级别价格表	id	sku_id、customer_level_id	按客户级别定价。
15	ydh_goods_customer_price	客户单独定价表	id	sku_id、customer_id	指定客户专属价格。
16	ydh_goods_stock	商品库存表	id	warehouse_id、sku_id	当前库存、锁定库存、上下限。
17	ydh_goods_stock_flow	商品库存流水表	id	sku_id、bill_no	库存变动记录。
18	ydh_goods_promotion	商品促销主表	id	-	促销活动主档。
19	ydh_goods_promotion_rule	促销规则表	id	promotion_id、sku_id	买赠、直降、打折、满减等规则。
20	ydh_goods_promotion_scope	促销范围表	id	promotion_id、scope_id	客户级别、区域、指定客户范围。
21	ydh_goods_import_task	商品导入任务表	id	-	导入批次。
22	ydh_goods_import_error	商品导入错误表	id	task_id	导入失败明细。

5. 商品基础资料表字段级设计

5.1 ydh_goods_category 商品分类表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	分类 ID	被 ydh_goods.category_id 引用。
tenant_id	bigint	idx	租户 ID	SaaS 隔离字段。
parent_id	bigint	idx	上级分类 ID	自关联 ydh_goods_category.id；顶级为 0。
category_code	varchar(64)	uk: tenant_id+category_code	分类编码	可系统生成或导入。
category_name	varchar(128)	not null	分类名称	同级分类建议 tenant_id+parent_id+category_name 唯一。
category_level	int		分类层级	1 一级，2 二级，支持多级扩展。
category_path	varchar(500)		分类路径	如 /1/5/9，用于快速查询子级。
sort_no	int	idx	排序号	越大越靠前或按系统约定排序。
is_top	tinyint		是否置顶	1 置顶，0 普通。
status	tinyint	idx	状态	1 启用，0 禁用。
remark	varchar(255)		备注
created_by	bigint		创建人	员工 ID。
created_at	datetime		创建时间
updated_by	bigint		更新人
updated_at	datetime		更新时间
deleted	tinyint	idx	逻辑删除	0 正常，1 删除。

5.2 ydh_goods_unit 计量单位表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	单位 ID	被商品、SKU、库存、订单明细引用。
tenant_id	bigint	idx	租户 ID
unit_code	varchar(64)	uk: tenant_id+unit_code	单位编码	如 PCS、BOX、JIN、KG。
unit_name	varchar(32)	uk: tenant_id+unit_name	单位名称	件、箱、瓶、斤、公斤、只。
unit_type	tinyint		单位类型	1 数量，2 重量，3 体积，4 长度，5 包装。
decimal_scale	int		数量小数位	件/箱通常 0，斤/kg 可 2~3。
rounding_mode	tinyint		舍入方式	1 四舍五入，2 向下取整，3 向上取整。
sort_no	int		排序
status	tinyint	idx	状态	1 启用，0 禁用。
created_at	datetime		创建时间
updated_at	datetime		更新时间
deleted	tinyint	idx	逻辑删除	被引用单位不建议物理删除。

5.3 ydh_goods_brand 商品品牌表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	品牌 ID	被 ydh_goods.brand_id 引用。
tenant_id	bigint	idx	租户 ID
brand_code	varchar(64)	uk	品牌编码	导入和接口对接使用。
brand_name	varchar(128)	not null	品牌名称	如怡宝、农夫山泉。
logo_url	varchar(500)		品牌 Logo
sort_no	int		排序
status	tinyint	idx	状态
created_at	datetime		创建时间
updated_at	datetime		更新时间
deleted	tinyint	idx	逻辑删除

5.4 ydh_goods_tag 商品标签表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	标签 ID	可被 ydh_goods.tag_id 引用。
tenant_id	bigint	idx	租户 ID
tag_code	varchar(64)	uk	标签编码	NEW、HOT、CLEARANCE。
tag_name	varchar(64)	not null	标签名称	新品上架、热卖推荐、清仓。
tag_style	varchar(64)		标签样式	前端样式标识，如 red、green。
sort_no	int		排序
status	tinyint	idx	状态
created_at	datetime		创建时间
updated_at	datetime		更新时间

5.5 ydh_goods 商品 SPU 主表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	商品 ID	被 SKU、价格、库存、促销、订单明细引用。
tenant_id	bigint	idx	租户 ID
goods_code	varchar(64)	uk: tenant_id+goods_code	商品编码	商品搜索、导入、ERP 对接关键字段。
goods_name	varchar(128)	idx	商品名称	前后台搜索、下单展示。
brand_id	bigint	FK	品牌 ID	关联 ydh_goods_brand.id，可为空。
category_id	bigint	FK/idx	商品分类 ID	关联 ydh_goods_category.id。
unit_id	bigint	FK	默认单位 ID	关联 ydh_goods_unit.id；SKU 可继承。
tag_id	bigint	FK	标签 ID	关联 ydh_goods_tag.id；多标签可改中间表。
sale_status	tinyint	idx	上下架状态	1 上架，0 下架；下架不可订货。
sort_no	int	idx	排序值	订货端展示排序。
search_keywords	varchar(255)	idx	搜索关键字	可包含拼音码、简称、别名。
weight	decimal(18,4)		商品重量	用于运费、物流、展示。
weight_unit	varchar(16)		重量单位	kg、g、斤等。
has_multi_spec	tinyint		是否多规格	0 单规格，1 多规格。
main_image_url	varchar(500)		商品主图 URL	冗余 ydh_goods_media 主图，提升列表性能。
description	text		商品介绍	订货端商品详情。
market_price	decimal(18,4)		市场价	展示价/兜底价。
cost_price	decimal(18,4)		成本价	内部管理，不建议对客户展示。
base_order_price	decimal(18,4)		默认订货价	无级别价/客户价时使用。
enable_customer_price	tinyint		是否启用客户单独定价	1 启用后查询 ydh_goods_customer_price。
min_order_qty	decimal(18,4)		默认起订量	可被 SKU、级别价、客户价覆盖。
max_order_qty	decimal(18,4)		默认限订量	可被 SKU、级别价、客户价覆盖。
can_order	tinyint	idx	默认是否允许订货	1 允许，0 不允许。
share_title	varchar(128)		分享标题	微信/移动分享。
share_desc	varchar(255)		分享描述
status	tinyint	idx	数据状态	1 正常，0 禁用。
created_by	bigint		创建人
created_at	datetime		创建时间
updated_by	bigint		更新人
updated_at	datetime		更新时间
deleted	tinyint	idx	逻辑删除	有历史订单/库存/流水时不能物理删除。

6. 商品规格 SKU 与多规格结构

多规格结构建议采用“规格组 + 规格值 + SKU + SKU规格关系”的经典模型。这样既可以支持颜色/尺码类标准规格，也可以兼容包装、等级、口味等 B2B 商品属性。

ydh_goods
  ├── ydh_goods_spec_group（颜色、尺码）
  │     └── ydh_goods_spec_value（红色、蓝色、S、M）
  └── ydh_goods_sku（红色/S、红色/M、蓝色/S）
        └── ydh_goods_sku_spec_rel（SKU 与规格值组合关系）

6.1 ydh_goods_spec_group 规格组表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	规格组 ID
tenant_id	bigint	idx	租户 ID
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
spec_name	varchar(64)	not null	规格名称	如颜色、尺码、口味。
sort_no	int		排序	用于前端规格选择顺序。
created_at	datetime		创建时间
updated_at	datetime		更新时间

6.2 ydh_goods_spec_value 规格值表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	规格值 ID
tenant_id	bigint	idx	租户 ID
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
spec_group_id	bigint	FK/idx	规格组 ID	关联 ydh_goods_spec_group.id。
spec_value	varchar(64)	not null	规格值	如红色、蓝色、S、M。
sort_no	int		排序
created_at	datetime		创建时间
updated_at	datetime		更新时间

6.3 ydh_goods_sku 商品 SKU 表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	SKU ID	订单、库存、价格的最小商品粒度。
tenant_id	bigint	idx	租户 ID
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
sku_code	varchar(64)	uk: tenant_id+sku_code	SKU 编码	导入、搜索、ERP 对接关键字段。
barcode	varchar(128)	uk 可空	条形码	扫码、库存查询。
sku_name	varchar(255)	idx	SKU 名称	通常为商品名 + 规格文本。
spec_text	varchar(255)		规格文本	如红色/S；冗余显示字段。
unit_id	bigint	FK	默认单位 ID	关联 ydh_goods_unit.id。
thumb_url	varchar(500)		规格缩略图	可冗余 ydh_goods_media。
market_price	decimal(18,4)		SKU 市场价	可覆盖商品市场价。
cost_price	decimal(18,4)		SKU 成本价	可覆盖商品成本价。
base_order_price	decimal(18,4)		SKU 默认订货价	下单兜底价格。
min_order_qty	decimal(18,4)		SKU 起订量	覆盖商品默认起订量。
max_order_qty	decimal(18,4)		SKU 限订量	覆盖商品默认限订量。
sale_status	tinyint	idx	SKU 上下架状态	SKU 级别可独立控制。
can_order	tinyint	idx	SKU 是否允许订货	1 允许，0 不允许。
sort_no	int		排序
created_at	datetime		创建时间
updated_at	datetime		更新时间
deleted	tinyint	idx	逻辑删除

6.4 ydh_goods_sku_spec_rel SKU 规格关系表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	主键 ID
tenant_id	bigint	idx	租户 ID
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
sku_id	bigint	FK/idx	SKU ID	关联 ydh_goods_sku.id。
spec_group_id	bigint	FK	规格组 ID	关联 ydh_goods_spec_group.id。
spec_value_id	bigint	FK	规格值 ID	关联 ydh_goods_spec_value.id。
spec_name	varchar(64)		规格名称快照	如颜色；避免规格名修改影响历史展示。
spec_value	varchar(64)		规格值快照	如红色。
created_at	datetime		创建时间

7. 商品图片、附件与标签结构

7.1 ydh_goods_media 商品图片表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	图片 ID
tenant_id	bigint	idx	租户 ID
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
sku_id	bigint	FK/idx 可空	SKU ID	规格图使用；商品主图/图册可为空。
media_type	tinyint	idx	图片类型	1 主图，2 图册，3 SKU 缩略图，4 详情图。
media_url	varchar(500)	not null	图片 URL	对象存储地址。
file_name	varchar(255)		文件名	商品图片导入匹配。
sort_no	int		排序	图册排序。
is_main	tinyint	idx	是否主图	主图建议同时回写 ydh_goods.main_image_url。
created_at	datetime		创建时间

7.2 ydh_goods_attachment 商品附件表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	附件 ID
tenant_id	bigint	idx	租户 ID
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
file_name	varchar(255)	not null	文件名	说明书、检测报告等。
file_url	varchar(500)	not null	文件 URL	对象存储地址。
file_type	varchar(64)		文件类型	pdf、docx、xlsx、jpg。
file_size	bigint		文件大小	字节数。
sort_no	int		排序
created_at	datetime		创建时间

8. 商品单位与单位换算结构

单位换算不能只在单位主表中定义。因为同样是“箱 → 个”，不同商品可能换算比例完全不同，例如矿泉水 1箱=24瓶，鸡蛋 1箱=360个，苹果 1箱=20斤。正确做法是按商品或 SKU 定义换算关系。

单位主表：定义斤、公斤、箱、瓶、个、只
SKU 可用单位表：定义这个 SKU 哪些单位可用于库存/销售/采购/订货/展示/计价
商品单位换算表：定义这个 SKU 的 A 单位换算成 B 单位的比例

8.1 ydh_goods_sku_unit SKU 可用单位表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	主键 ID
tenant_id	bigint	idx	租户 ID
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
sku_id	bigint	FK/idx	SKU ID	关联 ydh_goods_sku.id。
unit_id	bigint	FK/idx	单位 ID	关联 ydh_goods_unit.id。
unit_name	varchar(32)		单位名称快照	减少关联查询。
is_base_unit	tinyint	idx	是否库存基准单位	每个 SKU 只能有一个基准单位。
is_inventory_unit	tinyint		是否库存单位	库存核算可使用。
is_sale_unit	tinyint		是否销售单位	销售开单可使用。
is_purchase_unit	tinyint		是否采购单位	采购入库可使用。
is_order_unit	tinyint		是否订货单位	客户订货端可使用。
is_display_unit	tinyint		是否展示单位	前端库存或商品详情展示。
is_price_unit	tinyint		是否计价单位	金额计算使用。
default_sale_unit	tinyint		默认销售单位	每个 SKU 建议唯一。
default_purchase_unit	tinyint		默认采购单位	每个 SKU 建议唯一。
default_order_unit	tinyint		默认订货单位	每个 SKU 建议唯一。
decimal_scale	int		当前单位小数位	可覆盖单位主表默认小数位。
min_order_qty	decimal(18,4)		当前单位起订量	订货单位维度限制。
max_order_qty	decimal(18,4)		当前单位限订量	订货单位维度限制。
status	tinyint	idx	状态
created_at	datetime		创建时间
updated_at	datetime		更新时间

8.2 ydh_goods_unit_relation 商品单位换算关系表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	主键 ID
tenant_id	bigint	idx	租户 ID
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
sku_id	bigint	FK/idx 可空	SKU ID	为空表示商品级通用换算。
from_unit_id	bigint	FK/idx	来源单位 ID	关联 ydh_goods_unit.id。
to_unit_id	bigint	FK/idx	目标单位 ID	关联 ydh_goods_unit.id。
conversion_rate	decimal(24,8)	not null	换算率	to_qty = from_qty × conversion_rate。
conversion_formula	varchar(255)		换算公式	可选，用于复杂包装或浮动换算说明。
is_base_relation	tinyint	idx	是否基准换算关系	基准单位关系优先。
relation_type	tinyint	idx	换算类型	1 固定换算，2 浮动换算，3 手工录入。
effective_start_time	datetime		生效开始时间	支持历史换算率。
effective_end_time	datetime		生效结束时间	为空表示长期有效。
status	tinyint	idx	状态	1 启用，0 禁用。
remark	varchar(255)		备注
created_at	datetime		创建时间
updated_at	datetime		更新时间

8.3 单位换算示例

商品	来源单位	目标单位	conversion_rate	计算示例	换算类型
矿泉水	箱	瓶	24	2箱 × 24 = 48瓶	固定换算
鸡蛋	箱	个	360	1箱 × 360 = 360个	固定换算
公斤	公斤	斤	2	3公斤 × 2 = 6斤	固定换算
波士顿龙虾	只	斤	1.3	50只 × 1.3 = 65斤	浮动换算/默认估算
苹果	箱	斤	20	10箱 × 20 = 200斤	浮动换算/默认估算

9. 客户级别价格与客户单独定价结构

B2B 订货系统的价格不能只有商品默认价，必须支持客户级别价和客户专属价。实际下单时的价格优先级建议为：客户单独定价 > 客户级别价格 > SKU 默认订货价 > 商品默认订货价 > 市场价。

9.1 ydh_goods_level_price 客户级别价格表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	主键 ID
tenant_id	bigint	idx	租户 ID
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
sku_id	bigint	FK/idx	SKU ID	关联 ydh_goods_sku.id。
customer_level_id	bigint	FK/idx	客户级别 ID	关联客户级别表。
order_price	decimal(18,4)	not null	客户级别订货价	下单价格来源之一。
discount_rate	decimal(10,4)		折扣率	可与 order_price 二选一或冗余。
can_order	tinyint	idx	是否允许订货	1 允许，0 不允许。
min_order_qty	decimal(18,4)		起订量	级别维度覆盖商品/SKU 默认。
max_order_qty	decimal(18,4)		限定量	级别维度覆盖商品/SKU 默认。
start_time	datetime		生效时间	支持价格时段。
end_time	datetime		失效时间	为空表示长期有效。
status	tinyint	idx	状态
created_at	datetime		创建时间
updated_at	datetime		更新时间

9.2 ydh_goods_customer_price 客户单独定价表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	主键 ID
tenant_id	bigint	idx	租户 ID
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
sku_id	bigint	FK/idx	SKU ID	关联 ydh_goods_sku.id。
customer_id	bigint	FK/idx	客户 ID	关联客户表。
order_price	decimal(18,4)	not null	客户专属订货价	价格优先级最高。
can_order	tinyint	idx	是否允许订货	可用于客户级商品授权。
min_order_qty	decimal(18,4)		起订量	客户维度最高优先级。
max_order_qty	decimal(18,4)		限定量	客户维度最高优先级。
start_time	datetime		生效时间
end_time	datetime		失效时间
status	tinyint	idx	状态
created_at	datetime		创建时间
updated_at	datetime		更新时间

价格优先级：
1. ydh_goods_customer_price.order_price（客户专属价）
2. ydh_goods_level_price.order_price（客户级别价）
3. ydh_goods_sku.base_order_price（SKU 默认订货价）
4. ydh_goods.base_order_price（商品默认订货价）
5. ydh_goods.market_price（市场价兜底）

10. 商品库存与库存流水结构

订货系统中的库存可以是轻量库存，也可以与 WMS 深度集成。商品模块至少需要支持当前库存、锁定库存、可用库存、库存上下限和库存流水。

10.1 ydh_goods_stock 商品库存表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	库存 ID
tenant_id	bigint	idx	租户 ID
warehouse_id	bigint	idx 可空	仓库 ID	支持多仓时必填。
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
sku_id	bigint	FK/idx	SKU ID	库存最小粒度。
unit_id	bigint	FK	库存单位 ID	一般为基准库存单位。
stock_qty	decimal(18,4)		当前库存数量	账面库存。
lock_qty	decimal(18,4)		锁定库存数量	下单未出库、预占。
available_qty	decimal(18,4)		可用库存数量	stock_qty - lock_qty，可冗余。
stock_upper_limit	decimal(18,4)		库存上限	库存预警。
stock_lower_limit	decimal(18,4)		库存下限	低库存预警。
last_in_time	datetime		最近入库时间
last_out_time	datetime		最近出库时间
updated_at	datetime		更新时间

10.2 ydh_goods_stock_flow 商品库存流水表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	流水 ID
tenant_id	bigint	idx	租户 ID
warehouse_id	bigint	idx	仓库 ID
goods_id	bigint	FK/idx	商品 ID	关联 ydh_goods.id。
sku_id	bigint	FK/idx	SKU ID	关联 ydh_goods_sku.id。
unit_id	bigint	FK	单位 ID	流水数量单位。
bill_type	varchar(64)	idx	来源单据类型	STOCK_IN、STOCK_OUT、ORDER_OUT、RETURN_IN、CHECK_PROFIT、CHECK_LOSS。
bill_id	bigint	idx 可空	来源单据 ID
bill_no	varchar(64)	idx	来源单号	入库单、出库单、订单号、盘点单号。
flow_direction	tinyint	idx	库存方向	1 入库，2 出库。
change_qty	decimal(18,4)	not null	变动数量	正数保存，方向由 flow_direction 表示。
before_qty	decimal(18,4)		变动前库存
after_qty	decimal(18,4)		变动后库存
biz_time	datetime	idx	业务时间
remark	varchar(255)		备注
created_at	datetime		创建时间

库存扣减建议：
订单提交：可选择锁定库存 lock_qty += order_qty
出库审核：stock_qty -= out_qty，lock_qty -= out_qty，写库存流水
订单取消/审核退回：释放锁定库存 lock_qty -= order_qty
退货入库：stock_qty += return_qty，写库存流水

11. 商品促销结构

促销结构需要同时支持单品促销和订单促销。单品促销作用于商品/SKU，订单促销作用于订单总额或总数量。促销范围应支持客户级别、区域、指定客户。

11.1 ydh_goods_promotion 商品促销主表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	促销 ID
tenant_id	bigint	idx	租户 ID
promotion_no	varchar(64)	uk	促销编号
promotion_name	varchar(128)	not null	促销名称
promotion_type	tinyint	idx	促销类型	1 单品促销，2 订单促销，3 秒杀，4 大转盘。
rule_type	tinyint	idx	规则类型	1 买赠，2 直降，3 打折，4 满赠，5 满减，6 满折。
is_ladder	tinyint		是否阶梯促销	1 阶梯，0 非阶梯。
effective_priority	int		生效优先级	冲突时优先级高者生效。
start_time	datetime	idx	开始时间
end_time	datetime	idx	结束时间
status	tinyint	idx	状态	0 未开始，1 生效中，2 已结束，3 作废。
remark	varchar(255)		备注
created_at	datetime		创建时间
updated_at	datetime		更新时间

11.2 ydh_goods_promotion_rule 促销规则表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	规则 ID
tenant_id	bigint	idx	租户 ID
promotion_id	bigint	FK/idx	促销 ID	关联 ydh_goods_promotion.id。
goods_id	bigint	FK/idx 可空	促销商品 ID	单品促销使用。
sku_id	bigint	FK/idx 可空	促销 SKU ID	单品促销使用。
ladder_start_qty	decimal(18,4)		阶梯开始数量	买赠/数量阶梯。
ladder_end_qty	decimal(18,4)		阶梯结束数量	为空表示无上限。
ladder_start_amount	decimal(18,2)		阶梯开始金额	满减/满折。
ladder_end_amount	decimal(18,2)		阶梯结束金额	为空表示无上限。
discount_price	decimal(18,4)		直降后价格	直降促销。
discount_amount	decimal(18,2)		减免金额	满减促销。
discount_rate	decimal(10,4)		折扣率	打折、满折。
buy_qty	decimal(18,4)		购买数量	买 N 赠 M。
gift_goods_id	bigint	FK 可空	赠品商品 ID	关联 ydh_goods.id。
gift_sku_id	bigint	FK 可空	赠品 SKU ID	关联 ydh_goods_sku.id。
gift_qty	decimal(18,4)		赠品数量
sort_no	int		规则排序	阶梯规则顺序。

11.3 ydh_goods_promotion_scope 促销适用范围表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	主键 ID
tenant_id	bigint	idx	租户 ID
promotion_id	bigint	FK/idx	促销 ID	关联 ydh_goods_promotion.id。
scope_type	tinyint	idx	范围类型	1 客户级别，2 区域，3 指定客户，4 全部客户。
scope_id	bigint	idx	范围对象 ID	根据 scope_type 指向 customer_level、region、customer。
created_at	datetime		创建时间

12. 商品导入导出结构

商品导入建议按任务中心方式设计，避免前端长时间等待，同时记录每一行的错误原因，支持失败报告下载。

12.1 ydh_goods_import_task 商品导入任务表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	导入任务 ID
tenant_id	bigint	idx	租户 ID
import_no	varchar(64)	uk	导入任务号
import_type	tinyint	idx	导入类型	1 商品资料，2 客户单独定价，3 商品图片，4 库存初始化。
file_name	varchar(255)		源文件名
file_url	varchar(500)		源文件地址
total_count	int		总行数
success_count	int		成功数
fail_count	int		失败数
status	tinyint	idx	任务状态	0 待处理，1 处理中，2 成功，3 部分成功，4 失败。
operator_id	bigint	idx	操作人 ID
created_at	datetime		创建时间
finished_at	datetime		完成时间

12.2 ydh_goods_import_error 商品导入错误表

字段名	类型	约束/索引	中文说明	关联/业务规则
id	bigint	PK	错误 ID
tenant_id	bigint	idx	租户 ID
task_id	bigint	FK/idx	导入任务 ID	关联 ydh_goods_import_task.id。
row_no	int		Excel 行号
raw_data	json		原始行数据	MySQL 8.0 支持 JSON。
error_field	varchar(64)		错误字段	如 goods_code、unit_name。
error_message	varchar(500)		错误原因	用于失败报告。
created_at	datetime		创建时间

13. 商品与订单/退货/库存/促销的字段关联

ydh_goods_category.id
  └── ydh_goods.category_id

ydh_goods_unit.id
  ├── ydh_goods.unit_id
  ├── ydh_goods_sku.unit_id
  ├── ydh_goods_sku_unit.unit_id
  ├── ydh_goods_unit_relation.from_unit_id
  ├── ydh_goods_unit_relation.to_unit_id
  ├── ydh_goods_stock.unit_id
  └── ydh_order_item.unit_id / order_unit_id / price_unit_id / inventory_unit_id

ydh_goods.id
  ├── ydh_goods_sku.goods_id
  ├── ydh_goods_spec_group.goods_id
  ├── ydh_goods_spec_value.goods_id
  ├── ydh_goods_media.goods_id
  ├── ydh_goods_attachment.goods_id
  ├── ydh_goods_level_price.goods_id
  ├── ydh_goods_customer_price.goods_id
  ├── ydh_goods_stock.goods_id
  ├── ydh_goods_stock_flow.goods_id
  ├── ydh_goods_promotion_rule.goods_id / gift_goods_id
  └── ydh_order_item.goods_id

ydh_goods_sku.id
  ├── ydh_goods_sku_spec_rel.sku_id
  ├── ydh_goods_sku_unit.sku_id
  ├── ydh_goods_media.sku_id
  ├── ydh_goods_level_price.sku_id
  ├── ydh_goods_customer_price.sku_id
  ├── ydh_goods_stock.sku_id
  ├── ydh_goods_stock_flow.sku_id
  ├── ydh_goods_promotion_rule.sku_id / gift_sku_id
  └── ydh_order_item.sku_id

13.1 订单明细中的商品快照字段建议

订单明细字段	来源字段	是否快照	说明
goods_id	ydh_goods.id	否	关联商品 ID。
sku_id	ydh_goods_sku.id	否	关联 SKU ID。
goods_code	ydh_goods.goods_code	是	商品编码快照。
sku_code	ydh_goods_sku.sku_code	是	SKU 编码快照。
goods_name	ydh_goods.goods_name	是	商品名称快照。
spec_text	ydh_goods_sku.spec_text	是	规格文本快照。
unit_id	ydh_goods_unit.id	否/快照并存	单位 ID。
unit_name	ydh_goods_unit.unit_name	是	单位名称快照。
order_qty	前端输入	是	订货数量。
order_price	价格引擎结果	是	最终订货价。
market_price	ydh_goods_sku.market_price	是	市场价快照。
discount_amount	促销引擎结果	是	优惠金额。
line_amount	数量 × 单价 - 优惠	是	明细金额。
conversion_rate	ydh_goods_unit_relation.conversion_rate	是	下单时单位换算率快照。

14. 价格计算链路与可订购校验

价格计算链路：
customer_id
  ↓ 查询客户 level_id
sku_id
  ↓ 查询客户专属价 ydh_goods_customer_price
  ↓ 若不存在，查询客户级别价 ydh_goods_level_price
  ↓ 若不存在，读取 ydh_goods_sku.base_order_price
  ↓ 若不存在，读取 ydh_goods.base_order_price
  ↓ 最后使用 market_price 兜底
  ↓ 促销引擎计算优惠
  ↓ 生成订单明细价格快照

14.1 可订购校验规则

校验项	字段来源	通过条件	失败处理
商品上架	ydh_goods.sale_status	=1	不可加入购物车/不可提交订单。
SKU 上架	ydh_goods_sku.sale_status	=1	不可订购该规格。
商品允许订货	ydh_goods.can_order	=1	提示商品暂不允许订货。
SKU 允许订货	ydh_goods_sku.can_order	=1	提示规格暂不允许订货。
客户专属授权	ydh_goods_customer_price.can_order	不存在或=1	若=0，当前客户不可订。
客户级别授权	ydh_goods_level_price.can_order	不存在或=1	若=0，当前级别不可订。
起订量	客户价/级别价/SKU/商品 min_order_qty	order_qty >= min	提示起订量。
限订量	客户价/级别价/SKU/商品 max_order_qty	order_qty <= max	提示最大订购数量。
库存可用	ydh_goods_stock.available_qty	available_qty >= inventory_qty	提示库存不足，可允许超卖需配置。

15. 单位换算与双单位库存设计

升鲜宝做生鲜、水产、冻品时，必须把“订货单位、库存单位、计价单位、展示单位”拆开。否则会出现客户按只订货、仓库按只点数、财务按斤结算、库存又要显示只和斤的混乱。

通用公式：
to_qty = from_qty × conversion_rate

示例：
矿泉水：2箱 × 24 = 48瓶
波士顿龙虾：50只 × 1.3 = 65斤

浮动换算：
如果实际称重 actual_to_qty 不为空，则以实际称重为准；否则按默认 conversion_rate 估算。

15.1 双单位业务示例：波士顿龙虾

业务环节	单位	数量	说明
客户订货	只	50	客户按只下单，便于点数。
默认换算	斤	65	默认 1只=1.3斤。
实际称重	斤	67.8	出库/复核时可录入实际重量。
计价	斤	67.8	按实际斤数计价。
库存显示	只 + 斤	50只 / 67.8斤	双单位展示。

15.2 库存表双单位增强字段建议

字段名	类型	说明	业务含义
main_unit_id	bigint	主库存单位 ID	例如只。
main_qty	decimal(18,4)	主库存数量	例如 50只。
assist_unit_id	bigint	辅助库存单位 ID	例如斤。
assist_qty	decimal(18,4)	辅助库存数量	例如 67.8斤。
price_unit_id	bigint	计价单位 ID	例如斤。
cost_price	decimal(18,6)	成本单价	按计价单位或库存基准单位核算，需统一。
inventory_amount	decimal(18,2)	库存金额	数量 × 成本单价。

16. 推荐索引、唯一约束与数据校验规则

16.1 推荐唯一约束

表名	唯一约束	说明
ydh_goods_category	tenant_id + parent_id + category_name + deleted	同级分类名称不可重复。
ydh_goods_unit	tenant_id + unit_name + deleted	单位名称不可重复。
ydh_goods	tenant_id + goods_code + deleted	商品编码唯一。
ydh_goods_sku	tenant_id + sku_code + deleted	SKU 编码唯一。
ydh_goods_sku	tenant_id + barcode + deleted	条码建议唯一；空值需按数据库策略处理。
ydh_goods_sku_unit	tenant_id + sku_id + unit_id	一个 SKU 对同一单位只能配置一次。
ydh_goods_unit_relation	tenant_id + sku_id + from_unit_id + to_unit_id + status	同一有效换算关系不能重复。
ydh_goods_level_price	tenant_id + sku_id + customer_level_id	一个 SKU 对一个客户级别一条价。
ydh_goods_customer_price	tenant_id + sku_id + customer_id	一个 SKU 对一个客户一条专属价。
ydh_goods_stock	tenant_id + warehouse_id + sku_id	一个仓库一个 SKU 一条库存。

16.2 推荐普通索引

表名	索引字段	用途
ydh_goods	tenant_id, category_id, sale_status, deleted	按分类查询上架商品。
ydh_goods	tenant_id, goods_name, goods_code, search_keywords	后台/订货端搜索。
ydh_goods_sku	tenant_id, goods_id, sale_status, deleted	查询商品 SKU。
ydh_goods_stock	tenant_id, sku_id, warehouse_id	库存查询。
ydh_goods_stock_flow	tenant_id, sku_id, bill_no, biz_time	库存流水追踪。
ydh_goods_promotion	tenant_id, promotion_type, status, start_time, end_time	查询有效促销。
ydh_goods_promotion_scope	tenant_id, promotion_id, scope_type, scope_id	判断促销范围。
ydh_goods_customer_price	tenant_id, customer_id, sku_id, status	客户价批量查询。
ydh_goods_level_price	tenant_id, customer_level_id, sku_id, status	级别价批量查询。

16.3 数据校验规则

规则	涉及字段/表	说明
商品删除校验	ydh_goods、ydh_order_item、ydh_goods_stock	有未完成订单、库存、促销、价格记录时不允许直接删除。
分类删除校验	ydh_goods_category.parent_id、ydh_goods.category_id	有子分类或商品时不允许删除。
单位删除校验	ydh_goods_unit.id	被商品、SKU、库存、订单引用时只能禁用。
SKU 默认生成	ydh_goods_sku	无多规格商品也生成一个默认 SKU，统一价格、库存、订单逻辑。
基准单位唯一	ydh_goods_sku_unit.is_base_unit	每个 SKU 只能有一个基准库存单位。
换算闭环校验	ydh_goods_unit_relation	from_unit_id 不能等于 to_unit_id；有效期不能重叠。
价格有效期校验	level_price/customer_price	同一 SKU 同一客户/级别有效期不能重叠。
库存非负校验	ydh_goods_stock.available_qty	除非允许超卖，否则不能小于 0。
订单快照必填	ydh_order_item	goods_name、sku_code、unit_name、price 等快照字段必须保存。

17. Spring Boot 落地开发建议

17.1 后端服务拆分建议

服务类	职责	关键方法
GoodsCategoryService	分类树、分类新增修改删除、分类迁移	tree、create、update、deleteCheck、move
GoodsUnitService	单位维护、单位启用禁用	create、update、disable、listEnabled
GoodsService	商品主档维护、上下架、导入导出	createGoods、updateGoods、onSale、offSale、deleteGoods
GoodsSkuService	SKU 生成、规格维护、条码维护	generateSku、updateSku、listByGoodsId
GoodsUnitConvertService	单位换算、双单位换算、浮动换算处理	convert、convertToBaseUnit、convertForOrder
GoodsPriceService	客户价/级别价维护、下单取价	getOrderPrice、batchGetPrice、saveLevelPrice、saveCustomerPrice
GoodsStockService	库存查询、锁定、释放、出入库流水	lockStock、releaseStock、deductStock、increaseStock
GoodsPromotionService	促销查询和促销计算	matchPromotion、calculateDiscount
GoodsImportService	商品导入、图片导入、客户定价导入	createTask、parseExcel、validateRow、writeErrorReport

17.2 MyBatis-Plus 开发注意点

注意点	建议
避免大宽表	商品主表只保留核心冗余字段，价格、库存、图片、单位换算拆表。
查询性能	商品列表建议使用 QueryFacade 或自定义 VO 聚合，避免 N+1 查询。
批量取价	订单添加商品时需要批量查询客户专属价和级别价，不要每行单独查。
批量库存	购物车/订单确认页需要批量查询 SKU 可用库存。
快照保存	订单明细必须保存商品、规格、单位、价格快照。
乐观锁	库存扣减建议使用 version 或条件更新，防止并发超卖。
幂等性	库存流水和订单出库扣减要有业务唯一键。
缓存	单位、分类、品牌、标签、价格规则可做 Redis/Caffeine 缓存。
审计	价格修改、上下架、单位换算修改必须写操作日志。

推荐价格接口伪代码：
GoodsPriceResult getOrderPrice(Long tenantId, Long customerId, Long skuId, BigDecimal orderQty) {
    Customer customer = customerService.getById(customerId);
    CustomerPrice cp = customerPriceMapper.selectValid(tenantId, customerId, skuId, now);
    if (cp != null) return buildFromCustomerPrice(cp);

    LevelPrice lp = levelPriceMapper.selectValid(tenantId, customer.getLevelId(), skuId, now);
    if (lp != null) return buildFromLevelPrice(lp);

    GoodsSku sku = goodsSkuMapper.selectById(skuId);
    if (sku.getBaseOrderPrice() != null) return buildFromSku(sku);

    Goods goods = goodsMapper.selectById(sku.getGoodsId());
    return buildFromGoods(goods);
}

18. 升鲜宝参考改造建议

18.1 升鲜宝商品模块改造建议

改造点	建议方案	优先级
商品模型	采用 SPU + SKU + SKU 单位配置，不要只用单一商品表。	高
单位换算	按 SKU 定义单位换算，支持固定换算和浮动换算。	高
双单位库存	水产/生鲜商品支持主单位 + 辅助单位库存显示。	高
价格体系	支持默认价、客户级别价、客户专属价、促销价多级优先级。	高
订单快照	订单明细必须保存商品名称、规格、单位、单价、换算率快照。	高
库存联动	订单提交可锁库存，审核出库扣库存，取消释放库存。	中
商品授权	按客户级别、客户、区域控制商品可见/可订。	中
导入中心	商品、图片、客户价格导入使用任务中心和失败报告。	中
促销中心	商品促销、订单促销与客户级别/区域范围结合。	中
日志审计	价格、上下架、单位换算、库存调整必须记录日志。	高