From ad443f0bc9a52b8839924f7d6ced91cb642a4831 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9B=BE=E5=BF=97=E5=A8=81?= Date: Thu, 4 Jun 2026 15:37:28 +0800 Subject: [PATCH] docs: align shopee protocol interface inventory --- ...6-06-04-shopee-outbound-api-wes-mapping.md | 148 +++++++++++++++--- 1 file changed, 128 insertions(+), 20 deletions(-) diff --git a/superpowers/plans/2026-06-04-shopee-outbound-api-wes-mapping.md b/superpowers/plans/2026-06-04-shopee-outbound-api-wes-mapping.md index b0a505d..a1f63c0 100644 --- a/superpowers/plans/2026-06-04-shopee-outbound-api-wes-mapping.md +++ b/superpowers/plans/2026-06-04-shopee-outbound-api-wes-mapping.md @@ -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 = '' } ` + -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 = '' } ` + -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 外部入口。