# 数据库表结构设计

本目录存放 WMS SaaS 的数据库表结构设计，是 `backend/database/migrations` 的设计依据。通用规范见 [../09-database.md](../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 开始前创建，不提前为未来阶段编写。

## 单表设计模板

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

索引：

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

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

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

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