wms-saas/docs/04-domain-model.md

04 WMS 领域模型

业务编码优先

业务系统尽量使用明确的业务编码：

编码	含义
tenant_code	租户
warehouse_code	仓库
location_code	库位
customer_code	客户
supplier_code	供应商
product_code	商品
sku_code	SKU
order_no	订单
inbound_no	入库单
outbound_no	出库单
picking_no	拣货单
shipment_no	发货单
package_no	包裹

不要让业务逻辑全部依赖数据库自增 ID。数据库 ID 可以作为内部主键，但业务关联应优先考虑业务编码。

业务模块（第一阶段设计）

1. SaaS

租户、用户、角色、权限、租户设置、操作日志

2. 基础资料

客户、供应商、商品、SKU、SKU 条码、包装规格、重量、尺寸

3. 仓库

仓库、库区、库位、库位类型、库位容量、库位策略

4. 入库

入库单、入库明细、收货、收货差异、质检、上架、入库流水

5. 出库

出库单、出库明细、库存分配、波次、拣货任务、复核、打包、发货

6. 库存

库存查询、库存余额、库存流水、库存锁定、库存调整、库存盘点、库存冻结、库存解冻、库存预警

7. 退货

退货单、退货收货、退货质检、重新入库、报废

8. 物流

物流渠道、承运商、物流服务、运费规则、面单、发货、Tracking

9. 报表

库存报表、入库报表、出库报表、库存周转、SKU 销量、仓库作业统计

10. AI / 数据分析（预留 Python 服务接口）

库存分析、SKU 销量分析、缺货预测、补货建议、库存周转分析、异常库存、AI WMS Assistant

订单模型

WMS 不应和某一个电商平台强绑定，订单应抽象为统一订单模型，例如：

• order
• order_item
• order_source
• order_status
• order_external_no
• order_channel

以后可以支持：Amazon、Shopify、TikTok Shop、Temu、Shopee、Mirakl、ERP、API、手工订单。

不要在核心订单表中写死 Amazon / TikTok 等平台业务逻辑。

第三方平台架构

第三方平台必须采用 Adapter / Connector 思路：

MarketplaceConnector (接口)
├── AmazonConnector
├── ShopifyConnector
├── MiraklConnector
└── TikTokShopConnector

以后增加平台时，不应该修改大量核心 WMS 代码。核心 WMS 只关心：

• 统一订单
• 统一 SKU
• 统一库存
• 统一物流
• 统一状态

平台实现放在 app/Infrastructure/Platforms/{Platform}/，负责平台数据与统一模型之间的映射。

状态机

入库、出库、订单、库存任务不要到处使用：

if ($status == xxx)

应设计明确的状态流转。例如出库：

draft → allocated → picking → picked → packing → packed → shipped → completed

• 状态使用 PHP Enum 定义，禁止魔法字符串。
• 允许的状态转换集中定义，非法状态转换必须被阻止。
• 状态变更需记录日志（谁、何时、从何状态到何状态）。