wms-saas/docs/database/README.md

数据库表结构设计

本目录存放 WMS SaaS 的数据库表结构设计，是 backend/database/migrations 的设计依据。通用规范见 ../09-database.md。

先设计、确认，再写迁移；改表时迁移与本目录文档同步更新。

文件组织

按业务领域一个文件，文件内包含该领域所有表：

文件	领域	对应 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 开始前创建，不提前为未来阶段编写。

单表设计模板

### 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 | | |

索引：

| 名称 | 类型 | 字段 | 支撑的查询 |
| --- | --- | --- | --- |
| uk_tenant_xxx_code | UNIQUE | (tenant_code, xxx_code) | 按业务编码查找 |
| idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表筛选 |

状态说明 / 合法流转（有状态字段时必填）。

关联：与哪些表通过哪些业务编码关联。

并发 / 审计说明：是否需要行锁、乐观锁、流水、软删除，及原因。