zoe/ttx-project-doc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align shopee protocol interface inventory

Browse Source
This commit is contained in:
曾志威
2026-06-04 15:37:28 +08:00
parent 76ed80829c
commit ad443f0bc9
1 changed files with 128 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
superpowers/plans/2026-06-04-shopee-outbound-api-wes-mapping.md
+128 -20
View File
@@ -2,7 +2,7 @@
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Implement Shopee Automation outbound interfaces plus the user-confirmed `4.1` rack-transfer inventory sync interface, with `edi-shopee` as the external Shopee-facing entry and WES `ShopeeInboundApiHandler` as the internal business handler.
**Goal:** Implement Shopee Automation outbound interfaces plus protocol sections `4.1`-`5.8`, with `edi-shopee` as the external Shopee-facing entry and WES `ShopeeInboundApiHandler` as the internal business handler.
**Architecture:** Shopee calls `C:\work\gitlab\shopee\edi-shopee`; `edi-shopee` owns Shopee URL paths, JWT validation/generation, protocol response shape, EDI logging, and forwarding to WES. WES business handling stays in `wes-loghub/wms-api/src/main/groovy/com/ittx/wms/api/service/platform/ShopeeInboundApiHandler.groovy`, reached by `edi-shopee` through the existing WES sync API with `api=shopee...`.
@@ -12,13 +12,13 @@
## Scope
This plan covers the outbound module and the explicitly added `4.1` rack-transfer inventory interface, based on:
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`
- `wes-loghub/wms-api/src/main/groovy/com/ittx/wms/api/service/platform/ShopeeInboundApiHandler.groovy`
- `C:\work\gitlab\shopee\edi-shopee`
Do not implement inbound, basic-data, or the rest of inventory module in this plan. The only inventory interface included is `4.1 库内移库同步占用库存给Vendor接口`.
Do not implement inbound module interfaces in this plan. Include all concrete interfaces from `3.1`-`3.4`, `4.1`-`4.7`, and `5.1`-`5.8`.
## Current State
@@ -50,9 +50,9 @@ Do not implement inbound, basic-data, or the rest of inventory module in this pl
- Modify: `wms-wave/src/main/groovy/com/ittx/wms/wave/service/hairo/WaveRuleMatchService.groovy`
- Replace Shopee wave bind placeholder with a call to `edi-shopee` and parse failed shipment IDs.
- Modify: `wms-transfer/src/main/groovy/com/ittx/wms/transfer/service/TransferOrderHeaderService.groovy` or the existing transfer-order creation/release hook that creates rack-transfer reserved stock.
- Trigger `4.1` WMS-to-Vendor rack-transfer sync after WES has created and reserved the transfer order.
- Trigger WMS-to-Vendor rack-transfer sync after WES has created and reserved the transfer order.
- Create only if no existing transfer service method is suitable: `wms-api/src/main/groovy/com/ittx/wms/api/service/platform/ShopeeRackTransferMappingService.groovy`
- Build the `4.1` request body from existing `TransferOrderHeader`/detail data.
- Build `4.1`, `4.6`, and `4.7` WMS-to-Vendor request bodies from existing `TransferOrderHeader`/detail data.
- Modify: `src/main/resources/application.yml` and profile-specific config only if no existing system-parameter path is available.
- Add internal `edi-shopee` endpoint only if it cannot be represented by existing API/customer config.
@@ -74,9 +74,9 @@ Protocol alignment from `docs/Shopee_Automation_Vendor_接入协议手册_出库
- Outbound module title count: 45 entries under `3.1` to `3.4`.
- Outbound module URL count: 35 concrete, unique `/api/v2/automation/.../outbound/...` APIs.
- Reused/deprecated/explanation count: 10 title entries.
- Added inventory URL count: 1 user-confirmed `4.1` rack-transfer API.
- Total implemented protocol API inventory in this plan: 36 concrete APIs.
- Other inventory/rack-transfer URLs after `4.1` are not part of this implementation plan.
- Inventory/rack-transfer URL count: 7 concrete APIs under `4.1` to `4.7`.
- Basic-data URL count: 8 concrete APIs under `5.1` to `5.8`.
- Total implemented protocol API inventory in this plan: 50 concrete APIs.
### Concrete Outbound APIs
@@ -118,11 +118,25 @@ Protocol alignment from `docs/Shopee_Automation_Vendor_接入协议手册_出库
| 34 | 3.4.7 | Vendor -> WMS | `/api/v2/automation/toshopee/outbound/mto/sync_picking_detail` | `shopee.outbound.mto.syncPickingDetail` | MTO 增量拣货明细 |
| 35 | 3.4.8 | Vendor -> WMS | `/api/v2/automation/toshopee/outbound/mto/complete_picking_task` | `shopee.outbound.mto.completePickingTask` | MTO 完成拣货任务 |
### Added Inventory API
### Concrete Inventory and Basic APIs
| No. | Section | Direction | Shopee/edi-shopee path | WES api constant | Implementation note |
| --- | --- | --- | --- | --- | --- |
| 36 | 4.1 | WMS -> Vendor | `/api/v2/automation/tovendor/inventory/racktransfer/create_rt_order` | `shopee.inventory.racktransfer.createRtOrder` | WES 给 Vendor 同步移库占用库存；只纳入 4.1，不扩展 4.2-4.7 |
| 36 | 4.1 | WMS -> Vendor | `/api/v2/automation/tovendor/inventory/racktransfer/create_rt_order` | `shopee.inventory.racktransfer.createRtOrder` | WES 给 Vendor 同步移库占用库存 |
| 37 | 4.2 | Vendor -> WMS | `/api/v2/automation/toshopee/inventory/racktransfer/occupy_device` | `shopee.inventory.racktransfer.occupyDevice` | Vendor 占用或释放 PickingDevice |
| 38 | 4.3 | Vendor -> WMS | `/api/v2/automation/toshopee/inventory/racktransfer/submit_picking_sku_list` | `shopee.inventory.racktransfer.submitPickingSkuList` | Vendor 整箱同步移库拣货明细 |
| 39 | 4.4 | Vendor -> WMS | `/api/v2/automation/toshopee/inventory/racktransfer/sync_picking_sku_list` | `shopee.inventory.racktransfer.syncPickingSkuList` | Vendor 定时回传 WMS 创建移库单拣货明细 |
| 40 | 4.5 | Vendor -> WMS | `/api/v2/automation/toshopee/inventory/racktransfer/handle_diff_stock` | `shopee.inventory.racktransfer.handleDiffStock` | Vendor 盘点差异调减同步给 WMS |
| 41 | 4.6 | WMS -> Vendor | `/api/v2/automation/tovendor/inventory/racktransfer/query_picking_list` | `shopee.inventory.racktransfer.queryPickingList` | WES 查询 Vendor 移库拣货明细用于对账 |
| 42 | 4.7 | WMS -> Vendor | `/api/v2/automation/tovendor/inventory/racktransfer/update_rt_order` | `shopee.inventory.racktransfer.updateRtOrder` | WES 更新移库单优先级或取消状态 |
| 43 | 5.1 | Vendor -> WMS | `/api/v2/automation/toshopee/basic/user/query_user_exist` | `shopee.basic.user.queryUserExist` | Vendor 查询 WES 用户是否存在 |
| 44 | 5.2 | WMS -> Vendor | `/api/v2/automation/tovendor/basic/inventory/batch_status_update` | `shopee.basic.inventory.batchStatusUpdate` | WES 同步批次状态给 Vendor |
| 45 | 5.3 | WMS -> Vendor | `/api/v2/automation/tovendor/basic/inventory/query_sku_batch_inventory` | `shopee.basic.inventory.querySkuBatchInventory` | WES 查询 Vendor 批次库存信息 |
| 46 | 5.4 | WMS -> Vendor | `/api/v2/automation/tovendor/basic/inventory/sync_reconciliation_result` | `shopee.basic.inventory.syncReconciliationResult` | WES 同步库存对账结果给 Vendor |
| 47 | 5.5 | Vendor -> WMS | `/api/v2/automation/toshopee/basic/sku/query_sku_detail` | `shopee.basic.sku.querySkuDetail` | Vendor 查询 WES SKU 信息 |
| 48 | 5.6 | WMS -> Vendor | `/api/v2/automation/tovendor/basic/sku/sync_sku_info` | `shopee.basic.sku.syncSkuInfo` | WES 同步 SKU 信息给 Vendor |
| 49 | 5.7 | WMS -> Vendor | `/api/v2/automation/tovendor/basic/robot/query_agv_status` | `shopee.basic.robot.queryAgvStatus` | WES 查询 Vendor AGV 设备信息 |
| 50 | 5.8 | WMS -> Vendor | `/api/v2/automation/tovendor/basic/inventory/query_vendor_unit_list` | `shopee.basic.inventory.queryVendorUnitList` | WES 查询 Vendor Unit 信息 |
### Reused or Deprecated Title Entries
@@ -141,7 +155,7 @@ Protocol alignment from `docs/Shopee_Automation_Vendor_接入协议手册_出库
## Interface Names
Add constants for all 35 concrete outbound APIs above plus the `4.1` rack-transfer API. The first implementation slice may start with the high-risk sales, wave-number, and rack-transfer sync interfaces, but the constant inventory must stay aligned to the table and to Task 1 Step 1.
Add constants for all 50 concrete APIs above. The first implementation slice may start with the high-risk sales, wave-number, rack-transfer, and basic-data interfaces, but the constant inventory must stay aligned to the table and to Task 1 Step 1.
Two `cancel_order` protocol paths exist with different directions, so they use separate WES API identifiers: `cancelOrderToVendor` for `tovendor` and `vendorCancelOrder` for `toshopee`.
@@ -158,7 +172,7 @@ Use these names as WES internal API identifiers. Shopee does not call WES direct
- [ ] **Step 1: Add constants**
Add the full outbound constant set and the `4.1` rack-transfer constant under `PlatformApiConstants.ShopeeInterfaceType`. The first slice may only implement a subset in `ShopeeInboundApiHandler`, but unimplemented constants must return `ApiMessages.MSG_INTF_0005` until their task lands:
Add the full 50-interface constant set under `PlatformApiConstants.ShopeeInterfaceType`. The first slice may only implement a subset in `ShopeeInboundApiHandler`, but unimplemented constants must return `ApiMessages.MSG_INTF_0005` until their task lands:
```groovy
static final String SALES_CREATE_SUB_PICKING_TASK = 'shopee.outbound.salesorder.createSubPickingTask'
@@ -197,6 +211,20 @@ static final String MTO_BIND_PICKING_TASK = 'shopee.outbound.mto.bindPickingTask
static final String MTO_SYNC_PICKING_DETAIL = 'shopee.outbound.mto.syncPickingDetail'
static final String MTO_COMPLETE_PICKING_TASK = 'shopee.outbound.mto.completePickingTask'
static final String RACK_TRANSFER_CREATE_RT_ORDER = 'shopee.inventory.racktransfer.createRtOrder'
static final String RACK_TRANSFER_OCCUPY_DEVICE = 'shopee.inventory.racktransfer.occupyDevice'
static final String RACK_TRANSFER_SUBMIT_PICKING_SKU_LIST = 'shopee.inventory.racktransfer.submitPickingSkuList'
static final String RACK_TRANSFER_SYNC_PICKING_SKU_LIST = 'shopee.inventory.racktransfer.syncPickingSkuList'
static final String RACK_TRANSFER_HANDLE_DIFF_STOCK = 'shopee.inventory.racktransfer.handleDiffStock'
static final String RACK_TRANSFER_QUERY_PICKING_LIST = 'shopee.inventory.racktransfer.queryPickingList'
static final String RACK_TRANSFER_UPDATE_RT_ORDER = 'shopee.inventory.racktransfer.updateRtOrder'
static final String BASIC_USER_QUERY_USER_EXIST = 'shopee.basic.user.queryUserExist'
static final String BASIC_INVENTORY_BATCH_STATUS_UPDATE = 'shopee.basic.inventory.batchStatusUpdate'
static final String BASIC_INVENTORY_QUERY_SKU_BATCH_INVENTORY = 'shopee.basic.inventory.querySkuBatchInventory'
static final String BASIC_INVENTORY_SYNC_RECONCILIATION_RESULT = 'shopee.basic.inventory.syncReconciliationResult'
static final String BASIC_SKU_QUERY_SKU_DETAIL = 'shopee.basic.sku.querySkuDetail'
static final String BASIC_SKU_SYNC_SKU_INFO = 'shopee.basic.sku.syncSkuInfo'
static final String BASIC_ROBOT_QUERY_AGV_STATUS = 'shopee.basic.robot.queryAgvStatus'
static final String BASIC_INVENTORY_QUERY_VENDOR_UNIT_LIST = 'shopee.basic.inventory.queryVendorUnitList'
```
- [ ] **Step 2: Add DTO shells**
@@ -756,7 +784,7 @@ cd C:\work\gitlab\shopee\wes-loghub
.\gradlew :wms-wave:compileGroovy --no-problems-report
```
### Task 9: Implement 4.1 Rack-Transfer Create RT Order Sync
### Task 9A: Implement Inventory and Basic Interfaces 4.1-5.8
**Files:**
- Modify: `C:\work\gitlab\shopee\wes-loghub\wms-transfer\src\main\groovy\com\ittx\wms\transfer\service\TransferOrderHeaderService.groovy`
@@ -773,7 +801,7 @@ rg -n "locate|定位|lock|锁定|TransferOrderHeader|TransferOrderDetail" C:\wor
Use the existing point where the WES rack-transfer order has been created and inventory has been reserved/locked. Do not call Vendor before WES has a durable `rt_order_id`.
- [ ] **Step 2: Build the 4.1 request body from existing transfer data**
- [ ] **Step 2: Build the 4.1 WMS-to-Vendor request body from existing transfer data**
Request shape:
@@ -801,7 +829,29 @@ Request shape:
If `urgent_flag` or `oos_order_qty` is not represented on current transfer entities, omit that attr item instead of adding a field. Keep `ticket_type = 6` fixed for Rack Transfer.
- [ ] **Step 3: Call edi-shopee internal endpoint**
- [ ] **Step 3: Add 4.2-4.5 Vendor-to-WES rack-transfer handlers**
Expose these Shopee-facing `edi-shopee` endpoints and forward them to WES `ShopeeInboundApiHandler`:
| Section | Path | WES api |
| --- | --- | --- |
| 4.2 | `/api/v2/automation/toshopee/inventory/racktransfer/occupy_device` | `shopee.inventory.racktransfer.occupyDevice` |
| 4.3 | `/api/v2/automation/toshopee/inventory/racktransfer/submit_picking_sku_list` | `shopee.inventory.racktransfer.submitPickingSkuList` |
| 4.4 | `/api/v2/automation/toshopee/inventory/racktransfer/sync_picking_sku_list` | `shopee.inventory.racktransfer.syncPickingSkuList` |
| 4.5 | `/api/v2/automation/toshopee/inventory/racktransfer/handle_diff_stock` | `shopee.inventory.racktransfer.handleDiffStock` |
Route to existing WES transfer/inventory services first. Add new service methods only when existing transfer APIs cannot express the protocol action.
- [ ] **Step 4: Add 4.6-4.7 WMS-to-Vendor rack-transfer calls**
Use internal `edi-shopee` endpoints for:
| Section | Internal endpoint | Shopee path |
| --- | --- | --- |
| 4.6 | `/internal/shopee/automation/rackTransfer/queryPickingList` | `/api/v2/automation/tovendor/inventory/racktransfer/query_picking_list` |
| 4.7 | `/internal/shopee/automation/rackTransfer/updateRtOrder` | `/api/v2/automation/tovendor/inventory/racktransfer/update_rt_order` |
Keep the `4.1` internal endpoint:
Use the same internal client pattern as wave-number and wave-bind calls:
@@ -820,13 +870,41 @@ Failure handling:
- For retryable Shopee errors `-10013099` or timeout, record process history and let existing retry infrastructure retry the sync.
- For non-retryable errors `-10013001`, `-10013023`, `-10013049`, `-10013098`, record the response and block/flag the transfer order according to the current WES transfer failure pattern.
- [ ] **Step 4: Compile transfer and API modules**
- [ ] **Step 5: Add 5.1 and 5.5 Vendor-to-WES basic handlers**
Expose Shopee-facing `edi-shopee` endpoints and forward to WES:
| Section | Path | WES api |
| --- | --- | --- |
| 5.1 | `/api/v2/automation/toshopee/basic/user/query_user_exist` | `shopee.basic.user.queryUserExist` |
| 5.5 | `/api/v2/automation/toshopee/basic/sku/query_sku_detail` | `shopee.basic.sku.querySkuDetail` |
Reuse existing WES user and SKU services. Do not create duplicate user/SKU lookup SQL if a service already exists.
- [ ] **Step 6: Add 5.2-5.4 and 5.6-5.8 WMS-to-Vendor basic calls**
Use internal `edi-shopee` endpoints for:
| Section | Internal endpoint | Shopee path |
| --- | --- | --- |
| 5.2 | `/internal/shopee/automation/basic/inventory/batchStatusUpdate` | `/api/v2/automation/tovendor/basic/inventory/batch_status_update` |
| 5.3 | `/internal/shopee/automation/basic/inventory/querySkuBatchInventory` | `/api/v2/automation/tovendor/basic/inventory/query_sku_batch_inventory` |
| 5.4 | `/internal/shopee/automation/basic/inventory/syncReconciliationResult` | `/api/v2/automation/tovendor/basic/inventory/sync_reconciliation_result` |
| 5.6 | `/internal/shopee/automation/basic/sku/syncSkuInfo` | `/api/v2/automation/tovendor/basic/sku/sync_sku_info` |
| 5.7 | `/internal/shopee/automation/basic/robot/queryAgvStatus` | `/api/v2/automation/tovendor/basic/robot/query_agv_status` |
| 5.8 | `/internal/shopee/automation/basic/inventory/queryVendorUnitList` | `/api/v2/automation/tovendor/basic/inventory/query_vendor_unit_list` |
These calls stay in `edi-shopee`; WES triggers them through internal endpoints when the corresponding business event or reconciliation job runs.
- [ ] **Step 7: Compile transfer, API, inventory, and edi-shopee modules**
Run:
```powershell
cd C:\work\gitlab\shopee\wes-loghub
.\gradlew :wms-transfer:compileGroovy :wms-api:compileGroovy --no-problems-report
cd C:\work\gitlab\shopee\edi-shopee
.\gradlew compileGroovy
```
### Task 9: Add Sales Order and Demand Pool Interfaces
@@ -946,9 +1024,11 @@ Expected:
- `shipment_detail` rows exist.
- Duplicate request is idempotent.
- [ ] **Step 4: Manual 4.1 WES-to-Vendor smoke test**
- [ ] **Step 4: Manual 4.1-5.8 smoke tests**
Trigger or post the internal `edi-shopee` endpoint with a rack-transfer body:
Trigger or post representative `edi-shopee` endpoints from each added module.
4.1 WMS-to-Vendor rack-transfer body:
```powershell
Invoke-RestMethod `
@@ -973,6 +1053,34 @@ Expected:
- Shopee success maps to CBT success.
- Retryable `-10013099` remains retryable.
Vendor-to-WES samples:
```powershell
Invoke-RestMethod `
-Method Post `
-Uri 'http://localhost:9210/api/v2/automation/toshopee/inventory/racktransfer/occupy_device' `
-ContentType 'application/json' `
-Headers @{ Authorization = '<valid-shopee-jwt>' } `
-Body '<4.2 json body from protocol>'
Invoke-RestMethod `
-Method Post `
-Uri 'http://localhost:9210/api/v2/automation/toshopee/basic/user/query_user_exist' `
-ContentType 'application/json' `
-Headers @{ Authorization = '<valid-shopee-jwt>' } `
-Body '<5.1 json body from protocol>'
```
WMS-to-Vendor basic-data samples:
```powershell
Invoke-RestMethod `
-Method Post `
-Uri 'http://localhost:9210/internal/shopee/automation/basic/sku/syncSkuInfo' `
-ContentType 'application/json' `
-Body '<5.6 json body from protocol>'
```
- [ ] **Step 5: Manual internal WES smoke tests**
Use the WES sync API only as an internal verification target:
@@ -1003,7 +1111,7 @@ Update:
## Self-Review
- Spec coverage: Covers `edi-shopee` as Shopee-facing entry, WES field mapping, wave number request, wave binding, user-confirmed `4.1` rack-transfer sync, JWT ownership in `edi-shopee`, and verification.
- Scope control: Excludes inbound/basic modules and excludes inventory except `4.1`; avoids adding fields unless absent fields are explicitly confirmed as required.
- Spec coverage: Covers `edi-shopee` as Shopee-facing entry, WES field mapping, wave number request, wave binding, all concrete interfaces from `3.1`-`3.4`, `4.1`-`4.7`, and `5.1`-`5.8`, JWT ownership in `edi-shopee`, and verification.
- Scope control: Excludes inbound module interfaces; includes outbound, inventory/rack-transfer, and basic-data interfaces from this protocol file; avoids adding fields unless absent fields are explicitly confirmed as required.
- Type consistency: DTO names and handler method names match task references.
- Confirmed entry contract: Shopee 调 `edi-shopee`，`edi-shopee` 再转发到 WES `/api/wms/api/sync/in?api=shopee...`，WES 不直接作为 Shopee 外部入口。