docs/00-overview.md

docs/database/README.md

@@ -0,0 +1,57 @@
+# 数据库表结构设计
+
+本目录存放 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) | 列表筛选 |
+
+状态说明 / 合法流转（有状态字段时必填）。
+
+关联：与哪些表通过哪些业务编码关联。
+
+并发 / 审计说明：是否需要行锁、乐观锁、流水、软删除，及原因。
+````