chore: 整理 ttx 项目文档目录

2026-06-08 21:27:53 +08:00
parent f83f4751a2
commit a4af3ac9b4
12 changed files with 3541 additions and 21 deletions
@@ -7,8 +7,12 @@
 ## 主入口
 - [文档统一汇总](统一汇总.md)

+## 分类目录
+- [集波](集波/)
+- [出库单接口文档](出库单接口文档/)
+
 ## 接口文档
- [Shopee Automation Vendor 接入协议手册出库模块映射 WES 字段 V1.2](Shopee_Automation_Vendor_接入协议手册_出库模块映射WES字段_V1.2.md)
+- [Shopee Automation Vendor 接入协议手册出库模块映射 WES 字段 V1.2](出库单接口文档/Shopee_Automation_Vendor_接入协议手册_出库模块映射WES字段_V1.2.md)

 ## 说明
 - 需要快速了解当前工作时，先看统一汇总。
@@ -14,7 +14,7 @@

 This plan covers the outbound module, inventory/rack-transfer module, and basic-data module interfaces present in this protocol file, based on:

- `docs/Shopee_Automation_Vendor_接入协议手册_出库模块映射WES字段_V1.2.md`
+- `出库单接口文档/Shopee_Automation_Vendor_接入协议手册_出库模块映射WES字段_V1.2.md`
 - `wes-loghub/wms-api/src/main/groovy/com/ittx/wms/api/service/platform/ShopeeInboundApiHandler.groovy`
 - `C:\work\gitlab\shopee\edi-shopee`

@@ -73,7 +73,7 @@ Do not implement inbound module interfaces in this plan. Include all concrete in

 ## Interface Inventory

-Protocol alignment from `docs/Shopee_Automation_Vendor_接入协议手册_出库模块映射WES字段_V1.2.md`:
+Protocol alignment from `出库单接口文档/Shopee_Automation_Vendor_接入协议手册_出库模块映射WES字段_V1.2.md`:

 - Outbound module title count: 45 entries under `3.1` to `3.4`.
 - Outbound module URL count: 35 concrete, unique `/api/v2/automation/.../outbound/...` APIs.
@@ -1,6 +1,6 @@
 # Shopee Automation Vendor 接入协议手册出库模块映射 WES 字段 V1.2

-> 来源：`C:\Users\zoe\Downloads\Shopee Automation Vendor 接入协议手册出库模块映射WES字段V1.2.docx`
+> 来源：`C:\work\gitlab\shopee\ttx-project-doc\出库单接口文档\Shopee Automation Vendor 接入协议手册出库模块映射WES字段V1.2.docx`
 >
 > 说明：本文档由 Word 接入协议手册转换生成，保留原始章节、接口字段表、响应字段表和返回码表，便于在仓库 `docs/` 中维护和检索。

@@ -77,7 +77,7 @@

 ### 主题文档

- [Shopee Automation Vendor 接入协议手册出库模块映射 WES 字段 V1.2](Shopee_Automation_Vendor_接入协议手册_出库模块映射WES字段_V1.2.md)
+- [Shopee Automation Vendor 接入协议手册出库模块映射 WES 字段 V1.2](出库单接口文档/Shopee_Automation_Vendor_接入协议手册_出库模块映射WES字段_V1.2.md)
 - [Shopee 出库接口 WES 字段映射实现计划](superpowers/plans/2026-06-04-shopee-outbound-api-wes-mapping.md)
 - [出库集波改动计划](SHOPEE_010_出库集波V1.2_改动计划.md)
 - [待办事项](SHOPEE_010_出库集波V1.2_待办事项.md)
@@ -3,6 +3,8 @@
 > 对应实现：`C:\work\gitlab\shopee\wes-loghub\wms-wave\src\main\groovy\com\ittx\wms\wave\service\hairo\WaveRuleMatchService.groovy`
 >
 > 本文档描述该服务的**当前代码流程**，按调用入口到出口的完整链路展开，包括主流程、分流流程、补缺口流程、回滚流程和详细的规则匹配机制。
+>
+> 需求标准来源：`C:\work\gitlab\shopee\ttx-project-doc\集波\SHOPEE_010_出库集波V1.2.docx`，当前同步到 V1.4 口径：`wave_rule.waveType` 与 `shipment_header.orderStructure` 包含关系、同一 `groupKey` 集波约束、字段匹配字典规则。

 ---

@@ -22,6 +24,7 @@
 12. [Flow Pick 换箱换波流程](#12-flow-pick-换箱换波流程)
 13. [字段匹配规则（WAVE_RULE_FIELD_MATCHING）](#13-字段匹配规则wave_rule_field_matching)
 14. [方法调用关系图](#14-方法调用关系图)
+15. [标准需求与当前实现对照](#15-标准需求与当前实现对照)

 ---

@@ -36,6 +39,17 @@
 - 完成 Shopee 波次号绑定、ESS 合波校验、内部波次创建与运行
 - 首次集波成功返回 `ResponseMessageFactory.success()`，不返回「格口 + 命中规则 + 波次」明细

+**当前匹单核心口径：**
+
+| 维度 | 当前规则 |
+|------|----------|
+| 规则优先级 | `wave_rule.wavePriority` 数字越大越优先；高优先级规则订单数不足 `maxShipments` 时仍优先消费当前可匹配单据 |
+| 抓单数量 | 只使用 `wave_rule.maxShipments`；`wave_master.maxShipments` 不参与当前逻辑 |
+| 订单结构 | 出库单头 `shipment_header.orderStructure` 记录数字编码：`1=SSSQ`、`2=SSAQ`、`3=MSAQ` |
+| 规则类型匹配 | `wave_rule.waveType` 通过 `resolveMatchedOrderStructures` 转换为可抓的 `orderStructure` 集合 |
+| 字段匹配 | 通过 `WAVE_RULE_FIELD_MATCHING` 字典追加 `wave_rule` 字段与 `shipment_header` 字段的 `IN/EQ/LE` 条件 |
+| 同波约束 | 首次抓单会先按最早候选单解析 `groupKey`；补缺口时按当前 `shopee_wave.groupKey` 过滤，保证同一 Shopee 波次只集相同 `groupKey` |
+
 **三种分流入口：**

 | 分支 | 条件 | 处理方式 |
@@ -148,7 +162,10 @@ assignSingleShipmentWaves(warehouseCode, shipmentType, workstationId, rules)
 ```
 for each WaveRule:
  findSingleShipmentWaveShipments(warehouseCode, shipmentType, rule)
-    → buildAvailableShipmentSql + appendSingleWaveFilter + appendRuleFieldMatching
+    → buildAvailableShipmentSql
+    → appendSingleWaveFilter
+    → appendWaveTypeOrderStructureFilter
+    → appendRuleFieldMatching
    → LIMIT 1（只取 1 单）
  if shipment found:
    createInternalWave(warehouseCode, rule)  → 创建内部波次
@@ -165,6 +182,7 @@ for each WaveRule:
 - **当前一波一单分流不走 ESS 校验**
 - **不走格口分配**（不绑定格口）
 - **一单一个内部波次**
+- **同样受 waveType/orderStructure 包含关系约束**，避免一波一单候选绕过规则订单结构过滤

 ---

@@ -232,7 +250,8 @@ assignCellNumbers(warehouseCode, shipmentType, workstationId, rule, cells):
  │
  ├─ 2. findAvailableShipments → 查批量集波候选
  │     → 排除 pickType=1,2 + 排除一波一单 ticketType
-  │     → 规则字段匹配 + 订单结构匹配 + kickOutWave 过滤
+  │     → waveType/orderStructure 匹配 + 规则字段匹配 + kickOutWave 过滤
+  │     → 首次抓单按最早候选单确定 groupKey，并只抓相同 groupKey
  │     → LIMIT = maxShipments（默认 30）
  │
  ├─ 3. 仍无候选 → MSG_WRM_0010
@@ -267,7 +286,36 @@ assignCellNumbers(warehouseCode, shipmentType, workstationId, rule, cells):
  └─ 一个格口消费一批后 break（不再占用其他格口）
 ```

-### 6.3 订单池 SQL 基础条件
+### 6.3 waveType 与 orderStructure 匹配
+
+标准文档 V1.4 要求：匹单时除 `WAVE_RULE_FIELD_MATCHING` 字段匹配外，还要先按 `wave_rule.waveType` 与 `shipment_header.orderStructure` 的包含关系过滤候选出库单。
+
+当前实现方法：
+
+```
+appendWaveTypeOrderStructureFilter(sql, params, rule)
+  → resolveMatchedOrderStructures(rule)
+  → SQL: and orderStructure in (:matchedOrderStructures)
+```
+
+匹配关系如下：
+
+| `wave_rule.waveType` | 规则含义 | 可抓 `shipment_header.orderStructure` | 出库单结构含义 |
+|----------------------|----------|--------------------------------------|----------------|
+| `1` | SSSQ | `1` | SSSQ，单 SKU 单件 |
+| `5` | MSSQ | `1` | SSSQ，单 SKU 单件 |
+| `4` | SSAQ | `1, 2` | SSSQ / SSAQ |
+| `2` | SSSQ(Same SKU same Qty) | `3` | MSAQ |
+| `3` | MSAQ | `1, 2, 3` | SSSQ / SSAQ / MSAQ |
+
+说明：
+
+- `shipment_header.orderStructure` 由 `ShipmentHeaderService#calcOrderStructure` 写入，当前编码为 `1=SSSQ`、`2=SSAQ`、`3=MSAQ`。
+- `wave_rule.waveType` 是规则侧单选类型，不直接等值匹配订单结构，而是通过上表转换成可包含的订单结构集合。
+- `appendWaveTypeOrderStructureFilter` 同时用于普通批量候选和一波一单候选，保证入口一致。
+- 未识别的 `waveType` 不追加订单结构条件；此场景通常表示规则数据异常，应通过规则主数据维护修正。
+
+### 6.4 订单池 SQL 基础条件

 ```sql
 SELECT id FROM shipment_header
@@ -282,6 +330,20 @@ WHERE warehouseCode = :warehouseCode
  AND (holdTime IS NULL OR holdTime = '')        -- 未挂起
 ```

+### 6.5 groupKey 集波约束
+
+标准文档要求：匹单时除规则字段匹配外，还需要根据 `shipment_header.groupKey` 特征值一致才能集在一起。
+
+当前实现：
+
+| 场景 | 方法 | 规则 |
+|------|------|------|
+| 首次空格口集波 | `findAvailableShipments(..., groupKey='')` | 先用已拼好的候选 SQL 查最早候选单的 `groupKey`，再追加 `appendGroupKeyFilter` 限制同一特征值 |
+| 已绑波次格口补缺口 | `resolveShopeeWaveGroupKey` + `findAvailableShipments(..., shopeeWaveCode, groupKey)` | 从 `shopee_wave.groupKey` 解析当前波次特征值，只补相同 `groupKey` 的单 |
+| 空 `groupKey` | `appendGroupKeyFilter` | 空值只匹配空值，避免空值与非空值串波 |
+
+这意味着同一 Shopee 波次内不会混入不同 `groupKey` 的订单；如果候选池存在多个 `groupKey`，当前按抓单优先级排序后的首个候选单决定本轮特征值。
+
 ---

 ## 7. 格口分配策略
@@ -486,7 +548,10 @@ fillShortageCells(warehouseCode, shipmentType, workstationId, rules):
  ├─ resolveShopeeWaveGroupKey → 同一 Shopee 波次只补相同 groupKey 单据
  │
  ├─ findAvailableShipments(..., shopeeWaveCode, groupKey)
+  │   → waveType/orderStructure 匹配
+  │   → WAVE_RULE_FIELD_MATCHING 字段匹配
  │   → 排除 kickOutWave 过滤的已拒单
+  │   → 只补同一 groupKey 单据
  │
  └─ assignToCell
      ├─ ensureCellReadyForWave → 先抢占格口
@@ -565,36 +630,61 @@ changeFlowPickWave(workstation, cell, rule):

 ## 13. 字段匹配规则（WAVE_RULE_FIELD_MATCHING）

+> 注意：`wave_rule.waveType` 与 `shipment_header.orderStructure` 的包含关系不是通过 `WAVE_RULE_FIELD_MATCHING` 配置，而是由 `appendWaveTypeOrderStructureFilter + resolveMatchedOrderStructures` 固定维护。`WAVE_RULE_FIELD_MATCHING` 只负责其它规则属性与出库单字段的匹配。
+
 ### 13.1 数据字典结构

 通过数据字典表 `config_detail` + `config_value` 配置，`recordType = 'WAVE_RULE_FIELD_MATCHING'`。

 | 字段 | 含义 | 示例 |
 |------|------|------|
-| `identifier` | 出库单字段 | `userDef1`、`shipmentCategory1`、`priority` |
+| `identifier` | 出库单字段 | `userDef1`、`shipmentCategory2`、`priority` |
 | `value1` | 规则字段 | `channelId`、`shopId`、`urgentFlag` |
 | `value2` | 操作符 | `IN` / `EQ` / `LE` |
+| `value3` | Sales Outbound Order 是否参与匹配，`Y` 才生效 | 对应 `shipment_header.ticketType=2` |
+| `value4` | Sales Outbound Task 是否参与匹配，`Y` 才生效 | 对应 `shipment_header.ticketType=1` |
+| `value5` | Move Transfer Demand 是否参与匹配，`Y` 才生效 | 对应 `shipment_header.ticketType=4` |
+| `value6` | Move Transfer Task 是否参与匹配，`Y` 才生效 | 对应 `shipment_header.ticketType=5` |
+| `value7` | RTS Demand 是否参与匹配，`Y` 才生效 | 对应 `shipment_header.ticketType=3` |
+| `value8` | RT Order 是否参与匹配，`Y` 才生效 | 对应 `shipment_header.ticketType=6` |
 | `warehouseCode` | 仓库级/全局 | 优先匹配当前仓，无配置时读取 `*` |

+> 匹单字段需要同时满足字段映射和 `ticketType` 标记。某字段在对应订单类型列未标记 `Y` 时，该字段不参与该订单类型匹单；只有标记 `Y` 的订单类型才按 `value2` 操作符生成字段条件。
+
 ### 13.2 支持的操作符

 | 操作符 | SQL 生成 | 说明 |
 |--------|----------|------|
-| `IN`（默认） | `shipmentField IN (:values)` | 规则值按逗号/中文逗号拆分多选 |
-| `EQ` / `=` / `EQUAL` / `EQUALS` | `shipmentField = :value` | 等值匹配 |
-| `LE` / `<=` / `LESS_OR_EQUAL` | `ifnull(shipmentField, 0) <= :value` | 数值小于等于 |
+| `IN`（默认） | `ticketType 未标记 Y 或 shipmentField IN (:values)` | 规则值按逗号/中文逗号拆分多选 |
+| `EQ` / `=` / `EQUAL` / `EQUALS` | `ticketType 未标记 Y 或 shipmentField = :value` | 等值匹配 |
+| `LE` / `<=` / `LESS_OR_EQUAL` | `ticketType 未标记 Y 或 ifnull(shipmentField, 0) <= :value` | 数值小于等于 |

-### 13.3 字段白名单
+### 13.3 ticketType 字段适用关系
+
+`WAVE_RULE_FIELD_MATCHING` 每一行字段配置都可以按订单类型单独控制是否参与匹单。
+
+| 字典列 | 订单类型 | ticketType | 是否参与 |
+|--------|----------|------------|----------|
+| `value3` | Sales Outbound Order | `2` | 填 `Y` 参与，否则跳过该字段 |
+| `value4` | Sales Outbound Task | `1` | 填 `Y` 参与，否则跳过该字段 |
+| `value5` | Move Transfer Demand | `4` | 填 `Y` 参与，否则跳过该字段 |
+| `value6` | Move Transfer Task | `5` | 填 `Y` 参与，否则跳过该字段 |
+| `value7` | RTS Demand | `3` | 填 `Y` 参与，否则跳过该字段 |
+| `value8` | RT Order | `6` | 填 `Y` 参与，否则跳过该字段 |
+
+示例：`channelId` 这一行如果只在 `value3/value4` 填 `Y`，则只有 `ticketType=2/1` 的单据会校验 `channelId`；其它 `ticketType` 单据不会因为 `channelId` 不匹配被过滤。
+
+### 13.4 字段白名单

 防止字典配置拼出非预期 SQL，白名单校验在 `toRuleFieldMapping` 中执行：

 **出库单字段（30+）：**
-`shipmentType`, `ticketType`, `pickType`, `sourcePlatform`, `sourceErp`, `erpOrderType`, `route`, `carrierCode`, `shipmentSubType`, `shipmentCategory1~8`, `shipToCountry/State/City/District/Town(Code)`, `hostCompanyCode`, `storeCode`, `shipObjType`, `requestedDeliveryType`, `priority`, `userDef1~8`
+`shipmentType`, `pickType`, `sourcePlatform`, `sourceErp`, `erpOrderType`, `route`, `carrierCode`, `shipmentSubType`, `shipmentCategory2~8`, `shipToCountry/State/City/District/Town(Code)`, `hostCompanyCode`, `storeCode`, `shipObjType`, `requestedDeliveryType`, `priority`, `userDef1~8`

 **规则字段（16）：**
 `channelId`, `fulfillmentChainId`, `orderSize`, `skuSizeType`, `categoryLevel1Id`, `shopGroup`, `shopId`, `urgentFlag`, `outerPackaging`, `outerPackagingId`, `deliveryRegion`, `fragile`, `liquid`, `highValue`, `battery`, `danger`

-### 13.4 执行流程
+### 13.5 执行流程

 ```
 resolveRuleFieldMappings(warehouseCode)
@@ -602,14 +692,22 @@ resolveRuleFieldMappings(warehouseCode)
  → toRuleFieldMapping(detail)
    → 白名单校验
    → normalizeRuleOperator 规范化操作符
-    → 返回 RuleFieldMapping(ruleField, shipmentField, operator)
+    → resolveRuleFieldTicketTypes(detail) 解析 value3~value8 中标记 Y 的 ticketType
+    → 返回 RuleFieldMapping(ruleField, shipmentField, operator, ticketTypes)

 appendRuleFieldMatching(sql, params, warehouseCode, rule)
  for each mapping:
+    → mapping.ticketTypes 为空时跳过该字段
    switch operator:
-      IN  → appendIn(sql, params, shipmentField, ruleField + 'Values', splitCandidates(ruleValue))
-      EQ  → appendEquals(sql, params, shipmentField, ruleField + 'Value', ruleValue)
-      LE  → appendLessOrEqual(sql, params, shipmentField, ruleField + 'Value', toNonNegativeInteger(ruleValue))
+      IN  → appendTicketTypeScopedIn
+      EQ  → appendTicketTypeScopedEquals
+      LE  → appendTicketTypeScopedLessOrEqual
+
+SQL 形态:
+  and (
+        ifnull(ticketType, 0) not in (:当前字段适用ticketTypes)
+     or 字段条件成立
+  )
 ```

 ---
@@ -679,6 +777,8 @@ fillShortageCells
  buildAvailableShipmentParams      ← 基础参数
  appendBatchWaveFilter             ← 排除一波一单
  appendSingleWaveFilter            ← 一波一单条件
+  appendWaveTypeOrderStructureFilter ← wave_rule.waveType → shipment_header.orderStructure 包含关系
+    └─ resolveMatchedOrderStructures
  appendRuleFieldMatching           ← WAVE_RULE_FIELD_MATCHING 字典匹配
    ├─ appendIn / appendEquals / appendLessOrEqual
    └─ resolveRuleFieldMappings → toRuleFieldMapping
@@ -708,7 +808,7 @@ fillShortageCells
  splitCandidates / matchesCellWaveRule
  buildRuleMatchLockKey
  isSingleRule
-  resolveMasterCode / resolveShipmentLimit / resolveLowThreshold
+  resolveMasterCode / resolveShipmentLimit / resolveLowThreshold / resolveMatchedOrderStructures
  normalizeRuleOperator
 ```

@@ -728,6 +828,43 @@ fillShortageCells
 | `TICKET_TYPE_MTO_TASK` | `5` | MTO 任务 |
 | `WAVE_RULE_FIELD_MATCHING` | `'WAVE_RULE_FIELD_MATCHING'` | 字段匹配字典类型 |

+---
+
+## 15. 标准需求与当前实现对照
+
+### 15.1 标准文档 V1.4 已同步口径
+
+| 标准需求点 | 当前文档/代码口径 | 实现状态 |
+|------------|-------------------|----------|
+| `shipment_header.orderStructure` 自动分析 | `ShipmentHeaderService#calcOrderStructure` 写入 `1=SSSQ`、`2=SSAQ`、`3=MSAQ` | 已落地 |
+| `wave_rule.waveType` 与 `shipment_header.orderStructure` 包含关系 | `appendWaveTypeOrderStructureFilter` + `resolveMatchedOrderStructures` | 已落地 |
+| 同一波次 `groupKey` 一致 | `findAvailableShipments` 首次解析候选 `groupKey`；补缺口读取 `shopee_wave.groupKey` | 已落地 |
+| 上墙优先级 | `findEnabledRules` 按 `wavePriority desc, id asc`；高优先级不足 `maxShipments` 仍优先消费 | 已落地 |
+| 抓单优先级 | `priority desc`、`cutOffTime asc`、`purchaseTime asc`、`orderTime asc`、`id asc` | 已落地 |
+| `wave_rule.maxShipments` | `resolveShipmentLimit` 使用规则级 `maxShipments`，默认 30 | 已落地 |
+| `WAVE_RULE_FIELD_MATCHING` | `appendRuleFieldMatching` 按字典追加 `IN/EQ/LE` 条件 | 已落地 |
+| `kickOutWave` 过滤 | `appendKickOutFilter` 对同一 Shopee 波次过滤已拒单 | 已落地 |
+
+### 15.2 waveType/orderStructure 标准映射
+
+| 标准 waveType | 编码 | 当前可抓 orderStructure | 编码 |
+|---------------|------|--------------------------|------|
+| SSSQ | `1` | SSSQ | `1` |
+| MSSQ | `5` | SSSQ | `1` |
+| SSAQ | `4` | SSSQ / SSAQ | `1 / 2` |
+| SSSQ(Same SKU same Qty) | `2` | MSAQ | `3` |
+| MSAQ | `3` | SSSQ / SSAQ / MSAQ | `1 / 2 / 3` |
+
+### 15.3 标准需求中仍为占位或待恢复的点
+
+| 标准需求点 | 当前实现状态 | 后续落点 |
+|------------|--------------|----------|
+| Shopee 合波校验真实接口 | `requestShopeeWaveBind` 为预留入口，当前只保留整批成功/失败契约 | 接口契约明确后补真实调用 |
+| 库存不足踢单通知上游撤单 | 当前由回池链路清空 `shopeeWave/waveRule`，上游撤单接口仍待接入 | `wms-wave` 回池链路 |
+| 计划任务轮询补单 | 原 `pollReplenishment/pollReplenishmentOnce` 已删除；当前补缺口在首次集波入口 `fillShortageCells` 执行 | 如需后台轮询，需恢复独立计划任务入口 |
+| 推拣货任务一单一波一槽口 | 普通批量已过滤 `pickType=2`，独立分流入口当前未保留 | 待恢复 `pickType=2 + shopeeWave` 专用分流 |
+| Flow Pick 封箱/换箱接口 | 本地流程已有占位方法，真实 ESS/AGV 接口未接入 | `requestFlowPickSealBox` / `requestFlowPickChangeBox` / `handleFlowPickChangeWaveFailure` |
+
 ## 附录：TODO 清单（代码内标注）

 | 位置 | TODO | 优先级 |