front/docs/仓储模块设计方案.md

OMS 仓储模块 — 产品与技术设计方案

版本：v0.3（轻量版 + C_ 表前缀 + 库位 + 入库箱）
基线文档：docs/oms系统设计-050801.md、docs/rbac系统设计-060801.md、docs/前端页面设计规范.md
参考实现：WMS 六页业务逻辑（按需裁剪，不做完整 WMS）
对照仓库：C:\Users\wilso\Desktop\oms0414-back（Fake 框架 + SqlSugar）

---

0　轻量版总览（推荐阅读）

v0.1 按 WMS 能力完整对标，表多、接口多、状态细。若目标仅是「客户能管 SKU、预报入库、看库存、接店铺单发货」，采用本节 轻量版 即可，全文 §1～§11 中标注 〔轻量〕 / 〔延后〕 处以此为准。

0.1 设计取向

项	v0.1 完整版	v0.3 轻量版（当前）
定位	对标 WMS 仓储子系统	OMS 附属 基础仓储，保留库位与入库箱
仓储表命名	t_wh_*	C_ + 表名（如 C_sku、C_inventory）
数据表	18 张	13 张（店铺 4 t_* + 仓储 9 C_*）
后端 Service	6 个	3 个（店铺 2 + 仓储 1）
库存模型	批次 lot + 冻结 + 流水	SKU × 仓库 × 库位 余额，不做 FIFO/流水
入库预报	箱 → SKU + 收货日志	主表 + 箱 + 箱内 SKU（保留箱号）
组合 SKU / 库存同步 / 拆单	一期设计	延后
权限粒度	20+ Action	每页 Query + Save + Delete（库存加 Relocate）

0.2 表清单

命名约定

范围	前缀	示例
仓储模块（本文）	C_	C_sku、C_inventory、C_inbound_box
订单 — 店铺（归属订单模块）	t_	t_sales_store、t_sales_store_order
系统主数据	t_	t_warehouse_address

订单 — 店铺（4 张，t_ 前缀）

表	说明
t_sales_store	店铺 + Token 合并（Token 加密，列表脱敏）
t_sales_store_order	店铺订单主表
t_sales_store_order_line	订单明细
C_sku_platform_map	平台 SKU → 库内 SKU（发货匹配；归属仓储域，用 C_）

仓储（9 张，C_ 前缀）

表	说明
C_sku	我的 SKU
C_bin_location	库位主数据（按仓库）
C_inventory	库存余额：CustomerId + WarehouseId + SkuId + BinLocationId → Qty
C_inbound_notice	入库预报主表
C_inbound_box	入库箱（箱号/箱唛）
C_inbound_box_line	箱内 SKU 行
C_parcel	我的包裹
C_parcel_item	包裹明细

延后（相对 v0.1 / 原完整版）

原概念	处理
t_sales_store_token	合并进 t_sales_store
t_sales_store_share / 拆单 / 录单表	延后
C_sku_bundle（组合 SKU）	延后
C_stock_movement（库存流水）	延后
C_inbound_receipt_log（收货日志）	延后，状态字段够用

0.3 轻量版核心流程（够用即可）

flowchart LR
  SKU["我的 SKU<br/>C_sku"] --> MAP["平台映射<br/>C_sku_platform_map"]
  MAP --> PSO["店铺订单"]
  BIN["库位<br/>C_bin_location"]
  IBN["入库预报<br/>C_inbound_notice"] --> BOX["入库箱<br/>C_inbound_box"]
  BOX --> INV["库存<br/>C_inventory"]
  BIN --> INV
  PAR["我的包裹<br/>C_parcel"] -->|"上架到库位"| INV
  PSO -->|"匹配库存"| INV
  PSO -->|"生成小包单"| ORD["t_order"]

1. 我的 SKU：维护库内编码 + 尺重；绑平台 SKU（C_sku_platform_map）。
2. 库位：按仓库维护 C_bin_location；库存按 库位 记数量。
3. 入库预报：主表 + 箱号（C_inbound_box）+ 箱内 SKU（C_inbound_box_line）；收货上架时写入 C_inventory。
4. 我的库存：按 SKU 汇总展示，可展开 各库位明细；支持 换库位（不调 FIFO、不记流水）。
5. 我的包裹：预报快递单号；到仓后上架到指定库位。
6. 店铺订单：库存匹配时按库位扣减 C_inventory.Qty 并建 t_order。

0.4 轻量版接口原则

• 每个页面 列表 + 详情 + 保存 + 删除；统计合并为 summary。
• 仓储一个 WarehouseService（/warehouse/*）。
• 保留：库位列表、入库箱结构、换库位、上架指定库位。
• 不做：库存流水、FIFO 批次、冻结量、组合 SKU、平台库存回写。

0.5 轻量版实施顺序

阶段	交付	说明	状态
Step 1 表	SQL + SqlSugar 实体	sql/migrate_warehouse_module.sql + Oms.Domain 实体	已完成
Step 2 接口	WarehouseService + 店铺 Service	/warehouse/*、/order/platform-store*	已完成
Step 3 页面	前端 6 页 + 路由 + RBAC 菜单	views/warehouse/*、order/platformStore*	已完成

Step 2 交付物（2026-07-11）

层级	路径
Repository	Oms.Domain/WarehouseAggregate/Repositories、Oms.SqlSugarCore/Warehouse/；OrdersAggregate/Repositories（店铺）
DTO	Oms.Application/Dtos/Warehouse/、Dtos/PlatformStore/
Service	Services/Warehouse/WarehouseService；PlatformStoreService；PlatformStoreOrderService

M1～M4 业务分期

阶段	交付	说明
M1	C_sku + C_bin_location + C_inventory + 入库预报（含箱）	5 张 C_* 表 + 约 12 接口
M2	C_parcel + 库存列表/换库位	+2 张表 + 2 页
M3	店铺授权 + 店铺订单	+3 表 + 2 Service + 2 页
M4	库存匹配 → t_order	打通订单

M4 交付物（2026-07-11）

项	说明
PlatformStoreOrderParcelBuilder	店铺订单 → OrderParcelCreateInput
POST /order/platform-store-order/match-inventory	扣库存 → 创建小包 → 回写 LinkedOrderId
POST /order/platform-store-order/batch-match-inventory	批量匹配
前端	销售产品选择、关联服务单号、批量匹配按钮

---

1　导读

1.1 这份文档解决什么问题？

将 WMS 中与客户履约相关的 6 个页面 迁入 OMS，拆为两块：

归属	页面	原 WMS 路由（参考）
订单模块（扩展现有 §4）	店铺授权、店铺订单	/order/platform/shop、/order/platform/shop-orderv2
仓储模块（本文新建 §9）	我的包裹、我的库存、我的 SKU、入库预报	/wms/package/package、/wms/stock/myinventory2、/wms/stock/merchants、/wms/stock/warehousingorder

设计原则：

1. 表名、字段名、接口路径全部重新命名，不沿用 WMS 的 vip_* / wms_* 命名。
2. 业务逻辑对齐 WMS，在 OMS 会话隔离、分页规范、审计字段上对齐现有 OMS 约定。
3. 与现有 OMS 模块边界清晰：小包订单（t_order）与仓储库存（C_*）分离；店铺订单通过 C_sku_platform_map 匹配库存。

1.2 与 OMS 其它模块的关系

flowchart TB
  subgraph Order["订单模块 §4"]
    PS["店铺授权<br/>t_sales_store"]
    PSO["店铺订单<br/>t_sales_store_order"]
    PO["小包订单<br/>t_order"]
  end
  subgraph Warehouse["仓储模块 C_*"]
    BIN["库位<br/>C_bin_location"]
    PAR["我的包裹<br/>C_parcel"]
    SKU["我的 SKU<br/>C_sku"]
    INV["库存<br/>C_inventory"]
    IBN["入库预报<br/>C_inbound_notice"]
  end
  subgraph System["系统主数据 §8"]
    WA["仓库地址<br/>t_warehouse_address"]
  end
  subgraph Operation["操作模块 §6"]
    INB["入库扫描<br/>t_inbound_record"]
    OUT["出库扫描<br/>t_outbound_record"]
  end

  PS --> PSO
  PSO -->|"SKU 映射 + 库存匹配"| SKU
  PSO -->|"一键发货 / 录单"| PO
  PAR --> INV
  IBN --> INV
  BIN --> INV
  SKU --> INV
  WA --> PAR
  WA --> IBN
  INB -.->|"小包运单收货"| PO
  OUT -.->|"小包运单出库"| PO

边界	说明
t_order vs t_sales_store_order	前者为 OMS 小包物流订单；后者为电商平台拉取的 店铺履约单，二者通过 LinkedOrderId 可选关联
t_warehouse_address	仓储业务统一引用系统主数据仓库（WarehouseId → t_warehouse_address.Id），不新建客户侧仓库表
t_inbound_record / t_outbound_record	面向 小包运单（WaybillNo）的仓内扫描；与仓储模块的 SKU 入库预报 / 包裹到仓 是不同业务线，表不合并
客户隔离	全模块 CustomerId → t_customer.Id；规则同 OMS §3.3.5 / §4.4.0

1.3 建议阅读路径

角色	路径
产品 / 测试	§2 页面与菜单 → §5 主流程 → §8 枚举
后端 / DBA	§3 表结构 → §4 接口 → §7 WMS 对照
前端	§2 → §4 → docs/前端页面设计规范.md

---

2　页面、路由与权限

2.1 菜单结构

订单（已有 /order）
├── …（查价、下单、我的订单等）
├── 店铺授权          /order/platformStore
└── 店铺订单          /order/platformStoreOrder

仓储（新建 /warehouse）
├── 我的包裹          /warehouse/parcel
├── 我的库存          /warehouse/inventory
├── 我的 SKU          /warehouse/sku
└── 入库预报          /warehouse/inboundNotice

2.2 前端路由（src/router/routes/newModules/）

订单模块扩展（order.ts 追加 children）：

path	name	component	permission
platformStore	OrderPlatformStore	views/order/platformStore/index.vue	Order.PlatformStore.Query
platformStoreOrder	OrderPlatformStoreOrder	views/order/platformStoreOrder/index.vue	Order.PlatformStoreOrder.Query

仓储模块新建（warehouse.ts）：

path	name	component	permission
parcel	WarehouseParcel	views/warehouse/parcel/index.vue	Warehouse.Parcel.Query
inventory	WarehouseInventory	views/warehouse/inventory/index.vue	Warehouse.Inventory.Query
sku	WarehouseSku	views/warehouse/sku/index.vue	Warehouse.Sku.Query
inboundNotice	WarehouseInboundNotice	views/warehouse/inboundNotice/index.vue	Warehouse.InboundNotice.Query

列表页布局遵循 docs/前端页面设计规范.md：xxx-container、table-toolbar、分页右上角、PaginationPro 默认 30 条。

2.3 RBAC 权限码

格式：{Module}.{Resource}.{Action}（与 RBAC §5.2 一致）。

2.3.1 订单 — 店铺域

权限码	说明
Order.PlatformStore	店铺授权模块
Order.PlatformStore.Query	列表 / 详情
Order.PlatformStore.Create	新增授权 / OAuth 回调落库
Order.PlatformStore.Update	改名、自动发货开关
Order.PlatformStore.Delete	删除店铺
Order.PlatformStoreOrder	店铺订单模块
Order.PlatformStoreOrder.Query	列表 / 详情 / 状态统计
Order.PlatformStoreOrder.Sync	同步平台状态
Order.PlatformStoreOrder.Rts	准备发货（Ready To Ship）
Order.PlatformStoreOrder.AutoMatch	库存匹配生成小包订单
Order.PlatformStoreOrder.Suspend	搁置 / 取消搁置
Order.PlatformStoreOrder.Delete	删除
Order.PlatformStoreOrder.Export	导出
Order.PlatformStoreOrder.Label	获取 / 打印面单
Order.PlatformStoreOrder.Tag	自定义标签

2.3.2 仓储域 〔轻量：每资源 3 个权限即可〕

权限码	说明
Warehouse.Sku.Query / .Save / .Delete	我的 SKU
Warehouse.InboundNotice.Query / .Save / .Delete	入库预报
Warehouse.Parcel.Query / .Save / .Delete	我的包裹
Warehouse.Inventory.Query / .Relocate	我的库存（查询 + 换库位）
Warehouse.BinLocation.Query / .Save	库位维护（管理端/仓库端）

〔延后〕：ApplyStorage、Putaway、Relocate、Adjust、Import、Mapping、Print 等细粒度 Action — 首期 Save 接口内覆盖。

2.4 后端 Service 与路由前缀 〔轻量〕

业务域	Service 类	路由前缀
店铺授权	PlatformStoreService	/order/platform-store/*
店铺订单	PlatformStoreOrderService	/order/platform-store-order/*
仓储（合并）	WarehouseService	/warehouse/*

轻量版仓储 一个 Service 即可，按子路径分 SKU / 入库 / 包裹 / 库存。

---

3　数据表结构设计

遵循 OMS §3.1 公共规范。
轻量版以 §0.2 为准；下列分节含完整版字段，标注 〔延后〕 的表/字段在轻量版中不建。

3.0 轻量版表结构（v0.3 推荐落地）

仓储表一律 C_ 前缀；字段仍用 OMS 驼峰（PascalCase）；必备审计字段见 §3.1 公共规范。

3.0.1 t_sales_store（店铺，含 Token）

在 §3.1.1 基础上 合并 Token，新增：AccessToken、RefreshToken、TokenExtraJson（加密，列表脱敏）。

3.0.2 C_sku（我的 SKU）

字段	类型	非空	说明
Id	BIGINT	是	主键
CustomerId	BIGINT	是	客户
SkuCode	VARCHAR(64)	是	库内编码
SkuName	VARCHAR(256)	是	名称
SkuImageUrl	VARCHAR(512)	否	图片
WeightG / LengthCm / WidthCm / HeightCm	DECIMAL	否	尺重
Remark	VARCHAR(512)	否	备注
审计字段	—	是

索引：uk_c_sku_code (CustomerId, SkuCode)。

3.0.3 C_bin_location（库位）

字段	类型	非空	说明
Id	BIGINT	是	主键
WarehouseId	BIGINT	是	→ t_warehouse_address.Id
BinCode	VARCHAR(32)	是	库位编码，如 A-01-02
BinName	VARCHAR(64)	否	展示名称
ZoneCode	VARCHAR(32)	否	库区
IsEnabled	TINYINT	是	是否启用，默认 1
Remark	VARCHAR(512)	否	备注
审计字段	—	是

索引：uk_c_bin_wh_code (WarehouseId, BinCode)。

库位为 仓库级主数据（不按客户拆分）；库存余额按客户 + 库位区分。

3.0.4 C_inventory（库存余额）

字段	类型	非空	说明
Id	BIGINT	是	主键
CustomerId	BIGINT	是	客户
WarehouseId	BIGINT	是	仓库
SkuId	BIGINT	是	→ C_sku.Id
BinLocationId	BIGINT	是	→ C_bin_location.Id
Qty	INT	是	可用数量（匹配时直接扣减）
审计字段	—	是

唯一索引：uk_c_inventory (CustomerId, WarehouseId, SkuId, BinLocationId)。

「我的库存」列表：按 SkuId 聚合 SUM(Qty)；详情/换库位：按 BinLocationId 展开。
不做冻结量、FIFO 批次、库存流水表。

3.0.5 C_inbound_notice + C_inbound_box + C_inbound_box_line（入库预报，含箱号）

主表 C_inbound_notice

字段	类型	说明
CustomerId	BIGINT	客户
WarehouseId	BIGINT	仓库
NoticeNo	VARCHAR(32)	IN + 雪花
MarkReference	VARCHAR(64)	唛头
InboundType	VARCHAR(16)	normal / return
ReceiptStatus	VARCHAR(16)	forecasted → received → completed
ExpectedArrivalTime	DATETIME	可选
ActualArrivalTime	DATETIME	收货时写入
Remark	VARCHAR(512)

箱表 C_inbound_box

字段	类型	说明
InboundNoticeId	BIGINT	主表
BoxSeqNo	VARCHAR(16)	箱序号
MarkBoxNo	VARCHAR(64)	箱唛号/箱号
WeightG	DECIMAL(10,2)	箱重(g)，可选
LengthCm / WidthCm / HeightCm	DECIMAL	箱尺寸，可选
IsReceived	TINYINT	是否已收货

箱内 SKU 行 C_inbound_box_line

字段	类型	说明
InboundBoxId	BIGINT	箱
SkuId	BIGINT	→ C_sku.Id
SkuCode	VARCHAR(64)	冗余编码
PlannedQty	INT	计划数量
ReceivedQty	INT	实收数量
BinLocationId	BIGINT	上架库位（收货确认时填入）

收货上架逻辑：confirm-receive 按箱清点 → 按行 ReceivedQty + BinLocationId 累加 C_inventory.Qty → 主表 completed。

3.0.6 C_parcel + C_parcel_item（我的包裹）

主表：TrackingNo、CarrierName、WarehouseId、LifecycleStatus（inTransit / arrived / stored）、ArrivalTime、Remark。

明细：ProductName、Quantity、SkuId（上架时关联）、BinLocationId（上架库位，可选）。

3.0.7 C_sku_platform_map（平台 SKU 映射）

字段	类型	说明
CustomerId	BIGINT	客户
StoreId	BIGINT	→ t_sales_store.Id
PlatformSku	VARCHAR(128)	平台 listing SKU
SkuId	BIGINT	→ C_sku.Id
SkuCode	VARCHAR(64)	冗余

索引：uk_c_sku_map (StoreId, PlatformSku)。

3.0.8 t_sales_store_order（店铺订单，字段精简）

保留核心字段 + 明细行；MappedSkuId 指向 C_sku.Id。拆单/录单表延后。

---

3.1 订单模块 — 店铺授权

3.1.1 销售店铺表 t_sales_store

字段名	类型	非空	说明
Id	BIGINT	是	主键
CustomerId	BIGINT	是	客户 Id
PlatformCode	VARCHAR(32)	是	平台：lazada / shopee / tiktok / temu / manual
StoreNickname	VARCHAR(128)	是	店铺昵称（用户自定义）
PlatformStoreId	VARCHAR(64)	否	平台侧店铺 Id
PlatformAccount	VARCHAR(128)	否	平台账号
SiteCountry	VARCHAR(8)	否	开户站点国家码
SellerId	VARCHAR(64)	否	平台卖家 Id
AuthStatus	VARCHAR(16)	是	active / expired / revoked
AuthTime	DATETIME	否	授权时间
TokenExpireTime	DATETIME	否	Access Token 过期
RefreshExpireTime	DATETIME	否	Refresh Token 过期
IsAutoFulfill	TINYINT	是	是否自动发货，默认 0
SortOrder	INT	否	排序
Remark	VARCHAR(512)	否	备注
IsDeleted / 审计字段	—	是	见 §3.1 公共规范

索引：idx_sales_store_customer (CustomerId, IsDeleted)；uk_sales_store_platform (CustomerId, PlatformCode, PlatformStoreId) 唯一（PlatformStoreId 为空时 manual 店铺允许多条）。

3.1.2 店铺授权凭证表 t_sales_store_token 〔轻量：合并至 3.0.1，不单独建表〕

敏感字段加密存储；列表接口 不返回 AccessToken / RefreshToken 明文。

字段名	类型	非空	说明
Id	BIGINT	是	主键
StoreId	BIGINT	是	→ t_sales_store.Id
AccessToken	VARCHAR(2048)	否	加密
RefreshToken	VARCHAR(2048)	否	加密
TokenType	VARCHAR(32)	否	默认 Bearer
Scope	VARCHAR(512)	否	授权范围
ExtraJson	JSON	否	平台扩展（如 Lazada 多站点 userId）
IsDeleted / 审计字段	—	是

3.1.3 店铺共享表 t_sales_store_share 〔延后〕

字段名	类型	非空	说明
Id	BIGINT	是	主键
StoreId	BIGINT	是	主店铺
SharedCustomerId	BIGINT	是	被共享的子客户 Id
IsDeleted / 审计字段	—	是

---

3.2 订单模块 — 店铺订单

3.2.1 店铺订单表 t_sales_store_order

字段名	类型	非空	说明
Id	BIGINT	是	主键
CustomerId	BIGINT	是	客户 Id
StoreId	BIGINT	是	→ t_sales_store.Id
PlatformCode	VARCHAR(32)	是	冗余平台码
PlatformOrderNo	VARCHAR(64)	是	平台订单号
OrderCountry	VARCHAR(8)	否	订单国家
ItemCount	INT	否	商品行数
TotalAmount	DECIMAL(18,4)	否	订单总额
Currency	VARCHAR(8)	否	币种
PaymentMethod	VARCHAR(64)	否	付款方式
PlatformOrderTime	DATETIME	否	平台下单时间
PlatformPayTime	DATETIME	否	平台付款时间
FulfillStatus	VARCHAR(32)	是	履约状态，见 §8.1
PlatformStatus	VARCHAR(64)	否	平台原始状态码
PlatformStatusLabel	VARCHAR(128)	否	平台状态展示文案
ShippingLabelNo	VARCHAR(64)	否	面单号
ShippingLabelUrl	VARCHAR(512)	否	面单文件 URL
IsMultiLabel	TINYINT	是	是否多面单/拆单
DeliveryMethod	VARCHAR(64)	否	运输方式 code
DeliveryMethodLabel	VARCHAR(128)	否	运输方式展示
DeliveryStatus	VARCHAR(32)	否	物流子状态
ShippingCarrier	VARCHAR(64)	否	物流承运商
PickupType	VARCHAR(32)	否	取件类型：pickup / dropoff
CustomTags	VARCHAR(512)	否	用户自定义标签，逗号分隔
IsSuspended	TINYINT	是	是否搁置
PresaleDays	INT	否	预售天数
BuyerRemark	VARCHAR(1024)	否	买家备注
SellerPickRemark	VARCHAR(1024)	否	卖家拣货备注
SellerPickRemarkTime	DATETIME	否	拣货备注时间
WarehouseId	BIGINT	否	发货仓库 → t_warehouse_address.Id
LinkedOrderId	BIGINT	否	关联 OMS 小包订单 t_order.Id
LastSyncTime	DATETIME	否	最近同步时间
StatusChangedTime	DATETIME	否	状态变更时间
SystemShipTime	DATETIME	否	系统发货时间
SystemLabelPrintTime	DATETIME	否	系统打印面单时间
SystemPushTime	DATETIME	否	推送到出库时间
IsDeleted / 审计字段	—	是

索引：uk_store_order_no (StoreId, PlatformOrderNo)；idx_store_order_customer_status (CustomerId, FulfillStatus, PlatformOrderTime)。

3.2.2 店铺订单明细表 t_sales_store_order_line

字段名	类型	非空	说明
Id	BIGINT	是	主键
StoreOrderId	BIGINT	是	→ t_sales_store_order.Id
PlatformLineId	VARCHAR(64)	否	平台行 Id / itemId
PlatformSku	VARCHAR(128)	否	平台 SKU
ProductName	VARCHAR(512)	否	商品名称
ProductImageUrl	VARCHAR(512)	否	商品图
ProductUrl	VARCHAR(512)	否	商品链接
VariantText	VARCHAR(256)	否	规格属性
UnitPrice	DECIMAL(18,4)	否	单价
Quantity	INT	是	数量
Currency	VARCHAR(8)	否	币种
IsShipExcluded	TINYINT	是	是否拒绝发货
MappedSkuId	BIGINT	否	映射的仓储 SKU → C_sku.Id
IsDeleted / 审计字段	—	是

3.2.3 店铺订单快速录单表 t_sales_store_order_draft 〔延后〕

3.2.4 店铺订单拆单表 t_sales_store_order_split 〔延后〕

---

3.3 仓储模块 — 我的包裹

3.3.1 客户包裹表 C_parcel

字段名	类型	非空	说明
Id	BIGINT	是	主键
CustomerId	BIGINT	是	客户 Id
WarehouseId	BIGINT	是	→ t_warehouse_address.Id
TrackingNo	VARCHAR(64)	是	快递单号
CarrierName	VARCHAR(64)	否	快递公司
SourcePlatform	VARCHAR(32)	否	来源平台（淘宝、拼多多等）
ParcelCategory	VARCHAR(16)	是	single 一票一单 / multi 一票多单 / unclaimed 待认领 / stock 库存件
LifecycleStatus	VARCHAR(16)	是	见 §8.2：inTransit / arrived / unclaimed / expired
PurchaseOrderNo	VARCHAR(64)	否	采购订单号（与 OMS 小包无关）
BizScene	VARCHAR(16)	否	业务场景，如 consolidation 集运
ImageUrl	VARCHAR(512)	否	包裹图片
LengthCm	DECIMAL(10,2)	否	长(cm)
WidthCm	DECIMAL(10,2)	否	宽(cm)
HeightCm	DECIMAL(10,2)	否	高(cm)
VolumeCbm	DECIMAL(12,4)	否	体积
WeightKg	DECIMAL(10,3)	否	重量(kg)
ArrivalTime	DATETIME	否	到仓时间
LinkedSkuId	BIGINT	否	关联仓储 SKU
Remark	VARCHAR(512)	否	备注
IsDeleted / 审计字段	—	是

索引：uk_c_parcel_tracking (CustomerId, TrackingNo, WarehouseId)；idx_c_parcel_status (CustomerId, LifecycleStatus)。

3.3.2 包裹明细表 C_parcel_item

字段名	类型	非空	说明
Id	BIGINT	是	主键
ParcelId	BIGINT	是	→ C_parcel.Id
ProductName	VARCHAR(512)	否	商品名称
ProductCategory	VARCHAR(64)	否	商品分类
Quantity	INT	是	数量
ImageUrl	VARCHAR(512)	否	图片
AttributeText	VARCHAR(256)	否	属性
SkuId	BIGINT	否	库内 SKU（上架时关联）
SkuCode	VARCHAR(64)	否	冗余编码
BinLocationId	BIGINT	否	上架库位
IsDeleted / 审计字段	—	是

---

3.4 仓储模块 — 我的 SKU

3.4.1 仓储 SKU 主表 C_sku

字段名	类型	非空	说明
Id	BIGINT	是	主键
CustomerId	BIGINT	是	客户 Id
SkuCode	VARCHAR(64)	是	库内 SKU 编码
SkuName	VARCHAR(256)	是	SKU 名称
SkuImageUrl	VARCHAR(512)	否	图片
CategoryCode	VARCHAR(64)	否	分类
IsBundle	TINYINT	是	是否组合 SKU
WeightG	DECIMAL(10,2)	否	重量(g)
LengthCm	DECIMAL(10,2)	否	长(cm)
WidthCm	DECIMAL(10,2)	否	宽(cm)
HeightCm	DECIMAL(10,2)	否	高(cm)
ReferencePrice	DECIMAL(18,4)	否	参考价
Currency	VARCHAR(8)	否	币种
Remark	VARCHAR(512)	否	备注
IsDeleted / 审计字段	—	是

索引：uk_c_sku_code (CustomerId, SkuCode)。

3.4.2 组合 SKU 子项表 C_sku_bundle_item 〔延后〕

3.4.3 平台 SKU 映射表 C_sku_platform_map

字段名	类型	非空	说明
Id	BIGINT	是	主键
CustomerId	BIGINT	是	客户 Id
StoreId	BIGINT	是	→ t_sales_store.Id
PlatformSku	VARCHAR(128)	是	平台 listing SKU
PlatformProductId	VARCHAR(64)	否	平台商品 Id
SkuId	BIGINT	是	→ C_sku.Id
SkuCode	VARCHAR(64)	是	冗余库内编码
IsDeleted / 审计字段	—	是

索引：uk_c_sku_map (StoreId, PlatformSku)。

---

3.5 仓储模块 — 我的库存

3.5.1 库存余额表 C_inventory（见 §3.0.4）

3.5.2 库位表 C_bin_location（见 §3.0.3）

3.5.3 库存流水表 C_stock_movement 〔延后〕

---

3.6 仓储模块 — 入库预报

3.6.1 入库预报主表 C_inbound_notice

字段名	类型	非空	说明
Id	BIGINT	是	主键
CustomerId	BIGINT	是	客户 Id
WarehouseId	BIGINT	是	仓库
NoticeNo	VARCHAR(32)	是	入库单号，规则 IN + 雪花 Id
MarkReference	VARCHAR(64)	否	唛头参考号
InboundType	VARCHAR(16)	是	normal 普通 / return 退货
ReceiptStatus	VARCHAR(16)	是	见 §8.4
FirstMileCarrier	VARCHAR(64)	否	头程物流
FirstMileTrackingNo	VARCHAR(64)	否	头程单号
ExpectedArrivalTime	DATETIME	否	预计到货
ActualArrivalTime	DATETIME	否	实际到货
IsException	TINYINT	是	是否异常件
ExceptionNote	VARCHAR(1024)	否	异常说明
ExceptionImageUrls	VARCHAR(2048)	否	异常图片，分号分隔
CustomerFeedback	TINYINT	否	客户是否已确认异常
Remark	VARCHAR(512)	否	备注
IsDeleted / 审计字段	—	是

索引：uk_c_inbound_notice_no (NoticeNo)；idx_c_inbound_customer_status (CustomerId, ReceiptStatus)。

3.6.2 入库箱表 C_inbound_box（见 §3.0.5）

字段名	类型	非空	说明
Id	BIGINT	是	主键
InboundNoticeId	BIGINT	是	→ C_inbound_notice.Id
BoxSeqNo	VARCHAR(16)	是	箱序号
MarkBoxNo	VARCHAR(64)	否	箱唛号/箱号
WeightG	DECIMAL(10,2)	否	箱重(g)
LengthCm / WidthCm / HeightCm	DECIMAL(10,2)	否	箱尺寸
IsReceived	TINYINT	是	是否已收货
审计字段	—	是

3.6.3 入库箱 SKU 行表 C_inbound_box_line（见 §3.0.5）

字段名	类型	非空	说明
Id	BIGINT	是	主键
InboundBoxId	BIGINT	是	→ C_inbound_box.Id
SkuId	BIGINT	是	→ C_sku.Id
SkuCode	VARCHAR(64)	是	冗余编码
PlannedQty	INT	是	计划入库数量
ReceivedQty	INT	否	实收数量
BinLocationId	BIGINT	否	上架库位（收货时填）
审计字段	—	是

3.6.4 入库收货日志表 C_inbound_receipt_log 〔延后〕

---

4　接口设计

分页：{ items, total }；默认 pageSize=30。客户隔离同 §6。
轻量版接口以 §4.0 为准；§4.1～§4.6 为完整版参考。

4.0 轻量版接口清单（推荐）

仓储 WarehouseService — 共 20 个

页面	方法	路径	说明
SKU	POST	/warehouse/sku/list	列表
SKU	GET	/warehouse/sku/detail	详情
SKU	POST	/warehouse/sku/save	新增/编辑
SKU	POST	/warehouse/sku/delete	删除
SKU	POST	/warehouse/sku/bind-mapping	绑定平台 SKU
库位	POST	/warehouse/bin-location/list	按仓库查库位
库位	POST	/warehouse/bin-location/save	新增/编辑库位
入库	POST	/warehouse/inbound/list	列表
入库	GET	/warehouse/inbound/detail	详情含 boxes[].lines[]
入库	POST	/warehouse/inbound/save	新增/编辑（含箱号，仅 forecasted）
入库	POST	/warehouse/inbound/delete	删除
入库	POST	/warehouse/inbound/confirm-receive	按箱收货上架 → 写 C_inventory
入库	GET	/warehouse/inbound/summary	状态 Tab 数量
包裹	POST	/warehouse/parcel/list	列表
包裹	POST	/warehouse/parcel/save	新增/编辑
包裹	POST	/warehouse/parcel/delete	删除
包裹	POST	/warehouse/parcel/putaway	到仓上架（指定 binLocationId）
库存	POST	/warehouse/inventory/list	按 SKU 聚合列表
库存	GET	/warehouse/inventory/bin-detail	某 SKU 各库位明细
库存	POST	/warehouse/inventory/relocate	换库位（源库位 → 目标库位）

店铺 — 共 14 个（首期可再砍）

页面	方法	路径	说明
授权	POST	/order/platform-store/list	列表
授权	POST	/order/platform-store/auth-url	OAuth
授权	POST	/order/platform-store/save	改名等
授权	POST	/order/platform-store/delete	删除
订单	POST	/order/platform-store-order/list	列表
订单	GET	/order/platform-store-order/detail	详情
订单	GET	/order/platform-store-order/summary	状态统计（合并多个 count 接口）
订单	POST	/order/platform-store-order/sync-status	同步
订单	POST	/order/platform-store-order/ready-to-ship	RTS
订单	POST	/order/platform-store-order/match-inventory	库存匹配 → t_order
订单	POST	/order/platform-store-order/fetch-label	面单
订单	POST	/order/platform-store-order/toggle-suspend	搁置
订单	POST	/order/platform-store-order/delete	删除

入库 save 请求（含箱号）

{
  "id": 0,
  "warehouseId": 1,
  "markReference": "MARK-001",
  "inboundType": "normal",
  "remark": "",
  "boxes": [
    {
      "boxSeqNo": "1",
      "markBoxNo": "BOX-001",
      "weightG": 1200,
      "lengthCm": 40,
      "widthCm": 30,
      "heightCm": 20,
      "lines": [
        { "skuId": 1001, "skuCode": "SKU-A001", "plannedQty": 50 }
      ]
    }
  ]
}

confirm-receive 请求要点：按箱提交实收数量及每行 binLocationId，服务端 upsert C_inventory。

库存匹配：按 C_sku_platform_map 解析 SKU，从指定库位（或默认库位）扣减 C_inventory.Qty；不足则失败；不记流水。

---

4.1 订单 — 店铺授权 /order/platform-store/*（完整版参考）

接口	方法	路径	说明
店铺列表	POST	/order/platform-store/list	分页；筛 platformCode、storeNickname、授权到期
授权 URL	POST	/order/platform-store/auth-url	获取 OAuth 跳转地址
OAuth 回调落库	POST	/order/platform-store/auth-callback	各平台 token 写入 t_sales_store_token
店铺详情	GET	/order/platform-store/detail	id
改名	POST	/order/platform-store/rename	id, storeNickname
删除	POST	/order/platform-store/delete	ids[]
自动发货开关	POST	/order/platform-store/toggle-auto-fulfill	ids[], enabled
到期提醒统计	GET	/order/platform-store/expiration-stats	即将过期 / 已过期数量
状态统计	POST	/order/platform-store/dashboard-stats	按平台汇总店铺与订单数

列表请求示例

{
  "page": 1,
  "pageSize": 30,
  "platformCode": "shopee",
  "storeNickname": "",
  "expirationFilter": "normal"
}

expirationFilter：normal / within7days / expired。

列表响应 items[] 关键字段：id, platformCode, platformName, storeNickname, platformAccount, siteCountry, authStatus, authTime, tokenExpireTime, isAutoFulfill, createTime。

平台子接口（建议内聚于 PlatformStoreService，路径带平台段）：

平台	路径前缀
Shopee	/order/platform-store/shopee/*
Lazada	/order/platform-store/lazada/*
TikTok	/order/platform-store/tiktok/*

---

4.2 订单 — 店铺订单 /order/platform-store-order/*

接口	方法	路径	说明
订单列表	POST	/order/platform-store-order/list	分页 + 多 Tab 状态
状态统计	POST	/order/platform-store-order/status-count	各履约状态数量
待发货统计	GET	/order/platform-store-order/pending-ship-count
取消单统计	GET	/order/platform-store-order/canceled-count
订单详情	GET	/order/platform-store-order/detail	含 lines[]、拆单、草稿
准备发货 RTS	POST	/order/platform-store-order/ready-to-ship	单条
批量 RTS	POST	/order/platform-store-order/batch-ready-to-ship
库存匹配下单	POST	/order/platform-store-order/match-inventory	按 SKU 映射扣库存并创建 t_order 草稿
批量库存匹配	POST	/order/platform-store-order/batch-match-inventory
同步平台状态	POST	/order/platform-store-order/sync-status
搁置 / 取消搁置	POST	/order/platform-store-order/toggle-suspend
删除	POST	/order/platform-store-order/delete	ids[]
获取面单	POST	/order/platform-store-order/fetch-label	返回 shippingLabelUrl
更新标签	POST	/order/platform-store-order/update-tags	id, customTags
快速录单	POST	/order/platform-store-order/add-draft	写入 t_sales_store_order_draft
导出	POST	/order/platform-store-order/export	异步或同步文件流

列表请求关键字段

{
  "page": 1,
  "pageSize": 30,
  "platformCode": "shopee",
  "fulfillStatus": "pending",
  "platformOrderNo": "",
  "shippingLabelNo": "",
  "storeId": null,
  "isSuspended": false,
  "orderTimeStart": "2026-01-01",
  "orderTimeEnd": "2026-04-01",
  "searchType": "orderNo",
  "searchKeyword": ""
}

searchType：orderNo（平台单号）/ labelNo（面单号）/ whSku（库内 SKU）。

列表响应 items[] 关键字段：id, storeId, storeNickname, platformCode, platformOrderNo, orderCountry, totalAmount, currency, platformOrderTime, fulfillStatus, fulfillStatusLabel, shippingLabelNo, shippingLabelUrl, isMultiLabel, deliveryMethodLabel, customTags, isSuspended, presaleDays, lines[]（含 platformSku, productName, quantity, isShipExcluded）, linkedOrderId。

库存匹配下单逻辑（对齐 WMS matchSkuInventoryOrder）

1. 校验店铺订单归属与 fulfillStatus 允许发货。
2. 按 C_sku_platform_map 解析每行 MappedSkuId；未映射行失败。
3. 按库位扣减 C_inventory.Qty（优先默认库位或请求指定 binLocationId）。
4. 调用 OMS CreateParcelCoreAsync 创建小包订单草稿，回写 LinkedOrderId。
5. 更新店铺订单 fulfillStatus。

---

4.3 仓储 — 我的包裹 /warehouse/parcel/*

接口	方法	路径	说明
包裹列表	POST	/warehouse/parcel/list	按 lifecycleStatus Tab
状态统计	POST	/warehouse/parcel/status-count	各状态数量
包裹详情	GET	/warehouse/parcel/detail	含 items[]
新增	POST	/warehouse/parcel/create
编辑	POST	/warehouse/parcel/update
删除	POST	/warehouse/parcel/delete	ids[]
申请入库	POST	/warehouse/parcel/apply-storage	到仓包裹进入库存流程

列表请求：lifecycleStatus（inTransit/arrived/unclaimed/expired）、warehouseId、trackingNo、parcelCategory、productName（模糊搜明细）。

创建请求

{
  "warehouseId": 1,
  "trackingNo": "SF1234567890",
  "carrierName": "顺丰",
  "parcelCategory": "single",
  "remark": "",
  "items": [
    {
      "productName": "手机壳",
      "quantity": 2,
      "imageUrl": "",
      "attributeText": "黑色"
    }
  ]
}

---

4.4 仓储 — 我的库存 /warehouse/inventory/*

接口	方法	路径	说明
库存汇总列表	POST	/warehouse/inventory/list	已入库 SKU 维度
在途列表	POST	/warehouse/inventory/in-transit-list	已到仓未上架（对齐 WMS packageList3）
状态统计	GET	/warehouse/inventory/status-count	已到仓 / 已入库数量
库位明细	GET	/warehouse/inventory/bin-detail	某 SKU 多库位
上架	POST	/warehouse/inventory/putaway	包裹或 SKU 上架
换库位	POST	/warehouse/inventory/relocate
调整数量	POST	/warehouse/inventory/adjust-qty	多库位批量调整
更新尺重	POST	/warehouse/inventory/update-dimension
库存流水	POST	/warehouse/inventory/movement-list	分页
导出	POST	/warehouse/inventory/export

库存列表请求：whSkuCode, productName, availabilityFilter（available/replenish/all）、warehouseId, sortBy（putawayTime/availableQty）。

列表响应 items[]：whSkuId, whSkuCode, skuName, availableQty, onHandQty, frozenQty, binLocationCode, lengthCm, widthCm, heightCm, weightG, putawayTime, parcelTrackingNo（来源包裹）。

---

4.5 仓储 — 我的 SKU /warehouse/sku/*

接口	方法	路径	说明
SKU 列表	POST	/warehouse/sku/list	分页
类型统计	GET	/warehouse/sku/type-count	普通 / 组合数量
详情	GET	/warehouse/sku/detail	含映射、组合子项
新增	POST	/warehouse/sku/create
编辑	POST	/warehouse/sku/update
删除	POST	/warehouse/sku/delete
批量删除	POST	/warehouse/sku/batch-delete
批量导入	POST	/warehouse/sku/import	Excel
组合 SKU 导入	POST	/warehouse/sku/import-bundle
映射详情	GET	/warehouse/sku/mapping-detail	whSkuId
批量绑定平台 SKU	POST	/warehouse/sku/bind-platform-sku
导入映射	POST	/warehouse/sku/import-mapping
打印 SKU 标签	POST	/warehouse/sku/print-label	返回 PDF URL

列表请求：skuCode, skuName, isBundle, mappingStatus（mapped/unmapped/all）, sortBy。

列表响应：id, skuCode, skuName, skuImageUrl, isBundle, weightG, lengthCm, widthCm, heightCm, referencePrice, currency, mappingCount, onHandQty, inboundPendingQty, binLocationCode。

---

4.6 仓储 — 入库预报 /warehouse/inbound-notice/*

接口	方法	路径	说明
列表	POST	/warehouse/inbound-notice/list	分页
状态统计	POST	/warehouse/inbound-notice/status-count
详情	GET	/warehouse/inbound-notice/detail	含 boxes[].lines[]
新增	POST	/warehouse/inbound-notice/create
编辑	POST	/warehouse/inbound-notice/update	仅 receiptStatus=forecasted 可编辑
删除	POST	/warehouse/inbound-notice/delete
导入校验	POST	/warehouse/inbound-notice/import-validate	箱号导入预检
导入保存	POST	/warehouse/inbound-notice/import-save
异常信息	GET	/warehouse/inbound-notice/exception-detail
标记异常	POST	/warehouse/inbound-notice/mark-exception
取消异常	POST	/warehouse/inbound-notice/clear-exception
确认收货	POST	/warehouse/inbound-notice/confirm-receive	客户侧确认到仓
SKU 清点	POST	/warehouse/inbound-notice/inspect
打印标签	POST	/warehouse/inbound-notice/print-label	PDF
生成单号	GET	/warehouse/inbound-notice/next-no	可选预取

创建请求

{
  "warehouseId": 1,
  "markReference": "MARK-001",
  "inboundType": "normal",
  "remark": "",
  "boxes": [
    {
      "boxSeqNo": "1",
      "markBoxNo": "BOX-001",
      "weightG": 1200,
      "lengthCm": 40,
      "widthCm": 30,
      "heightCm": 20,
      "lines": [
        {
          "whSkuId": 1001,
          "whSkuCode": "SKU-A001",
          "plannedQty": 50
        }
      ]
    }
  ]
}

服务端生成 noticeNo = IN + SnowflakeId。

列表响应关键字段：id, noticeNo, markReference, warehouseId, warehouseName, inboundType, receiptStatus, receiptStatusLabel, expectedArrivalTime, actualArrivalTime, skuSummary, receivedSkuSummary, receiveProgress, boxCount, receivedBoxCount, isException, createTime。

---

5　主业务流程

5.1 店铺授权 → 拉单

sequenceDiagram
  participant U as 客户
  participant OMS as OMS API
  participant Plat as 电商平台

  U->>OMS: 获取 auth-url
  OMS-->>U: OAuth URL
  U->>Plat: 授权
  Plat-->>OMS: auth-callback(code)
  OMS->>OMS: 写入 t_sales_store + token
  Note over OMS,Plat: 定时任务拉取店铺订单
  OMS->>Plat: 拉单 API
  OMS->>OMS: upsert t_sales_store_order

• 平台订单 定时同步 + 手动「同步状态」；Token 过期前刷新（各平台 Adapter）。
• Manual 店铺：无 OAuth，支持手工录入订单（二期）。

5.2 店铺订单 → 小包发货

1. 用户在「店铺订单」筛选 fulfillStatus=pending。
2. 操作「库存匹配」：映射 → 扣库存 → 创建 t_order。
3. 或操作「准备发货」：调平台 RTS API → 更新 fulfillStatus。
4. 获取平台面单 → 可关联 OMS 出库流程。

5.3 入库预报 → 库存

1. 客户维护 C_sku → 创建入库预报（C_inbound_notice + 箱号 C_inbound_box + 箱内行 C_inbound_box_line）→ ReceiptStatus=forecasted。
2. 仓库 confirm-receive：按箱清点，每行指定 BinLocationId → 累加 C_inventory.Qty → completed。
3. 不做清点/上架多态、收货日志表。

5.4 我的包裹 → 库存

1. 客户登记快递单号 → inTransit。
2. 到仓 → arrived；putaway 指定 SkuId + BinLocationId → 累加 C_inventory → stored。

---

6　客户数据隔离

与 OMS §4.4.0 对齐，扩展至仓储模块：

规则	说明
隔离键	effectiveCustomerId = t_customer.Id
列表	强制 CustomerId = effectiveCustomerId
单条读写	先查主表 CustomerId，不匹配返回「数据不存在」
子客户	与订单模块策略统一（推荐归并主客户 Id）
关联表	通过主表 OrderId / ParcelId / InboundNoticeId 间接隔离
管理员	loginType=0 可传 customerId 查指定客户（与现网订单一致）

---

7　WMS 对照表（实现参考，非字段拷贝）

WMS 概念	WMS 表/字段	OMS 设计
店铺	vip_shop	t_sales_store + t_sales_store_token
店铺订单	vip_shop_ord	t_sales_store_order
订单明细	vip_shop_ord_pro	t_sales_store_order_line
包裹	vip_package	C_parcel
包裹明细	vip_package_pro	C_parcel_item
库存余额	vip_package_inventory	C_inventory（按库位）
库位	storage_id / storageText	C_bin_location
库存流水	wms_stock_record	C_stock_movement
商品 SKU	wms_goods_sku	C_sku
组合 SKU	wms_goods_sku_combine	C_sku_bundle_item
平台映射	wms_shop_mapping_products_contact	C_sku_platform_map
入库单	wms_warehousing_order	C_inbound_notice
入库箱	wms_warehousing_box	C_inbound_box
箱内 SKU	wms_warehousing_box_goods	C_inbound_box_line
收货日志	wms_warehousing_order_inbound_log	C_inbound_receipt_log
会员	vipId	CustomerId
仓库	whseId	WarehouseId → t_warehouse_address

WMS 接口前缀	OMS 接口前缀
/vip/shop/*	/order/platform-store/*
/vip/ord/*	/order/platform-store-order/*
/vip/package/*	/warehouse/parcel/*、/warehouse/inventory/*
/wms/warehousing/sku/*	/warehouse/sku/*
/wms/warehousing/order/*	/warehouse/inbound/*

---

8　枚举与常量

8.1 店铺订单履约状态 FulfillStatus

值	说明	WMS 对应
all	全部（筛选用）	0
pending	待处理	pending
toShip	待发货	toBeShipped
canceled	已取消	cancel
suspended	已搁置	suspended
shipped	已发货	shipped
completed	已完成	completed

8.2 包裹生命周期 LifecycleStatus

轻量版（3 态）：inTransit / arrived / stored

值	说明	WMS pkgStatus
inTransit	待到仓	1
arrived	已到仓	2
stored	已入库	—
unclaimed	待认领 〔延后〕	3
expired	已到期 〔延后〕	4

8.3 库存变动类型 MovementType 〔延后，轻量版不建流水表〕

值	说明
inbound	入库上架
allocate	订单分配冻结
release	释放冻结
outbound	出库扣减
adjust	人工调整
relocate	换库位

8.4 入库预报状态 ReceiptStatus

轻量版（3 态）：forecasted → received → completed

值	说明	WMS adopt
forecasted	已预报	N
received	已到仓待确认	B/C 合并
completed	已入库	Y
inspecting / putaway / exception	〔延后〕

8.5 平台编码 PlatformCode

值	平台
lazada	Lazada
shopee	Shopee
tiktok	TikTok Shop
temu	Temu
manual	手工店铺

---

9　实施分期建议 〔轻量版见 §0.5〕

阶段	范围	交付物
M1	SKU + 入库预报 + 库存余额	3 表 + WarehouseService 10 个接口 + 2 页
M2	包裹 + 库存只读页	+2 表 + 6 接口 + 2 页
M3	店铺授权 + 店铺订单	+3 表 + 2 Service + 2 页
M4	库存匹配 → t_order	打通订单

完整版分期（v0.1，仅供参考）

阶段	范围
P0～P4	见原表

---

10　附录：迁移脚本

一步建表（推荐）

sql/migrate_warehouse_module.sql   -- 仓储 C_* 9 张 + 店铺 t_sales_* 3 张

执行后需在 Oms.Domain 中已有对应实体（Step 1 已落地）。

---

11　待决事项（评审时确认）

1. 子客户订单归属：与订单模块统一。
2. 库位维护入口：C_bin_location 放仓储菜单还是系统仓库管理 — 建议 仓库地址详情页 或仓储下子页。
3. 默认库位：每仓库是否预置一个 DEFAULT 库位，简化客户上架。
4. 包裹是否 M1 必做：主路径若为入库预报，包裹可 M2。
5. 平台首期范围：Shopee / Lazada / TikTok 择几先做。

---

文档结束。实现时以 docs/oms系统设计-050801.md §3 公共规范与 docs/rbac系统设计-060801.md 权限模型为准；若与本文冲突，以评审结论更新本文档版本号。