init

docs/database/00-conventions.md

@@ -0,0 +1,74 @@
+# 数据库约定
+
+本目录的 `.sql` 是表结构的设计稿，供评审和后续 Laravel migration 对照。不要把这些文件当作生产迁移直接执行，也不要一次把尚未开工的 Phase 全部做成 migration。
+
+## 库与字符集
+
+- MySQL 8、InnoDB、`utf8mb4`、`utf8mb4_0900_ai_ci`
+- 时间用 `DATETIME(3)`，由应用写入租户或仓库时区换算后的时刻，库内不存时区
+
+## 命名
+
+- 表名使用单数，统一 `wms_` 前缀，例如 `wms_sku`、`wms_stock_log`
+- 每张表一个文件，文件名即表名，放在对应领域目录
+- 字段 snake_case。业务编码以 `_code` 或 `_no` 结尾
+
+## 公共字段
+
+- `id`：`BIGINT UNSIGNED` 自增，只做内部主键和加锁顺序
+- `tenant_code`：核心业务表必有。例外只有两张全局目录：`wms_tenant`、`wms_permission`
+- `created_at`、`updated_at`：每张表都有
+- 单据头有 `created_by`、`updated_by`，存 `user_code`
+- 不使用 `deleted_at`。主数据用 `status=disabled` 停用；流水和日志只追加，禁止修改和删除
+
+## 类型
+
+- 数量：`DECIMAL(16,4)`，禁止 `FLOAT` / `DOUBLE`
+- 金额：`DECIMAL(16,4)`，币种 `CHAR(3)`
+- 重量：千克，`DECIMAL(12,4)`；尺寸：厘米
+- 状态：`VARCHAR(32)`，取值写在字段注释里。应用层用 Enum 和集中定义的合法迁移，禁止散落比较魔法字符串
+
+## 关联
+
+- 表与表用业务编码关联，不建外键。编码的唯一约束都包含 `tenant_code`
+- 需要「允许多个空值」的可选单号（外部订单号、入库参考号、非销售出库的订单号）使用 `NULL`，不要用空字符串，否则唯一索引会撞车
+- 参与库存唯一键的可选编码（库位、批次）使用空字符串，保证唯一索引生效
+- Laravel 的 `personal_access_tokens`、队列表、缓存表由框架 migration 维护，不在这里重复
+
+## 库存
+
+余额行的粒度是：租户 + 仓库 + 货主 + 库位 + SKU + 批次。
+
+库存状态不另做一行维度，由数量桶表达：
+
+| 字段 | 含义 |
+| --- | --- |
+| available_qty | 可用 |
+| reserved_qty | 已分配、未拣货 |
+| picked_qty | 已拣货、未出库 |
+| hold_qty | 冻结 |
+| damaged_qty | 残损 |
+| in_transit_qty | 在途，只放在库位编码为空的行 |
+
+待检、待上架的实物放在收货或质检库位，仍记在 `available_qty`，靠库位策略排除出可分配范围。
+
+任何余额变化必须和 `wms_stock_log` 在同一事务。扣减用带数量条件的原子更新。一次动作跨两个桶或两个库位时写多行流水，共用 `biz_type` 和 `biz_no`。打包不改数量桶。
+
+## 订单和出库
+
+- `wms_order` 是统一履约订单，不包含任何平台专用列
+- `wms_outbound` 是仓库作业单。一笔订单可以按仓库拆成多张出库单
+- 平台差异留在 `wms_platform_shop` 和连接器
+
+## 不单独建表的概念
+
+| 概念 | 落点 |
+| --- | --- |
+| 库位容量 | `wms_location` 的容量列 |
+| 收货差异 | `wms_inbound_receipt_item` 的差异列 |
+| 入库流水 | `wms_stock_log`，`biz_type` 为入库相关 |
+| 库存锁定 / 预占 | `wms_allocation` |
+| 复核 | `wms_outbound.review_status` |
+| 报废单 | 退货明细的处置加 `wms_stock_log` |
+| 订单渠道、来源、外部单号、状态 | `wms_order` 的列，不是独立表 |
+| 报表、AI 分析结果 | 查询或 Python 服务返回，不落核心业务表 |