# OMS 仓储模块 — 产品与技术设计方案

> **版本**：v0.3（轻量版 + `C_` 表前缀 + 库位 + 入库箱）  
> **基线文档**：`docs/oms系统设计-050801.md`、`docs/rbac系统设计-060801.md`、`docs/前端页面设计规范.md`  
> **参考实现**：WMS 六页业务逻辑（**按需裁剪，不做完整 WMS**）  
> **对照仓库**：`C:\Users\wilso\Desktop\oms0414-back`（Fake 框架 + SqlSugar）

---

## 0　轻量版总览（推荐阅读）

> v0.1 按 WMS 能力完整对标，**表多、接口多、状态细**。若目标仅是「客户能管 SKU、预报入库、看库存、接店铺单发货」，采用本节 **轻量版** 即可，全文 §1～§11 中标注 **〔轻量〕** / **〔延后〕** 处以此为准。

### 0.1 设计取向

| 项 | v0.1 完整版 | **v0.3 轻量版（当前）** |
| --- | --- | --- |
| 定位 | 对标 WMS 仓储子系统 | OMS 附属 **基础仓储**，保留库位与入库箱 |
| **仓储表命名** | `t_wh_*` | **`C_` + 表名**（如 `C_sku`、`C_inventory`） |
| 数据表 | 18 张 | **13 张**（店铺 4 `t_*` + 仓储 9 `C_*`） |
| 后端 Service | 6 个 | **3 个**（店铺 2 + 仓储 1） |
| 库存模型 | 批次 lot + 冻结 + 流水 | **SKU × 仓库 × 库位** 余额，不做 FIFO/流水 |
| 入库预报 | 箱 → SKU + 收货日志 | **主表 + 箱 + 箱内 SKU**（保留箱号） |
| 组合 SKU / 库存同步 / 拆单 | 一期设计 | **延后** |
| 权限粒度 | 20+ Action | **每页 Query + Save + Delete**（库存加 Relocate） |

### 0.2 表清单

**命名约定**

| 范围 | 前缀 | 示例 |
| --- | --- | --- |
| 仓储模块（本文） | **`C_`** | `C_sku`、`C_inventory`、`C_inbound_box` |
| 订单 — 店铺（归属订单模块） | `t_` | `t_sales_store`、`t_sales_store_order` |
| 系统主数据 | `t_` | `t_warehouse_address` |

**订单 — 店铺（4 张，`t_` 前缀）**

| 表 | 说明 |
| --- | --- |
| `t_sales_store` | 店铺 + Token 合并（Token 加密，列表脱敏） |
| `t_sales_store_order` | 店铺订单主表 |
| `t_sales_store_order_line` | 订单明细 |
| `C_sku_platform_map` | 平台 SKU → 库内 SKU（发货匹配；归属仓储域，用 `C_`） |

**仓储（9 张，`C_` 前缀）**

| 表 | 说明 |
| --- | --- |
| `C_sku` | 我的 SKU |
| `C_bin_location` | 库位主数据（按仓库） |
| `C_inventory` | 库存余额：`CustomerId + WarehouseId + SkuId + BinLocationId → Qty` |
| `C_inbound_notice` | 入库预报主表 |
| `C_inbound_box` | 入库箱（箱号/箱唛） |
| `C_inbound_box_line` | 箱内 SKU 行 |
| `C_parcel` | 我的包裹 |
| `C_parcel_item` | 包裹明细 |

**延后（相对 v0.1 / 原完整版）**

| 原概念 | 处理 |
| --- | --- |
| `t_sales_store_token` | 合并进 `t_sales_store` |
| `t_sales_store_share` / 拆单 / 录单表 | 延后 |
| `C_sku_bundle`（组合 SKU） | 延后 |
| `C_stock_movement`（库存流水） | 延后 |
| `C_inbound_receipt_log`（收货日志） | 延后，状态字段够用 |

### 0.3 轻量版核心流程（够用即可）

```mermaid
flowchart LR
  SKU["我的 SKU<br/>C_sku"] --> MAP["平台映射<br/>C_sku_platform_map"]
  MAP --> PSO["店铺订单"]
  BIN["库位<br/>C_bin_location"]
  IBN["入库预报<br/>C_inbound_notice"] --> BOX["入库箱<br/>C_inbound_box"]
  BOX --> INV["库存<br/>C_inventory"]
  BIN --> INV
  PAR["我的包裹<br/>C_parcel"] -->|"上架到库位"| INV
  PSO -->|"匹配库存"| INV
  PSO -->|"生成小包单"| ORD["t_order"]
```

1. **我的 SKU**：维护库内编码 + 尺重；绑平台 SKU（`C_sku_platform_map`）。  
2. **库位**：按仓库维护 `C_bin_location`；库存按 **库位** 记数量。  
3. **入库预报**：主表 + **箱号**（`C_inbound_box`）+ 箱内 SKU（`C_inbound_box_line`）；收货上架时写入 `C_inventory`。  
4. **我的库存**：按 SKU 汇总展示，可展开 **各库位明细**；支持 **换库位**（不调 FIFO、不记流水）。  
5. **我的包裹**：预报快递单号；到仓后上架到指定库位。  
6. **店铺订单**：库存匹配时按库位扣减 `C_inventory.Qty` 并建 `t_order`。

### 0.4 轻量版接口原则

- 每个页面 **列表 + 详情 + 保存 + 删除**；统计合并为 `summary`。  
- 仓储一个 `WarehouseService`（`/warehouse/*`）。  
- **保留**：库位列表、入库箱结构、换库位、上架指定库位。  
- **不做**：库存流水、FIFO 批次、冻结量、组合 SKU、平台库存回写。

### 0.5 轻量版实施顺序

| 阶段 | 交付 | 说明 | 状态 |
| --- | --- | --- | --- |
| **Step 1 表** | SQL + SqlSugar 实体 | `sql/migrate_warehouse_module.sql` + `Oms.Domain` 实体 | **已完成** |
| **Step 2 接口** | `WarehouseService` + 店铺 Service | `/warehouse/*`、`/order/platform-store*` | **已完成** |
| **Step 3 页面** | 前端 6 页 + 路由 + RBAC 菜单 | `views/warehouse/*`、`order/platformStore*` | **已完成** |

**Step 2 交付物（2026-07-11）**

| 层级 | 路径 |
| --- | --- |
| Repository | `Oms.Domain/WarehouseAggregate/Repositories`、`Oms.SqlSugarCore/Warehouse/`；`OrdersAggregate/Repositories`（店铺） |
| DTO | `Oms.Application/Dtos/Warehouse/`、`Dtos/PlatformStore/` |
| Service | `Services/Warehouse/WarehouseService`；`PlatformStoreService`；`PlatformStoreOrderService` |

**M1～M4 业务分期**

| 阶段 | 交付 | 说明 |
| --- | --- | --- |
| **M1** | `C_sku` + `C_bin_location` + `C_inventory` + 入库预报（含箱） | 5 张 `C_*` 表 + 约 12 接口 |
| **M2** | `C_parcel` + 库存列表/换库位 | +2 张表 + 2 页 |
| **M3** | 店铺授权 + 店铺订单 | +3 表 + 2 Service + 2 页 |
| **M4** | 库存匹配 → `t_order` | 打通订单 | **已完成** |

**M4 交付物（2026-07-11）**

| 项 | 说明 |
| --- | --- |
| `PlatformStoreOrderParcelBuilder` | 店铺订单 → `OrderParcelCreateInput` |
| `POST /order/platform-store-order/match-inventory` | 扣库存 → 创建小包 → 回写 `LinkedOrderId` |
| `POST /order/platform-store-order/batch-match-inventory` | 批量匹配 |
| 前端 | 销售产品选择、关联服务单号、批量匹配按钮 |

---

## 1　导读

### 1.1 这份文档解决什么问题？

将 WMS 中与客户履约相关的 **6 个页面** 迁入 OMS，拆为两块：

| 归属 | 页面 | 原 WMS 路由（参考） |
| --- | --- | --- |
| **订单模块**（扩展现有 §4） | 店铺授权、店铺订单 | `/order/platform/shop`、`/order/platform/shop-orderv2` |
| **仓储模块**（本文新建 §9） | 我的包裹、我的库存、我的 SKU、入库预报 | `/wms/package/package`、`/wms/stock/myinventory2`、`/wms/stock/merchants`、`/wms/stock/warehousingorder` |

设计原则：

1. **表名、字段名、接口路径全部重新命名**，不沿用 WMS 的 `vip_*` / `wms_*` 命名。
2. **业务逻辑对齐 WMS**，在 OMS 会话隔离、分页规范、审计字段上对齐现有 OMS 约定。
3. **与现有 OMS 模块边界清晰**：小包订单（`t_order`）与仓储库存（`C_*`）分离；店铺订单通过 `C_sku_platform_map` 匹配库存。

### 1.2 与 OMS 其它模块的关系

```mermaid
flowchart TB
  subgraph Order["订单模块 §4"]
    PS["店铺授权<br/>t_sales_store"]
    PSO["店铺订单<br/>t_sales_store_order"]
    PO["小包订单<br/>t_order"]
  end
  subgraph Warehouse["仓储模块 C_*"]
    BIN["库位<br/>C_bin_location"]
    PAR["我的包裹<br/>C_parcel"]
    SKU["我的 SKU<br/>C_sku"]
    INV["库存<br/>C_inventory"]
    IBN["入库预报<br/>C_inbound_notice"]
  end
  subgraph System["系统主数据 §8"]
    WA["仓库地址<br/>t_warehouse_address"]
  end
  subgraph Operation["操作模块 §6"]
    INB["入库扫描<br/>t_inbound_record"]
    OUT["出库扫描<br/>t_outbound_record"]
  end

  PS --> PSO
  PSO -->|"SKU 映射 + 库存匹配"| SKU
  PSO -->|"一键发货 / 录单"| PO
  PAR --> INV
  IBN --> INV
  BIN --> INV
  SKU --> INV
  WA --> PAR
  WA --> IBN
  INB -.->|"小包运单收货"| PO
  OUT -.->|"小包运单出库"| PO
```

| 边界 | 说明 |
| --- | --- |
| `t_order` vs `t_sales_store_order` | 前者为 OMS 小包物流订单；后者为电商平台拉取的 **店铺履约单**，二者通过 `LinkedOrderId` 可选关联 |
| `t_warehouse_address` | 仓储业务统一引用系统主数据仓库（`WarehouseId` → `t_warehouse_address.Id`），**不新建**客户侧仓库表 |
| `t_inbound_record` / `t_outbound_record` | 面向 **小包运单**（`WaybillNo`）的仓内扫描；与仓储模块的 **SKU 入库预报 / 包裹到仓** 是不同业务线，表不合并 |
| 客户隔离 | 全模块 `CustomerId` → `t_customer.Id`；规则同 OMS §3.3.5 / §4.4.0 |

### 1.3 建议阅读路径

| 角色 | 路径 |
| --- | --- |
| 产品 / 测试 | **§2 页面与菜单** → **§5 主流程** → **§8 枚举** |
| 后端 / DBA | **§3 表结构** → **§4 接口** → **§7 WMS 对照** |
| 前端 | **§2** → **§4** → `docs/前端页面设计规范.md` |

---

## 2　页面、路由与权限

### 2.1 菜单结构

```
订单（已有 /order）
├── …（查价、下单、我的订单等）
├── 店铺授权          /order/platformStore
└── 店铺订单          /order/platformStoreOrder

仓储（新建 /warehouse）
├── 我的包裹          /warehouse/parcel
├── 我的库存          /warehouse/inventory
├── 我的 SKU          /warehouse/sku
└── 入库预报          /warehouse/inboundNotice
```

### 2.2 前端路由（`src/router/routes/newModules/`）

**订单模块扩展**（`order.ts` 追加 children）：

| path | name | component | permission |
| --- | --- | --- | --- |
| `platformStore` | `OrderPlatformStore` | `views/order/platformStore/index.vue` | `Order.PlatformStore.Query` |
| `platformStoreOrder` | `OrderPlatformStoreOrder` | `views/order/platformStoreOrder/index.vue` | `Order.PlatformStoreOrder.Query` |

**仓储模块新建**（`warehouse.ts`）：

| path | name | component | permission |
| --- | --- | --- | --- |
| `parcel` | `WarehouseParcel` | `views/warehouse/parcel/index.vue` | `Warehouse.Parcel.Query` |
| `inventory` | `WarehouseInventory` | `views/warehouse/inventory/index.vue` | `Warehouse.Inventory.Query` |
| `sku` | `WarehouseSku` | `views/warehouse/sku/index.vue` | `Warehouse.Sku.Query` |
| `inboundNotice` | `WarehouseInboundNotice` | `views/warehouse/inboundNotice/index.vue` | `Warehouse.InboundNotice.Query` |

列表页布局遵循 `docs/前端页面设计规范.md`：`xxx-container`、`table-toolbar`、分页右上角、`PaginationPro` 默认 30 条。

### 2.3 RBAC 权限码

格式：`{Module}.{Resource}.{Action}`（与 RBAC §5.2 一致）。

#### 2.3.1 订单 — 店铺域

| 权限码 | 说明 |
| --- | --- |
| `Order.PlatformStore` | 店铺授权模块 |
| `Order.PlatformStore.Query` | 列表 / 详情 |
| `Order.PlatformStore.Create` | 新增授权 / OAuth 回调落库 |
| `Order.PlatformStore.Update` | 改名、自动发货开关 |
| `Order.PlatformStore.Delete` | 删除店铺 |
| `Order.PlatformStoreOrder` | 店铺订单模块 |
| `Order.PlatformStoreOrder.Query` | 列表 / 详情 / 状态统计 |
| `Order.PlatformStoreOrder.Sync` | 同步平台状态 |
| `Order.PlatformStoreOrder.Rts` | 准备发货（Ready To Ship） |
| `Order.PlatformStoreOrder.AutoMatch` | 库存匹配生成小包订单 |
| `Order.PlatformStoreOrder.Suspend` | 搁置 / 取消搁置 |
| `Order.PlatformStoreOrder.Delete` | 删除 |
| `Order.PlatformStoreOrder.Export` | 导出 |
| `Order.PlatformStoreOrder.Label` | 获取 / 打印面单 |
| `Order.PlatformStoreOrder.Tag` | 自定义标签 |

#### 2.3.2 仓储域 **〔轻量：每资源 3 个权限即可〕**

| 权限码 | 说明 |
| --- | --- |
| `Warehouse.Sku.Query` / `.Save` / `.Delete` | 我的 SKU |
| `Warehouse.InboundNotice.Query` / `.Save` / `.Delete` | 入库预报 |
| `Warehouse.Parcel.Query` / `.Save` / `.Delete` | 我的包裹 |
| `Warehouse.Inventory.Query` / `.Relocate` | 我的库存（查询 + 换库位） |
| `Warehouse.BinLocation.Query` / `.Save` | 库位维护（管理端/仓库端） |

**〔延后〕**：ApplyStorage、Putaway、Relocate、Adjust、Import、Mapping、Print 等细粒度 Action — 首期 Save 接口内覆盖。

### 2.4 后端 Service 与路由前缀 **〔轻量〕**

| 业务域 | Service 类 | 路由前缀 |
| --- | --- | --- |
| 店铺授权 | `PlatformStoreService` | `/order/platform-store/*` |
| 店铺订单 | `PlatformStoreOrderService` | `/order/platform-store-order/*` |
| 仓储（合并） | **`WarehouseService`** | `/warehouse/*` |

> 轻量版仓储 **一个 Service** 即可，按子路径分 SKU / 入库 / 包裹 / 库存。

---

## 3　数据表结构设计

> 遵循 OMS §3.1 公共规范。  
> **轻量版以 §0.2 为准**；下列分节含完整版字段，标注 **〔延后〕** 的表/字段在轻量版中不建。

### 3.0 轻量版表结构（v0.3 推荐落地）

> **仓储表一律 `C_` 前缀**；字段仍用 OMS 驼峰（`PascalCase`）；必备审计字段见 §3.1 公共规范。

#### 3.0.1 `t_sales_store`（店铺，含 Token）

在 §3.1.1 基础上 **合并** Token，新增：`AccessToken`、`RefreshToken`、`TokenExtraJson`（加密，列表脱敏）。

#### 3.0.2 `C_sku`（我的 SKU）

| 字段 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| CustomerId | BIGINT | 是 | 客户 |
| SkuCode | VARCHAR(64) | 是 | 库内编码 |
| SkuName | VARCHAR(256) | 是 | 名称 |
| SkuImageUrl | VARCHAR(512) | 否 | 图片 |
| WeightG / LengthCm / WidthCm / HeightCm | DECIMAL | 否 | 尺重 |
| Remark | VARCHAR(512) | 否 | 备注 |
| 审计字段 | — | 是 | |

**索引**：`uk_c_sku_code` (`CustomerId`, `SkuCode`)。

#### 3.0.3 `C_bin_location`（库位）

| 字段 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| WarehouseId | BIGINT | 是 | → `t_warehouse_address.Id` |
| BinCode | VARCHAR(32) | 是 | 库位编码，如 `A-01-02` |
| BinName | VARCHAR(64) | 否 | 展示名称 |
| ZoneCode | VARCHAR(32) | 否 | 库区 |
| IsEnabled | TINYINT | 是 | 是否启用，默认 1 |
| Remark | VARCHAR(512) | 否 | 备注 |
| 审计字段 | — | 是 | |

**索引**：`uk_c_bin_wh_code` (`WarehouseId`, `BinCode`)。

> 库位为 **仓库级主数据**（不按客户拆分）；库存余额按客户 + 库位区分。

#### 3.0.4 `C_inventory`（库存余额）

| 字段 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| CustomerId | BIGINT | 是 | 客户 |
| WarehouseId | BIGINT | 是 | 仓库 |
| SkuId | BIGINT | 是 | → `C_sku.Id` |
| BinLocationId | BIGINT | 是 | → `C_bin_location.Id` |
| Qty | INT | 是 | 可用数量（匹配时直接扣减） |
| 审计字段 | — | 是 | |

**唯一索引**：`uk_c_inventory` (`CustomerId`, `WarehouseId`, `SkuId`, `BinLocationId`)。

> 「我的库存」列表：按 `SkuId` 聚合 `SUM(Qty)`；详情/换库位：按 `BinLocationId` 展开。  
> **不做**冻结量、FIFO 批次、库存流水表。

#### 3.0.5 `C_inbound_notice` + `C_inbound_box` + `C_inbound_box_line`（入库预报，含箱号）

**主表 `C_inbound_notice`**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| CustomerId | BIGINT | 客户 |
| WarehouseId | BIGINT | 仓库 |
| NoticeNo | VARCHAR(32) | `IN` + 雪花 |
| MarkReference | VARCHAR(64) | 唛头 |
| InboundType | VARCHAR(16) | `normal` / `return` |
| ReceiptStatus | VARCHAR(16) | `forecasted` → `received` → `completed` |
| ExpectedArrivalTime | DATETIME | 可选 |
| ActualArrivalTime | DATETIME | 收货时写入 |
| Remark | VARCHAR(512) | |

**箱表 `C_inbound_box`**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| InboundNoticeId | BIGINT | 主表 |
| BoxSeqNo | VARCHAR(16) | 箱序号 |
| MarkBoxNo | VARCHAR(64) | **箱唛号/箱号** |
| WeightG | DECIMAL(10,2) | 箱重(g)，可选 |
| LengthCm / WidthCm / HeightCm | DECIMAL | 箱尺寸，可选 |
| IsReceived | TINYINT | 是否已收货 |

**箱内 SKU 行 `C_inbound_box_line`**

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| InboundBoxId | BIGINT | 箱 |
| SkuId | BIGINT | → `C_sku.Id` |
| SkuCode | VARCHAR(64) | 冗余编码 |
| PlannedQty | INT | 计划数量 |
| ReceivedQty | INT | 实收数量 |
| BinLocationId | BIGINT | 上架库位（收货确认时填入） |

**收货上架逻辑**：`confirm-receive` 按箱清点 → 按行 `ReceivedQty` + `BinLocationId` **累加** `C_inventory.Qty` → 主表 `completed`。

#### 3.0.6 `C_parcel` + `C_parcel_item`（我的包裹）

**主表**：`TrackingNo`、`CarrierName`、`WarehouseId`、`LifecycleStatus`（`inTransit` / `arrived` / `stored`）、`ArrivalTime`、`Remark`。

**明细**：`ProductName`、`Quantity`、`SkuId`（上架时关联）、`BinLocationId`（上架库位，可选）。

#### 3.0.7 `C_sku_platform_map`（平台 SKU 映射）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| CustomerId | BIGINT | 客户 |
| StoreId | BIGINT | → `t_sales_store.Id` |
| PlatformSku | VARCHAR(128) | 平台 listing SKU |
| SkuId | BIGINT | → `C_sku.Id` |
| SkuCode | VARCHAR(64) | 冗余 |

**索引**：`uk_c_sku_map` (`StoreId`, `PlatformSku`)。

#### 3.0.8 `t_sales_store_order`（店铺订单，字段精简）

保留核心字段 + 明细行；`MappedSkuId` 指向 `C_sku.Id`。拆单/录单表延后。

---

### 3.1 订单模块 — 店铺授权

#### 3.1.1 销售店铺表 `t_sales_store`

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| CustomerId | BIGINT | 是 | 客户 Id |
| PlatformCode | VARCHAR(32) | 是 | 平台：`lazada` / `shopee` / `tiktok` / `temu` / `manual` |
| StoreNickname | VARCHAR(128) | 是 | 店铺昵称（用户自定义） |
| PlatformStoreId | VARCHAR(64) | 否 | 平台侧店铺 Id |
| PlatformAccount | VARCHAR(128) | 否 | 平台账号 |
| SiteCountry | VARCHAR(8) | 否 | 开户站点国家码 |
| SellerId | VARCHAR(64) | 否 | 平台卖家 Id |
| AuthStatus | VARCHAR(16) | 是 | `active` / `expired` / `revoked` |
| AuthTime | DATETIME | 否 | 授权时间 |
| TokenExpireTime | DATETIME | 否 | Access Token 过期 |
| RefreshExpireTime | DATETIME | 否 | Refresh Token 过期 |
| IsAutoFulfill | TINYINT | 是 | 是否自动发货，默认 0 |
| SortOrder | INT | 否 | 排序 |
| Remark | VARCHAR(512) | 否 | 备注 |
| IsDeleted / 审计字段 | — | 是 | 见 §3.1 公共规范 |

**索引**：`idx_sales_store_customer` (`CustomerId`, `IsDeleted`)；`uk_sales_store_platform` (`CustomerId`, `PlatformCode`, `PlatformStoreId`) 唯一（`PlatformStoreId` 为空时 manual 店铺允许多条）。

#### 3.1.2 店铺授权凭证表 `t_sales_store_token` **〔轻量：合并至 3.0.1，不单独建表〕**

> 敏感字段加密存储；列表接口 **不返回** `AccessToken` / `RefreshToken` 明文。

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| StoreId | BIGINT | 是 | → `t_sales_store.Id` |
| AccessToken | VARCHAR(2048) | 否 | 加密 |
| RefreshToken | VARCHAR(2048) | 否 | 加密 |
| TokenType | VARCHAR(32) | 否 | 默认 `Bearer` |
| Scope | VARCHAR(512) | 否 | 授权范围 |
| ExtraJson | JSON | 否 | 平台扩展（如 Lazada 多站点 userId） |
| IsDeleted / 审计字段 | — | 是 | |

#### 3.1.3 店铺共享表 `t_sales_store_share` **〔延后〕**

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| StoreId | BIGINT | 是 | 主店铺 |
| SharedCustomerId | BIGINT | 是 | 被共享的子客户 Id |
| IsDeleted / 审计字段 | — | 是 | |

---

### 3.2 订单模块 — 店铺订单

#### 3.2.1 店铺订单表 `t_sales_store_order`

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| CustomerId | BIGINT | 是 | 客户 Id |
| StoreId | BIGINT | 是 | → `t_sales_store.Id` |
| PlatformCode | VARCHAR(32) | 是 | 冗余平台码 |
| PlatformOrderNo | VARCHAR(64) | 是 | 平台订单号 |
| OrderCountry | VARCHAR(8) | 否 | 订单国家 |
| ItemCount | INT | 否 | 商品行数 |
| TotalAmount | DECIMAL(18,4) | 否 | 订单总额 |
| Currency | VARCHAR(8) | 否 | 币种 |
| PaymentMethod | VARCHAR(64) | 否 | 付款方式 |
| PlatformOrderTime | DATETIME | 否 | 平台下单时间 |
| PlatformPayTime | DATETIME | 否 | 平台付款时间 |
| FulfillStatus | VARCHAR(32) | 是 | 履约状态，见 §8.1 |
| PlatformStatus | VARCHAR(64) | 否 | 平台原始状态码 |
| PlatformStatusLabel | VARCHAR(128) | 否 | 平台状态展示文案 |
| ShippingLabelNo | VARCHAR(64) | 否 | 面单号 |
| ShippingLabelUrl | VARCHAR(512) | 否 | 面单文件 URL |
| IsMultiLabel | TINYINT | 是 | 是否多面单/拆单 |
| DeliveryMethod | VARCHAR(64) | 否 | 运输方式 code |
| DeliveryMethodLabel | VARCHAR(128) | 否 | 运输方式展示 |
| DeliveryStatus | VARCHAR(32) | 否 | 物流子状态 |
| ShippingCarrier | VARCHAR(64) | 否 | 物流承运商 |
| PickupType | VARCHAR(32) | 否 | 取件类型：`pickup` / `dropoff` |
| CustomTags | VARCHAR(512) | 否 | 用户自定义标签，逗号分隔 |
| IsSuspended | TINYINT | 是 | 是否搁置 |
| PresaleDays | INT | 否 | 预售天数 |
| BuyerRemark | VARCHAR(1024) | 否 | 买家备注 |
| SellerPickRemark | VARCHAR(1024) | 否 | 卖家拣货备注 |
| SellerPickRemarkTime | DATETIME | 否 | 拣货备注时间 |
| WarehouseId | BIGINT | 否 | 发货仓库 → `t_warehouse_address.Id` |
| LinkedOrderId | BIGINT | 否 | 关联 OMS 小包订单 `t_order.Id` |
| LastSyncTime | DATETIME | 否 | 最近同步时间 |
| StatusChangedTime | DATETIME | 否 | 状态变更时间 |
| SystemShipTime | DATETIME | 否 | 系统发货时间 |
| SystemLabelPrintTime | DATETIME | 否 | 系统打印面单时间 |
| SystemPushTime | DATETIME | 否 | 推送到出库时间 |
| IsDeleted / 审计字段 | — | 是 | |

**索引**：`uk_store_order_no` (`StoreId`, `PlatformOrderNo`)；`idx_store_order_customer_status` (`CustomerId`, `FulfillStatus`, `PlatformOrderTime`)。

#### 3.2.2 店铺订单明细表 `t_sales_store_order_line`

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| StoreOrderId | BIGINT | 是 | → `t_sales_store_order.Id` |
| PlatformLineId | VARCHAR(64) | 否 | 平台行 Id / itemId |
| PlatformSku | VARCHAR(128) | 否 | 平台 SKU |
| ProductName | VARCHAR(512) | 否 | 商品名称 |
| ProductImageUrl | VARCHAR(512) | 否 | 商品图 |
| ProductUrl | VARCHAR(512) | 否 | 商品链接 |
| VariantText | VARCHAR(256) | 否 | 规格属性 |
| UnitPrice | DECIMAL(18,4) | 否 | 单价 |
| Quantity | INT | 是 | 数量 |
| Currency | VARCHAR(8) | 否 | 币种 |
| IsShipExcluded | TINYINT | 是 | 是否拒绝发货 |
| MappedSkuId | BIGINT | 否 | 映射的仓储 SKU → `C_sku.Id` |
| IsDeleted / 审计字段 | — | 是 | |

#### 3.2.3 店铺订单快速录单表 `t_sales_store_order_draft` **〔延后〕**

#### 3.2.4 店铺订单拆单表 `t_sales_store_order_split` **〔延后〕**

---

### 3.3 仓储模块 — 我的包裹

#### 3.3.1 客户包裹表 `C_parcel`

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| CustomerId | BIGINT | 是 | 客户 Id |
| WarehouseId | BIGINT | 是 | → `t_warehouse_address.Id` |
| TrackingNo | VARCHAR(64) | 是 | 快递单号 |
| CarrierName | VARCHAR(64) | 否 | 快递公司 |
| SourcePlatform | VARCHAR(32) | 否 | 来源平台（淘宝、拼多多等） |
| ParcelCategory | VARCHAR(16) | 是 | `single` 一票一单 / `multi` 一票多单 / `unclaimed` 待认领 / `stock` 库存件 |
| LifecycleStatus | VARCHAR(16) | 是 | 见 §8.2：`inTransit` / `arrived` / `unclaimed` / `expired` |
| PurchaseOrderNo | VARCHAR(64) | 否 | 采购订单号（与 OMS 小包无关） |
| BizScene | VARCHAR(16) | 否 | 业务场景，如 `consolidation` 集运 |
| ImageUrl | VARCHAR(512) | 否 | 包裹图片 |
| LengthCm | DECIMAL(10,2) | 否 | 长(cm) |
| WidthCm | DECIMAL(10,2) | 否 | 宽(cm) |
| HeightCm | DECIMAL(10,2) | 否 | 高(cm) |
| VolumeCbm | DECIMAL(12,4) | 否 | 体积 |
| WeightKg | DECIMAL(10,3) | 否 | 重量(kg) |
| ArrivalTime | DATETIME | 否 | 到仓时间 |
| LinkedSkuId | BIGINT | 否 | 关联仓储 SKU |
| Remark | VARCHAR(512) | 否 | 备注 |
| IsDeleted / 审计字段 | — | 是 | |

**索引**：`uk_c_parcel_tracking` (`CustomerId`, `TrackingNo`, `WarehouseId`)；`idx_c_parcel_status` (`CustomerId`, `LifecycleStatus`)。

#### 3.3.2 包裹明细表 `C_parcel_item`

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| ParcelId | BIGINT | 是 | → `C_parcel.Id` |
| ProductName | VARCHAR(512) | 否 | 商品名称 |
| ProductCategory | VARCHAR(64) | 否 | 商品分类 |
| Quantity | INT | 是 | 数量 |
| ImageUrl | VARCHAR(512) | 否 | 图片 |
| AttributeText | VARCHAR(256) | 否 | 属性 |
| SkuId | BIGINT | 否 | 库内 SKU（上架时关联） |
| SkuCode | VARCHAR(64) | 否 | 冗余编码 |
| BinLocationId | BIGINT | 否 | 上架库位 |
| IsDeleted / 审计字段 | — | 是 | |

---

### 3.4 仓储模块 — 我的 SKU

#### 3.4.1 仓储 SKU 主表 `C_sku`

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| CustomerId | BIGINT | 是 | 客户 Id |
| SkuCode | VARCHAR(64) | 是 | 库内 SKU 编码 |
| SkuName | VARCHAR(256) | 是 | SKU 名称 |
| SkuImageUrl | VARCHAR(512) | 否 | 图片 |
| CategoryCode | VARCHAR(64) | 否 | 分类 |
| IsBundle | TINYINT | 是 | 是否组合 SKU |
| WeightG | DECIMAL(10,2) | 否 | 重量(g) |
| LengthCm | DECIMAL(10,2) | 否 | 长(cm) |
| WidthCm | DECIMAL(10,2) | 否 | 宽(cm) |
| HeightCm | DECIMAL(10,2) | 否 | 高(cm) |
| ReferencePrice | DECIMAL(18,4) | 否 | 参考价 |
| Currency | VARCHAR(8) | 否 | 币种 |
| Remark | VARCHAR(512) | 否 | 备注 |
| IsDeleted / 审计字段 | — | 是 | |

**索引**：`uk_c_sku_code` (`CustomerId`, `SkuCode`)。

#### 3.4.2 组合 SKU 子项表 `C_sku_bundle_item` **〔延后〕**

#### 3.4.3 平台 SKU 映射表 `C_sku_platform_map`

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| CustomerId | BIGINT | 是 | 客户 Id |
| StoreId | BIGINT | 是 | → `t_sales_store.Id` |
| PlatformSku | VARCHAR(128) | 是 | 平台 listing SKU |
| PlatformProductId | VARCHAR(64) | 否 | 平台商品 Id |
| SkuId | BIGINT | 是 | → `C_sku.Id` |
| SkuCode | VARCHAR(64) | 是 | 冗余库内编码 |
| IsDeleted / 审计字段 | — | 是 | |

**索引**：`uk_c_sku_map` (`StoreId`, `PlatformSku`)。

---

### 3.5 仓储模块 — 我的库存

#### 3.5.1 库存余额表 `C_inventory`（见 §3.0.4）

#### 3.5.2 库位表 `C_bin_location`（见 §3.0.3）

#### 3.5.3 库存流水表 `C_stock_movement` **〔延后〕**

---

### 3.6 仓储模块 — 入库预报

#### 3.6.1 入库预报主表 `C_inbound_notice`

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| CustomerId | BIGINT | 是 | 客户 Id |
| WarehouseId | BIGINT | 是 | 仓库 |
| NoticeNo | VARCHAR(32) | 是 | 入库单号，规则 `IN` + 雪花 Id |
| MarkReference | VARCHAR(64) | 否 | 唛头参考号 |
| InboundType | VARCHAR(16) | 是 | `normal` 普通 / `return` 退货 |
| ReceiptStatus | VARCHAR(16) | 是 | 见 §8.4 |
| FirstMileCarrier | VARCHAR(64) | 否 | 头程物流 |
| FirstMileTrackingNo | VARCHAR(64) | 否 | 头程单号 |
| ExpectedArrivalTime | DATETIME | 否 | 预计到货 |
| ActualArrivalTime | DATETIME | 否 | 实际到货 |
| IsException | TINYINT | 是 | 是否异常件 |
| ExceptionNote | VARCHAR(1024) | 否 | 异常说明 |
| ExceptionImageUrls | VARCHAR(2048) | 否 | 异常图片，分号分隔 |
| CustomerFeedback | TINYINT | 否 | 客户是否已确认异常 |
| Remark | VARCHAR(512) | 否 | 备注 |
| IsDeleted / 审计字段 | — | 是 | |

**索引**：`uk_c_inbound_notice_no` (`NoticeNo`)；`idx_c_inbound_customer_status` (`CustomerId`, `ReceiptStatus`)。

#### 3.6.2 入库箱表 `C_inbound_box`（见 §3.0.5）

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| InboundNoticeId | BIGINT | 是 | → `C_inbound_notice.Id` |
| BoxSeqNo | VARCHAR(16) | 是 | 箱序号 |
| MarkBoxNo | VARCHAR(64) | 否 | 箱唛号/箱号 |
| WeightG | DECIMAL(10,2) | 否 | 箱重(g) |
| LengthCm / WidthCm / HeightCm | DECIMAL(10,2) | 否 | 箱尺寸 |
| IsReceived | TINYINT | 是 | 是否已收货 |
| 审计字段 | — | 是 | |

#### 3.6.3 入库箱 SKU 行表 `C_inbound_box_line`（见 §3.0.5）

| 字段名 | 类型 | 非空 | 说明 |
| --- | --- | --- | --- |
| Id | BIGINT | 是 | 主键 |
| InboundBoxId | BIGINT | 是 | → `C_inbound_box.Id` |
| SkuId | BIGINT | 是 | → `C_sku.Id` |
| SkuCode | VARCHAR(64) | 是 | 冗余编码 |
| PlannedQty | INT | 是 | 计划入库数量 |
| ReceivedQty | INT | 否 | 实收数量 |
| BinLocationId | BIGINT | 否 | 上架库位（收货时填） |
| 审计字段 | — | 是 | |

#### 3.6.4 入库收货日志表 `C_inbound_receipt_log` **〔延后〕**

---

## 4　接口设计

> 分页：`{ items, total }`；默认 `pageSize=30`。客户隔离同 §6。  
> **轻量版接口以 §4.0 为准**；§4.1～§4.6 为完整版参考。

### 4.0 轻量版接口清单（推荐）

#### 仓储 `WarehouseService` — 共 **20 个**

| 页面 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| SKU | POST | `/warehouse/sku/list` | 列表 |
| SKU | GET | `/warehouse/sku/detail` | 详情 |
| SKU | POST | `/warehouse/sku/save` | 新增/编辑 |
| SKU | POST | `/warehouse/sku/delete` | 删除 |
| SKU | POST | `/warehouse/sku/bind-mapping` | 绑定平台 SKU |
| 库位 | POST | `/warehouse/bin-location/list` | 按仓库查库位 |
| 库位 | POST | `/warehouse/bin-location/save` | 新增/编辑库位 |
| 入库 | POST | `/warehouse/inbound/list` | 列表 |
| 入库 | GET | `/warehouse/inbound/detail` | 详情含 `boxes[].lines[]` |
| 入库 | POST | `/warehouse/inbound/save` | 新增/编辑（含箱号，仅 forecasted） |
| 入库 | POST | `/warehouse/inbound/delete` | 删除 |
| 入库 | POST | `/warehouse/inbound/confirm-receive` | 按箱收货上架 → 写 `C_inventory` |
| 入库 | GET | `/warehouse/inbound/summary` | 状态 Tab 数量 |
| 包裹 | POST | `/warehouse/parcel/list` | 列表 |
| 包裹 | POST | `/warehouse/parcel/save` | 新增/编辑 |
| 包裹 | POST | `/warehouse/parcel/delete` | 删除 |
| 包裹 | POST | `/warehouse/parcel/putaway` | 到仓上架（指定 `binLocationId`） |
| 库存 | POST | `/warehouse/inventory/list` | 按 SKU 聚合列表 |
| 库存 | GET | `/warehouse/inventory/bin-detail` | 某 SKU 各库位明细 |
| 库存 | POST | `/warehouse/inventory/relocate` | 换库位（源库位 → 目标库位） |

#### 店铺 — 共 **14 个**（首期可再砍）

| 页面 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| 授权 | POST | `/order/platform-store/list` | 列表 |
| 授权 | POST | `/order/platform-store/auth-url` | OAuth |
| 授权 | POST | `/order/platform-store/save` | 改名等 |
| 授权 | POST | `/order/platform-store/delete` | 删除 |
| 订单 | POST | `/order/platform-store-order/list` | 列表 |
| 订单 | GET | `/order/platform-store-order/detail` | 详情 |
| 订单 | GET | `/order/platform-store-order/summary` | 状态统计（合并多个 count 接口） |
| 订单 | POST | `/order/platform-store-order/sync-status` | 同步 |
| 订单 | POST | `/order/platform-store-order/ready-to-ship` | RTS |
| 订单 | POST | `/order/platform-store-order/match-inventory` | 库存匹配 → `t_order` |
| 订单 | POST | `/order/platform-store-order/fetch-label` | 面单 |
| 订单 | POST | `/order/platform-store-order/toggle-suspend` | 搁置 |
| 订单 | POST | `/order/platform-store-order/delete` | 删除 |

**入库 `save` 请求（含箱号）**

```json
{
  "id": 0,
  "warehouseId": 1,
  "markReference": "MARK-001",
  "inboundType": "normal",
  "remark": "",
  "boxes": [
    {
      "boxSeqNo": "1",
      "markBoxNo": "BOX-001",
      "weightG": 1200,
      "lengthCm": 40,
      "widthCm": 30,
      "heightCm": 20,
      "lines": [
        { "skuId": 1001, "skuCode": "SKU-A001", "plannedQty": 50 }
      ]
    }
  ]
}
```

**`confirm-receive` 请求要点**：按箱提交实收数量及每行 `binLocationId`，服务端 upsert `C_inventory`。

**库存匹配**：按 `C_sku_platform_map` 解析 SKU，从指定库位（或默认库位）扣减 `C_inventory.Qty`；不足则失败；不记流水。

---

### 4.1 订单 — 店铺授权 `/order/platform-store/*`（完整版参考）

| 接口 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| 店铺列表 | POST | `/order/platform-store/list` | 分页；筛 `platformCode`、`storeNickname`、授权到期 |
| 授权 URL | POST | `/order/platform-store/auth-url` | 获取 OAuth 跳转地址 |
| OAuth 回调落库 | POST | `/order/platform-store/auth-callback` | 各平台 token 写入 `t_sales_store_token` |
| 店铺详情 | GET | `/order/platform-store/detail` | `id` |
| 改名 | POST | `/order/platform-store/rename` | `id`, `storeNickname` |
| 删除 | POST | `/order/platform-store/delete` | `ids[]` |
| 自动发货开关 | POST | `/order/platform-store/toggle-auto-fulfill` | `ids[]`, `enabled` |
| 到期提醒统计 | GET | `/order/platform-store/expiration-stats` | 即将过期 / 已过期数量 |
| 状态统计 | POST | `/order/platform-store/dashboard-stats` | 按平台汇总店铺与订单数 |

**列表请求示例**

```json
{
  "page": 1,
  "pageSize": 30,
  "platformCode": "shopee",
  "storeNickname": "",
  "expirationFilter": "normal"
}
```

`expirationFilter`：`normal` / `within7days` / `expired`。

**列表响应 `items[]` 关键字段**：`id`, `platformCode`, `platformName`, `storeNickname`, `platformAccount`, `siteCountry`, `authStatus`, `authTime`, `tokenExpireTime`, `isAutoFulfill`, `createTime`。

**平台子接口**（建议内聚于 `PlatformStoreService`，路径带平台段）：

| 平台 | 路径前缀 |
| --- | --- |
| Shopee | `/order/platform-store/shopee/*` |
| Lazada | `/order/platform-store/lazada/*` |
| TikTok | `/order/platform-store/tiktok/*` |

---

### 4.2 订单 — 店铺订单 `/order/platform-store-order/*`

| 接口 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| 订单列表 | POST | `/order/platform-store-order/list` | 分页 + 多 Tab 状态 |
| 状态统计 | POST | `/order/platform-store-order/status-count` | 各履约状态数量 |
| 待发货统计 | GET | `/order/platform-store-order/pending-ship-count` | |
| 取消单统计 | GET | `/order/platform-store-order/canceled-count` | |
| 订单详情 | GET | `/order/platform-store-order/detail` | 含 `lines[]`、拆单、草稿 |
| 准备发货 RTS | POST | `/order/platform-store-order/ready-to-ship` | 单条 |
| 批量 RTS | POST | `/order/platform-store-order/batch-ready-to-ship` | |
| 库存匹配下单 | POST | `/order/platform-store-order/match-inventory` | 按 SKU 映射扣库存并创建 `t_order` 草稿 |
| 批量库存匹配 | POST | `/order/platform-store-order/batch-match-inventory` | |
| 同步平台状态 | POST | `/order/platform-store-order/sync-status` | |
| 搁置 / 取消搁置 | POST | `/order/platform-store-order/toggle-suspend` | |
| 删除 | POST | `/order/platform-store-order/delete` | `ids[]` |
| 获取面单 | POST | `/order/platform-store-order/fetch-label` | 返回 `shippingLabelUrl` |
| 更新标签 | POST | `/order/platform-store-order/update-tags` | `id`, `customTags` |
| 快速录单 | POST | `/order/platform-store-order/add-draft` | 写入 `t_sales_store_order_draft` |
| 导出 | POST | `/order/platform-store-order/export` | 异步或同步文件流 |

**列表请求关键字段**

```json
{
  "page": 1,
  "pageSize": 30,
  "platformCode": "shopee",
  "fulfillStatus": "pending",
  "platformOrderNo": "",
  "shippingLabelNo": "",
  "storeId": null,
  "isSuspended": false,
  "orderTimeStart": "2026-01-01",
  "orderTimeEnd": "2026-04-01",
  "searchType": "orderNo",
  "searchKeyword": ""
}
```

`searchType`：`orderNo`（平台单号）/ `labelNo`（面单号）/ `whSku`（库内 SKU）。

**列表响应 `items[]` 关键字段**：`id`, `storeId`, `storeNickname`, `platformCode`, `platformOrderNo`, `orderCountry`, `totalAmount`, `currency`, `platformOrderTime`, `fulfillStatus`, `fulfillStatusLabel`, `shippingLabelNo`, `shippingLabelUrl`, `isMultiLabel`, `deliveryMethodLabel`, `customTags`, `isSuspended`, `presaleDays`, `lines[]`（含 `platformSku`, `productName`, `quantity`, `isShipExcluded`）, `linkedOrderId`。

**库存匹配下单逻辑（对齐 WMS `matchSkuInventoryOrder`）**

1. 校验店铺订单归属与 `fulfillStatus` 允许发货。
2. 按 `C_sku_platform_map` 解析每行 `MappedSkuId`；未映射行失败。
3. 按库位扣减 `C_inventory.Qty`（优先默认库位或请求指定 `binLocationId`）。
4. 调用 OMS `CreateParcelCoreAsync` 创建小包订单草稿，回写 `LinkedOrderId`。
5. 更新店铺订单 `fulfillStatus`。

---

### 4.3 仓储 — 我的包裹 `/warehouse/parcel/*`

| 接口 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| 包裹列表 | POST | `/warehouse/parcel/list` | 按 `lifecycleStatus` Tab |
| 状态统计 | POST | `/warehouse/parcel/status-count` | 各状态数量 |
| 包裹详情 | GET | `/warehouse/parcel/detail` | 含 `items[]` |
| 新增 | POST | `/warehouse/parcel/create` | |
| 编辑 | POST | `/warehouse/parcel/update` | |
| 删除 | POST | `/warehouse/parcel/delete` | `ids[]` |
| 申请入库 | POST | `/warehouse/parcel/apply-storage` | 到仓包裹进入库存流程 |

**列表请求**：`lifecycleStatus`（`inTransit`/`arrived`/`unclaimed`/`expired`）、`warehouseId`、`trackingNo`、`parcelCategory`、`productName`（模糊搜明细）。

**创建请求**

```json
{
  "warehouseId": 1,
  "trackingNo": "SF1234567890",
  "carrierName": "顺丰",
  "parcelCategory": "single",
  "remark": "",
  "items": [
    {
      "productName": "手机壳",
      "quantity": 2,
      "imageUrl": "",
      "attributeText": "黑色"
    }
  ]
}
```

---

### 4.4 仓储 — 我的库存 `/warehouse/inventory/*`

| 接口 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| 库存汇总列表 | POST | `/warehouse/inventory/list` | 已入库 SKU 维度 |
| 在途列表 | POST | `/warehouse/inventory/in-transit-list` | 已到仓未上架（对齐 WMS `packageList3`） |
| 状态统计 | GET | `/warehouse/inventory/status-count` | 已到仓 / 已入库数量 |
| 库位明细 | GET | `/warehouse/inventory/bin-detail` | 某 SKU 多库位 |
| 上架 | POST | `/warehouse/inventory/putaway` | 包裹或 SKU 上架 |
| 换库位 | POST | `/warehouse/inventory/relocate` | |
| 调整数量 | POST | `/warehouse/inventory/adjust-qty` | 多库位批量调整 |
| 更新尺重 | POST | `/warehouse/inventory/update-dimension` | |
| 库存流水 | POST | `/warehouse/inventory/movement-list` | 分页 |
| 导出 | POST | `/warehouse/inventory/export` | |

**库存列表请求**：`whSkuCode`, `productName`, `availabilityFilter`（`available`/`replenish`/`all`）、`warehouseId`, `sortBy`（`putawayTime`/`availableQty`）。

**列表响应 `items[]`**：`whSkuId`, `whSkuCode`, `skuName`, `availableQty`, `onHandQty`, `frozenQty`, `binLocationCode`, `lengthCm`, `widthCm`, `heightCm`, `weightG`, `putawayTime`, `parcelTrackingNo`（来源包裹）。

---

### 4.5 仓储 — 我的 SKU `/warehouse/sku/*`

| 接口 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| SKU 列表 | POST | `/warehouse/sku/list` | 分页 |
| 类型统计 | GET | `/warehouse/sku/type-count` | 普通 / 组合数量 |
| 详情 | GET | `/warehouse/sku/detail` | 含映射、组合子项 |
| 新增 | POST | `/warehouse/sku/create` | |
| 编辑 | POST | `/warehouse/sku/update` | |
| 删除 | POST | `/warehouse/sku/delete` | |
| 批量删除 | POST | `/warehouse/sku/batch-delete` | |
| 批量导入 | POST | `/warehouse/sku/import` | Excel |
| 组合 SKU 导入 | POST | `/warehouse/sku/import-bundle` | |
| 映射详情 | GET | `/warehouse/sku/mapping-detail` | `whSkuId` |
| 批量绑定平台 SKU | POST | `/warehouse/sku/bind-platform-sku` | |
| 导入映射 | POST | `/warehouse/sku/import-mapping` | |
| 打印 SKU 标签 | POST | `/warehouse/sku/print-label` | 返回 PDF URL |

**列表请求**：`skuCode`, `skuName`, `isBundle`, `mappingStatus`（`mapped`/`unmapped`/`all`）, `sortBy`。

**列表响应**：`id`, `skuCode`, `skuName`, `skuImageUrl`, `isBundle`, `weightG`, `lengthCm`, `widthCm`, `heightCm`, `referencePrice`, `currency`, `mappingCount`, `onHandQty`, `inboundPendingQty`, `binLocationCode`。

---

### 4.6 仓储 — 入库预报 `/warehouse/inbound-notice/*`

| 接口 | 方法 | 路径 | 说明 |
| --- | --- | --- | --- |
| 列表 | POST | `/warehouse/inbound-notice/list` | 分页 |
| 状态统计 | POST | `/warehouse/inbound-notice/status-count` | |
| 详情 | GET | `/warehouse/inbound-notice/detail` | 含 `boxes[].lines[]` |
| 新增 | POST | `/warehouse/inbound-notice/create` | |
| 编辑 | POST | `/warehouse/inbound-notice/update` | 仅 `receiptStatus=forecasted` 可编辑 |
| 删除 | POST | `/warehouse/inbound-notice/delete` | |
| 导入校验 | POST | `/warehouse/inbound-notice/import-validate` | 箱号导入预检 |
| 导入保存 | POST | `/warehouse/inbound-notice/import-save` | |
| 异常信息 | GET | `/warehouse/inbound-notice/exception-detail` | |
| 标记异常 | POST | `/warehouse/inbound-notice/mark-exception` | |
| 取消异常 | POST | `/warehouse/inbound-notice/clear-exception` | |
| 确认收货 | POST | `/warehouse/inbound-notice/confirm-receive` | 客户侧确认到仓 |
| SKU 清点 | POST | `/warehouse/inbound-notice/inspect` | |
| 打印标签 | POST | `/warehouse/inbound-notice/print-label` | PDF |
| 生成单号 | GET | `/warehouse/inbound-notice/next-no` | 可选预取 |

**创建请求**

```json
{
  "warehouseId": 1,
  "markReference": "MARK-001",
  "inboundType": "normal",
  "remark": "",
  "boxes": [
    {
      "boxSeqNo": "1",
      "markBoxNo": "BOX-001",
      "weightG": 1200,
      "lengthCm": 40,
      "widthCm": 30,
      "heightCm": 20,
      "lines": [
        {
          "whSkuId": 1001,
          "whSkuCode": "SKU-A001",
          "plannedQty": 50
        }
      ]
    }
  ]
}
```

服务端生成 `noticeNo` = `IN` + SnowflakeId。

**列表响应关键字段**：`id`, `noticeNo`, `markReference`, `warehouseId`, `warehouseName`, `inboundType`, `receiptStatus`, `receiptStatusLabel`, `expectedArrivalTime`, `actualArrivalTime`, `skuSummary`, `receivedSkuSummary`, `receiveProgress`, `boxCount`, `receivedBoxCount`, `isException`, `createTime`。

---

## 5　主业务流程

### 5.1 店铺授权 → 拉单

```mermaid
sequenceDiagram
  participant U as 客户
  participant OMS as OMS API
  participant Plat as 电商平台

  U->>OMS: 获取 auth-url
  OMS-->>U: OAuth URL
  U->>Plat: 授权
  Plat-->>OMS: auth-callback(code)
  OMS->>OMS: 写入 t_sales_store + token
  Note over OMS,Plat: 定时任务拉取店铺订单
  OMS->>Plat: 拉单 API
  OMS->>OMS: upsert t_sales_store_order
```

- 平台订单 **定时同步** + 手动「同步状态」；Token 过期前刷新（各平台 Adapter）。
- Manual 店铺：无 OAuth，支持手工录入订单（二期）。

### 5.2 店铺订单 → 小包发货

1. 用户在「店铺订单」筛选 `fulfillStatus=pending`。
2. 操作「库存匹配」：映射 → 扣库存 → 创建 `t_order`。
3. 或操作「准备发货」：调平台 RTS API → 更新 `fulfillStatus`。
4. 获取平台面单 → 可关联 OMS 出库流程。

### 5.3 入库预报 → 库存

1. 客户维护 `C_sku` → 创建入库预报（`C_inbound_notice` + **箱号** `C_inbound_box` + 箱内行 `C_inbound_box_line`）→ `ReceiptStatus=forecasted`。
2. 仓库 `confirm-receive`：按箱清点，每行指定 `BinLocationId` → 累加 `C_inventory.Qty` → `completed`。
3. **不做**清点/上架多态、收货日志表。

### 5.4 我的包裹 → 库存

1. 客户登记快递单号 → `inTransit`。
2. 到仓 → `arrived`；`putaway` 指定 `SkuId` + `BinLocationId` → 累加 `C_inventory` → `stored`。

---

## 6　客户数据隔离

与 OMS §4.4.0 对齐，扩展至仓储模块：

| 规则 | 说明 |
| --- | --- |
| 隔离键 | `effectiveCustomerId` = `t_customer.Id` |
| 列表 | 强制 `CustomerId = effectiveCustomerId` |
| 单条读写 | 先查主表 `CustomerId`，不匹配返回「数据不存在」 |
| 子客户 | 与订单模块策略统一（推荐归并主客户 Id） |
| 关联表 | 通过主表 `OrderId` / `ParcelId` / `InboundNoticeId` 间接隔离 |
| 管理员 | `loginType=0` 可传 `customerId` 查指定客户（与现网订单一致） |

---

## 7　WMS 对照表（实现参考，非字段拷贝）

| WMS 概念 | WMS 表/字段 | OMS 设计 |
| --- | --- | --- |
| 店铺 | `vip_shop` | `t_sales_store` + `t_sales_store_token` |
| 店铺订单 | `vip_shop_ord` | `t_sales_store_order` |
| 订单明细 | `vip_shop_ord_pro` | `t_sales_store_order_line` |
| 包裹 | `vip_package` | `C_parcel` |
| 包裹明细 | `vip_package_pro` | `C_parcel_item` |
| 库存余额 | `vip_package_inventory` | `C_inventory`（按库位） |
| 库位 | `storage_id` / `storageText` | `C_bin_location` |
| 库存流水 | `wms_stock_record` | `C_stock_movement` |
| 商品 SKU | `wms_goods_sku` | `C_sku` |
| 组合 SKU | `wms_goods_sku_combine` | `C_sku_bundle_item` |
| 平台映射 | `wms_shop_mapping_products_contact` | `C_sku_platform_map` |
| 入库单 | `wms_warehousing_order` | `C_inbound_notice` |
| 入库箱 | `wms_warehousing_box` | `C_inbound_box` |
| 箱内 SKU | `wms_warehousing_box_goods` | `C_inbound_box_line` |
| 收货日志 | `wms_warehousing_order_inbound_log` | `C_inbound_receipt_log` |
| 会员 | `vipId` | `CustomerId` |
| 仓库 | `whseId` | `WarehouseId` → `t_warehouse_address` |

| WMS 接口前缀 | OMS 接口前缀 |
| --- | --- |
| `/vip/shop/*` | `/order/platform-store/*` |
| `/vip/ord/*` | `/order/platform-store-order/*` |
| `/vip/package/*` | `/warehouse/parcel/*`、`/warehouse/inventory/*` |
| `/wms/warehousing/sku/*` | `/warehouse/sku/*` |
| `/wms/warehousing/order/*` | `/warehouse/inbound/*` |

---

## 8　枚举与常量

### 8.1 店铺订单履约状态 `FulfillStatus`

| 值 | 说明 | WMS 对应 |
| --- | --- | --- |
| `all` | 全部（筛选用） | `0` |
| `pending` | 待处理 | `pending` |
| `toShip` | 待发货 | `toBeShipped` |
| `canceled` | 已取消 | `cancel` |
| `suspended` | 已搁置 | `suspended` |
| `shipped` | 已发货 | `shipped` |
| `completed` | 已完成 | `completed` |

### 8.2 包裹生命周期 `LifecycleStatus`

**轻量版（3 态）**：`inTransit` / `arrived` / `stored`

| 值 | 说明 | WMS `pkgStatus` |
| --- | --- | --- |
| `inTransit` | 待到仓 | `1` |
| `arrived` | 已到仓 | `2` |
| `stored` | 已入库 | — |
| ~~`unclaimed`~~ | 待认领 **〔延后〕** | `3` |
| ~~`expired`~~ | 已到期 **〔延后〕** | `4` |

### 8.3 库存变动类型 `MovementType` **〔延后，轻量版不建流水表〕**

| 值 | 说明 |
| --- | --- |
| `inbound` | 入库上架 |
| `allocate` | 订单分配冻结 |
| `release` | 释放冻结 |
| `outbound` | 出库扣减 |
| `adjust` | 人工调整 |
| `relocate` | 换库位 |

### 8.4 入库预报状态 `ReceiptStatus`

**轻量版（3 态）**：`forecasted` → `received` → `completed`

| 值 | 说明 | WMS `adopt` |
| --- | --- | --- |
| `forecasted` | 已预报 | `N` |
| `received` | 已到仓待确认 | `B`/`C` 合并 |
| `completed` | 已入库 | `Y` |
| ~~`inspecting`~~ / ~~`putaway`~~ / ~~`exception`~~ | **〔延后〕** | |

### 8.5 平台编码 `PlatformCode`

| 值 | 平台 |
| --- | --- |
| `lazada` | Lazada |
| `shopee` | Shopee |
| `tiktok` | TikTok Shop |
| `temu` | Temu |
| `manual` | 手工店铺 |

---

## 9　实施分期建议 **〔轻量版见 §0.5〕**

| 阶段 | 范围 | 交付物 |
| --- | --- | --- |
| **M1** | SKU + 入库预报 + 库存余额 | 3 表 + `WarehouseService` 10 个接口 + 2 页 |
| **M2** | 包裹 + 库存只读页 | +2 表 + 6 接口 + 2 页 |
| **M3** | 店铺授权 + 店铺订单 | +3 表 + 2 Service + 2 页 |
| **M4** | 库存匹配 → `t_order` | 打通订单 | **已完成** |

**完整版分期（v0.1，仅供参考）**

| 阶段 | 范围 |
| --- | --- |
| P0～P4 | 见原表 |

---

## 10　附录：迁移脚本

**一步建表（推荐）**

```
sql/migrate_warehouse_module.sql   -- 仓储 C_* 9 张 + 店铺 t_sales_* 3 张
```

执行后需在 `Oms.Domain` 中已有对应实体（Step 1 已落地）。

---

## 11　待决事项（评审时确认）

1. **子客户订单归属**：与订单模块统一。
2. **库位维护入口**：`C_bin_location` 放仓储菜单还是系统仓库管理 — 建议 **仓库地址详情页** 或仓储下子页。
3. **默认库位**：每仓库是否预置一个 `DEFAULT` 库位，简化客户上架。
4. **包裹是否 M1 必做**：主路径若为入库预报，包裹可 M2。
5. **平台首期范围**：Shopee / Lazada / TikTok 择几先做。

---

*文档结束。实现时以 `docs/oms系统设计-050801.md` §3 公共规范与 `docs/rbac系统设计-060801.md` 权限模型为准；若与本文冲突，以评审结论更新本文档版本号。*