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 服务返回，不落核心业务表 |

docs/database/01-er-overview.md

@@ -0,0 +1,100 @@
+# ER 关系
+
+Phase 1 锁定的核心模型。表结构见同目录各领域文件。退货、物流主数据、平台店铺、登录 / API 日志不在本图中，留到对应 Phase。
+
+关联一律用业务编码，并始终带 `tenant_code`。
+
+```mermaid
+erDiagram
+    wms_tenant ||--o{ wms_user : tenant_code
+    wms_tenant ||--o{ wms_role : tenant_code
+    wms_role ||--o{ wms_user_role : role_code
+    wms_user ||--o{ wms_user_role : user_code
+    wms_role ||--o{ wms_role_permission : role_code
+    wms_permission ||--o{ wms_role_permission : permission_code
+
+    wms_warehouse ||--o{ wms_zone : warehouse_code
+    wms_zone ||--o{ wms_location : zone_code
+
+    wms_customer ||--o{ wms_product : customer_code
+    wms_product ||--o{ wms_sku : product_code
+    wms_sku ||--o{ wms_sku_barcode : sku_code
+    wms_sku ||--o{ wms_pack_spec : sku_code
+
+    wms_sku ||--o{ wms_inventory : sku_code
+    wms_location ||--o{ wms_inventory : location_code
+    wms_batch ||--o{ wms_inventory : batch_no
+    wms_inventory ||--o{ wms_stock_log : movement
+
+    wms_inbound ||--o{ wms_inbound_line : inbound_no
+    wms_inbound_line ||--o{ wms_inbound_receipt : line_no
+    wms_inbound_line ||--o{ wms_inbound_putaway : line_no
+
+    wms_order ||--o{ wms_order_line : order_no
+    wms_order ||--o{ wms_outbound : order_no
+    wms_outbound ||--o{ wms_outbound_line : outbound_no
+    wms_outbound_line ||--o{ wms_outbound_allocation : line_no
+    wms_wave ||--o{ wms_wave_outbound : wave_no
+    wms_outbound ||--o{ wms_wave_outbound : outbound_no
+    wms_outbound_allocation ||--o{ wms_pick_task : allocation_no
+    wms_outbound ||--o{ wms_package : outbound_no
+    wms_package ||--o{ wms_package_line : package_no
+    wms_outbound ||--o{ wms_shipment : outbound_no
+```
+
+## 库存落在哪一行
+
+余额行的粒度：
+
+`tenant_code + customer_code + warehouse_code + location_code + sku_code + batch_no`
+
+货主（`customer_code`）必须在粒度里。租户是仓配公司，客户是 3PL 的货主，两家客户的库存不能混在一行。
+
+在途、尚未落到库位时，`location_code` 为空字符串，表示虚拟在途位置。
+
+## 数量怎么变
+
+在手库存（不含在途）：
+
+`available_qty + reserved_qty + picked_qty + hold_qty + damaged_qty`
+
+| 业务 | 数量桶 |
+| --- | --- |
+| 入库确认 | 在途 `+` |
+| 收货到收货位 | 在途 `-`，收货位可用或残损 `+` |
+| 上架 | 源库位可用 `-`，目标库位可用 `+` |
+| 分配 | 可用 `-`，预占 `+` |
+| 取消分配 | 预占 `-`，可用 `+` |
+| 拣货 | 预占 `-`，已拣 `+` |
+| 发货 | 已拣 `-`（离开仓库） |
+| 冻结 / 解冻 | 可用与冻结对转 |
+| 转残 / 转良 | 可用与残损对转 |
+| 调整、盘点确认 | 对应桶按差额 `+/-` |
+
+每一次桶的变化写一行 `wms_stock_log`。同一次业务动作的多行共用 `movement_no`。余额更新与流水插入在同一数据库事务中。
+
+## 单据链
+
+```
+订单 wms_order
+  → 出库单 wms_outbound
+    → 分配 wms_outbound_allocation
+      → 波次 wms_wave（可无，则按单拣货）
+      → 拣货任务 wms_pick_task
+      → 包裹 wms_package
+      → 发货 wms_shipment
+```
+
+第一阶段业务上一单一张出库单。表结构允许多张出库单指向同一 `order_no`，后续拆单不用改表。
+
+入库不经过订单：
+
+```
+入库单 → 明细 → 收货记录 → 上架记录 → 库存余额 + 流水
+```
+
+收货差异不单独建表，用明细上的 `expected_qty - received_qty` 得出。
+
+## 状态日志
+
+入库、出库、订单、波次、调整、盘点的状态变化写 `wms_status_log`（见 [10-saas.md](./10-saas.md)）。非法转换在领域层拒绝，不写日志。

docs/database/01-saas/wms_number_sequence.sql

@@ -0,0 +1,16 @@
+-- 表：wms_number_sequence
+-- 用途：单号序列。按租户、业务类型发号，保证并发下单号不重复。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：发号必须用单条原子更新：UPDATE ... SET current_value = LAST_INSERT_ID(current_value + 1)，再 SELECT LAST_INSERT_ID()。禁止先查后加。
+
+CREATE TABLE `wms_number_sequence` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `biz_type` VARCHAR(32) NOT NULL COMMENT '业务类型，如 order、inbound、outbound、picking',
+  `period_key` VARCHAR(16) NOT NULL DEFAULT '' COMMENT '重置周期，如 202609；空表示连续递增',
+  `current_value` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '当前已分配到的序号',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_biz_period` (`tenant_code`, `biz_type`, `period_key`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='单号序列';

docs/database/01-saas/wms_permission.sql

@@ -0,0 +1,19 @@
+-- 表：wms_permission
+-- 用途：权限。全局权限码目录，不按租户复制。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：本表无 tenant_code。权限码格式为 模块:动作，与前端按钮权限、后端 Policy 使用同一套编码。
+
+CREATE TABLE `wms_permission` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `permission_code` VARCHAR(64) NOT NULL COMMENT '权限码，如 inventory:adjust',
+  `permission_name` VARCHAR(64) NOT NULL COMMENT '权限名称',
+  `module` VARCHAR(32) NOT NULL COMMENT '模块，如 inventory、inbound、outbound',
+  `perm_type` VARCHAR(16) NOT NULL COMMENT 'menu 菜单，page 页面，button 按钮或接口',
+  `parent_code` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '上级权限码，空表示顶级',
+  `sort` INT NOT NULL DEFAULT 0 COMMENT '排序',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_permission_code` (`permission_code`),
+  KEY `idx_module` (`module`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='权限';

docs/database/01-saas/wms_role.sql

@@ -0,0 +1,17 @@
+-- 表：wms_role
+-- 用途：角色。租户内角色。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：权限码本身是全局目录，角色与权限的绑定按租户隔离，见 wms_role_permission。
+
+CREATE TABLE `wms_role` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `role_code` VARCHAR(32) NOT NULL COMMENT '角色编码，租户内唯一',
+  `role_name` VARCHAR(64) NOT NULL COMMENT '角色名称',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_role_code` (`tenant_code`, `role_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='角色';

docs/database/01-saas/wms_role_permission.sql

@@ -0,0 +1,16 @@
+-- 表：wms_role_permission
+-- 用途：角色权限。租户内角色与全局权限码的绑定。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：同一权限码可授予多个角色。解除授权删除本表行，不使用软删除。
+
+CREATE TABLE `wms_role_permission` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `role_code` VARCHAR(32) NOT NULL COMMENT '角色编码',
+  `permission_code` VARCHAR(64) NOT NULL COMMENT '权限码',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_role_perm` (`tenant_code`, `role_code`, `permission_code`),
+  KEY `idx_tenant_perm` (`tenant_code`, `permission_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='角色权限';

docs/database/01-saas/wms_tenant.sql

@@ -0,0 +1,21 @@
+-- 表：wms_tenant
+-- 用途：租户。SaaS 隔离边界，tenant_code 全局唯一。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：初始化时写入 tenant_code=platform 的平台租户，平台管理员挂在该租户下，不另建认证中心。本表没有 tenant_code 过滤列，因为行本身就是租户。
+
+CREATE TABLE `wms_tenant` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码，全局唯一',
+  `tenant_name` VARCHAR(128) NOT NULL COMMENT '租户名称',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，suspended 停用',
+  `timezone` VARCHAR(64) NOT NULL DEFAULT 'Asia/Shanghai' COMMENT 'IANA 时区',
+  `contact_name` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '联系人',
+  `contact_phone` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '联系电话',
+  `contact_email` VARCHAR(128) NOT NULL DEFAULT '' COMMENT '联系邮箱',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_code` (`tenant_code`),
+  KEY `idx_status` (`status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='租户';

docs/database/01-saas/wms_tenant_setting.sql

@@ -0,0 +1,15 @@
+-- 表：wms_tenant_setting
+-- 用途：租户设置。租户级可配置项，包括定时任务开关。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：密钥类配置不要放这里，第三方凭证放 wms_platform_shop.credential_cipher 并加密。
+
+CREATE TABLE `wms_tenant_setting` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `setting_key` VARCHAR(64) NOT NULL COMMENT '配置键',
+  `setting_value` TEXT NOT NULL COMMENT '配置值',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_setting_key` (`tenant_code`, `setting_key`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='租户设置';

docs/database/01-saas/wms_user.sql

@@ -0,0 +1,22 @@
+-- 表：wms_user
+-- 用途：用户。租户内登录账号。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：令牌表使用 Laravel Sanctum 的 personal_access_tokens，不在本目录重复定义。
+
+CREATE TABLE `wms_user` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `user_code` VARCHAR(64) NOT NULL COMMENT '用户编码，租户内唯一',
+  `user_name` VARCHAR(64) NOT NULL COMMENT '姓名',
+  `email` VARCHAR(128) NOT NULL COMMENT '登录邮箱，租户内唯一',
+  `password_hash` VARCHAR(255) NOT NULL COMMENT '密码哈希，禁止保存明文',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用，locked 锁定',
+  `is_platform_admin` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '1 表示平台管理员，仅 platform 租户使用',
+  `last_login_at` DATETIME(3) NULL COMMENT '最近登录时间',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_user_code` (`tenant_code`, `user_code`),
+  UNIQUE KEY `uk_tenant_email` (`tenant_code`, `email`),
+  KEY `idx_tenant_status` (`tenant_code`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='用户';

docs/database/01-saas/wms_user_role.sql

@@ -0,0 +1,16 @@
+-- 表：wms_user_role
+-- 用途：用户角色。租户内用户与角色的绑定。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：一个用户可绑定多个角色。
+
+CREATE TABLE `wms_user_role` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `user_code` VARCHAR(64) NOT NULL COMMENT '用户编码',
+  `role_code` VARCHAR(32) NOT NULL COMMENT '角色编码',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_user_role` (`tenant_code`, `user_code`, `role_code`),
+  KEY `idx_tenant_role` (`tenant_code`, `role_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='用户角色';

docs/database/02-warehouse/wms_location.sql

@@ -0,0 +1,32 @@
+-- 表：wms_location
+-- 用途：库位。仓库内可存放库存的最小位置，同时保存容量。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：空置还是占用由库存余额推导，不在本表存占用状态。容量字段即库位容量，不另建容量表。
+
+CREATE TABLE `wms_location` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `zone_code` VARCHAR(32) NOT NULL COMMENT '库区编码',
+  `location_code` VARCHAR(64) NOT NULL COMMENT '库位编码，仓库内唯一',
+  `location_type_code` VARCHAR(32) NOT NULL COMMENT '库位类型编码',
+  `aisle` VARCHAR(16) NOT NULL DEFAULT '' COMMENT '巷道',
+  `rack` VARCHAR(16) NOT NULL DEFAULT '' COMMENT '货架',
+  `level_no` VARCHAR(16) NOT NULL DEFAULT '' COMMENT '层',
+  `bin_no` VARCHAR(16) NOT NULL DEFAULT '' COMMENT '位',
+  `pick_sequence` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '拣货路径序号，小的优先',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'enabled' COMMENT 'enabled 可作业，disabled 停用，locked 锁定（盘点或异常，暂停入出）',
+  `max_qty` DECIMAL(16,4) NULL COMMENT '容量：最大件数，空表示不限制',
+  `max_weight` DECIMAL(12,4) NULL COMMENT '容量：最大重量千克，空表示不限制',
+  `max_volume` DECIMAL(16,4) NULL COMMENT '容量：最大体积立方厘米，空表示不限制',
+  `length_cm` DECIMAL(12,4) NULL COMMENT '长，厘米，空表示未维护',
+  `width_cm` DECIMAL(12,4) NULL COMMENT '宽，厘米，空表示未维护',
+  `height_cm` DECIMAL(12,4) NULL COMMENT '高，厘米，空表示未维护',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_wh_location` (`tenant_code`, `warehouse_code`, `location_code`),
+  KEY `idx_tenant_wh_zone` (`tenant_code`, `warehouse_code`, `zone_code`),
+  KEY `idx_tenant_wh_status` (`tenant_code`, `warehouse_code`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库位';

docs/database/02-warehouse/wms_location_strategy.sql

@@ -0,0 +1,26 @@
+-- 表：wms_location_strategy
+-- 用途：库位策略。上架、分配、拣货的规则。空编码表示该条件不限。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：新增平台或货主只加策略行，不改库存核心代码。
+
+CREATE TABLE `wms_location_strategy` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `strategy_code` VARCHAR(32) NOT NULL COMMENT '策略编码，租户内唯一',
+  `strategy_name` VARCHAR(64) NOT NULL COMMENT '策略名称',
+  `warehouse_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '仓库编码，空表示该租户全部仓库',
+  `strategy_type` VARCHAR(32) NOT NULL COMMENT 'putaway 上架，allocation 库存分配，picking 拣货路径',
+  `priority` INT UNSIGNED NOT NULL DEFAULT 100 COMMENT '优先级，数字小的先匹配',
+  `customer_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '货主编码，空表示不限',
+  `sku_code` VARCHAR(64) NOT NULL DEFAULT '' COMMENT 'SKU 编码，空表示不限',
+  `zone_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '目标或来源库区，空表示不限',
+  `location_type_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '库位类型，空表示不限',
+  `rule_json` JSON NULL COMMENT '扩展条件，核心条件优先用独立列',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_strategy_code` (`tenant_code`, `strategy_code`),
+  KEY `idx_tenant_wh_type` (`tenant_code`, `warehouse_code`, `strategy_type`, `priority`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库位策略';

docs/database/02-warehouse/wms_location_type.sql

@@ -0,0 +1,20 @@
+-- 表：wms_location_type
+-- 用途：库位类型。库位的混放规则。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：混放校验在上架时执行，不靠数据库外键。
+
+CREATE TABLE `wms_location_type` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `location_type_code` VARCHAR(32) NOT NULL COMMENT '库位类型编码，租户内唯一',
+  `location_type_name` VARCHAR(64) NOT NULL COMMENT '类型名称',
+  `allow_mixed_sku` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '1 允许同一库位放多个 SKU',
+  `allow_mixed_batch` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '1 允许同一 SKU 的多个批次放在同一库位',
+  `allow_mixed_customer` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '1 允许同一库位放多个货主的库存',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_location_type` (`tenant_code`, `location_type_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库位类型';

docs/database/02-warehouse/wms_warehouse.sql

@@ -0,0 +1,28 @@
+-- 表：wms_warehouse
+-- 用途：仓库。租户下的物理仓库。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：停用仓库不得再开新的入出库作业，已有库存保留。
+
+CREATE TABLE `wms_warehouse` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码，租户内唯一',
+  `warehouse_name` VARCHAR(128) NOT NULL COMMENT '仓库名称',
+  `warehouse_type` VARCHAR(32) NOT NULL COMMENT 'private 自营，three_pl 第三方仓，overseas 海外仓',
+  `country_code` CHAR(2) NOT NULL DEFAULT '' COMMENT '国家 ISO 3166-1 alpha-2',
+  `province` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '省或州',
+  `city` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '城市',
+  `district` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '区县',
+  `address` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '详细地址',
+  `postcode` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '邮编',
+  `contact_name` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '联系人',
+  `contact_phone` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '联系电话',
+  `timezone` VARCHAR(64) NOT NULL DEFAULT 'Asia/Shanghai' COMMENT '仓库时区',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_warehouse_code` (`tenant_code`, `warehouse_code`),
+  KEY `idx_tenant_status` (`tenant_code`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='仓库';

docs/database/02-warehouse/wms_zone.sql

@@ -0,0 +1,20 @@
+-- 表：wms_zone
+-- 用途：库区。仓库内的功能分区。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：可售库存的分配策略只选择允许拣货的库区。收货区、质检区的库存不可直接分配给出库。
+
+CREATE TABLE `wms_zone` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `zone_code` VARCHAR(32) NOT NULL COMMENT '库区编码，仓库内唯一',
+  `zone_name` VARCHAR(64) NOT NULL COMMENT '库区名称',
+  `zone_type` VARCHAR(32) NOT NULL COMMENT 'receiving 收货，storage 存储，picking 拣货，shipping 发货，return 退货，quarantine 质检，exception 异常',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_wh_zone` (`tenant_code`, `warehouse_code`, `zone_code`),
+  KEY `idx_tenant_wh_type` (`tenant_code`, `warehouse_code`, `zone_type`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库区';

docs/database/03-master/wms_customer.sql

@@ -0,0 +1,21 @@
+-- 表：wms_customer
+-- 用途：货主。3PL 的客户。自营租户也建一个默认货主，库存一律落到货主。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：customer_code 是货主，不是电商买家。收件人信息在订单上。
+
+CREATE TABLE `wms_customer` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码，租户内唯一',
+  `customer_name` VARCHAR(128) NOT NULL COMMENT '货主名称',
+  `contact_name` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '联系人',
+  `contact_phone` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '联系电话',
+  `contact_email` VARCHAR(128) NOT NULL DEFAULT '' COMMENT '联系邮箱',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_customer_code` (`tenant_code`, `customer_code`),
+  KEY `idx_tenant_status` (`tenant_code`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='货主';

docs/database/03-master/wms_customer_warehouse.sql

@@ -0,0 +1,17 @@
+-- 表：wms_customer_warehouse
+-- 用途：货主仓库。货主可以使用哪些仓库。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：订单和入库选择仓库时必须落在已启用的绑定上。
+
+CREATE TABLE `wms_customer_warehouse` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_customer_wh` (`tenant_code`, `customer_code`, `warehouse_code`),
+  KEY `idx_tenant_wh` (`tenant_code`, `warehouse_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='货主仓库';

docs/database/03-master/wms_package_spec.sql

@@ -0,0 +1,23 @@
+-- 表：wms_package_spec
+-- 用途：包装规格。SKU 的装箱规格，如一件箱装多少件。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：库存数量一律按 SKU 基本单位记账，包装规格只用于换算展示和装箱，不单独记库存。
+
+CREATE TABLE `wms_package_spec` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `spec_code` VARCHAR(32) NOT NULL COMMENT '规格编码，SKU 内唯一',
+  `spec_name` VARCHAR(64) NOT NULL COMMENT '规格名称',
+  `unit_qty` DECIMAL(16,4) NOT NULL COMMENT '1 个该包装包含的基本单位数量',
+  `weight` DECIMAL(12,4) NULL COMMENT '包装重量，千克',
+  `length_cm` DECIMAL(12,4) NULL COMMENT '长，厘米，空表示未维护',
+  `width_cm` DECIMAL(12,4) NULL COMMENT '宽，厘米，空表示未维护',
+  `height_cm` DECIMAL(12,4) NULL COMMENT '高，厘米，空表示未维护',
+  `is_default` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '1 默认规格',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_sku_spec` (`tenant_code`, `sku_code`, `spec_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='包装规格';

docs/database/03-master/wms_product.sql

@@ -0,0 +1,19 @@
+-- 表：wms_product
+-- 用途：商品。SKU 的上层商品，属于一个货主。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：product_code 在租户内唯一，不按货主再分一层。
+
+CREATE TABLE `wms_product` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `product_code` VARCHAR(64) NOT NULL COMMENT '商品编码，租户内唯一',
+  `product_name` VARCHAR(128) NOT NULL COMMENT '商品名称',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_product_code` (`tenant_code`, `product_code`),
+  KEY `idx_tenant_customer` (`tenant_code`, `customer_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='商品';

docs/database/03-master/wms_sku.sql

@@ -0,0 +1,30 @@
+-- 表：wms_sku
+-- 用途：SKU。库存与订单的最小商品单位，含单件重量和尺寸。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：不同货主不得复用同一个 sku_code。重量尺寸变更不影响历史单据上的快照。
+
+CREATE TABLE `wms_sku` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `product_code` VARCHAR(64) NOT NULL COMMENT '商品编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码，租户内唯一',
+  `sku_name` VARCHAR(128) NOT NULL COMMENT 'SKU 名称',
+  `unit` VARCHAR(16) NOT NULL DEFAULT 'pcs' COMMENT '计量单位',
+  `net_weight` DECIMAL(12,4) NULL COMMENT '单件净重，千克',
+  `length_cm` DECIMAL(12,4) NULL COMMENT '长，厘米，空表示未维护',
+  `width_cm` DECIMAL(12,4) NULL COMMENT '宽，厘米，空表示未维护',
+  `height_cm` DECIMAL(12,4) NULL COMMENT '高，厘米，空表示未维护',
+  `is_batch_managed` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '1 强制批次管理',
+  `is_expiry_managed` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '1 管理效期',
+  `shelf_life_days` INT UNSIGNED NULL COMMENT '保质期天数，不管效期时为空',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_sku_code` (`tenant_code`, `sku_code`),
+  KEY `idx_tenant_customer` (`tenant_code`, `customer_code`),
+  KEY `idx_tenant_product` (`tenant_code`, `product_code`),
+  KEY `idx_tenant_status` (`tenant_code`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='SKU';

docs/database/03-master/wms_sku_barcode.sql

@@ -0,0 +1,18 @@
+-- 表：wms_sku_barcode
+-- 用途：SKU 条码。SKU 的扫描条码，租户内一条码只对应一个 SKU。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：同一 SKU 可以有多条码。扫描时按租户加条码唯一定位 SKU。
+
+CREATE TABLE `wms_sku_barcode` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `barcode` VARCHAR(64) NOT NULL COMMENT '条码',
+  `barcode_type` VARCHAR(16) NOT NULL DEFAULT 'sku' COMMENT 'sku 单品，case 外箱，other 其他',
+  `is_primary` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '1 主条码',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_barcode` (`tenant_code`, `barcode`),
+  KEY `idx_tenant_sku` (`tenant_code`, `sku_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='SKU 条码';

docs/database/03-master/wms_supplier.sql

@@ -0,0 +1,20 @@
+-- 表：wms_supplier
+-- 用途：供应商。入库来源供应商。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：供应商按租户隔离。
+
+CREATE TABLE `wms_supplier` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `supplier_code` VARCHAR(32) NOT NULL COMMENT '供应商编码，租户内唯一',
+  `supplier_name` VARCHAR(128) NOT NULL COMMENT '供应商名称',
+  `contact_name` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '联系人',
+  `contact_phone` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '联系电话',
+  `contact_email` VARCHAR(128) NOT NULL DEFAULT '' COMMENT '联系邮箱',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_supplier_code` (`tenant_code`, `supplier_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='供应商';

docs/database/04-inventory/wms_batch.sql

@@ -0,0 +1,22 @@
+-- 表：wms_batch
+-- 用途：批次。启用批次或效期管理的 SKU 的批次档案。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：不管批次的 SKU 在库存行上使用空批次号，不强制建本表记录。
+
+CREATE TABLE `wms_batch` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL COMMENT '批次号，SKU 内唯一',
+  `production_date` DATE NULL COMMENT '生产日期',
+  `expiry_date` DATE NULL COMMENT '失效日期',
+  `supplier_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '供应商编码，可空',
+  `supplier_batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '供应商批次号',
+  `inbound_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '首次入库单号',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_sku_batch` (`tenant_code`, `sku_code`, `batch_no`),
+  KEY `idx_tenant_expiry` (`tenant_code`, `expiry_date`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='批次';

docs/database/04-inventory/wms_inventory.sql

@@ -0,0 +1,32 @@
+-- 表：wms_inventory
+-- 用途：库存余额。某个货主、仓库、库位、SKU、批次上的数量结果。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：余额是结果。任何数量变化必须与 wms_stock_log 处于同一事务。扣减使用带数量条件的原子 UPDATE（affected rows = 0 即库存不足），禁止先 SELECT 再在应用里计算后 UPDATE。多行更新按 id 升序加锁。库位上的待检、待上架库存放在收货或质检库位，靠库位策略排除出可分配范围，不另设数量桶。
+
+CREATE TABLE `wms_inventory` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `location_code` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '库位编码；在途库存使用空字符串，表示仓库级',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '批次号，不管批次时为空字符串',
+  `available_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '可用数量',
+  `reserved_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '预占数量，已分配给出库尚未拣货',
+  `picked_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '已拣数量，已拣下尚未出库',
+  `hold_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '冻结数量',
+  `damaged_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '残损数量',
+  `in_transit_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '在途数量，只出现在库位编码为空的行',
+  `version` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '乐观锁版本',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_inventory_bucket` (`tenant_code`, `warehouse_code`, `customer_code`, `location_code`, `sku_code`, `batch_no`),
+  KEY `idx_tenant_wh_sku` (`tenant_code`, `warehouse_code`, `sku_code`),
+  KEY `idx_tenant_sku` (`tenant_code`, `sku_code`),
+  KEY `idx_tenant_wh_location` (`tenant_code`, `warehouse_code`, `location_code`),
+  CONSTRAINT `chk_inventory_qty_nonneg` CHECK (
+    `available_qty` >= 0 AND `reserved_qty` >= 0 AND `picked_qty` >= 0
+    AND `hold_qty` >= 0 AND `damaged_qty` >= 0 AND `in_transit_qty` >= 0
+  )
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库存余额';

docs/database/04-inventory/wms_inventory_alert.sql

@@ -0,0 +1,18 @@
+-- 表：wms_inventory_alert
+-- 用途：库存预警规则。SKU 在仓库的最低可用量阈值。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：本表只存规则。预警扫描由定时任务完成，不在这里存每次预警记录。
+
+CREATE TABLE `wms_inventory_alert` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `warehouse_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '仓库编码，空表示该货主全仓合计',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `min_available_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '可用数量低于该值时预警',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_alert_rule` (`tenant_code`, `warehouse_code`, `customer_code`, `sku_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库存预警规则';

docs/database/04-inventory/wms_inventory_hold.sql

@@ -0,0 +1,21 @@
+-- 表：wms_inventory_hold
+-- 用途：库存冻结单。把可用库存转为冻结的业务单据。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：frozen 时 available 转为 hold；released 时反向转回。两次变化都写流水，biz_type 分别为 freeze、unfreeze。
+
+CREATE TABLE `wms_inventory_hold` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `hold_no` VARCHAR(64) NOT NULL COMMENT '冻结单号，租户内唯一',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'draft' COMMENT 'draft 草稿，frozen 已冻结，released 已解冻，cancelled 已取消',
+  `reason` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '冻结原因',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人 user_code，系统任务为空',
+  `updated_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '更新人 user_code',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_hold_no` (`tenant_code`, `hold_no`),
+  KEY `idx_tenant_wh_status` (`tenant_code`, `warehouse_code`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库存冻结单';

docs/database/04-inventory/wms_inventory_hold_item.sql

@@ -0,0 +1,22 @@
+-- 表：wms_inventory_hold_item
+-- 用途：库存冻结明细。冻结单的库位与数量。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：解冻按本行数量执行，不部分解冻；需要部分解冻时另开冻结单。
+
+CREATE TABLE `wms_inventory_hold_item` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `hold_no` VARCHAR(64) NOT NULL COMMENT '冻结单号',
+  `line_no` INT UNSIGNED NOT NULL COMMENT '行号，单内唯一',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `location_code` VARCHAR(64) NOT NULL COMMENT '库位编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '批次号，可空',
+  `qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '冻结数量',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_hold_line` (`tenant_code`, `hold_no`, `line_no`),
+  KEY `idx_tenant_sku` (`tenant_code`, `sku_code`),
+  CONSTRAINT `chk_hold_qty_positive` CHECK (`qty` > 0)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库存冻结明细';

docs/database/04-inventory/wms_stock_adjustment.sql

@@ -0,0 +1,24 @@
+-- 表：wms_stock_adjustment
+-- 用途：库存调整单。盘盈盘亏、报损等人工调整。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：只有 completed 时改余额并写流水，biz_type=adjust 或 stocktake。完成后不可修改。
+
+CREATE TABLE `wms_stock_adjustment` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `adjustment_no` VARCHAR(64) NOT NULL COMMENT '调整单号，租户内唯一',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'draft' COMMENT 'draft 草稿，completed 已完成，cancelled 已取消',
+  `reason_type` VARCHAR(32) NOT NULL COMMENT 'gain 盘盈，loss 盘亏，damage 转残，other 其他',
+  `stocktake_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '来源盘点单号，手工调整为空',
+  `reason` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '调整原因',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人 user_code，系统任务为空',
+  `updated_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '更新人 user_code',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_adjustment_no` (`tenant_code`, `adjustment_no`),
+  KEY `idx_tenant_wh_status` (`tenant_code`, `warehouse_code`, `status`),
+  KEY `idx_tenant_stocktake` (`tenant_code`, `stocktake_no`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库存调整单';

docs/database/04-inventory/wms_stock_adjustment_item.sql

@@ -0,0 +1,24 @@
+-- 表：wms_stock_adjustment_item
+-- 用途：库存调整明细。调整的数量桶与变化量。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：草稿阶段不写 qty_before/qty_after。完成时以当时余额为准回填，并受非负约束。
+
+CREATE TABLE `wms_stock_adjustment_item` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `adjustment_no` VARCHAR(64) NOT NULL COMMENT '调整单号',
+  `line_no` INT UNSIGNED NOT NULL COMMENT '行号',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `location_code` VARCHAR(64) NOT NULL COMMENT '库位编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '批次号，可空',
+  `bucket` VARCHAR(32) NOT NULL COMMENT '被调整的数量桶，取值同 wms_stock_log.bucket',
+  `qty_change` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '变化量，可正可负',
+  `qty_before` DECIMAL(16,4) NULL COMMENT '完成时回填的变化前数量',
+  `qty_after` DECIMAL(16,4) NULL COMMENT '完成时回填的变化后数量',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_adjustment_line` (`tenant_code`, `adjustment_no`, `line_no`),
+  KEY `idx_tenant_sku` (`tenant_code`, `sku_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库存调整明细';

docs/database/04-inventory/wms_stock_log.sql

@@ -0,0 +1,35 @@
+-- 表：wms_stock_log
+-- 用途：库存流水。库存变化的事实记录，只能追加。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：一次业务动作跨两个数量桶或两个库位时写多行，共用 biz_type 与 biz_no。例如预占写 available 减少和 reserved 增加；上架写移出库位与移入库位各一行，桶仍是 available_qty。打包不改变数量桶。禁止 UPDATE 与 DELETE。
+
+CREATE TABLE `wms_stock_log` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `stock_log_no` VARCHAR(64) NOT NULL COMMENT '流水号，租户内唯一',
+  `idempotency_key` VARCHAR(128) NOT NULL COMMENT '幂等键，同一租户重复写入必须被唯一约束拒绝',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `location_code` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '库位编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '批次号',
+  `inventory_id` BIGINT UNSIGNED NOT NULL COMMENT '余额行内部主键，仅用于对账，业务关联以编码为准',
+  `bucket` VARCHAR(32) NOT NULL COMMENT '变化的数量桶：available_qty、reserved_qty、picked_qty、hold_qty、damaged_qty、in_transit_qty',
+  `biz_type` VARCHAR(32) NOT NULL COMMENT '业务类型：inbound_receipt、inbound_putaway、reserve、release、pick、ship、adjust、stocktake、freeze、unfreeze、return_restock、scrap、transfer',
+  `biz_no` VARCHAR(64) NOT NULL COMMENT '业务单号',
+  `qty_before` DECIMAL(16,4) NOT NULL COMMENT '变化前数量',
+  `qty_change` DECIMAL(16,4) NOT NULL COMMENT '变化量，入库为正、出库为负',
+  `qty_after` DECIMAL(16,4) NOT NULL COMMENT '变化后数量',
+  `request_id` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '请求 ID',
+  `occurred_at` DATETIME(3) NOT NULL COMMENT '业务发生时间',
+  `created_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '操作人 user_code，系统任务为空',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_stock_log_no` (`tenant_code`, `stock_log_no`),
+  UNIQUE KEY `uk_tenant_idempotency` (`tenant_code`, `idempotency_key`),
+  KEY `idx_tenant_sku_time` (`tenant_code`, `warehouse_code`, `sku_code`, `occurred_at`),
+  KEY `idx_tenant_biz` (`tenant_code`, `biz_type`, `biz_no`),
+  KEY `idx_inventory_id` (`inventory_id`),
+  CONSTRAINT `chk_stock_log_balance` CHECK (`qty_after` = `qty_before` + `qty_change`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库存流水';

docs/database/04-inventory/wms_stocktake.sql

@@ -0,0 +1,21 @@
+-- 表：wms_stocktake
+-- 用途：盘点单。仓库盘点任务。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：进入 counting 时按范围对库位加锁定。确认差异后生成 wms_stock_adjustment，不直接改余额。
+
+CREATE TABLE `wms_stocktake` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `stocktake_no` VARCHAR(64) NOT NULL COMMENT '盘点单号，租户内唯一',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `zone_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '库区编码，空表示全仓',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'draft' COMMENT 'draft 草稿，counting 盘点中，confirming 待确认，completed 已完成，cancelled 已取消',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人 user_code，系统任务为空',
+  `updated_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '更新人 user_code',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_stocktake_no` (`tenant_code`, `stocktake_no`),
+  KEY `idx_tenant_wh_status` (`tenant_code`, `warehouse_code`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='盘点单';

docs/database/04-inventory/wms_stocktake_item.sql

@@ -0,0 +1,24 @@
+-- 表：wms_stocktake_item
+-- 用途：盘点明细。系统数量与实盘数量。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：system_qty 是开盘快照。确认前若发生其他库存变化，由应用层拦截或重算，不在盘点中途覆盖快照。
+
+CREATE TABLE `wms_stocktake_item` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `stocktake_no` VARCHAR(64) NOT NULL COMMENT '盘点单号',
+  `line_no` INT UNSIGNED NOT NULL COMMENT '行号',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `location_code` VARCHAR(64) NOT NULL COMMENT '库位编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '批次号，可空',
+  `system_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '快照时的可用数量',
+  `counted_qty` DECIMAL(16,4) NULL COMMENT '实盘数量，未盘为空',
+  `diff_qty` DECIMAL(16,4) NULL COMMENT '实盘减系统，确认时回填',
+  `count_status` VARCHAR(32) NOT NULL DEFAULT 'pending' COMMENT 'pending 待盘，counted 已盘',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_stocktake_line` (`tenant_code`, `stocktake_no`, `line_no`),
+  KEY `idx_tenant_location` (`tenant_code`, `location_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='盘点明细';

docs/database/05-inbound/wms_inbound.sql

@@ -0,0 +1,27 @@
+-- 表：wms_inbound
+-- 用途：入库单。入库作业的头单据。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：状态只能按 draft、receiving、received、qc、putting_away、completed 前进。免检时可从 received 进入 putting_away。cancelled 只允许在尚未上架时发生。入库引起的库存变化记在 wms_stock_log，不另建入库流水表。
+
+CREATE TABLE `wms_inbound` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `inbound_no` VARCHAR(64) NOT NULL COMMENT '入库单号，租户内唯一',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `supplier_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '供应商编码，可空',
+  `inbound_type` VARCHAR(32) NOT NULL COMMENT 'purchase 采购，return 退货，transfer 调拨，other 其他',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'draft' COMMENT 'draft 草稿，receiving 收货中，received 已收货，qc 质检中，putting_away 上架中，completed 已完成，cancelled 已取消',
+  `ref_no` VARCHAR(64) NULL COMMENT '外部参考号，如 ASN；空必须为 NULL，以便唯一约束允许多张无参考号单据',
+  `expected_arrive_at` DATETIME(3) NULL COMMENT '预计到货时间',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人 user_code，系统任务为空',
+  `updated_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '更新人 user_code',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_inbound_no` (`tenant_code`, `inbound_no`),
+  UNIQUE KEY `uk_tenant_ref_no` (`tenant_code`, `ref_no`),
+  KEY `idx_tenant_wh_status_created` (`tenant_code`, `warehouse_code`, `status`, `created_at`),
+  KEY `idx_tenant_customer` (`tenant_code`, `customer_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='入库单';

docs/database/05-inbound/wms_inbound_item.sql

@@ -0,0 +1,24 @@
+-- 表：wms_inbound_item
+-- 用途：入库明细。入库单行，数量列是各作业的汇总结果。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：汇总列由收货、质检、上架记录在同一事务内回写。事实以那些记录和库存流水为准。
+
+CREATE TABLE `wms_inbound_item` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `inbound_no` VARCHAR(64) NOT NULL COMMENT '入库单号',
+  `line_no` INT UNSIGNED NOT NULL COMMENT '行号',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `sku_name` VARCHAR(128) NOT NULL DEFAULT '' COMMENT '下单时的 SKU 名称快照',
+  `expected_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '预计数量',
+  `received_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '已收数量汇总',
+  `qualified_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '质检合格数量汇总',
+  `unqualified_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '质检不合格数量汇总',
+  `putaway_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '已上架数量汇总',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_inbound_line` (`tenant_code`, `inbound_no`, `line_no`),
+  KEY `idx_tenant_sku` (`tenant_code`, `sku_code`),
+  CONSTRAINT `chk_inbound_item_qty` CHECK (`expected_qty` > 0 AND `received_qty` >= 0 AND `qualified_qty` >= 0 AND `unqualified_qty` >= 0 AND `putaway_qty` >= 0)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='入库明细';

docs/database/05-inbound/wms_inbound_putaway.sql

@@ -0,0 +1,28 @@
+-- 表：wms_inbound_putaway
+-- 用途：上架任务。把收货库位的合格库存移到存储库位。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：完成时同一事务：移出库位 available 减少、移入库位 available 增加、写两行 inbound_putaway 流水、回写入库明细 putaway_qty。目标库位要满足库位类型的混放规则和容量。
+
+CREATE TABLE `wms_inbound_putaway` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `putaway_no` VARCHAR(64) NOT NULL COMMENT '上架单号，租户内唯一',
+  `inbound_no` VARCHAR(64) NOT NULL COMMENT '入库单号',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '批次号，可空',
+  `from_location_code` VARCHAR(64) NOT NULL COMMENT '移出库位，通常是收货或质检库位',
+  `to_location_code` VARCHAR(64) NOT NULL COMMENT '移入库位',
+  `qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '上架数量',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'pending' COMMENT 'pending 待上架，completed 已完成，cancelled 已取消',
+  `operator` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '上架人 user_code',
+  `finished_at` DATETIME(3) NULL COMMENT '完成时间',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_putaway_no` (`tenant_code`, `putaway_no`),
+  KEY `idx_tenant_inbound_status` (`tenant_code`, `inbound_no`, `status`),
+  KEY `idx_tenant_to_location` (`tenant_code`, `warehouse_code`, `to_location_code`),
+  CONSTRAINT `chk_putaway_qty` CHECK (`qty` > 0)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='上架任务';

docs/database/05-inbound/wms_inbound_qc.sql

@@ -0,0 +1,28 @@
+-- 表：wms_inbound_qc
+-- 用途：入库质检。按收货结果做的质检记录。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：不合格数量从收货库位的 available 转入 damaged，并写流水。合格数量等待上架。
+
+CREATE TABLE `wms_inbound_qc` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `qc_no` VARCHAR(64) NOT NULL COMMENT '质检单号，租户内唯一',
+  `inbound_no` VARCHAR(64) NOT NULL COMMENT '入库单号',
+  `receipt_no` VARCHAR(64) NOT NULL COMMENT '收货单号',
+  `inbound_line_no` INT UNSIGNED NOT NULL COMMENT '入库明细行号',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '批次号，可空',
+  `inspect_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '送检数量',
+  `pass_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '合格数量',
+  `fail_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '不合格数量',
+  `result` VARCHAR(32) NOT NULL COMMENT 'pass 全部合格，partial 部分合格，fail 全部不合格',
+  `fail_reason` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '不合格原因',
+  `qc_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '质检人 user_code',
+  `qc_at` DATETIME(3) NOT NULL COMMENT '质检时间',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_qc_no` (`tenant_code`, `qc_no`),
+  KEY `idx_tenant_inbound` (`tenant_code`, `inbound_no`),
+  CONSTRAINT `chk_qc_qty` CHECK (`inspect_qty` > 0 AND `pass_qty` >= 0 AND `fail_qty` >= 0 AND `pass_qty` + `fail_qty` = `inspect_qty`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='入库质检';

docs/database/05-inbound/wms_inbound_receipt.sql

@@ -0,0 +1,20 @@
+-- 表：wms_inbound_receipt
+-- 用途：收货记录。一张入库单可以分多次收货。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：收货增加收货库位的 available_qty，并写 biz_type=inbound_receipt 的流水。
+
+CREATE TABLE `wms_inbound_receipt` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `receipt_no` VARCHAR(64) NOT NULL COMMENT '收货单号，租户内唯一',
+  `inbound_no` VARCHAR(64) NOT NULL COMMENT '入库单号',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `received_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '收货人 user_code',
+  `received_at` DATETIME(3) NOT NULL COMMENT '收货时间',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_receipt_no` (`tenant_code`, `receipt_no`),
+  KEY `idx_tenant_inbound` (`tenant_code`, `inbound_no`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='收货记录';

docs/database/05-inbound/wms_inbound_receipt_item.sql

@@ -0,0 +1,24 @@
+-- 表：wms_inbound_receipt_item
+-- 用途：收货明细。本次实收数量以及与预计的差异。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：收货差异记在本行，不另建差异表。差异不直接改预计数量，最终以实收和质检合格数量进入库存。
+
+CREATE TABLE `wms_inbound_receipt_item` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `receipt_no` VARCHAR(64) NOT NULL COMMENT '收货单号',
+  `line_no` INT UNSIGNED NOT NULL COMMENT '收货行号',
+  `inbound_no` VARCHAR(64) NOT NULL COMMENT '入库单号',
+  `inbound_line_no` INT UNSIGNED NOT NULL COMMENT '入库明细行号',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '批次号，不管批次时为空',
+  `expected_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '收货时该行剩余预计数量快照',
+  `received_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '本次实收数量',
+  `variance_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '实收减预计快照，短收为负、超收为正',
+  `variance_reason` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '差异原因，无差异为空',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_receipt_line` (`tenant_code`, `receipt_no`, `line_no`),
+  KEY `idx_tenant_inbound_line` (`tenant_code`, `inbound_no`, `inbound_line_no`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='收货明细';

docs/database/06-outbound/wms_allocation.sql

@@ -0,0 +1,26 @@
+-- 表：wms_allocation
+-- 用途：库存分配。出库行预占到具体库位批次的记录，也是库存锁定明细。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：reserved 时 available 转为 reserved。released 时转回。picked 时 reserved 转为 picked。不另建预占表。
+
+CREATE TABLE `wms_allocation` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `allocation_no` VARCHAR(64) NOT NULL COMMENT '分配单号，租户内唯一',
+  `outbound_no` VARCHAR(64) NOT NULL COMMENT '出库单号',
+  `outbound_line_no` INT UNSIGNED NOT NULL COMMENT '出库行号',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `location_code` VARCHAR(64) NOT NULL COMMENT '库位编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '批次号，可空',
+  `qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '分配数量',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'reserved' COMMENT 'reserved 已预占，picked 已拣货，released 已释放',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_allocation_no` (`tenant_code`, `allocation_no`),
+  KEY `idx_tenant_outbound` (`tenant_code`, `outbound_no`),
+  KEY `idx_tenant_sku_location` (`tenant_code`, `warehouse_code`, `sku_code`, `location_code`),
+  CONSTRAINT `chk_allocation_qty` CHECK (`qty` > 0)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='库存分配';

docs/database/06-outbound/wms_order.sql

@@ -0,0 +1,38 @@
+-- 表：wms_order
+-- 用途：统一订单。与具体电商平台解耦的履约订单。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：核心订单只保存统一字段。平台特有属性留在连接器，不在本表加 Amazon、TikTok 等专用列。订单状态表示履约进度，仓库作业状态以 wms_outbound.status 为准。
+
+CREATE TABLE `wms_order` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `order_no` VARCHAR(64) NOT NULL COMMENT '订单号，租户内唯一',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `warehouse_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '指定仓库；拆到多个仓库时为空，以出库单为准',
+  `order_channel` VARCHAR(32) NOT NULL COMMENT '来源渠道：manual、api、erp、amazon、shopify、tiktok_shop、temu、shopee、mirakl',
+  `order_source` VARCHAR(32) NOT NULL COMMENT '进入方式：manual 手工，open_api 开放接口，connector 平台连接器',
+  `external_order_no` VARCHAR(64) NULL COMMENT '外部订单号；手工单必须为 NULL',
+  `shop_code` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '店铺编码，非平台单为空',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'draft' COMMENT 'draft 草稿，confirmed 已确认，processing 作业中，partially_shipped 部分发货，shipped 已发货，completed 已完成，cancelled 已取消',
+  `currency` CHAR(3) NOT NULL DEFAULT 'CNY' COMMENT '申报金额币种',
+  `required_ship_at` DATETIME(3) NULL COMMENT '要求发货时间',
+  `ship_name` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '收件人',
+  `ship_phone` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '收件电话',
+  `ship_country_code` CHAR(2) NOT NULL DEFAULT '' COMMENT '收件国家',
+  `ship_province` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '收件省或州',
+  `ship_city` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '收件城市',
+  `ship_district` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '收件区县',
+  `ship_address` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '收件详细地址',
+  `ship_postcode` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '收件邮编',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人 user_code，系统任务为空',
+  `updated_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '更新人 user_code',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_order_no` (`tenant_code`, `order_no`),
+  UNIQUE KEY `uk_tenant_channel_external` (`tenant_code`, `order_channel`, `external_order_no`),
+  KEY `idx_tenant_status_created` (`tenant_code`, `status`, `created_at`),
+  KEY `idx_tenant_customer` (`tenant_code`, `customer_code`),
+  KEY `idx_tenant_shop` (`tenant_code`, `shop_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='统一订单';

docs/database/06-outbound/wms_order_item.sql

@@ -0,0 +1,23 @@
+-- 表：wms_order_item
+-- 用途：订单明细。订单要履约的 SKU 与数量。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：已发货数量由出库发货回写。不在订单行上直接扣库存。
+
+CREATE TABLE `wms_order_item` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `order_no` VARCHAR(64) NOT NULL COMMENT '订单号',
+  `line_no` INT UNSIGNED NOT NULL COMMENT '行号',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `sku_name` VARCHAR(128) NOT NULL DEFAULT '' COMMENT '下单时的 SKU 名称快照',
+  `ordered_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '订购数量',
+  `cancelled_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '取消数量',
+  `shipped_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '已发货数量',
+  `declared_value` DECIMAL(16,4) NULL COMMENT '单件申报价值，供跨境物流使用',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_order_line` (`tenant_code`, `order_no`, `line_no`),
+  KEY `idx_tenant_sku` (`tenant_code`, `sku_code`),
+  CONSTRAINT `chk_order_item_qty` CHECK (`ordered_qty` > 0 AND `cancelled_qty` >= 0 AND `shipped_qty` >= 0 AND `cancelled_qty` + `shipped_qty` <= `ordered_qty`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='订单明细';

docs/database/06-outbound/wms_outbound.sql

@@ -0,0 +1,29 @@
+-- 表：wms_outbound
+-- 用途：出库单。仓库执行单据。一张订单可按仓库拆成多张出库单。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：主路径只能 draft、allocated、picking、picked、packing、packed、shipped、completed 前进。进入 packing 前 review_status 必须为 passed。cancelled 只允许从 draft、allocated 进入，且 allocated 必须先释放预占。状态变更写 wms_status_log。
+
+CREATE TABLE `wms_outbound` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `outbound_no` VARCHAR(64) NOT NULL COMMENT '出库单号，租户内唯一',
+  `order_no` VARCHAR(64) NULL COMMENT '来源订单号；非销售出库必须为 NULL',
+  `outbound_type` VARCHAR(32) NOT NULL COMMENT 'sales 销售，transfer 调拨，supplier_return 退供，scrap 报废，other 其他',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'draft' COMMENT 'draft 草稿，allocated 已分配，picking 拣货中，picked 已拣货，packing 打包中，packed 已打包，shipped 已发货，completed 已完成，cancelled 已取消',
+  `review_status` VARCHAR(32) NOT NULL DEFAULT 'pending' COMMENT '复核：pending 待复核，passed 通过，rejected 驳回',
+  `reviewed_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '复核人 user_code',
+  `reviewed_at` DATETIME(3) NULL COMMENT '复核时间',
+  `required_ship_at` DATETIME(3) NULL COMMENT '要求发货时间',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人 user_code，系统任务为空',
+  `updated_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '更新人 user_code',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_outbound_no` (`tenant_code`, `outbound_no`),
+  KEY `idx_tenant_order` (`tenant_code`, `order_no`),
+  KEY `idx_tenant_wh_status_created` (`tenant_code`, `warehouse_code`, `status`, `created_at`),
+  KEY `idx_tenant_customer` (`tenant_code`, `customer_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='出库单';

docs/database/06-outbound/wms_outbound_item.sql

@@ -0,0 +1,27 @@
+-- 表：wms_outbound_item
+-- 用途：出库明细。出库单行及各作业数量汇总。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：数量汇总由分配、拣货、打包、发货在同一事务回写。
+
+CREATE TABLE `wms_outbound_item` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `outbound_no` VARCHAR(64) NOT NULL COMMENT '出库单号',
+  `line_no` INT UNSIGNED NOT NULL COMMENT '行号',
+  `order_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '来源订单号，非销售出库为空',
+  `order_line_no` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '来源订单行号，非销售出库为 0',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `sku_name` VARCHAR(128) NOT NULL DEFAULT '' COMMENT 'SKU 名称快照',
+  `planned_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '计划出库数量',
+  `allocated_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '已分配数量',
+  `picked_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '已拣数量',
+  `packed_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '已打包数量',
+  `shipped_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '已发货数量',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_outbound_line` (`tenant_code`, `outbound_no`, `line_no`),
+  KEY `idx_tenant_sku` (`tenant_code`, `sku_code`),
+  KEY `idx_tenant_order` (`tenant_code`, `order_no`),
+  CONSTRAINT `chk_outbound_item_qty` CHECK (`planned_qty` > 0 AND `allocated_qty` >= 0 AND `picked_qty` >= 0 AND `packed_qty` >= 0 AND `shipped_qty` >= 0 AND `shipped_qty` <= `planned_qty`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='出库明细';

docs/database/06-outbound/wms_package.sql

@@ -0,0 +1,24 @@
+-- 表：wms_package
+-- 用途：包裹。复核通过后的打包结果。打包不改变库存数量桶。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：复核结果在出库单 review_status。本表只表示物理包裹。作废包裹不得再关联发货单。
+
+CREATE TABLE `wms_package` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `package_no` VARCHAR(64) NOT NULL COMMENT '包裹号，租户内唯一',
+  `outbound_no` VARCHAR(64) NOT NULL COMMENT '出库单号',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'open' COMMENT 'open 打包中，packed 已封箱，shipped 已发货，void 已作废',
+  `weight` DECIMAL(12,4) NULL COMMENT '实际重量，千克',
+  `length_cm` DECIMAL(12,4) NULL COMMENT '长，厘米，空表示未维护',
+  `width_cm` DECIMAL(12,4) NULL COMMENT '宽，厘米，空表示未维护',
+  `height_cm` DECIMAL(12,4) NULL COMMENT '高，厘米，空表示未维护',
+  `packed_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '打包人 user_code',
+  `packed_at` DATETIME(3) NULL COMMENT '封箱时间',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_package_no` (`tenant_code`, `package_no`),
+  KEY `idx_tenant_outbound` (`tenant_code`, `outbound_no`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='包裹';

docs/database/06-outbound/wms_package_item.sql

@@ -0,0 +1,22 @@
+-- 表：wms_package_item
+-- 用途：包裹明细。包裹内的 SKU 数量。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：同一出库行可以拆到多个包裹。各包裹数量之和不得超过该行已拣数量。
+
+CREATE TABLE `wms_package_item` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `package_no` VARCHAR(64) NOT NULL COMMENT '包裹号',
+  `line_no` INT UNSIGNED NOT NULL COMMENT '行号',
+  `outbound_no` VARCHAR(64) NOT NULL COMMENT '出库单号',
+  `outbound_line_no` INT UNSIGNED NOT NULL COMMENT '出库行号',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '批次号，可空',
+  `qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '包裹内数量',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_package_line` (`tenant_code`, `package_no`, `line_no`),
+  KEY `idx_tenant_outbound_line` (`tenant_code`, `outbound_no`, `outbound_line_no`),
+  CONSTRAINT `chk_package_item_qty` CHECK (`qty` > 0)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='包裹明细';

docs/database/06-outbound/wms_picking_task.sql

@@ -0,0 +1,24 @@
+-- 表：wms_picking_task
+-- 用途：拣货任务。一次派给拣货人的任务，可来自波次或单张出库单。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：短拣不把未拣数量自动改判为零库存，由应用层决定释放预占或留下异常。
+
+CREATE TABLE `wms_picking_task` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `picking_no` VARCHAR(64) NOT NULL COMMENT '拣货单号，租户内唯一',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `wave_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '波次号，单张出库拣货时为空',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'pending' COMMENT 'pending 待拣，picking 拣货中，picked 已拣完，short 短拣，cancelled 已取消',
+  `assignee` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '拣货人 user_code',
+  `started_at` DATETIME(3) NULL COMMENT '开始时间',
+  `finished_at` DATETIME(3) NULL COMMENT '完成时间',
+  `created_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人 user_code',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_picking_no` (`tenant_code`, `picking_no`),
+  KEY `idx_tenant_wh_status` (`tenant_code`, `warehouse_code`, `status`),
+  KEY `idx_tenant_wave` (`tenant_code`, `wave_no`),
+  KEY `idx_tenant_assignee` (`tenant_code`, `assignee`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='拣货任务';

docs/database/06-outbound/wms_picking_task_item.sql

@@ -0,0 +1,25 @@
+-- 表：wms_picking_task_item
+-- 用途：拣货任务明细。按库位给出的应拣与实拣数量。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：实拣确认时 reserved 转为 picked，并回写出库明细。按 pick_sequence 生成行序。
+
+CREATE TABLE `wms_picking_task_item` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `picking_no` VARCHAR(64) NOT NULL COMMENT '拣货单号',
+  `line_no` INT UNSIGNED NOT NULL COMMENT '行号',
+  `outbound_no` VARCHAR(64) NOT NULL COMMENT '出库单号',
+  `allocation_no` VARCHAR(64) NOT NULL COMMENT '分配单号',
+  `location_code` VARCHAR(64) NOT NULL COMMENT '库位编码',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `batch_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '批次号，可空',
+  `qty_required` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '应拣数量',
+  `qty_picked` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '实拣数量',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_picking_line` (`tenant_code`, `picking_no`, `line_no`),
+  KEY `idx_tenant_outbound` (`tenant_code`, `outbound_no`),
+  KEY `idx_tenant_allocation` (`tenant_code`, `allocation_no`),
+  CONSTRAINT `chk_picking_qty` CHECK (`qty_required` > 0 AND `qty_picked` >= 0 AND `qty_picked` <= `qty_required`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='拣货任务明细';

docs/database/06-outbound/wms_wave.sql

@@ -0,0 +1,22 @@
+-- 表：wms_wave
+-- 用途：波次。把多张出库单组成一次拣货。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：一张出库单同一时刻只能属于一个未取消的波次，由应用层校验。
+
+CREATE TABLE `wms_wave` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `wave_no` VARCHAR(64) NOT NULL COMMENT '波次号，租户内唯一',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `wave_type` VARCHAR(32) NOT NULL DEFAULT 'batch' COMMENT 'single 一单一拣，batch 批量拣货',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'draft' COMMENT 'draft 草稿，released 已释放，picking 拣货中，completed 已完成，cancelled 已取消',
+  `released_at` DATETIME(3) NULL COMMENT '释放时间',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人 user_code，系统任务为空',
+  `updated_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '更新人 user_code',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_wave_no` (`tenant_code`, `wave_no`),
+  KEY `idx_tenant_wh_status` (`tenant_code`, `warehouse_code`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='波次';

docs/database/06-outbound/wms_wave_outbound.sql

@@ -0,0 +1,16 @@
+-- 表：wms_wave_outbound
+-- 用途：波次出库。波次包含的出库单。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：取消波次后本行保留，用于追溯；重新组波时插入新波次的行。
+
+CREATE TABLE `wms_wave_outbound` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `wave_no` VARCHAR(64) NOT NULL COMMENT '波次号',
+  `outbound_no` VARCHAR(64) NOT NULL COMMENT '出库单号',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_wave_outbound` (`tenant_code`, `wave_no`, `outbound_no`),
+  KEY `idx_tenant_outbound` (`tenant_code`, `outbound_no`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='波次出库';

docs/database/07-return/wms_return_order.sql

@@ -0,0 +1,23 @@
+-- 表：wms_return_order
+-- 用途：退货单。客户退回仓库的单据。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：良品重新入库与报废都通过库存流水入账，biz_type 分别为 return_restock、scrap，不另建报废单。
+
+CREATE TABLE `wms_return_order` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `return_no` VARCHAR(64) NOT NULL COMMENT '退货单号，租户内唯一',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `customer_code` VARCHAR(32) NOT NULL COMMENT '货主编码',
+  `order_no` VARCHAR(64) NULL COMMENT '原订单号，无原单退货为 NULL',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'draft' COMMENT 'draft 草稿，receiving 收货中，qc 质检中，completed 已完成，cancelled 已取消',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人 user_code，系统任务为空',
+  `updated_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '更新人 user_code',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_return_no` (`tenant_code`, `return_no`),
+  KEY `idx_tenant_wh_status` (`tenant_code`, `warehouse_code`, `status`),
+  KEY `idx_tenant_order` (`tenant_code`, `order_no`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='退货单';

docs/database/07-return/wms_return_order_item.sql

@@ -0,0 +1,25 @@
+-- 表：wms_return_order_item
+-- 用途：退货明细。退货数量、质检结论和处置方式。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：重新入库增加良品库位 available；报废增加 damaged 或直接按报废出账，两种都写流水。
+
+CREATE TABLE `wms_return_order_item` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `return_no` VARCHAR(64) NOT NULL COMMENT '退货单号',
+  `line_no` INT UNSIGNED NOT NULL COMMENT '行号',
+  `sku_code` VARCHAR(64) NOT NULL COMMENT 'SKU 编码',
+  `sku_name` VARCHAR(128) NOT NULL DEFAULT '' COMMENT 'SKU 名称快照',
+  `qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '预报退货数量',
+  `received_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '实收数量',
+  `qc_result` VARCHAR(32) NOT NULL DEFAULT 'pending' COMMENT 'pending 待检，good 良品，damaged 残损',
+  `disposition` VARCHAR(32) NOT NULL DEFAULT 'pending' COMMENT 'pending 待定，restock 重新入库，scrap 报废',
+  `restock_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '已重新入库数量',
+  `scrap_qty` DECIMAL(16,4) NOT NULL DEFAULT 0.0000 COMMENT '已报废数量',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_return_line` (`tenant_code`, `return_no`, `line_no`),
+  KEY `idx_tenant_sku` (`tenant_code`, `sku_code`),
+  CONSTRAINT `chk_return_item_qty` CHECK (`qty` >= 0 AND `received_qty` >= 0 AND `restock_qty` >= 0 AND `scrap_qty` >= 0 AND `restock_qty` + `scrap_qty` <= `received_qty`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='退货明细';

docs/database/08-logistics/wms_carrier.sql

@@ -0,0 +1,17 @@
+-- 表：wms_carrier
+-- 用途：承运商。租户配置的承运商主数据。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：对接承运商 API 的凭证不放本表，避免和可展示主数据混在一起；需要时再单独加密存储。
+
+CREATE TABLE `wms_carrier` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `carrier_code` VARCHAR(32) NOT NULL COMMENT '承运商编码，租户内唯一',
+  `carrier_name` VARCHAR(128) NOT NULL COMMENT '承运商名称',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_carrier_code` (`tenant_code`, `carrier_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='承运商';

docs/database/08-logistics/wms_freight_rule.sql

@@ -0,0 +1,26 @@
+-- 表：wms_freight_rule
+-- 用途：运费规则。渠道上的重量段首重续重价格。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：重量段重叠由应用层拒绝。金额使用 DECIMAL。
+
+CREATE TABLE `wms_freight_rule` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `rule_code` VARCHAR(32) NOT NULL COMMENT '规则编码，租户内唯一',
+  `channel_code` VARCHAR(32) NOT NULL COMMENT '渠道编码',
+  `country_code` VARCHAR(8) NOT NULL DEFAULT '' COMMENT '目的国，空表示不限',
+  `min_weight` DECIMAL(12,4) NOT NULL DEFAULT 0.0000 COMMENT '重量段下限千克，含',
+  `max_weight` DECIMAL(12,4) NOT NULL COMMENT '重量段上限千克，不含',
+  `currency` CHAR(3) NOT NULL DEFAULT 'CNY' COMMENT '币种',
+  `first_weight` DECIMAL(12,4) NOT NULL COMMENT '首重千克',
+  `first_price` DECIMAL(16,4) NOT NULL COMMENT '首重价格',
+  `extra_weight` DECIMAL(12,4) NOT NULL COMMENT '续重单位千克',
+  `extra_price` DECIMAL(16,4) NOT NULL COMMENT '每续重单位价格',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_rule_code` (`tenant_code`, `rule_code`),
+  KEY `idx_tenant_channel` (`tenant_code`, `channel_code`, `country_code`),
+  CONSTRAINT `chk_freight_weight` CHECK (`max_weight` > `min_weight` AND `first_weight` > 0 AND `extra_weight` > 0)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='运费规则';

docs/database/08-logistics/wms_logistics_channel.sql

@@ -0,0 +1,21 @@
+-- 表：wms_logistics_channel
+-- 用途：物流渠道。仓库实际可选用的承运商服务。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：发货单选渠道，不直接选平台物流接口。
+
+CREATE TABLE `wms_logistics_channel` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `channel_code` VARCHAR(32) NOT NULL COMMENT '渠道编码，租户内唯一',
+  `channel_name` VARCHAR(64) NOT NULL COMMENT '渠道名称',
+  `carrier_code` VARCHAR(32) NOT NULL COMMENT '承运商编码',
+  `service_code` VARCHAR(32) NOT NULL COMMENT '服务编码',
+  `warehouse_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '适用仓库，空表示该租户全部仓库',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_channel_code` (`tenant_code`, `channel_code`),
+  KEY `idx_tenant_wh` (`tenant_code`, `warehouse_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='物流渠道';

docs/database/08-logistics/wms_logistics_service.sql

@@ -0,0 +1,17 @@
+-- 表：wms_logistics_service
+-- 用途：物流服务。承运商下的服务产品，如标准、快递、经济。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：新增承运商服务只加行，不改发货核心单据。
+
+CREATE TABLE `wms_logistics_service` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `carrier_code` VARCHAR(32) NOT NULL COMMENT '承运商编码',
+  `service_code` VARCHAR(32) NOT NULL COMMENT '服务编码',
+  `service_name` VARCHAR(64) NOT NULL COMMENT '服务名称',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_carrier_service` (`tenant_code`, `carrier_code`, `service_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='物流服务';

docs/database/08-logistics/wms_shipment.sql

@@ -0,0 +1,27 @@
+-- 表：wms_shipment
+-- 用途：发货单。包裹交给承运商的记录。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：状态变为 shipped 时扣减 picked_qty 并写 biz_type=ship 的流水，同时回写出库与订单的已发数量。获取面单、同步轨迹走队列，不在用户请求里等待承运商。
+
+CREATE TABLE `wms_shipment` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `shipment_no` VARCHAR(64) NOT NULL COMMENT '发货单号，租户内唯一',
+  `outbound_no` VARCHAR(64) NOT NULL COMMENT '出库单号',
+  `package_no` VARCHAR(64) NOT NULL COMMENT '包裹号',
+  `warehouse_code` VARCHAR(32) NOT NULL COMMENT '仓库编码',
+  `channel_code` VARCHAR(32) NOT NULL COMMENT '物流渠道编码',
+  `carrier_code` VARCHAR(32) NOT NULL COMMENT '承运商编码',
+  `tracking_no` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '运单号，取得面单前可空',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'pending' COMMENT 'pending 待获取面单，labeled 已有面单，shipped 已交出，exception 异常，delivered 已妥投，cancelled 已取消',
+  `shipped_at` DATETIME(3) NULL COMMENT '交运时间',
+  `created_by` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '创建人 user_code',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_shipment_no` (`tenant_code`, `shipment_no`),
+  UNIQUE KEY `uk_tenant_package` (`tenant_code`, `package_no`),
+  KEY `idx_tenant_outbound` (`tenant_code`, `outbound_no`),
+  KEY `idx_tenant_tracking` (`tenant_code`, `tracking_no`),
+  KEY `idx_tenant_status` (`tenant_code`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='发货单';

docs/database/08-logistics/wms_tracking_event.sql

@@ -0,0 +1,21 @@
+-- 表：wms_tracking_event
+-- 用途：轨迹事件。运单轨迹，按时间追加。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：同步任务用承运商事件时间加事件码做幂等，重复拉取不插重复行。
+
+CREATE TABLE `wms_tracking_event` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `shipment_no` VARCHAR(64) NOT NULL COMMENT '发货单号',
+  `tracking_no` VARCHAR(64) NOT NULL COMMENT '运单号',
+  `event_time` DATETIME(3) NOT NULL COMMENT '承运商事件时间',
+  `event_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '承运商事件码',
+  `description` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '事件描述',
+  `event_location` VARCHAR(128) NOT NULL DEFAULT '' COMMENT '事件地点',
+  `raw_payload` JSON NULL COMMENT '原始报文，不得包含密钥',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  KEY `idx_tenant_tracking_time` (`tenant_code`, `tracking_no`, `event_time`),
+  KEY `idx_tenant_shipment` (`tenant_code`, `shipment_no`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='轨迹事件';

docs/database/08-logistics/wms_waybill.sql

@@ -0,0 +1,19 @@
+-- 表：wms_waybill
+-- 用途：面单。发货单对应的面单文件，允许作废后重开。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：同一发货单同时只能有一张 active 面单，由应用层保证。文件上传遵守安全规范，路径不暴露公网目录。
+
+CREATE TABLE `wms_waybill` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `waybill_no` VARCHAR(64) NOT NULL COMMENT '面单号，租户内唯一',
+  `shipment_no` VARCHAR(64) NOT NULL COMMENT '发货单号',
+  `label_format` VARCHAR(16) NOT NULL COMMENT 'pdf、zpl 或 png',
+  `label_path` VARCHAR(255) NOT NULL COMMENT '面单文件存储路径，不存二进制',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 当前有效，voided 已作废',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_waybill_no` (`tenant_code`, `waybill_no`),
+  KEY `idx_tenant_shipment` (`tenant_code`, `shipment_no`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='面单';

docs/database/09-integration/wms_platform_shop.sql

@@ -0,0 +1,19 @@
+-- 表：wms_platform_shop
+-- 用途：平台店铺。第三方平台连接。新增平台不改订单表。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：连接器在 Infrastructure/Platforms 下按平台实现，本表只提供找凭证和租户的入口。Webhook 先用凭证确定租户，再进入业务。
+
+CREATE TABLE `wms_platform_shop` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `platform` VARCHAR(32) NOT NULL COMMENT '平台标识：amazon、shopify、tiktok_shop、temu、shopee、mirakl',
+  `shop_code` VARCHAR(64) NOT NULL COMMENT '店铺编码，同一平台下租户内唯一',
+  `shop_name` VARCHAR(128) NOT NULL COMMENT '店铺名称',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'active' COMMENT 'active 启用，disabled 停用',
+  `credential_cipher` TEXT NOT NULL COMMENT '加密后的凭证，禁止明文',
+  `extra_json` JSON NULL COMMENT '非敏感的店铺配置',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_platform_shop` (`tenant_code`, `platform`, `shop_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='平台店铺';

docs/database/09-integration/wms_sync_task.sql

@@ -0,0 +1,23 @@
+-- 表：wms_sync_task
+-- 用途：同步任务。订单、库存、轨迹等拉取任务的进度。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：由队列执行。任务载荷带 tenant_code。同一店铺同一类型避免重叠执行。
+
+CREATE TABLE `wms_sync_task` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `sync_no` VARCHAR(64) NOT NULL COMMENT '同步任务号，租户内唯一',
+  `shop_code` VARCHAR(64) NOT NULL COMMENT '店铺编码',
+  `platform` VARCHAR(32) NOT NULL COMMENT '平台标识',
+  `sync_type` VARCHAR(32) NOT NULL COMMENT 'order 订单，inventory 库存，tracking 轨迹',
+  `status` VARCHAR(32) NOT NULL DEFAULT 'pending' COMMENT 'pending 待执行，running 执行中，success 成功，failed 失败',
+  `cursor_value` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '增量游标',
+  `error_message` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '失败原因，不得包含凭证',
+  `started_at` DATETIME(3) NULL COMMENT '开始时间',
+  `finished_at` DATETIME(3) NULL COMMENT '结束时间',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_sync_no` (`tenant_code`, `sync_no`),
+  KEY `idx_tenant_shop_type_status` (`tenant_code`, `shop_code`, `sync_type`, `status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='同步任务';

docs/database/09-integration/wms_webhook_log.sql

@@ -0,0 +1,22 @@
+-- 表：wms_webhook_log
+-- 用途：Webhook 日志。平台回调的接收与处理结果，用于验签后的幂等。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：先校验签名和时间戳再入库。重复 event_id 直接返回成功，不重复建单。
+
+CREATE TABLE `wms_webhook_log` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `shop_code` VARCHAR(64) NOT NULL COMMENT '店铺编码',
+  `platform` VARCHAR(32) NOT NULL COMMENT '平台标识',
+  `event_id` VARCHAR(128) NOT NULL COMMENT '平台事件 ID',
+  `event_type` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '事件类型',
+  `process_status` VARCHAR(32) NOT NULL DEFAULT 'pending' COMMENT 'pending 待处理，processed 已处理，failed 处理失败',
+  `payload` JSON NULL COMMENT '报文体，不得包含密钥明文',
+  `error_message` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '处理失败原因',
+  `received_at` DATETIME(3) NOT NULL COMMENT '接收时间',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_tenant_shop_event` (`tenant_code`, `shop_code`, `event_id`),
+  KEY `idx_tenant_status` (`tenant_code`, `process_status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='Webhook 日志';

docs/database/10-audit/wms_api_log.sql

@@ -0,0 +1,22 @@
+-- 表：wms_api_log
+-- 用途：API 日志。接口访问记录，不保存完整报文。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：数据量大，允许按月归档。不作为业务事实来源。
+
+CREATE TABLE `wms_api_log` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '租户编码，未认证请求为空',
+  `user_code` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '用户编码',
+  `request_id` VARCHAR(64) NOT NULL COMMENT '请求 ID',
+  `method` VARCHAR(8) NOT NULL COMMENT 'HTTP 方法',
+  `path` VARCHAR(255) NOT NULL COMMENT '请求路径，不含查询串中的敏感参数',
+  `http_status` SMALLINT UNSIGNED NOT NULL COMMENT 'HTTP 状态码',
+  `ip` VARCHAR(45) NOT NULL DEFAULT '' COMMENT '来源 IP',
+  `duration_ms` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '耗时毫秒',
+  `summary` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '脱敏后的摘要',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  KEY `idx_request` (`request_id`),
+  KEY `idx_tenant_time` (`tenant_code`, `created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='API 日志';

docs/database/10-audit/wms_login_log.sql

@@ -0,0 +1,19 @@
+-- 表：wms_login_log
+-- 用途：登录日志。登录成功与失败记录。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：只追加。不记录密码。
+
+CREATE TABLE `wms_login_log` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL DEFAULT '' COMMENT '租户编码，未能识别租户时为空',
+  `user_code` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '用户编码，未知用户时为空',
+  `success` TINYINT(1) NOT NULL COMMENT '1 成功，0 失败',
+  `fail_reason` VARCHAR(128) NOT NULL DEFAULT '' COMMENT '失败原因',
+  `ip` VARCHAR(45) NOT NULL DEFAULT '' COMMENT '来源 IP，兼容 IPv6',
+  `user_agent` VARCHAR(255) NOT NULL DEFAULT '' COMMENT '客户端标识',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  KEY `idx_tenant_user_time` (`tenant_code`, `user_code`, `created_at`),
+  KEY `idx_created` (`created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='登录日志';

docs/database/10-audit/wms_operation_log.sql

@@ -0,0 +1,24 @@
+-- 表：wms_operation_log
+-- 用途：操作日志。关键业务数据谁在何时改了什么。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：库存数量本身以 wms_stock_log 为事实，本表记录操作上下文。JSON 中不得出现密码、Token、完整证件号。只追加。
+
+CREATE TABLE `wms_operation_log` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `user_code` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '操作人，系统任务为空',
+  `module` VARCHAR(32) NOT NULL COMMENT '模块',
+  `action` VARCHAR(64) NOT NULL COMMENT '动作',
+  `target_type` VARCHAR(32) NOT NULL COMMENT '对象类型，如 outbound、inventory',
+  `target_no` VARCHAR(64) NOT NULL COMMENT '对象业务单号或编码',
+  `before_data` JSON NULL COMMENT '修改前',
+  `after_data` JSON NULL COMMENT '修改后',
+  `ip` VARCHAR(45) NOT NULL DEFAULT '' COMMENT '来源 IP',
+  `request_id` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '请求 ID',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  KEY `idx_tenant_target` (`tenant_code`, `target_type`, `target_no`),
+  KEY `idx_tenant_module_time` (`tenant_code`, `module`, `created_at`),
+  KEY `idx_request` (`request_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='操作日志';

docs/database/10-audit/wms_status_log.sql

@@ -0,0 +1,21 @@
+-- 表：wms_status_log
+-- 用途：状态变更日志。订单、入库、出库等单据的状态迁移。
+-- 约定：InnoDB / utf8mb4 / 无外键，表间按业务编码关联。详见 docs/database/00-conventions.md
+-- 说明：与状态机放在同一事务。非法迁移不会产生本表记录。只追加。
+
+CREATE TABLE `wms_status_log` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '内部主键',
+  `tenant_code` VARCHAR(32) NOT NULL COMMENT '租户编码',
+  `biz_type` VARCHAR(32) NOT NULL COMMENT '单据类型：order、inbound、outbound、return、wave、picking、shipment',
+  `biz_no` VARCHAR(64) NOT NULL COMMENT '业务单号',
+  `from_status` VARCHAR(32) NOT NULL COMMENT '变更前状态',
+  `to_status` VARCHAR(32) NOT NULL COMMENT '变更后状态',
+  `operator` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '操作人 user_code，系统任务为空',
+  `remark` VARCHAR(500) NOT NULL DEFAULT '' COMMENT '备注',
+  `request_id` VARCHAR(64) NOT NULL DEFAULT '' COMMENT '请求 ID',
+  `created_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  `updated_at` DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY (`id`),
+  KEY `idx_tenant_biz` (`tenant_code`, `biz_type`, `biz_no`),
+  KEY `idx_tenant_time` (`tenant_code`, `created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='状态变更日志';

docs/database/10-saas.md

@@ -0,0 +1,248 @@
+# SaaS：租户、用户、权限、日志
+
+约定见 [00-conventions.md](./00-conventions.md)。本文件在 Phase 1 锁定，Phase 4 写迁移。
+
+认证令牌用 Laravel Sanctum 自带的 `personal_access_tokens`，不另建 `wms_` 表。
+
+## wms_tenant 租户
+
+用途：租户注册表。行本身就是租户，不套 TenantContext 的自动过滤。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| name | VARCHAR(128) | N | | 租户名称 |
+| status | VARCHAR(32) | N | active | 状态 |
+| timezone | VARCHAR(64) | N | UTC | IANA 时区 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_code | UNIQUE | (tenant_code) | 按租户编码查找 |
+
+状态：`active` 可用，`suspended` 停用（拒绝新的业务写入）。
+
+关联：被所有带 `tenant_code` 的表引用。
+
+并发 / 审计：无乐观锁。不停用后物理删除。状态变更写 `wms_status_log`，`biz_type = tenant`。
+
+## wms_user 用户
+
+用途：租户内登录用户。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| user_code | VARCHAR(64) | N | | 用户编码 |
+| name | VARCHAR(128) | N | | 显示名 |
+| email | VARCHAR(255) | N | | 登录邮箱 |
+| password | VARCHAR(255) | N | | 密码哈希，禁止写入日志 |
+| status | VARCHAR(32) | N | active | 状态 |
+| last_login_at | TIMESTAMP | Y | | 最近登录 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+| deleted_at | TIMESTAMP | Y | | 软删除 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_user_code | UNIQUE | (tenant_code, user_code) | 按用户编码查找 |
+| uk_tenant_email | UNIQUE | (tenant_code, email) | 登录 |
+
+状态：`active`、`disabled`。
+
+关联：`wms_user_role.user_code`。操作人字段一律存 `user_code`。
+
+并发 / 审计：无乐观锁。软删除规则见约定。权限变更写 `wms_operation_log`。
+
+## wms_role 角色
+
+用途：租户内角色。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| role_code | VARCHAR(64) | N | | 角色编码 |
+| name | VARCHAR(128) | N | | 角色名称 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+| deleted_at | TIMESTAMP | Y | | 软删除 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_role_code | UNIQUE | (tenant_code, role_code) | 按角色编码查找 |
+
+关联：`wms_user_role`、`wms_role_permission`。
+
+并发 / 审计：被用户引用时不能软删。
+
+## wms_permission 权限目录
+
+用途：系统预置权限，全租户共用。不按租户复制，因此没有 `tenant_code`。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| permission_code | VARCHAR(64) | N | | 权限编码，如 `inbound.receive` |
+| name | VARCHAR(128) | N | | 名称 |
+| module | VARCHAR(64) | N | | 模块，如 `inbound` |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_permission_code | UNIQUE | (permission_code) | 按权限编码查找 |
+
+关联：`wms_role_permission.permission_code`。数据由迁移或 Seeder 写入，不开放租户自行新增。
+
+## wms_role_permission 角色权限
+
+用途：租户角色与权限目录的对应。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| role_code | VARCHAR(64) | N | | 角色编码 |
+| permission_code | VARCHAR(64) | N | | 权限编码 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_role_permission | UNIQUE | (tenant_code, role_code, permission_code) | 防止重复授权 |
+| idx_tenant_permission | INDEX | (tenant_code, permission_code) | 反查拥有某权限的角色 |
+
+并发 / 审计：变更写 `wms_operation_log`。无软删除，收回权限即删行。
+
+## wms_user_role 用户角色
+
+用途：用户与角色的对应。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| user_code | VARCHAR(64) | N | | 用户编码 |
+| role_code | VARCHAR(64) | N | | 角色编码 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_user_role | UNIQUE | (tenant_code, user_code, role_code) | 防止重复绑定 |
+| idx_tenant_role | INDEX | (tenant_code, role_code) | 查角色下的用户 |
+
+并发 / 审计：同角色权限。无软删除。
+
+## wms_tenant_setting 租户设置
+
+用途：租户级配置。值用字符串，由应用解析。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| setting_key | VARCHAR(64) | N | | 配置键 |
+| setting_value | TEXT | Y | | 配置值 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_setting_key | UNIQUE | (tenant_code, setting_key) | 读取一项配置 |
+
+并发 / 审计：覆盖写 `updated_at`。变更写 `wms_operation_log`。不存第三方密钥明文以外的内容；密钥加密存储留到平台对接 Phase。
+
+## wms_number_sequence 取号
+
+用途：租户内单号序号。见 [00-conventions.md](./00-conventions.md)。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| biz_type | VARCHAR(32) | N | | 单据类型，如 `inbound` |
+| period | CHAR(8) | N | | `yyyyMMdd` |
+| current_value | INT UNSIGNED | N | 0 | 当日已分配到的序号 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_biz_period | UNIQUE | (tenant_code, biz_type, period) | 取号时锁这一行 |
+
+并发 / 审计：`SELECT ... FOR UPDATE` 后递增。独立短事务。不软删除。
+
+## wms_status_log 状态变更日志
+
+用途：状态机审计。只追加。登录日志与 API 日志留在后续 `95-audit.md`。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| biz_type | VARCHAR(32) | N | | `order`、`inbound`、`outbound`、`wave`、`adjust`、`stocktake`、`tenant` |
+| biz_no | VARCHAR(64) | N | | 业务单号 |
+| from_status | VARCHAR(32) | Y | | 变更前，新建时可空 |
+| to_status | VARCHAR(32) | N | | 变更后 |
+| operator_user_code | VARCHAR(64) | Y | | 操作人，系统任务为空 |
+| request_id | VARCHAR(64) | Y | | 请求标识 |
+| remark | VARCHAR(500) | Y | | |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | 行创建后不更新 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| idx_tenant_biz_created | INDEX | (tenant_code, biz_type, biz_no, created_at) | 查一张单据的状态历史 |
+
+并发 / 审计：禁止更新和删除。与状态变更同一事务写入。
+
+## wms_operation_log 操作日志
+
+用途：主数据、权限、设置等关键变更。只追加。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| operator_user_code | VARCHAR(64) | Y | | 操作人 |
+| action | VARCHAR(64) | N | | 如 `user.update`、`role.grant` |
+| biz_type | VARCHAR(32) | N | | 对象类型 |
+| biz_no | VARCHAR(64) | N | | 对象编码 |
+| biz_ip | VARCHAR(64) | Y | | 来源 IP |
+| request_id | VARCHAR(64) | Y | | 请求标识 |
+| before_data | JSON | Y | | 变更前 |
+| after_data | JSON | Y | | 变更后 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | 行创建后不更新 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| idx_tenant_biz_created | INDEX | (tenant_code, biz_type, biz_no, created_at) | 查某对象的操作历史 |
+| idx_tenant_created | INDEX | (tenant_code, created_at) | 按时间查日志 |
+
+并发 / 审计：禁止更新和删除。`before_data` / `after_data` 不得包含密码、Token。

docs/database/20-warehouse.md

@@ -0,0 +1,111 @@
+# 仓库、库区、库位
+
+约定见 [00-conventions.md](./00-conventions.md)。Phase 1 锁定，Phase 5 写迁移。
+
+库位策略不单独建规则表。容量与混放开关放在库位上。策略引擎等到有明确规则后再加表。
+
+一个租户的客户默认可使用该租户的全部仓库。仓库与客户的授权表等到需要限制时再加。
+
+## wms_warehouse 仓库
+
+用途：租户下的仓库。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| warehouse_code | VARCHAR(32) | N | | 仓库编码 |
+| warehouse_name | VARCHAR(128) | N | | 仓库名称 |
+| warehouse_status | VARCHAR(32) | N | active | 状态 |
+| timezone | VARCHAR(64) | N | UTC | IANA 时区 |
+| country_code | CHAR(2) | Y | | ISO 国家码 |
+| postal_code | VARCHAR(32) | Y | | |
+| province | VARCHAR(64) | Y | | |
+| city | VARCHAR(64) | Y | | |
+| address_line | VARCHAR(255) | Y | | |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+| deleted_at | TIMESTAMP | Y | | 软删除 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_warehouse_code | UNIQUE | (tenant_code, warehouse_code) | 按仓库编码查找 |
+| idx_tenant_status | INDEX | (tenant_code, status) | 列表筛选 |
+
+状态：`active`、`disabled`。
+
+关联：库区、库位、库存、入库、出库、订单都带 `warehouse_code`。
+
+并发 / 审计：有库存或未完成单据时不能软删，只能停用。变更写 `wms_operation_log`。
+
+## wms_zone 库区
+
+用途：仓库内的区域。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| warehouse_code | VARCHAR(32) | N | | 仓库编码 |
+| zone_code | VARCHAR(32) | N | | 库区编码，仓库内唯一 |
+| name | VARCHAR(128) | N | | 名称 |
+| zone_type | VARCHAR(32) | N | | 类型 |
+| status | VARCHAR(32) | N | active | 状态 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+| deleted_at | TIMESTAMP | Y | | 软删除 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_wh_zone | UNIQUE | (tenant_code, warehouse_code, zone_code) | 按库区查找 |
+| idx_tenant_wh_status | INDEX | (tenant_code, warehouse_code, status) | 仓库下的库区列表 |
+
+`zone_type`：`storage` 存储、`receiving` 收货、`shipping` 发货、`qc` 质检、`damaged` 残品、`staging` 暂存。
+
+状态：`active`、`disabled`。
+
+关联：`wms_location.zone_code`，同时带 `warehouse_code`。
+
+并发 / 审计：下属库位仍存在时不能软删。
+
+## wms_location 库位
+
+用途：库存存放位置。在途库存不使用本表，余额行的 `location_code` 为空字符串。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| warehouse_code | VARCHAR(32) | N | | 仓库编码 |
+| zone_code | VARCHAR(32) | N | | 库区编码 |
+| location_code | VARCHAR(64) | N | | 库位编码，仓库内唯一 |
+| location_type | VARCHAR(32) | N | bin | 类型 |
+| status | VARCHAR(32) | N | active | 状态 |
+| allow_mix_sku | TINYINT UNSIGNED | N | 1 | 1 允许混放 SKU |
+| allow_mix_batch | TINYINT UNSIGNED | N | 1 | 1 允许混放批次 |
+| max_sku_count | INT UNSIGNED | Y | | 最大 SKU 数，空为不限制 |
+| max_qty | DECIMAL(16,4) | Y | | 最大数量 |
+| max_volume_mm3 | DECIMAL(20,2) | Y | | 最大体积，立方毫米 |
+| max_weight_g | DECIMAL(16,4) | Y | | 最大重量，克 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+| deleted_at | TIMESTAMP | Y | | 软删除 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_wh_location | UNIQUE | (tenant_code, warehouse_code, location_code) | 扫描 / 上架定位 |
+| idx_tenant_wh_zone | INDEX | (tenant_code, warehouse_code, zone_code) | 库区下的库位 |
+
+`location_type`：`bin` 货位、`pallet` 托盘、`floor` 地堆、`virtual` 虚拟位（系统收货位、发货位）。
+
+状态：`active`、`disabled`、`locked`（锁定后禁止上架与分配）。
+
+关联：`wms_inventory.location_code`。
+
+并发 / 审计：仍有非零库存时不能软删、不能停用。容量在上架时由应用校验，不靠数据库约束。

docs/database/30-master-data.md

@@ -0,0 +1,186 @@
+# 客户、供应商、商品、SKU
+
+约定见 [00-conventions.md](./00-conventions.md)。Phase 1 锁定，Phase 6 写迁移。
+
+`customer` 是货主，不是商城买家。3PL 场景下库存、商品、订单都归属某个货主。
+
+`sku_code` 在租户内唯一。两个货主不能共用同一个 SKU 编码；需要区分时由租户分配不同编码。
+
+## wms_customer 客户（货主）
+
+用途：租户服务的货主。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| customer_code | VARCHAR(64) | N | | 客户编码 |
+| name | VARCHAR(128) | N | | 名称 |
+| status | VARCHAR(32) | N | active | 状态 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+| deleted_at | TIMESTAMP | Y | | 软删除 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_customer_code | UNIQUE | (tenant_code, customer_code) | 按客户编码查找 |
+| idx_tenant_status | INDEX | (tenant_code, status) | 列表筛选 |
+
+状态：`active`、`disabled`。
+
+关联：商品、库存、入库、出库、订单带 `customer_code`。
+
+并发 / 审计：已有库存或未完成单据时不能软删。变更写 `wms_operation_log`。
+
+## wms_supplier 供应商
+
+用途：入库来源。`customer_code` 为空表示租户共用供应商，有值表示该货主的供应商。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| supplier_code | VARCHAR(64) | N | | 供应商编码 |
+| customer_code | VARCHAR(64) | Y | | 所属货主，空为租户共用 |
+| name | VARCHAR(128) | N | | 名称 |
+| status | VARCHAR(32) | N | active | 状态 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+| deleted_at | TIMESTAMP | Y | | 软删除 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_supplier_code | UNIQUE | (tenant_code, supplier_code) | 按供应商编码查找 |
+| idx_tenant_customer | INDEX | (tenant_code, customer_code) | 某货主的供应商 |
+
+状态：`active`、`disabled`。
+
+关联：`wms_inbound.supplier_code`、`wms_batch.supplier_code`。
+
+并发 / 审计：被未完成入库单引用时不能软删。
+
+## wms_product 商品
+
+用途：SKU 的上层商品，归属货主。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| customer_code | VARCHAR(64) | N | | 货主 |
+| product_code | VARCHAR(64) | N | | 商品编码，租户内唯一 |
+| product_name | VARCHAR(255) | N | | 名称 |
+| status | VARCHAR(32) | N | active | 状态 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+| deleted_at | TIMESTAMP | Y | | 软删除 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_product_code | UNIQUE | (tenant_code, product_code) | 按商品编码查找 |
+| idx_tenant_customer_status | INDEX | (tenant_code, customer_code, status) | 货主下的商品列表 |
+
+状态：`active`、`disabled`。
+
+关联：`wms_sku.product_code`。
+
+并发 / 审计：下属 SKU 仍存在时不能软删。
+
+## wms_sku SKU
+
+用途：库存与单据的基本物料。数量的「1」等于本表的基本单位。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| customer_code | VARCHAR(64) | N | | 货主 |
+| product_code | VARCHAR(64) | N | | 商品编码 |
+| sku_code | VARCHAR(64) | N | | SKU 编码，租户内唯一 |
+| sku_name_cn | VARCHAR(255) | N | | 中文名称 |
+| sku_name_en | VARCHAR(255) | N | | 英文名称 |
+| sku_unit | VARCHAR(32) | N | pcs | 基本单位 |
+| length_cm | DECIMAL(10,2) | Y | | 长，厘米 |
+| width_cm | DECIMAL(10,2) | Y | | 宽，厘米 |
+| height_cm | DECIMAL(10,2) | Y | | 高，厘米 |
+| weight_g | DECIMAL(16,4) | Y | | 重量，克 |
+| status | VARCHAR(32) | N | active | 状态 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+| deleted_at | TIMESTAMP | Y | | 软删除 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_sku_code | UNIQUE | (tenant_code, sku_code) | 按 SKU 编码查找 |
+| idx_tenant_customer_product | INDEX | (tenant_code, customer_code, product_code) | 商品下的 SKU |
+| idx_tenant_customer_status | INDEX | (tenant_code, customer_code, status) | 货主下的 SKU 列表 |
+
+状态：`active`、`disabled`。停用后禁止新的入库与分配，已有库存仍可出完。
+
+关联：条码、包装、库存、单据明细。
+
+并发 / 审计：存在非零库存时不能软删。变更写 `wms_operation_log`。
+
+## wms_sku_barcode 条码
+
+用途：一个 SKU 多条码。扫描时按租户内条码定位 SKU。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| sku_code | VARCHAR(64) | N | | SKU 编码 |
+| barcode | VARCHAR(64) | N | | 条码，租户内唯一 |
+| barcode_type | VARCHAR(32) | N | unit | 类型 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_barcode | UNIQUE | (tenant_code, barcode) | 扫码 |
+| idx_tenant_sku | INDEX | (tenant_code, sku_code) | SKU 的全部条码 |
+
+`barcode_type`：`unit` 单品、`case` 箱、`pallet` 托。
+
+关联：`wms_sku.sku_code`。箱、托条码只用于识别 SKU，换算数量以 `wms_pack_spec` 为准。
+
+并发 / 审计：无软删除。解除绑定即删行，并写 `wms_operation_log`。
+
+## wms_pack_spec 包装规格
+
+用途：相对基本单位的包装。`qty_per_pack` 表示这一包等于多少基本单位。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| sku_code | VARCHAR(64) | N | | SKU 编码 |
+| pack_code | VARCHAR(64) | N | | 包装编码，SKU 内唯一 |
+| name | VARCHAR(128) | N | | 名称 |
+| qty_per_pack | DECIMAL(16,4) | N | | 含基本单位数量，必须大于 0 |
+| length_mm | DECIMAL(10,2) | Y | | |
+| width_mm | DECIMAL(10,2) | Y | | |
+| height_mm | DECIMAL(10,2) | Y | | |
+| weight_g | DECIMAL(16,4) | Y | | |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_sku_pack | UNIQUE | (tenant_code, sku_code, pack_code) | 按包装编码查找 |
+
+关联：`wms_sku.sku_code`。库存与单据数量仍记基本单位，不按包装记账。
+
+并发 / 审计：无软删除。修改 `qty_per_pack` 不影响已记账数量。

docs/database/40-inventory.md

@@ -0,0 +1,236 @@
+# 库存余额、批次、流水、调整、盘点
+
+约定见 [00-conventions.md](./00-conventions.md)。数量桶的业务含义见 [01-er-overview.md](./01-er-overview.md) 与 [05-inventory.md](../05-inventory.md)。Phase 1 锁定，Phase 7、8 写迁移。
+
+冻结、锁定不单独建单据表。冻结是可用与 `hold_qty` 的对转；订单锁定是可用与 `reserved_qty` 的对转，锁定对象记在 `wms_outbound_allocation` 和流水的 `biz_no` 上。
+
+## wms_batch 批次
+
+用途：批次属性。不管理批次的库存使用 `batch_no = ''`，不写本表。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| customer_code | VARCHAR(64) | N | | 货主 |
+| sku_code | VARCHAR(64) | N | | SKU 编码 |
+| batch_no | VARCHAR(64) | N | | 批次号，禁止空字符串 |
+| supplier_code | VARCHAR(64) | Y | | 供应商 |
+| mfg_date | DATE | Y | | 生产日期 |
+| expiry_date | DATE | Y | | 失效日期 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_customer_sku_batch | UNIQUE | (tenant_code, customer_code, sku_code, batch_no) | 定位批次 |
+| idx_tenant_sku_expiry | INDEX | (tenant_code, sku_code, expiry_date) | 临期查询 |
+
+关联：`wms_inventory.batch_no`。首次收货写入，之后只允许补空缺的日期，不改已有批次号。
+
+并发 / 审计：无软删除。属性变更写 `wms_operation_log`。
+
+## wms_inventory 库存余额
+
+用途：某一货主、仓库、库位、SKU、批次上的数量结果。余额是结果，不是事实。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| customer_code | VARCHAR(64) | N | | 货主 |
+| warehouse_code | VARCHAR(32) | N | | 仓库编码 |
+| location_code | VARCHAR(64) | N | '' | 库位；在途为空字符串 |
+| sku_code | VARCHAR(64) | N | | SKU 编码 |
+| batch_no | VARCHAR(64) | N | '' | 批次；无批次为空字符串 |
+| available_qty | DECIMAL(16,4) | N | 0 | 可用 |
+| reserved_qty | DECIMAL(16,4) | N | 0 | 预占 |
+| picked_qty | DECIMAL(16,4) | N | 0 | 已拣 |
+| hold_qty | DECIMAL(16,4) | N | 0 | 冻结 |
+| damaged_qty | DECIMAL(16,4) | N | 0 | 残损 |
+| in_transit_qty | DECIMAL(16,4) | N | 0 | 在途 |
+| version | INT UNSIGNED | N | 0 | 乐观锁，随数量更新递增 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_inventory_grain | UNIQUE | (tenant_code, customer_code, warehouse_code, location_code, sku_code, batch_no) | 定位余额行 |
+| idx_tenant_wh_sku | INDEX | (tenant_code, warehouse_code, sku_code) | 仓库内某 SKU 库存 |
+| idx_tenant_customer_sku | INDEX | (tenant_code, customer_code, sku_code) | 货主下某 SKU 库存 |
+
+关联：维度对应仓库、库位、SKU、批次。在途行的 `location_code` 不引用 `wms_location`。
+
+并发 / 审计：
+
+- 禁止先查出数量再在 PHP 里相减后回写。
+- 扣减使用单条条件更新，例如可用转预占：
+
+```sql
+UPDATE wms_inventory
+SET available_qty = available_qty - :qty,
+    reserved_qty = reserved_qty + :qty,
+    version = version + 1
+WHERE tenant_code = :tenant_code
+  AND id = :id
+  AND available_qty >= :qty;
+```
+
+- 受影响行数为 0：库存不足或版本冲突，抛业务异常，整单事务回滚。
+- 同一事务插入对应的 `wms_stock_log`。
+- 各数量桶不得为负。不软删除；数量全为 0 的行保留，避免并发下反复插入同一粒度。
+
+## wms_stock_log 库存流水
+
+用途：库存变化的事实。任何余额变化都要有流水。只追加。
+
+一次业务动作若改变多个数量桶或多行余额，每个桶一行，共用同一个 `movement_no`。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| movement_no | VARCHAR(64) | N | | 同一次动作的组号 |
+| customer_code | VARCHAR(64) | N | | 货主 |
+| warehouse_code | VARCHAR(32) | N | | 仓库 |
+| location_code | VARCHAR(64) | N | '' | 库位 |
+| sku_code | VARCHAR(64) | N | | SKU |
+| batch_no | VARCHAR(64) | N | '' | 批次 |
+| qty_bucket | VARCHAR(32) | N | | `available`、`reserved`、`picked`、`hold`、`damaged`、`in_transit` |
+| qty_before | DECIMAL(16,4) | N | | 该桶变更前 |
+| qty_delta | DECIMAL(16,4) | N | | 有符号变化量 |
+| qty_after | DECIMAL(16,4) | N | | 该桶变更后 |
+| biz_type | VARCHAR(32) | N | | 业务类型 |
+| biz_no | VARCHAR(64) | N | | 业务单号 |
+| biz_line_no | INT UNSIGNED | Y | | 单据行号 |
+| operator_user_code | VARCHAR(64) | Y | | 操作人 |
+| request_id | VARCHAR(64) | Y | | 请求标识 |
+| created_at | TIMESTAMP | Y | | 发生时间 |
+| updated_at | TIMESTAMP | Y | | 行创建后不更新 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| idx_tenant_sku_created | INDEX | (tenant_code, sku_code, created_at) | 某 SKU 的库存为何变化 |
+| idx_tenant_biz | INDEX | (tenant_code, biz_type, biz_no) | 某单据的流水 |
+| idx_tenant_movement | INDEX | (tenant_code, movement_no) | 同一次动作的各行 |
+
+`biz_type`：`inbound_confirm`、`inbound_receive`、`inbound_putaway`、`reserve`、`release`、`pick`、`ship`、`hold`、`unhold`、`damage`、`transfer`、`adjust`、`stocktake`。
+
+关联：`biz_no` 指向入库单、出库单、调整单或盘点单。
+
+并发 / 审计：禁止更新和删除。`qty_after = qty_before + qty_delta`，且 `qty_after` 等于同一事务中余额桶的新值。
+
+## wms_stock_adjust 库存调整单
+
+用途：人工调整的单据头。确认时才改余额并写流水。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| adjust_no | VARCHAR(64) | N | | 调整单号 |
+| warehouse_code | VARCHAR(32) | N | | 仓库 |
+| customer_code | VARCHAR(64) | N | | 货主 |
+| status | VARCHAR(32) | N | draft | 状态 |
+| reason | VARCHAR(500) | N | | 原因 |
+| version | INT UNSIGNED | N | 0 | 乐观锁 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_adjust_no | UNIQUE | (tenant_code, adjust_no) | 按单号查找 |
+| idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表 |
+
+状态：`draft → confirmed`，`draft → cancelled`。`confirmed`、`cancelled` 为终态。
+
+确认时按明细对指定数量桶做原子增减，`biz_type = adjust`。减少时受影响行数为 0 则整单回滚。状态变更写 `wms_status_log`。不软删除。
+
+## wms_stock_adjust_line 调整明细
+
+用途：调整单的一行，只改一个数量桶。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| adjust_no | VARCHAR(64) | N | | 调整单号 |
+| line_no | INT UNSIGNED | N | | 行号，单内从 1 递增 |
+| location_code | VARCHAR(64) | N | '' | 库位 |
+| sku_code | VARCHAR(64) | N | | SKU |
+| batch_no | VARCHAR(64) | N | '' | 批次 |
+| qty_bucket | VARCHAR(32) | N | | 数量桶 |
+| qty_delta | DECIMAL(16,4) | N | | 有符号数量，禁止 0 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_adjust_line | UNIQUE | (tenant_code, adjust_no, line_no) | 定位明细 |
+
+关联：头表 `wms_stock_adjust`。确认后明细不再修改。
+
+## wms_stocktake 盘点单
+
+用途：盘点单据头。确认时把账面与实盘的差额写成流水，`biz_type = stocktake`。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| stocktake_no | VARCHAR(64) | N | | 盘点单号 |
+| warehouse_code | VARCHAR(32) | N | | 仓库 |
+| status | VARCHAR(32) | N | draft | 状态 |
+| version | INT UNSIGNED | N | 0 | 乐观锁 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_stocktake_no | UNIQUE | (tenant_code, stocktake_no) | 按单号查找 |
+| idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表 |
+
+状态：`draft → counting → confirmed`，`draft` 或 `counting` 可到 `cancelled`。`confirmed`、`cancelled` 为终态。
+
+盘点期间不锁死全仓。确认时按当时账面重算差额；若并发导致目标桶不足，确认失败并回滚。不软删除。
+
+## wms_stocktake_line 盘点明细
+
+用途：一个库位、SKU、批次、数量桶上的账面与实盘。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| stocktake_no | VARCHAR(64) | N | | 盘点单号 |
+| line_no | INT UNSIGNED | N | | 行号 |
+| customer_code | VARCHAR(64) | N | | 货主 |
+| location_code | VARCHAR(64) | N | | 库位 |
+| sku_code | VARCHAR(64) | N | | SKU |
+| batch_no | VARCHAR(64) | N | '' | 批次 |
+| qty_bucket | VARCHAR(32) | N | available | 盘点的数量桶 |
+| system_qty | DECIMAL(16,4) | N | | 生成明细时的账面 |
+| counted_qty | DECIMAL(16,4) | Y | | 实盘，未盘为空 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_stocktake_line | UNIQUE | (tenant_code, stocktake_no, line_no) | 定位明细 |
+| idx_tenant_stocktake_loc | INDEX | (tenant_code, stocktake_no, location_code) | 按库位录入 |
+
+关联：头表 `wms_stocktake`。确认时差额为 `counted_qty - 当前账面`，不以生成时的 `system_qty` 作为扣减依据。`system_qty` 只说明生成时刻的账面。

docs/database/50-inbound.md

@@ -0,0 +1,150 @@
+# 入库
+
+约定见 [00-conventions.md](./00-conventions.md)。库存变化见 [40-inventory.md](./40-inventory.md)。Phase 1 锁定，Phase 9 写迁移。
+
+收货差异不建表，由明细的 `expected_qty - received_qty` 得出。质检结果记在收货记录上。
+
+## wms_inbound 入库单
+
+用途：入库单据头。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| inbound_no | VARCHAR(64) | N | | 入库单号 |
+| warehouse_code | VARCHAR(32) | N | | 仓库 |
+| customer_code | VARCHAR(64) | N | | 货主 |
+| inbound_type | VARCHAR(32) | N | | 类型 |
+| supplier_code | VARCHAR(64) | Y | | 供应商 |
+| status | VARCHAR(32) | N | draft | 状态 |
+| qc_required | TINYINT UNSIGNED | N | 0 | 1 表示收货后需质检 |
+| expected_at | TIMESTAMP | Y | | 预计到货 |
+| remark | VARCHAR(500) | Y | | |
+| version | INT UNSIGNED | N | 0 | 乐观锁 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_inbound_no | UNIQUE | (tenant_code, inbound_no) | 按单号查找 |
+| idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表 |
+| idx_tenant_wh_customer | INDEX | (tenant_code, warehouse_code, customer_code, status) | 仓库 / 货主筛选 |
+
+`inbound_type`：`purchase` 采购、`return` 退货入库、`transfer` 调拨、`other` 其他。退货业务单据表在后续 Phase 再设计，这里只保留类型值。
+
+状态与合法转换：
+
+```
+draft → confirmed → receiving → received → putting_away → completed
+draft → cancelled
+confirmed → cancelled
+receiving → cancelled   （仅当全部明细 received_qty = 0）
+```
+
+`completed`、`cancelled` 为终态。禁止跳步。每次成功转换写 `wms_status_log`，`biz_type = inbound`。
+
+关联：明细、收货、上架。不软删除，取消用状态。
+
+并发 / 审计：更新状态时带 `version`。确认时按预计数量增加在途（`location_code = ''`，`biz_type = inbound_confirm`）。取消已确认且未收货的单据时冲回在途。
+
+## wms_inbound_line 入库明细
+
+用途：入库单的 SKU 行。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| inbound_no | VARCHAR(64) | N | | 入库单号 |
+| line_no | INT UNSIGNED | N | | 行号，单内从 1 递增 |
+| sku_code | VARCHAR(64) | N | | SKU |
+| batch_no | VARCHAR(64) | N | '' | 指定批次；收货时才知道则为空，记到收货记录 |
+| expected_qty | DECIMAL(16,4) | N | | 预计数量，大于 0 |
+| received_qty | DECIMAL(16,4) | N | 0 | 已收，由收货记录累计 |
+| putaway_qty | DECIMAL(16,4) | N | 0 | 已上架，由上架记录累计 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_inbound_line | UNIQUE | (tenant_code, inbound_no, line_no) | 定位明细 |
+| idx_tenant_inbound_sku | INDEX | (tenant_code, inbound_no, sku_code) | 按 SKU 找行 |
+
+关联：头表 `wms_inbound`。`received_qty`、`putaway_qty` 只由收货、上架事务回写，不单独做接口改数。
+
+约束：`putaway_qty <= received_qty <= expected_qty` 不强制等于预计。短收允许进入 `received`。超收拒绝。
+
+## wms_inbound_receipt 收货记录
+
+用途：一次收货的事实。只追加。质检结论写在本行。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| receipt_no | VARCHAR(64) | N | | 收货记录号，可用 movement 同源取号或与 movement_no 相同 |
+| inbound_no | VARCHAR(64) | N | | 入库单号 |
+| line_no | INT UNSIGNED | N | | 明细行号 |
+| sku_code | VARCHAR(64) | N | | SKU |
+| batch_no | VARCHAR(64) | N | '' | 实收批次 |
+| location_code | VARCHAR(64) | N | | 收到的库位，通常是收货位 |
+| qty | DECIMAL(16,4) | N | | 数量，大于 0 |
+| qc_result | VARCHAR(32) | N | skipped | 质检结果 |
+| operator_user_code | VARCHAR(64) | Y | | 操作人 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | 行创建后不更新 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_receipt_no | UNIQUE | (tenant_code, receipt_no) | 按收货号查找 |
+| idx_tenant_inbound_line | INDEX | (tenant_code, inbound_no, line_no) | 某行的收货历史 |
+
+`qc_result`：`skipped` 无需质检，`passed` 合格，`failed` 不合格。
+
+同一事务：
+
+- 在途减少 `qty`。
+- `passed` 或 `skipped`：收货位 `available_qty` 增加。
+- `failed`：收货位 `damaged_qty` 增加。
+- 流水 `biz_type = inbound_receive`，`biz_no = inbound_no`。
+- 明细 `received_qty` 增加。
+
+不需要质检时 `qc_result` 直接为 `skipped`。需要质检时，本阶段仍在收货事务内给出结论，不另建质检单。
+
+## wms_inbound_putaway 上架记录
+
+用途：从收货位移到存储位的事实。只追加。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| putaway_no | VARCHAR(64) | N | | 上架记录号 |
+| inbound_no | VARCHAR(64) | N | | 入库单号 |
+| line_no | INT UNSIGNED | N | | 明细行号 |
+| sku_code | VARCHAR(64) | N | | SKU |
+| batch_no | VARCHAR(64) | N | '' | 批次 |
+| from_location_code | VARCHAR(64) | N | | 源库位 |
+| to_location_code | VARCHAR(64) | N | | 目标库位 |
+| qty | DECIMAL(16,4) | N | | 数量，大于 0 |
+| operator_user_code | VARCHAR(64) | Y | | 操作人 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | 行创建后不更新 |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_putaway_no | UNIQUE | (tenant_code, putaway_no) | 按上架号查找 |
+| idx_tenant_inbound_line | INDEX | (tenant_code, inbound_no, line_no) | 某行的上架历史 |
+
+同一事务：源库位可用减少、目标库位可用增加，流水 `biz_type = inbound_putaway`。目标库位须为 `active`，并满足混放与容量。残损数量不上架到存储位，留在收货 / 残品位。明细 `putaway_qty` 增加。
+
+全部明细 `putaway_qty = received_qty` 且状态为 `putting_away` 时，才允许转到 `completed`。

docs/database/60-outbound.md

@@ -0,0 +1,324 @@
+# 订单与出库
+
+约定见 [00-conventions.md](./00-conventions.md)。库存变化见 [40-inventory.md](./40-inventory.md)。Phase 1 锁定。订单与出库单在 Phase 10 写迁移，波次、拣货、打包、发货在 Phase 11 写迁移。
+
+订单是统一需求模型。表内没有平台专有字段。上游平台、店铺、ERP 只通过 `channel`、`source_code`、`external_no` 表达。平台报文的转换放在 Connector，不进这些表。
+
+`wms_order_line` 对应领域模型里的 order item。
+
+承运商主数据在 Phase 12。发货单上的 `carrier_code`、`tracking_no` 先作为普通字符串保存。
+
+## wms_order 订单
+
+用途：出库需求。手工单、API、ERP、电商平台都落这张表。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| order_no | VARCHAR(64) | N | | 系统订单号 |
+| warehouse_code | VARCHAR(32) | N | | 发货仓库 |
+| customer_code | VARCHAR(64) | N | | 货主 |
+| channel | VARCHAR(32) | N | | 来源通道 |
+| source_code | VARCHAR(64) | Y | | 来源实例，如店铺或 ERP 连接编码；手工单为空 |
+| external_no | VARCHAR(64) | Y | | 上游单号；手工单为空 |
+| status | VARCHAR(32) | N | draft | 状态 |
+| version | INT UNSIGNED | N | 0 | 乐观锁 |
+| remark | VARCHAR(500) | Y | | |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_order_no | UNIQUE | (tenant_code, order_no) | 按订单号查找 |
+| uk_tenant_source_external | UNIQUE | (tenant_code, source_code, external_no) | 上游单去重 |
+| idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表 |
+
+`channel`：`manual`、`api`、`erp`、`marketplace`。
+
+`channel = manual` 时 `source_code` 与 `external_no` 必须为 `NULL`。其他通道两者必填。MySQL 唯一索引对 `NULL` 不判重，因此多张手工单可以并存。
+
+状态：
+
+```
+draft → confirmed → processing → shipped → completed
+draft → cancelled
+confirmed → cancelled
+processing → cancelled   （关联出库单尚未 shipped）
+```
+
+`completed`、`cancelled` 为终态。出库单进入 `shipped` 时，订单改为 `shipped`。不软删除。
+
+## wms_order_line 订单明细
+
+用途：订单要发的 SKU 与数量。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| order_no | VARCHAR(64) | N | | 订单号 |
+| line_no | INT UNSIGNED | N | | 行号 |
+| sku_code | VARCHAR(64) | N | | SKU |
+| qty | DECIMAL(16,4) | N | | 需求数量，大于 0 |
+| allocated_qty | DECIMAL(16,4) | N | 0 | 已分配，由出库分配回写 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_order_line | UNIQUE | (tenant_code, order_no, line_no) | 定位明细 |
+
+关联：`wms_order`。`allocated_qty <= qty`。
+
+## wms_outbound 出库单
+
+用途：仓库执行单。第一阶段业务上一单一张出库单；表允许同一 `order_no` 对应多张出库单。无订单的手工出库 `order_no` 为空。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| outbound_no | VARCHAR(64) | N | | 出库单号 |
+| order_no | VARCHAR(64) | Y | | 订单号 |
+| warehouse_code | VARCHAR(32) | N | | 仓库 |
+| customer_code | VARCHAR(64) | N | | 货主 |
+| status | VARCHAR(32) | N | draft | 状态 |
+| version | INT UNSIGNED | N | 0 | 乐观锁 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_outbound_no | UNIQUE | (tenant_code, outbound_no) | 按出库单号查找 |
+| idx_tenant_order | INDEX | (tenant_code, order_no) | 订单下的出库单 |
+| idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表 |
+
+状态（与领域模型一致，并补上取消）：
+
+```
+draft → allocated → picking → picked → packing → packed → shipped → completed
+draft → cancelled
+allocated → cancelled   （必须释放预占）
+```
+
+`completed`、`cancelled` 为终态。禁止跳步。`picking` 之后取消不在本阶段打开，避免已拣库存没有回退规则。状态变更写 `wms_status_log`，`biz_type = outbound`。
+
+短拣不新增头状态。行上的已拣数量可以小于需求数量，头状态仍按上面的路径走；是否允许短拣完成，在 Phase 11 做业务校验。
+
+## wms_outbound_line 出库明细
+
+用途：出库单的 SKU 行。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| outbound_no | VARCHAR(64) | N | | 出库单号 |
+| line_no | INT UNSIGNED | N | | 行号 |
+| order_line_no | INT UNSIGNED | Y | | 对应订单行，无订单时为空 |
+| sku_code | VARCHAR(64) | N | | SKU |
+| qty | DECIMAL(16,4) | N | | 需求数量，大于 0 |
+| allocated_qty | DECIMAL(16,4) | N | 0 | 已分配 |
+| picked_qty | DECIMAL(16,4) | N | 0 | 已拣 |
+| packed_qty | DECIMAL(16,4) | N | 0 | 已打包 |
+| shipped_qty | DECIMAL(16,4) | N | 0 | 已发 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_outbound_line | UNIQUE | (tenant_code, outbound_no, line_no) | 定位明细 |
+
+关联：数量由分配、拣货、打包、发货事务回写。`shipped_qty <= packed_qty <= picked_qty <= allocated_qty <= qty`。
+
+## wms_outbound_allocation 库存分配
+
+用途：出库行占住的具体库位与批次。分配成功才把可用转为预占。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| allocation_no | VARCHAR(64) | N | | 分配号 |
+| outbound_no | VARCHAR(64) | N | | 出库单号 |
+| line_no | INT UNSIGNED | N | | 出库行号 |
+| sku_code | VARCHAR(64) | N | | SKU |
+| location_code | VARCHAR(64) | N | | 库位，不能是在途空库位 |
+| batch_no | VARCHAR(64) | N | '' | 批次 |
+| qty | DECIMAL(16,4) | N | | 分配数量，大于 0 |
+| status | VARCHAR(32) | N | allocated | 状态 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_allocation_no | UNIQUE | (tenant_code, allocation_no) | 按分配号查找 |
+| idx_tenant_outbound_line | INDEX | (tenant_code, outbound_no, line_no) | 某行的分配 |
+
+状态：`allocated → picked`，`allocated → cancelled`。
+
+创建时原子更新库存（可用减、预占加），流水 `biz_type = reserve`，`biz_no = outbound_no`。取消时反向，`biz_type = release`。拣货确认时预占减、已拣加，`biz_type = pick`，本行改为 `picked`。
+
+全部需求行 `allocated_qty = qty` 后，出库单才从 `draft` 到 `allocated`。库存不足则整单分配回滚，不产生部分成功的预占。
+
+## wms_wave 波次
+
+用途：把多张出库单放进一次拣货。不使用波次时，拣货任务的 `wave_no` 为空，按单拣货。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| wave_no | VARCHAR(64) | N | | 波次号 |
+| warehouse_code | VARCHAR(32) | N | | 仓库 |
+| status | VARCHAR(32) | N | draft | 状态 |
+| version | INT UNSIGNED | N | 0 | 乐观锁 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_wave_no | UNIQUE | (tenant_code, wave_no) | 按波次号查找 |
+| idx_tenant_wh_status | INDEX | (tenant_code, warehouse_code, status) | 仓库内的波次 |
+
+状态：`draft → released → picking → completed`，`draft → cancelled`。释放波次时，关联出库单从 `allocated` 进入 `picking`。
+
+## wms_wave_outbound 波次与出库单
+
+用途：波次包含哪些出库单。一张出库单同时只属于一个未取消的波次。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| wave_no | VARCHAR(64) | N | | 波次号 |
+| outbound_no | VARCHAR(64) | N | | 出库单号 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_wave_outbound | UNIQUE | (tenant_code, wave_no, outbound_no) | 防止重复加入同一波次 |
+| idx_tenant_outbound | INDEX | (tenant_code, outbound_no) | 查出库单所在波次 |
+
+一张出库单同时只能属于一个未取消波次，由应用在加入时检查，不靠删除行来腾出唯一约束。波次取消后这些行保留，出库单回到 `allocated`。不软删除。
+
+## wms_pick_task 拣货任务
+
+用途：拣货执行行。由分配生成。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| picking_no | VARCHAR(64) | N | | 拣货任务号 |
+| wave_no | VARCHAR(64) | Y | | 波次，按单拣货时为空 |
+| outbound_no | VARCHAR(64) | N | | 出库单号 |
+| allocation_no | VARCHAR(64) | N | | 分配号 |
+| sku_code | VARCHAR(64) | N | | SKU |
+| location_code | VARCHAR(64) | N | | 拣货库位 |
+| batch_no | VARCHAR(64) | N | '' | 批次 |
+| qty | DECIMAL(16,4) | N | | 应拣数量 |
+| picked_qty | DECIMAL(16,4) | N | 0 | 实拣数量 |
+| status | VARCHAR(32) | N | pending | 状态 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_picking_no | UNIQUE | (tenant_code, picking_no) | 按任务号查找 |
+| uk_tenant_allocation | UNIQUE | (tenant_code, allocation_no) | 一条分配一个任务 |
+| idx_tenant_outbound | INDEX | (tenant_code, outbound_no, status) | 出库单的拣货任务 |
+
+状态：`pending → picked`。确认拣货时 `picked_qty` 等于 `qty`（短拣规则 Phase 11 再放开），并完成分配行的库存桶转换。该出库单全部分配都已 `picked` 后，出库单才到 `picked`。
+
+## wms_package 包裹
+
+用途：复核打包结果。一张出库单可有多个包裹。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| package_no | VARCHAR(64) | N | | 包裹号 |
+| outbound_no | VARCHAR(64) | N | | 出库单号 |
+| status | VARCHAR(32) | N | open | 状态 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_package_no | UNIQUE | (tenant_code, package_no) | 按包裹号查找 |
+| idx_tenant_outbound | INDEX | (tenant_code, outbound_no) | 出库单的包裹 |
+
+状态：`open → sealed`。全部应发数量进入已封箱包裹后，出库单从 `packing` 到 `packed`。打包不改变库存桶，只增加明细 `packed_qty`。
+
+## wms_package_line 包裹明细
+
+用途：包裹里的 SKU 数量。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| package_no | VARCHAR(64) | N | | 包裹号 |
+| line_no | INT UNSIGNED | N | | 行号 |
+| sku_code | VARCHAR(64) | N | | SKU |
+| qty | DECIMAL(16,4) | N | | 数量，大于 0 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_package_line | UNIQUE | (tenant_code, package_no, line_no) | 定位明细 |
+
+关联：`wms_package`。封箱后不改行。
+
+## wms_shipment 发货
+
+用途：出库单发出的记录。物流渠道主数据尚未建表，承运商与运单号先记在这里。
+
+| 字段 | 类型 | 可空 | 默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
+| tenant_code | VARCHAR(32) | N | | 租户编码 |
+| shipment_no | VARCHAR(64) | N | | 发货单号 |
+| outbound_no | VARCHAR(64) | N | | 出库单号 |
+| package_no | VARCHAR(64) | Y | | 包裹号，整单发货可空 |
+| carrier_code | VARCHAR(64) | Y | | 承运商编码，Phase 12 再约束到主数据 |
+| tracking_no | VARCHAR(64) | Y | | 运单号 |
+| status | VARCHAR(32) | N | shipped | 状态 |
+| shipped_at | TIMESTAMP | Y | | 发货时间 |
+| created_at | TIMESTAMP | Y | | |
+| updated_at | TIMESTAMP | Y | | |
+
+索引：
+
+| 名称 | 类型 | 字段 | 支撑的查询 |
+| --- | --- | --- | --- |
+| uk_tenant_shipment_no | UNIQUE | (tenant_code, shipment_no) | 按发货单号查找 |
+| idx_tenant_outbound | INDEX | (tenant_code, outbound_no) | 出库单的发货记录 |
+| idx_tenant_tracking | INDEX | (tenant_code, tracking_no) | 按运单号查 |
+
+状态：`shipped`。本阶段发货即终态。同一事务把已拣数量减掉（离开仓库），流水 `biz_type = ship`，并回写出库明细 `shipped_qty`。出库单改为 `shipped`，若有订单则订单改为 `shipped`。之后出库单再进入 `completed` 只表示作业关闭，不再改库存。

docs/database/README.md

@@ -1,57 +1,100 @@
 # 数据库表结构设计
 
-本目录存放 WMS SaaS 的数据库表结构设计，是 `backend/database/migrations` 的设计依据。通用规范见 [../09-database.md](../09-database.md)。
+本目录是 MySQL 8 建表设计稿，每张表一个 `.sql` 文件。通用规范见 [../09-database.md](../09-database.md)，命名、类型和库存粒度见 [00-conventions.md](./00-conventions.md)。
 
-**先设计、确认，再写迁移；改表时迁移与本目录文档同步更新。**
+落地方式：某个 Phase 开工时，只把本阶段要用的表写成 Laravel migration，并与这里的 SQL 保持一致。不要一次生成全部 migration，也不要在生产库直接执行这些文件。
 
-## 文件组织
+表之间没有外键，执行顺序没有依赖。
 
-按业务领域一个文件，文件内包含该领域所有表：
+## 表清单
 
-| 文件 | 领域 | 对应 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 | | |
-
-索引：
-
-| 名称 | 类型 | 字段 | 支撑的查询 |
+| 表 | 说明 | 目录 | Phase |
 | --- | --- | --- | --- |
-| uk_tenant_xxx_code | UNIQUE | (tenant_code, xxx_code) | 按业务编码查找 |
-| idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表筛选 |
+| [wms_tenant](./01-saas/wms_tenant.sql) | 租户。SaaS 隔离边界，tenant_code 全局唯一。 | `01-saas` | 4 |
+| [wms_user](./01-saas/wms_user.sql) | 用户。租户内登录账号。 | `01-saas` | 4 |
+| [wms_role](./01-saas/wms_role.sql) | 角色。租户内角色。 | `01-saas` | 4 |
+| [wms_permission](./01-saas/wms_permission.sql) | 权限。全局权限码目录，不按租户复制。 | `01-saas` | 4 |
+| [wms_role_permission](./01-saas/wms_role_permission.sql) | 角色权限。租户内角色与全局权限码的绑定。 | `01-saas` | 4 |
+| [wms_user_role](./01-saas/wms_user_role.sql) | 用户角色。租户内用户与角色的绑定。 | `01-saas` | 4 |
+| [wms_tenant_setting](./01-saas/wms_tenant_setting.sql) | 租户设置。租户级可配置项，包括定时任务开关。 | `01-saas` | 4 |
+| [wms_number_sequence](./01-saas/wms_number_sequence.sql) | 单号序列。按租户、业务类型发号，保证并发下单号不重复。 | `01-saas` | 4 |
+| [wms_warehouse](./02-warehouse/wms_warehouse.sql) | 仓库。租户下的物理仓库。 | `02-warehouse` | 5 |
+| [wms_zone](./02-warehouse/wms_zone.sql) | 库区。仓库内的功能分区。 | `02-warehouse` | 5 |
+| [wms_location_type](./02-warehouse/wms_location_type.sql) | 库位类型。库位的混放规则。 | `02-warehouse` | 5 |
+| [wms_location](./02-warehouse/wms_location.sql) | 库位。仓库内可存放库存的最小位置，同时保存容量。 | `02-warehouse` | 5 |
+| [wms_location_strategy](./02-warehouse/wms_location_strategy.sql) | 库位策略。上架、分配、拣货的规则。空编码表示该条件不限。 | `02-warehouse` | 5 |
+| [wms_customer](./03-master/wms_customer.sql) | 货主。3PL 的客户。自营租户也建一个默认货主，库存一律落到货主。 | `03-master` | 6 |
+| [wms_customer_warehouse](./03-master/wms_customer_warehouse.sql) | 货主仓库。货主可以使用哪些仓库。 | `03-master` | 6 |
+| [wms_supplier](./03-master/wms_supplier.sql) | 供应商。入库来源供应商。 | `03-master` | 6 |
+| [wms_product](./03-master/wms_product.sql) | 商品。SKU 的上层商品，属于一个货主。 | `03-master` | 6 |
+| [wms_sku](./03-master/wms_sku.sql) | SKU。库存与订单的最小商品单位，含单件重量和尺寸。 | `03-master` | 6 |
+| [wms_sku_barcode](./03-master/wms_sku_barcode.sql) | SKU 条码。SKU 的扫描条码，租户内一条码只对应一个 SKU。 | `03-master` | 6 |
+| [wms_package_spec](./03-master/wms_package_spec.sql) | 包装规格。SKU 的装箱规格，如一件箱装多少件。 | `03-master` | 6 |
+| [wms_batch](./04-inventory/wms_batch.sql) | 批次。启用批次或效期管理的 SKU 的批次档案。 | `04-inventory` | 7 |
+| [wms_inventory](./04-inventory/wms_inventory.sql) | 库存余额。某个货主、仓库、库位、SKU、批次上的数量结果。 | `04-inventory` | 7 |
+| [wms_stock_log](./04-inventory/wms_stock_log.sql) | 库存流水。库存变化的事实记录，只能追加。 | `04-inventory` | 8 |
+| [wms_inventory_hold](./04-inventory/wms_inventory_hold.sql) | 库存冻结单。把可用库存转为冻结的业务单据。 | `04-inventory` | 8 |
+| [wms_inventory_hold_item](./04-inventory/wms_inventory_hold_item.sql) | 库存冻结明细。冻结单的库位与数量。 | `04-inventory` | 8 |
+| [wms_stock_adjustment](./04-inventory/wms_stock_adjustment.sql) | 库存调整单。盘盈盘亏、报损等人工调整。 | `04-inventory` | 8 |
+| [wms_stock_adjustment_item](./04-inventory/wms_stock_adjustment_item.sql) | 库存调整明细。调整的数量桶与变化量。 | `04-inventory` | 8 |
+| [wms_stocktake](./04-inventory/wms_stocktake.sql) | 盘点单。仓库盘点任务。 | `04-inventory` | 8 |
+| [wms_stocktake_item](./04-inventory/wms_stocktake_item.sql) | 盘点明细。系统数量与实盘数量。 | `04-inventory` | 8 |
+| [wms_inventory_alert](./04-inventory/wms_inventory_alert.sql) | 库存预警规则。SKU 在仓库的最低可用量阈值。 | `04-inventory` | 8 |
+| [wms_inbound](./05-inbound/wms_inbound.sql) | 入库单。入库作业的头单据。 | `05-inbound` | 9 |
+| [wms_inbound_item](./05-inbound/wms_inbound_item.sql) | 入库明细。入库单行，数量列是各作业的汇总结果。 | `05-inbound` | 9 |
+| [wms_inbound_receipt](./05-inbound/wms_inbound_receipt.sql) | 收货记录。一张入库单可以分多次收货。 | `05-inbound` | 9 |
+| [wms_inbound_receipt_item](./05-inbound/wms_inbound_receipt_item.sql) | 收货明细。本次实收数量以及与预计的差异。 | `05-inbound` | 9 |
+| [wms_inbound_qc](./05-inbound/wms_inbound_qc.sql) | 入库质检。按收货结果做的质检记录。 | `05-inbound` | 9 |
+| [wms_inbound_putaway](./05-inbound/wms_inbound_putaway.sql) | 上架任务。把收货库位的合格库存移到存储库位。 | `05-inbound` | 9 |
+| [wms_order](./06-outbound/wms_order.sql) | 统一订单。与具体电商平台解耦的履约订单。 | `06-outbound` | 10 |
+| [wms_order_item](./06-outbound/wms_order_item.sql) | 订单明细。订单要履约的 SKU 与数量。 | `06-outbound` | 10 |
+| [wms_outbound](./06-outbound/wms_outbound.sql) | 出库单。仓库执行单据。一张订单可按仓库拆成多张出库单。 | `06-outbound` | 10 |
+| [wms_outbound_item](./06-outbound/wms_outbound_item.sql) | 出库明细。出库单行及各作业数量汇总。 | `06-outbound` | 10 |
+| [wms_allocation](./06-outbound/wms_allocation.sql) | 库存分配。出库行预占到具体库位批次的记录，也是库存锁定明细。 | `06-outbound` | 10 |
+| [wms_wave](./06-outbound/wms_wave.sql) | 波次。把多张出库单组成一次拣货。 | `06-outbound` | 11 |
+| [wms_wave_outbound](./06-outbound/wms_wave_outbound.sql) | 波次出库。波次包含的出库单。 | `06-outbound` | 11 |
+| [wms_picking_task](./06-outbound/wms_picking_task.sql) | 拣货任务。一次派给拣货人的任务，可来自波次或单张出库单。 | `06-outbound` | 11 |
+| [wms_picking_task_item](./06-outbound/wms_picking_task_item.sql) | 拣货任务明细。按库位给出的应拣与实拣数量。 | `06-outbound` | 11 |
+| [wms_package](./06-outbound/wms_package.sql) | 包裹。复核通过后的打包结果。打包不改变库存数量桶。 | `06-outbound` | 11 |
+| [wms_package_item](./06-outbound/wms_package_item.sql) | 包裹明细。包裹内的 SKU 数量。 | `06-outbound` | 11 |
+| [wms_return_order](./07-return/wms_return_order.sql) | 退货单。客户退回仓库的单据。 | `07-return` | 9 |
+| [wms_return_order_item](./07-return/wms_return_order_item.sql) | 退货明细。退货数量、质检结论和处置方式。 | `07-return` | 9 |
+| [wms_carrier](./08-logistics/wms_carrier.sql) | 承运商。租户配置的承运商主数据。 | `08-logistics` | 12 |
+| [wms_logistics_service](./08-logistics/wms_logistics_service.sql) | 物流服务。承运商下的服务产品，如标准、快递、经济。 | `08-logistics` | 12 |
+| [wms_logistics_channel](./08-logistics/wms_logistics_channel.sql) | 物流渠道。仓库实际可选用的承运商服务。 | `08-logistics` | 12 |
+| [wms_freight_rule](./08-logistics/wms_freight_rule.sql) | 运费规则。渠道上的重量段首重续重价格。 | `08-logistics` | 12 |
+| [wms_shipment](./08-logistics/wms_shipment.sql) | 发货单。包裹交给承运商的记录。 | `08-logistics` | 11 |
+| [wms_waybill](./08-logistics/wms_waybill.sql) | 面单。发货单对应的面单文件，允许作废后重开。 | `08-logistics` | 12 |
+| [wms_tracking_event](./08-logistics/wms_tracking_event.sql) | 轨迹事件。运单轨迹，按时间追加。 | `08-logistics` | 12 |
+| [wms_platform_shop](./09-integration/wms_platform_shop.sql) | 平台店铺。第三方平台连接。新增平台不改订单表。 | `09-integration` | 14 |
+| [wms_sync_task](./09-integration/wms_sync_task.sql) | 同步任务。订单、库存、轨迹等拉取任务的进度。 | `09-integration` | 14 |
+| [wms_webhook_log](./09-integration/wms_webhook_log.sql) | Webhook 日志。平台回调的接收与处理结果，用于验签后的幂等。 | `09-integration` | 14 |
+| [wms_login_log](./10-audit/wms_login_log.sql) | 登录日志。登录成功与失败记录。 | `10-audit` | 4 |
+| [wms_operation_log](./10-audit/wms_operation_log.sql) | 操作日志。关键业务数据谁在何时改了什么。 | `10-audit` | 4 |
+| [wms_api_log](./10-audit/wms_api_log.sql) | API 日志。接口访问记录，不保存完整报文。 | `10-audit` | 4 |
+| [wms_status_log](./10-audit/wms_status_log.sql) | 状态变更日志。订单、入库、出库等单据的状态迁移。 | `10-audit` | 4 |
 
-状态说明 / 合法流转（有状态字段时必填）。
+## 领域关系
 
-关联：与哪些表通过哪些业务编码关联。
+```mermaid
+erDiagram
+  wms_tenant ||--o{ wms_warehouse : tenant_code
+  wms_customer ||--o{ wms_sku : customer_code
+  wms_warehouse ||--o{ wms_zone : warehouse_code
+  wms_zone ||--o{ wms_location : zone_code
+  wms_sku ||--o{ wms_inventory : sku_code
+  wms_location ||--o{ wms_inventory : location_code
+  wms_inventory ||--o{ wms_stock_log : "同一事务"
+  wms_order ||--o{ wms_order_item : order_no
+  wms_order ||--o{ wms_outbound : order_no
+  wms_outbound ||--o{ wms_outbound_item : outbound_no
+  wms_outbound ||--o{ wms_allocation : outbound_no
+  wms_allocation ||--o{ wms_picking_task_item : allocation_no
+  wms_outbound ||--o{ wms_package : outbound_no
+  wms_package ||--|| wms_shipment : package_no
+  wms_inbound ||--o{ wms_inbound_item : inbound_no
+  wms_inbound ||--o{ wms_inbound_receipt : inbound_no
+  wms_inbound ||--o{ wms_inbound_putaway : inbound_no
+```
 
-并发 / 审计说明：是否需要行锁、乐观锁、流水、软删除，及原因。
-````
+关联字段都是业务编码。`wms_stock_log.inventory_id` 只用于和余额行对账。