57651173/wms-saas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
Yangxt
2026-09-30 11:11:54 +08:00
parent cb9b7a4bd4
commit 2fb57ec490
160 changed files with 14764 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/database/README.md
+90 -47
View File
@@ -1,57 +1,100 @@
# 数据库表结构设计
本目录存放 WMS SaaS 的数据库表结构设计，是 `backend/database/migrations` 的设计依据。通用规范见 [../09-database.md](../09-database.md)。
本目录是 MySQL 8 建表设计稿，每张表一个 `.sql` 文件。通用规范见 [../09-database.md](../09-database.md)，命名、类型和库存粒度见 [00-conventions.md](./00-conventions.md)。
**先设计、确认，再写迁移；改表时迁移与本目录文档同步更新。**
落地方式：某个 Phase 开工时，只把本阶段要用的表写成 Laravel migration，并与这里的 SQL 保持一致。不要一次生成全部 migration，也不要在生产库直接执行这些文件。
## 文件组织
表之间没有外键，执行顺序没有依赖。
按业务领域一个文件，文件内包含该领域所有表：
## 表清单
| 文件 | 领域 | 对应 Phase |
| --- | --- | --- |
| `00-conventions.md` | 命名、公共字段、类型、索引约定 | 1 |
| `01-er-overview.md` | 全局 ER 关系图 | 1 |
| `10-saas.md` | 租户、用户、角色、权限、租户设置、操作日志 | 4 |
| `20-warehouse.md` | 仓库、库区、库位、库位类型 / 容量 / 策略 | 5 |
| `30-master-data.md` | 客户、供应商、商品、SKU、条码、包装规格 | 6 |
| `40-inventory.md` | 库存余额、批次、库存流水、锁定 / 冻结、调整、盘点 | 7、8 |
| `50-inbound.md` | 入库单、明细、收货、差异、质检、上架 | 9 |
| `60-outbound.md` | 订单、出库单、明细、分配、波次、拣货、复核、打包、发货 | 10、11 |
| `70-return.md` | 退货单、退货收货、质检、重新入库、报废 | — |
| `80-logistics.md` | 物流渠道、承运商、服务、运费规则、面单、Tracking | 12 |
| `90-integration.md` | 第三方平台店铺、凭证、同步任务、Webhook 日志 | 14 |
| `95-audit.md` | 登录日志、API 日志、状态变更日志、数据审计 | 4 起 |
文件在对应 Phase 开始前创建，不提前为未来阶段编写。
## 单表设计模板
````markdown
### wms_xxx 表中文名
用途：一句话说明。
| 字段 | 类型 | 可空 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
| tenant_code | VARCHAR(32) | N | | 租户编码 |
| xxx_code | VARCHAR(64) | N | | 业务编码 |
| status | VARCHAR(32) | N | | 状态，取值见下方状态说明 |
| version | INT UNSIGNED | N | 0 | 乐观锁（按需） |
| created_at | TIMESTAMP | Y | | |
| updated_at | TIMESTAMP | Y | | |
索引：
| 名称 | 类型 | 字段 | 支撑的查询 |
| 表 | 说明 | 目录 | Phase |
| --- | --- | --- | --- |
| uk_tenant_xxx_code | UNIQUE | (tenant_code, xxx_code) | 按业务编码查找 |
| idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表筛选 |
| [wms_tenant](./01-saas/wms_tenant.sql) | 租户。SaaS 隔离边界，tenant_code 全局唯一。 | `01-saas` | 4 |
| [wms_user](./01-saas/wms_user.sql) | 用户。租户内登录账号。 | `01-saas` | 4 |
| [wms_role](./01-saas/wms_role.sql) | 角色。租户内角色。 | `01-saas` | 4 |
| [wms_permission](./01-saas/wms_permission.sql) | 权限。全局权限码目录，不按租户复制。 | `01-saas` | 4 |
| [wms_role_permission](./01-saas/wms_role_permission.sql) | 角色权限。租户内角色与全局权限码的绑定。 | `01-saas` | 4 |
| [wms_user_role](./01-saas/wms_user_role.sql) | 用户角色。租户内用户与角色的绑定。 | `01-saas` | 4 |
| [wms_tenant_setting](./01-saas/wms_tenant_setting.sql) | 租户设置。租户级可配置项，包括定时任务开关。 | `01-saas` | 4 |
| [wms_number_sequence](./01-saas/wms_number_sequence.sql) | 单号序列。按租户、业务类型发号，保证并发下单号不重复。 | `01-saas` | 4 |
| [wms_warehouse](./02-warehouse/wms_warehouse.sql) | 仓库。租户下的物理仓库。 | `02-warehouse` | 5 |
| [wms_zone](./02-warehouse/wms_zone.sql) | 库区。仓库内的功能分区。 | `02-warehouse` | 5 |
| [wms_location_type](./02-warehouse/wms_location_type.sql) | 库位类型。库位的混放规则。 | `02-warehouse` | 5 |
| [wms_location](./02-warehouse/wms_location.sql) | 库位。仓库内可存放库存的最小位置，同时保存容量。 | `02-warehouse` | 5 |
| [wms_location_strategy](./02-warehouse/wms_location_strategy.sql) | 库位策略。上架、分配、拣货的规则。空编码表示该条件不限。 | `02-warehouse` | 5 |
| [wms_customer](./03-master/wms_customer.sql) | 货主。3PL 的客户。自营租户也建一个默认货主，库存一律落到货主。 | `03-master` | 6 |
| [wms_customer_warehouse](./03-master/wms_customer_warehouse.sql) | 货主仓库。货主可以使用哪些仓库。 | `03-master` | 6 |
| [wms_supplier](./03-master/wms_supplier.sql) | 供应商。入库来源供应商。 | `03-master` | 6 |
| [wms_product](./03-master/wms_product.sql) | 商品。SKU 的上层商品，属于一个货主。 | `03-master` | 6 |
| [wms_sku](./03-master/wms_sku.sql) | SKU。库存与订单的最小商品单位，含单件重量和尺寸。 | `03-master` | 6 |
| [wms_sku_barcode](./03-master/wms_sku_barcode.sql) | SKU 条码。SKU 的扫描条码，租户内一条码只对应一个 SKU。 | `03-master` | 6 |
| [wms_package_spec](./03-master/wms_package_spec.sql) | 包装规格。SKU 的装箱规格，如一件箱装多少件。 | `03-master` | 6 |
| [wms_batch](./04-inventory/wms_batch.sql) | 批次。启用批次或效期管理的 SKU 的批次档案。 | `04-inventory` | 7 |
| [wms_inventory](./04-inventory/wms_inventory.sql) | 库存余额。某个货主、仓库、库位、SKU、批次上的数量结果。 | `04-inventory` | 7 |
| [wms_stock_log](./04-inventory/wms_stock_log.sql) | 库存流水。库存变化的事实记录，只能追加。 | `04-inventory` | 8 |
| [wms_inventory_hold](./04-inventory/wms_inventory_hold.sql) | 库存冻结单。把可用库存转为冻结的业务单据。 | `04-inventory` | 8 |
| [wms_inventory_hold_item](./04-inventory/wms_inventory_hold_item.sql) | 库存冻结明细。冻结单的库位与数量。 | `04-inventory` | 8 |
| [wms_stock_adjustment](./04-inventory/wms_stock_adjustment.sql) | 库存调整单。盘盈盘亏、报损等人工调整。 | `04-inventory` | 8 |
| [wms_stock_adjustment_item](./04-inventory/wms_stock_adjustment_item.sql) | 库存调整明细。调整的数量桶与变化量。 | `04-inventory` | 8 |
| [wms_stocktake](./04-inventory/wms_stocktake.sql) | 盘点单。仓库盘点任务。 | `04-inventory` | 8 |
| [wms_stocktake_item](./04-inventory/wms_stocktake_item.sql) | 盘点明细。系统数量与实盘数量。 | `04-inventory` | 8 |
| [wms_inventory_alert](./04-inventory/wms_inventory_alert.sql) | 库存预警规则。SKU 在仓库的最低可用量阈值。 | `04-inventory` | 8 |
| [wms_inbound](./05-inbound/wms_inbound.sql) | 入库单。入库作业的头单据。 | `05-inbound` | 9 |
| [wms_inbound_item](./05-inbound/wms_inbound_item.sql) | 入库明细。入库单行，数量列是各作业的汇总结果。 | `05-inbound` | 9 |
| [wms_inbound_receipt](./05-inbound/wms_inbound_receipt.sql) | 收货记录。一张入库单可以分多次收货。 | `05-inbound` | 9 |
| [wms_inbound_receipt_item](./05-inbound/wms_inbound_receipt_item.sql) | 收货明细。本次实收数量以及与预计的差异。 | `05-inbound` | 9 |
| [wms_inbound_qc](./05-inbound/wms_inbound_qc.sql) | 入库质检。按收货结果做的质检记录。 | `05-inbound` | 9 |
| [wms_inbound_putaway](./05-inbound/wms_inbound_putaway.sql) | 上架任务。把收货库位的合格库存移到存储库位。 | `05-inbound` | 9 |
| [wms_order](./06-outbound/wms_order.sql) | 统一订单。与具体电商平台解耦的履约订单。 | `06-outbound` | 10 |
| [wms_order_item](./06-outbound/wms_order_item.sql) | 订单明细。订单要履约的 SKU 与数量。 | `06-outbound` | 10 |
| [wms_outbound](./06-outbound/wms_outbound.sql) | 出库单。仓库执行单据。一张订单可按仓库拆成多张出库单。 | `06-outbound` | 10 |
| [wms_outbound_item](./06-outbound/wms_outbound_item.sql) | 出库明细。出库单行及各作业数量汇总。 | `06-outbound` | 10 |
| [wms_allocation](./06-outbound/wms_allocation.sql) | 库存分配。出库行预占到具体库位批次的记录，也是库存锁定明细。 | `06-outbound` | 10 |
| [wms_wave](./06-outbound/wms_wave.sql) | 波次。把多张出库单组成一次拣货。 | `06-outbound` | 11 |
| [wms_wave_outbound](./06-outbound/wms_wave_outbound.sql) | 波次出库。波次包含的出库单。 | `06-outbound` | 11 |
| [wms_picking_task](./06-outbound/wms_picking_task.sql) | 拣货任务。一次派给拣货人的任务，可来自波次或单张出库单。 | `06-outbound` | 11 |
| [wms_picking_task_item](./06-outbound/wms_picking_task_item.sql) | 拣货任务明细。按库位给出的应拣与实拣数量。 | `06-outbound` | 11 |
| [wms_package](./06-outbound/wms_package.sql) | 包裹。复核通过后的打包结果。打包不改变库存数量桶。 | `06-outbound` | 11 |
| [wms_package_item](./06-outbound/wms_package_item.sql) | 包裹明细。包裹内的 SKU 数量。 | `06-outbound` | 11 |
| [wms_return_order](./07-return/wms_return_order.sql) | 退货单。客户退回仓库的单据。 | `07-return` | 9 |
| [wms_return_order_item](./07-return/wms_return_order_item.sql) | 退货明细。退货数量、质检结论和处置方式。 | `07-return` | 9 |
| [wms_carrier](./08-logistics/wms_carrier.sql) | 承运商。租户配置的承运商主数据。 | `08-logistics` | 12 |
| [wms_logistics_service](./08-logistics/wms_logistics_service.sql) | 物流服务。承运商下的服务产品，如标准、快递、经济。 | `08-logistics` | 12 |
| [wms_logistics_channel](./08-logistics/wms_logistics_channel.sql) | 物流渠道。仓库实际可选用的承运商服务。 | `08-logistics` | 12 |
| [wms_freight_rule](./08-logistics/wms_freight_rule.sql) | 运费规则。渠道上的重量段首重续重价格。 | `08-logistics` | 12 |
| [wms_shipment](./08-logistics/wms_shipment.sql) | 发货单。包裹交给承运商的记录。 | `08-logistics` | 11 |
| [wms_waybill](./08-logistics/wms_waybill.sql) | 面单。发货单对应的面单文件，允许作废后重开。 | `08-logistics` | 12 |
| [wms_tracking_event](./08-logistics/wms_tracking_event.sql) | 轨迹事件。运单轨迹，按时间追加。 | `08-logistics` | 12 |
| [wms_platform_shop](./09-integration/wms_platform_shop.sql) | 平台店铺。第三方平台连接。新增平台不改订单表。 | `09-integration` | 14 |
| [wms_sync_task](./09-integration/wms_sync_task.sql) | 同步任务。订单、库存、轨迹等拉取任务的进度。 | `09-integration` | 14 |
| [wms_webhook_log](./09-integration/wms_webhook_log.sql) | Webhook 日志。平台回调的接收与处理结果，用于验签后的幂等。 | `09-integration` | 14 |
| [wms_login_log](./10-audit/wms_login_log.sql) | 登录日志。登录成功与失败记录。 | `10-audit` | 4 |
| [wms_operation_log](./10-audit/wms_operation_log.sql) | 操作日志。关键业务数据谁在何时改了什么。 | `10-audit` | 4 |
| [wms_api_log](./10-audit/wms_api_log.sql) | API 日志。接口访问记录，不保存完整报文。 | `10-audit` | 4 |
| [wms_status_log](./10-audit/wms_status_log.sql) | 状态变更日志。订单、入库、出库等单据的状态迁移。 | `10-audit` | 4 |
状态说明 / 合法流转（有状态字段时必填）。
## 领域关系
关联：与哪些表通过哪些业务编码关联。
```mermaid
erDiagram
wms_tenant ||--o{ wms_warehouse : tenant_code
wms_customer ||--o{ wms_sku : customer_code
wms_warehouse ||--o{ wms_zone : warehouse_code
wms_zone ||--o{ wms_location : zone_code
wms_sku ||--o{ wms_inventory : sku_code
wms_location ||--o{ wms_inventory : location_code
wms_inventory ||--o{ wms_stock_log : "同一事务"
wms_order ||--o{ wms_order_item : order_no
wms_order ||--o{ wms_outbound : order_no
wms_outbound ||--o{ wms_outbound_item : outbound_no
wms_outbound ||--o{ wms_allocation : outbound_no
wms_allocation ||--o{ wms_picking_task_item : allocation_no
wms_outbound ||--o{ wms_package : outbound_no
wms_package ||--|| wms_shipment : package_no
wms_inbound ||--o{ wms_inbound_item : inbound_no
wms_inbound ||--o{ wms_inbound_receipt : inbound_no
wms_inbound ||--o{ wms_inbound_putaway : inbound_no
```
并发 / 审计说明：是否需要行锁、乐观锁、流水、软删除，及原因。
````
关联字段都是业务编码。`wms_stock_log.inventory_id` 只用于和余额行对账。