wms-saas/docs/database/00-conventions.md

数据库约定

本目录的 .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 服务返回，不落核心业务表