docs/00-overview.md

2026-09-29 13:08:21 +08:00
parent c30f7e2e7b
commit cb9b7a4bd4
20 changed files with 1383 additions and 0 deletions
@@ -0,0 +1,110 @@
+# 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}/`，负责平台数据与统一模型之间的映射。
+
+## 状态机
+
+入库、出库、订单、库存任务不要到处使用：
+
+```php
+if ($status == xxx)
+```
+
+应设计明确的状态流转。例如出库：
+
+```
+draft → allocated → picking → picked → packing → packed → shipped → completed
+```
+
+- 状态使用 PHP Enum 定义，禁止魔法字符串。
+- 允许的状态转换集中定义，**非法状态转换必须被阻止**。
+- 状态变更需记录日志（谁、何时、从何状态到何状态）。