814 lines
36 KiB
Markdown
814 lines
36 KiB
Markdown
# 接口文档：反查 Shopee 入库任务列表
|
||
|
||
> 接口地址：`POST /api/wms/schedule/searchShopeeInboundOrderList`
|
||
> 模块：`wms-schedule`（计划任务入口）/ `wms-api`（异步消费）/ `wms-receiving`（业务处理）
|
||
> 业务域：Shopee 2.5 WES 反查入库任务
|
||
|
||
---
|
||
|
||
## 1. 功能概述
|
||
|
||
定时（或手工触发）反向调用 Shopee，按入库任务号查询 Shopee 侧**最新任务状态**，并将结果回写、应用到本地入库单（Receipt）。
|
||
|
||
适用场景：
|
||
|
||
- 本地存在未完成（未关闭）的 Shopee 入库单，需要周期性反查上游状态（如明细变更、任务被取消等）。
|
||
- 多仓库场景：不指定 `warehouseCode` 时，自动遍历所有启用仓库逐仓反查。
|
||
|
||
底层对接的 Shopee 协议：**`2_5_shopee_inbound_order_searchInboundOrderList`**。
|
||
|
||
---
|
||
|
||
## 2. 调用链（请求流转）
|
||
|
||
```
|
||
HTTP POST /api/wms/schedule/searchShopeeInboundOrderList
|
||
│
|
||
▼
|
||
ScheduleApiController.process() ← 路由分发
|
||
通过反射调用方法名 == {type}（即 searchShopeeInboundOrderList）
|
||
│
|
||
▼
|
||
ScheduleApiController.searchShopeeInboundOrderList() ← 组装 AisMessage（异步）
|
||
msg.queue = "wms.api.searchShopeeInboundOrderList"
|
||
msgSender.sendMessage(msg) → 同步返回 success
|
||
│
|
||
▼ （异步消费队列）
|
||
SearchShopeeInboundOrderList.process() ← @AisConsumer(queue=...)
|
||
insertLog { shopeeInboundService.searchInboundOrderList(session, body) }
|
||
│
|
||
▼
|
||
ShopeeInboundService.searchInboundOrderList() ← 入口：单仓/多仓分发
|
||
│
|
||
├─ 指定 warehouseCode → fetchAndApplyInboundTasks()
|
||
└─ 未指定 → 遍历所有启用仓库 → fetchAndApplyInboundTasks()
|
||
│
|
||
▼
|
||
fetchInboundTasks() ← 决定要反查哪些 taskId
|
||
│
|
||
▼
|
||
fetchInboundTasksFromShopee() ← 经 EDI 调用 Shopee 2.5
|
||
│ ediRouteReqService.routeShopeeReq(SEARCH_INBOUND_ORDER_LIST_API, ...)
|
||
▼
|
||
applyFetchedInboundTaskResult() ← 结果落库
|
||
ReceiptInboundOrderService.applyFetchedInboundTaskResult()
|
||
```
|
||
|
||
> 设计要点：HTTP 层只做"投递异步消息"，真正反查与落库在 AIS 消费端执行，避免计划任务 HTTP 请求长时间阻塞。
|
||
|
||
---
|
||
|
||
## 3. 涉及类与文件
|
||
|
||
| 角色 | 文件 |
|
||
|------|------|
|
||
| Controller（HTTP 入口 + 反射分发） | `wms-schedule/.../schedule/controller/ScheduleApiController.groovy` |
|
||
| AIS 消费者（异步处理） | `wms-api/.../api/endpoint/SearchShopeeInboundOrderList.groovy` |
|
||
| 业务服务（反查/应用主逻辑） | `wms-receiving/.../receiving/service/shopee/ShopeeInboundService.groovy` |
|
||
| 落库服务（Receipt 应用） | `wms-receiving/.../receiving/service/ReceiptInboundOrderService.groovy` |
|
||
| EDI 转发 | `wms-general/.../general/service/EdiRouteReqService.groovy` |
|
||
|
||
---
|
||
|
||
## 4. 入口：ScheduleApiController
|
||
|
||
### 4.1 路由分发机制
|
||
|
||
```groovy
|
||
@RestController
|
||
@RequestMapping('/api/wms/schedule')
|
||
class ScheduleApiController extends BaseController {
|
||
|
||
@RequestMapping(value = "{type}")
|
||
ResponseMessage process(HttpServletRequest request, @PathVariable String type,
|
||
@RequestParam(required = false) Map<String, String> params,
|
||
@RequestBody(required = false) Map body) {
|
||
// 用 type 作为方法名反射调用：this.getClass().getMethod(type, ...)
|
||
// 找不到方法 → 返回 MSG_INTF_0003（无法识别的接口操作类型）
|
||
// 调用异常 → 返回 MSG_GNRL_0000（通用错误）
|
||
}
|
||
}
|
||
```
|
||
|
||
- 访问 `/api/wms/schedule/searchShopeeInboundOrderList` 时，`type = "searchShopeeInboundOrderList"`，反射调用同名方法。
|
||
- `params`（query 参数）和 `body`（请求体）都会传入。
|
||
|
||
### 4.2 searchShopeeInboundOrderList 方法
|
||
|
||
```groovy
|
||
ResponseMessage searchShopeeInboundOrderList(TtxSession session, Map<String, String> params, Map body) {
|
||
Map<String, Object> request = ((params ?: [:]) + (body ?: [:])) as Map<String, Object> // 合并 query + body
|
||
String warehouseCode = request.get('warehouseCode') as String
|
||
session.params[WmsConstants.CURRENT_WAREHOUSE] = warehouseCode
|
||
|
||
AisMessage<Map> msg = new AisMessage<>()
|
||
msg.session = session
|
||
msg.msgSubject = warehouseCode
|
||
msg.queue = "wms.api.searchShopeeInboundOrderList"
|
||
msg.body = request
|
||
msgSender.sendMessage(msg) // 异步投递
|
||
return ResponseMessageFactory.success() // 立即返回
|
||
}
|
||
```
|
||
|
||
> 该层仅完成"参数合并 + 仓库上下文设置 + 异步消息投递"，HTTP 调用立即返回成功，不代表业务已处理完成。
|
||
|
||
---
|
||
|
||
## 5. 异步消费：SearchShopeeInboundOrderList
|
||
|
||
```groovy
|
||
@AisConsumer(queue = 'wms.api.searchShopeeInboundOrderList')
|
||
class SearchShopeeInboundOrderList extends AisService<AisMessage<Map>> implements SchedulerLogTrait {
|
||
|
||
@Autowired
|
||
ShopeeInboundService shopeeInboundService
|
||
|
||
@Override
|
||
void process(AisMessage<Map> msg) {
|
||
insertLog(msg.session) {
|
||
shopeeInboundService.searchInboundOrderList(msg.session, msg.body as Map<String, Object>)
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
- 监听队列 `wms.api.searchShopeeInboundOrderList`。
|
||
- 通过 `insertLog`（`SchedulerLogTrait`）包裹执行，自动记录计划任务执行日志。
|
||
|
||
---
|
||
|
||
## 6. 核心业务：ShopeeInboundService
|
||
|
||
核心业务分两个阶段：**①反查 Shopee**（拿到上游最新任务）+ **②应用到本地 Receipt**（对账并落库）。下面逐方法展开到字段级、SQL 级。
|
||
|
||
---
|
||
|
||
### 6.1 searchInboundOrderList —— 单仓 / 多仓分发
|
||
|
||
```groovy
|
||
ResponseMessage searchInboundOrderList(TtxSession session, Map<String, Object> request) {
|
||
String warehouseCode = request.warehouseCode as String
|
||
if (warehouseCode) {
|
||
return fetchAndApplyInboundTasks(session, request) // 单仓
|
||
}
|
||
// 未指定 → 遍历所有启用仓库（status = 1）
|
||
List<Map> whs = whSvc.findMaps([status: 1], ['code'])
|
||
List<Map<String, Object>> results = []
|
||
for (Map wh : whs) {
|
||
String code = wh.code as String
|
||
Map warehouseRequest = (request + [warehouseCode: code]) as Map<String, Object>
|
||
session.params[CURRENT_WAREHOUSE] = code // 每仓切换上下文
|
||
ResponseMessage rsp = fetchAndApplyInboundTasks(session, warehouseRequest)
|
||
results << [warehouseCode: code, success: !rsp.hasError(), message: rsp.msg, data: rsp.data]
|
||
}
|
||
return ResponseMessageFactory.success(results)
|
||
}
|
||
```
|
||
|
||
要点：
|
||
- 多仓遍历时**任一仓库失败不会中断其它仓**，结果按仓库维度汇总；多仓总响应仍为 `success`，单仓错误体现在 `results[i].success/message`。
|
||
- 单仓路径直接返回 `fetchAndApplyInboundTasks` 的结果（成功或失败）。
|
||
|
||
---
|
||
|
||
### 6.2 fetchAndApplyInboundTasks —— 反查 + 应用（公共入口）
|
||
|
||
```groovy
|
||
private ResponseMessage fetchAndApplyInboundTasks(TtxSession session, Map<String, Object> request) {
|
||
ResponseMessage rsp = fetchInboundTasks(session, request) // ① 反查 Shopee
|
||
if (rsp.hasError()) return rsp
|
||
return receiptInboundOrderSvc.applyFetchedInboundTaskResult( // ② 应用到本地
|
||
session, rsp.data, request.warehouseCode, request.companyCode)
|
||
}
|
||
```
|
||
|
||
> 反查失败直接短路返回，不进入落库阶段。
|
||
|
||
---
|
||
|
||
### 6.3 fetchInboundTasks —— 确定要反查哪些任务号
|
||
|
||
```groovy
|
||
ResponseMessage fetchInboundTasks(TtxSession session, Map<String, Object> request) {
|
||
String warehouseCode = request.get('warehouseCode')
|
||
String companyCode = request.get('companyCode')
|
||
if (!warehouseCode) return error('warehouseCode不能为空')
|
||
|
||
// 是否显式指定了 taskIdList
|
||
boolean searchByTaskIds = request.containsKey('taskIdList') && request.get('taskIdList') != null
|
||
List<String> taskIds = normalizeList(request.get('taskIdList')) // 去重 + 去空
|
||
if (searchByTaskIds && !taskIds) return error('taskIdList不能为空')
|
||
|
||
// 未指定 → 从本地未完成 Shopee 入库单中领取一批
|
||
if (!taskIds) {
|
||
Integer months = resolveCreatedWithinMonths(request.get('createdWithinMonths')) // 默认 6
|
||
taskIds = findUnfinishedReceiptCodes(warehouseCode, companyCode, 50 /*DEFAULT_CLAIM_TASK_COUNT*/, months)
|
||
}
|
||
|
||
if (!taskIds) return success([total: 0, results: []]) // 没有可反查的任务
|
||
if (taskIds.size() > 2000) return error(WmsMessages.MSG_BASE_0024) // 单次上限 2000
|
||
|
||
String ediBaseUrl = ediRouteReqService.resolveEdiBaseUrl(session, SHOPEE_EDI_SERVER_IDENTIFIER)
|
||
Map body = buildInboundTaskSearchRequestBody(warehouseCode, taskIds, request) // {whs_id, task_id_list}
|
||
return fetchInboundTasksFromShopee(session, companyCode, ediBaseUrl, body, searchByTaskIds)
|
||
}
|
||
```
|
||
|
||
`searchByTaskIds` 标志位贯穿后续逻辑：它决定"上游返回空"是否视为错误（见 6.5）。
|
||
|
||
`buildInboundTaskSearchRequestBody` 组装的 Shopee 2.5 请求体：
|
||
|
||
```json
|
||
{ "whs_id": "<warehouseCode>", "task_id_list": ["任务号1", "任务号2", ...] }
|
||
```
|
||
|
||
#### 6.3.1 findUnfinishedReceiptCodes —— 待反查任务的"领取"
|
||
|
||
从本地未完成的 Shopee 入库单中**领**出一批任务号，核心是 **Redis 分布式锁 + `customInboundSearchNextTime` 节流字段**：
|
||
|
||
```groovy
|
||
private List<String> findUnfinishedReceiptCodes(String warehouseCode, String companyCode,
|
||
Integer limit, Integer createdWithinMonths) {
|
||
RLock lock = RedissonLockService.getAndTryLock(
|
||
getLockKey(ReceiptHeader.table, 'shopeeInboundSearch', warehouseCode, companyCode ?: ''))
|
||
if (!lock) return [] // 抢锁失败 → 直接放弃本轮，避免多实例重复领取
|
||
|
||
LocalDateTime now = LocalDateTime.now()
|
||
LocalDateTime createdFrom = now.minusMonths(createdWithinMonths)
|
||
|
||
// 选取条件：
|
||
// warehouseCode = ? [+ companyCode = ? 可选]
|
||
// AND sourceErp = SHOPEE
|
||
// AND trailingSts < CLOSED （未关闭）
|
||
// AND created >= createdFrom （近 N 个月，默认 6）
|
||
// AND (customInboundSearchNextTime IS NULL OR customInboundSearchNextTime <= now) ← 节流：未到下次反查时间
|
||
// 排序：
|
||
// CASE WHEN customInboundSearchNextTime IS NULL THEN 0 ELSE 1 END ← 从未反查过的优先
|
||
// customInboundSearchNextTime, id
|
||
// LIMIT :limit （默认 50）
|
||
|
||
rows = namedTemplate().queryForList(SQL, params)
|
||
|
||
// 关键：领取后立即把 nextTime 推后，避免下一轮被重复选中
|
||
LocalDateTime nextTime = now.plusMinutes(DEFAULT_SEARCH_INTERVAL_MONTHS) // 常量名虽叫 MONTHS，实际 plusMinutes
|
||
rows.each { rhSvc.updateByCondition([customInboundSearchNextTime: nextTime], [id: it.id]) }
|
||
|
||
return rows.collect { it.code } // 返回入库单号（即 Shopee 任务号）
|
||
}
|
||
finally { if (lock) unlock(lock) }
|
||
```
|
||
|
||
设计要点：
|
||
- **Redis 锁粒度**：`(表, 'shopeeInboundSearch', warehouseCode, companyCode)`。同仓同货主同一时间只有一个实例在领取，避免同一批单据被多节点并发反查。
|
||
- **节流字段 `customInboundSearchNextTime`**：领取即推后下次反查时间，降低单据被高频反查；从未反查过的单据（NULL）优先。
|
||
- **抢锁失败即返回空**：当前实例本轮不领取，等下轮再试，保证不重复。
|
||
|
||
#### 6.3.2 resolveCreatedWithinMonths —— 时间范围解析
|
||
|
||
```groovy
|
||
private Integer resolveCreatedWithinMonths(Object value) {
|
||
Integer months = value ? value as Integer : 6 // DEFAULT_CREATED_WITHIN_MONTHS
|
||
return months > 0 ? months : 6 // 非正数回退默认值，避免扫描范围异常
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.4 fetchInboundTasksFromShopee —— 经 EDI 调用 Shopee 2.5
|
||
|
||
```groovy
|
||
private ResponseMessage fetchInboundTasksFromShopee(session, companyCode, ediBaseUrl, requestBody, searchByTaskIds) {
|
||
logInboundTaskSearchStart(session, requestBody, companyCode) // ProcessHistory: "开始"
|
||
|
||
ResponseMessage remoteRsp = ediRouteReqService.routeShopeeReq(
|
||
session,
|
||
'2_5_shopee_inbound_order_searchInboundOrderList', // SEARCH_INBOUND_ORDER_LIST_API
|
||
requestBody,
|
||
receiptDataWrapperListType(), // List<ReceiptDataWrapper>
|
||
ediBaseUrl)
|
||
|
||
if (remoteRsp.hasError()) {
|
||
logInboundTaskSearchResult(session, requestBody, remoteRsp, companyCode, null) // "失败"
|
||
return remoteRsp
|
||
}
|
||
|
||
// 关键分支：显式按 taskIdList 查询，但上游无任何返回 → 判定为"任务在上游已不存在"
|
||
if (searchByTaskIds && !hasRemoteReceiptData(remoteRsp.data)) {
|
||
ResponseMessage rsp = error('未查询到入库任务')
|
||
logInboundTaskSearchResult(session, requestBody, rsp, companyCode, remoteRsp.data)
|
||
return rsp
|
||
}
|
||
|
||
logInboundTaskSearchResult(session, requestBody, remoteRsp, companyCode, remoteRsp.data) // "完成"
|
||
return remoteRsp
|
||
}
|
||
```
|
||
|
||
- 返回类型用 Jackson `List<ReceiptDataWrapper>` 泛型解析，EDI 侧返回的 JSON 直接映射成本地领域包装类。
|
||
- `searchByTaskIds` 与自动领取的差异：自动领取若上游返回空（任务可能已完成关闭），不报错；显式按 ID 查返回空则视为异常。
|
||
|
||
#### 6.4.1 日志埋点（logInboundTaskSearchStart / Result）
|
||
|
||
通过 `ProcessHistoryService.logProcess` 写入处理历史，关键参数：
|
||
|
||
| 项 | 值 |
|
||
|----|----|
|
||
| `type` | `WmsConstants.ProcessHistoryType.RECEIPT` |
|
||
| `action` | `UPDATE` |
|
||
| `refType` | `'ShopeeInboundOrderSearch'` |
|
||
| `refId` | warehouseCode |
|
||
| `companyCode` | 货主 |
|
||
| `count` | `task_id_list.size()` |
|
||
| `result` | 成功为返回总数，失败为错误信息 |
|
||
| `level` | 成功 INFO / 失败 ERROR |
|
||
|
||
日志消息模板：
|
||
- 开始：`Shopee反查入库任务开始，仓库：{0}，货主：{1}，任务号数量：{2}`
|
||
- 成功：`Shopee反查入库任务完成，仓库：{0}，货主：{1}，任务号数量：{2}，返回总数：{3}`
|
||
- 失败：`Shopee反查入库任务失败，仓库：{0}，货主：{1}，任务号数量：{2}，错误信息：{3}`
|
||
|
||
> 日志写入用 try-catch 包裹，**日志失败绝不影响反查主流程**。
|
||
|
||
#### 6.4.2 EDI 转发（EdiRouteReqService.routeShopeeReq）
|
||
|
||
```groovy
|
||
static final String SHOPEE_EDI_SERVER_IDENTIFIER = 'shopee-edi-wms'
|
||
static final String SHOPEE_ROUTE_REQ_PATH = 'api/edi/shopee/routeReq'
|
||
static final String SHOPEE_EDI_CUSTOMER_ID = 'shopee'
|
||
|
||
ResponseMessage routeShopeeReq(session, api, requestBody, JavaType dataType, baseUrl) {
|
||
return routeReq(session, SHOPEE_EDI_SERVER_IDENTIFIER, SHOPEE_ROUTE_REQ_PATH,
|
||
api, requestBody, SHOPEE_EDI_CUSTOMER_ID, baseUrl, dataType)
|
||
}
|
||
```
|
||
|
||
WES 只负责把请求体交给 EDI 的 `api/edi/shopee/routeReq`，由 EDI 完成 Shopee 平台协议转换、签名、HTTP 转发和响应解析。
|
||
|
||
---
|
||
|
||
## 7. 结果落库：ReceiptInboundOrderService
|
||
|
||
反查拿到 `List<ReceiptDataWrapper>` 后，进入对账落库阶段。这是最复杂的部分，涉及**三层锁、明细级对账、数量重算、UID 清理、整单删除**。
|
||
|
||
### 7.1 applyFetchedInboundTaskResult —— 列表层
|
||
|
||
```groovy
|
||
ResponseMessage applyFetchedInboundTaskResult(TtxSession session, Object data,
|
||
String warehouseCode, String companyCode) {
|
||
List<ReceiptDataWrapper> receipts = convertToReceiptDataWrapperList(data) // List 或单对象统一成列表
|
||
if (!receipts) return error('未查询到入库任务')
|
||
|
||
receipts.each { removeOutboundSerialNumbers(it) } // ★ 数据清洗：过滤已出库 UID
|
||
|
||
List<Map<String, Object>> results = []
|
||
StringBuilder errors = new StringBuilder()
|
||
for (ReceiptDataWrapper receipt : receipts) {
|
||
ReceiptHeader header = receipt?.header?.receiptHeader
|
||
fillFetchedInboundTaskHeaderDefaults(header, warehouseCode, companyCode) // 补默认仓/货主
|
||
ResponseMessage rsp = applyFetchedInboundTaskReceipt(session, receipt) // 单据级应用
|
||
results << [code: header?.code, success: !rsp.hasError(), message: rsp.msg]
|
||
if (rsp.hasError()) errors.append(rsp.msg)
|
||
}
|
||
|
||
if (errors) return error(errors.toString()) // 任一单据失败 → 整体失败，错误聚合
|
||
return success([total: receipts.size(), results: results])
|
||
}
|
||
```
|
||
|
||
#### 7.1.1 removeOutboundSerialNumbers —— UID 清洗
|
||
|
||
递归过滤掉状态为 `OUTBOUND`（已出库）的 UID，避免上游回传或本地缓存的脏 UID 被写回：
|
||
|
||
```groovy
|
||
private void removeOutboundSerialNumbers(ReceiptDataWrapper receipt) {
|
||
receipt?.serialNumbers = filterAvailable(receipt?.serialNumbers)
|
||
receipt?.details?.each { detail ->
|
||
detail.serialNumbers = filterAvailable(detail?.serialNumbers)
|
||
detail.containers?.each { container ->
|
||
container.serialNumbers = filterAvailable(container?.serialNumbers) // 头/明细/容器三层全清
|
||
}
|
||
}
|
||
}
|
||
// filterAvailable: findAll { it.status != SerialNumberStatus.OUTBOUND }
|
||
```
|
||
|
||
> 与列表层不同：多单据中**任一单据失败会导致整批返回 error**（错误信息拼接）。这是与 6.1 多仓遍历"单仓失败不影响其它仓"的显著区别。
|
||
|
||
---
|
||
|
||
### 7.2 applyFetchedInboundTaskReceipt —— 单据级（第二层锁）
|
||
|
||
```groovy
|
||
private ResponseMessage applyFetchedInboundTaskReceipt(TtxSession session, ReceiptDataWrapper receiptData) {
|
||
ReceiptHeader h = receiptData?.header?.receiptHeader
|
||
if (!h?.warehouseCode || !h.companyCode || !h.code) return error(INVALID_MESSAGE_BODY)
|
||
|
||
RLock lock = null
|
||
try {
|
||
lock = rhSvc.tryLockByCode(h.warehouseCode, h.companyCode, h.code) // ★ 按单号锁
|
||
if (!lock) return error(WmsMessages.MSG_GNRL_0003) // 锁占用 → 失败
|
||
return doApplyFetchedInboundTaskReceipt(session, receiptData, h)
|
||
} finally {
|
||
if (lock) unlock(lock)
|
||
}
|
||
}
|
||
```
|
||
|
||
锁粒度：`(warehouseCode, companyCode, code)`，即**按入库单号串行化**，防止同一单据被并发反查/收货/上架交叉修改。
|
||
|
||
---
|
||
|
||
### 7.3 doApplyFetchedInboundTaskReceipt —— 单据对账主流程
|
||
|
||
```groovy
|
||
private ResponseMessage doApplyFetchedInboundTaskReceipt(session, receiptData, incomingHeader) {
|
||
// 1. 定位本地入库单
|
||
Map cv = [warehouseCode: incomingHeader.warehouseCode, code: incomingHeader.code]
|
||
if (incomingHeader.companyCode) cv.companyCode = incomingHeader.companyCode
|
||
ReceiptHeader receipt = rhSvc.findFirstEntity(cv)
|
||
if (!receipt) return error(MSG_INBD_0003) // 本地无此单
|
||
|
||
// 2. 可用性校验（如是否被锁定/作废）
|
||
ResponseMessage availableRsp = rhSvc.checkIsAvailable(session, receipt)
|
||
if (availableRsp.hasError()) return availableRsp
|
||
|
||
// 3. 加载本地明细 + 上游明细，按键匹配
|
||
List<ReceiptDetail> localDetails = rdSvc.findEntities([receiptId: receipt.id])
|
||
Map<String, ReceiptDetailDataWrapper> incomingMap = buildFetchedTaskDetailMap(receiptData.details)
|
||
Map<String, ReceiptDetail> localMap = buildLocalFetchedTaskDetailMap(localDetails)
|
||
|
||
// ★ 上游有而本地没有的明细 → 直接整体失败（不允许凭空新增明细）
|
||
if (incomingMap.keySet().any { key -> !localMap.containsKey(key) }) {
|
||
return error(MSG_INBD_0004)
|
||
}
|
||
|
||
// 4. 逐明细对账
|
||
List<String> syncedDetailIds = [], deletedDetailIds = []
|
||
for (ReceiptDetail localDetail : localDetails) {
|
||
ReceiptDetailDataWrapper incoming = incomingMap[fetchedTaskDetailKey(localDetail)]
|
||
ResponseMessage<FetchedTaskApplyPlan> planRsp = buildFetchedTaskApplyPlan(receipt, localDetail, incoming)
|
||
if (planRsp.hasError()) return planRsp
|
||
if (!shouldApplyFetchedTaskDetail(planRsp.data)) continue // 无变化跳过
|
||
|
||
// ★ 第三层锁：明细级
|
||
RLock detailLock = getAndTryLock(rdSvc.getLockKey(session, localDetail.id))
|
||
if (!detailLock) return error(MSG_GNRL_0003)
|
||
try {
|
||
// 锁内重新加载，避免并发漂移（双重检查）
|
||
localDetail = rdSvc.getEntity(localDetail.id)
|
||
incoming = incomingMap[fetchedTaskDetailKey(localDetail)]
|
||
planRsp = buildFetchedTaskApplyPlan(receipt, localDetail, incoming)
|
||
if (planRsp.hasError()) return planRsp
|
||
if (!shouldApplyFetchedTaskDetail(planRsp.data)) continue
|
||
|
||
if (incoming?.receiptDetail) {
|
||
applyFetchedTaskReturnedDetail(receipt, localDetail, incoming, planRsp.data) // 上游有 → 同步
|
||
syncedDetailIds << localDetail.id
|
||
} else {
|
||
ResponseMessage rsp = applyFetchedTaskMissingDetail(receipt, localDetail, planRsp.data) // 上游无 → 删/调
|
||
if (rsp.hasError()) return rsp
|
||
if ((rsp.data as Map)?.deleted) deletedDetailIds << localDetail.id
|
||
}
|
||
} finally {
|
||
if (detailLock) unlock(detailLock)
|
||
}
|
||
}
|
||
|
||
// 5. 整单是否应删除（所有明细都没了）
|
||
if (shouldDeleteFetchedTaskReceipt(receipt.id)) {
|
||
deleteFetchedTaskReceiptRelatedData(receipt.id)
|
||
receipt = rhSvc.getEntity(receipt.id)
|
||
ResponseMessage rsp = rhSvc.deleteEntity(receipt)
|
||
if (rsp.hasError()) return rsp
|
||
return success([deleted: true, syncedDetailIds: syncedDetailIds, deletedDetailIds: deletedDetailIds])
|
||
}
|
||
|
||
// 6. 刷新单据状态 + 统计
|
||
rhSvc.updateStatus(session, receipt.id)
|
||
rhSvc.updateStatistics(session, receipt.id)
|
||
return success([syncedDetailIds: syncedDetailIds, deletedDetailIds: deletedDetailIds])
|
||
}
|
||
```
|
||
|
||
#### 7.3.1 明细匹配键 fetchedTaskDetailKey
|
||
|
||
```groovy
|
||
private String fetchedTaskDetailKey(ReceiptDetail detail) {
|
||
return detail?.itemCode ? "${detail.itemCode}|${detail.batch ?: ''}" : null
|
||
}
|
||
```
|
||
|
||
- **匹配维度 = itemCode + batch**。同一 itemCode + batch 视为同一明细行。
|
||
- map 构建时 `if (!result.containsKey(key))` 保证**首次出现优先**，重复键忽略。
|
||
|
||
#### 7.3.2 双重检查（锁外 + 锁内）
|
||
|
||
明细对账执行了两次 `buildFetchedTaskApplyPlan`：
|
||
1. **锁外**：快速判断是否需要处理（`shouldApplyFetchedTaskDetail`），无需处理直接跳过，避免无谓加锁。
|
||
2. **锁内**：重新 `getEntity` 拉最新数据再算一次，防止加锁前被其它事务改动造成漂移。
|
||
|
||
这是典型的"先查后锁再查"并发安全模式。
|
||
|
||
---
|
||
|
||
### 7.4 buildFetchedTaskApplyPlan —— 对账计划（核心数量逻辑）
|
||
|
||
逐明细计算"应该怎么改"，输出 `FetchedTaskApplyPlan`：
|
||
|
||
```groovy
|
||
private static class FetchedTaskApplyPlan {
|
||
BigDecimal openQty = 0 // 重算后的待上架数量
|
||
Boolean remoteDetailMissing = false // 上游该明细是否已不存在
|
||
Boolean shouldUpdateQty = false // 是否需要更新数量
|
||
Boolean shouldCheckPendingSerialNumbers = false // 是否需要校验/清理 UID
|
||
}
|
||
```
|
||
|
||
构造逻辑：
|
||
|
||
```groovy
|
||
private ResponseMessage<FetchedTaskApplyPlan> buildFetchedTaskApplyPlan(
|
||
ReceiptHeader localHeader, ReceiptDetail localDetail, ReceiptDetailDataWrapper incoming) {
|
||
|
||
// 分支A：上游该明细已不存在
|
||
if (!incoming?.receiptDetail) {
|
||
FetchedTaskApplyPlan plan = new FetchedTaskApplyPlan(
|
||
openQty: 0,
|
||
remoteDetailMissing: true,
|
||
shouldUpdateQty: shouldUpdateFetchedTaskDetailQty(localDetail, plan_with_openQty_0)
|
||
)
|
||
return success(plan)
|
||
}
|
||
|
||
// 分支B：上游有该明细 → 算数量差额
|
||
BigDecimal remoteUnputawayQty = resolveRemoteUnputawayQty(incoming) // 上游"未上架数量"
|
||
BigDecimal localCheckedInNotPutawayQty = resolveLocalCheckedInNotPutawayQty(localDetail) // 本地"已收货未上架"
|
||
|
||
// ★ 核心保护：上游未上架数 < 本地已收货未上架数 → 数据矛盾，拒绝
|
||
if (remoteUnputawayQty < localCheckedInNotPutawayQty) {
|
||
return error(MSG_INBD_0040)
|
||
}
|
||
|
||
FetchedTaskApplyPlan plan = new FetchedTaskApplyPlan()
|
||
plan.openQty = remoteUnputawayQty - localCheckedInNotPutawayQty // 新的待上架量
|
||
plan.shouldUpdateQty = shouldUpdateFetchedTaskDetailQty(localDetail, plan)
|
||
// 指定UID模式(customSpecifyUid=1) 且上游带回了 UID 列表 → 需要校验
|
||
plan.shouldCheckPendingSerialNumbers =
|
||
(localHeader.customSpecifyUid == 1 && incoming?.serialNumbers != null)
|
||
return success(plan)
|
||
}
|
||
```
|
||
|
||
数量计算的两个关键函数：
|
||
|
||
```groovy
|
||
// 上游未上架数量 = 上游 totalQty - 上游 fulfillQty（已上架），负数归 0
|
||
private BigDecimal resolveRemoteUnputawayQty(ReceiptDetailDataWrapper incoming) {
|
||
BigDecimal remotePutawayQty = toBigDecimal(incoming.receiptDetail.fulfillQty)
|
||
BigDecimal remoteUnputawayQty = toBigDecimal(incoming.receiptDetail.totalQty) - remotePutawayQty
|
||
return remoteUnputawayQty < 0 ? 0 : remoteUnputawayQty
|
||
}
|
||
|
||
// 本地已收货未上架数量 = 本地 fulfillQty(已收货) - 已关闭容器数量(已上架)，负数归 0
|
||
private BigDecimal resolveLocalCheckedInNotPutawayQty(ReceiptDetail localDetail) {
|
||
BigDecimal checkedInQty = toBigDecimal(localDetail.fulfillQty)
|
||
BigDecimal putawayQty = findClosedReceiptContainerQty(localDetail.id) // sum(receipt_container.quantity where status=CLOSED)
|
||
BigDecimal notPutawayQty = checkedInQty - putawayQty
|
||
return notPutawayQty < 0 ? 0 : notPutawayQty
|
||
}
|
||
```
|
||
|
||
`shouldUpdateFetchedTaskDetailQty` —— 判断数量是否真的变了：
|
||
|
||
```groovy
|
||
private Boolean shouldUpdateFetchedTaskDetailQty(ReceiptDetail localDetail, FetchedTaskApplyPlan plan) {
|
||
// 期望的 totalQty = 已收货 + 已拒收 + 新算出的待上架量
|
||
BigDecimal expectedQty = localDetail.fulfillQty + localDetail.rejectedQty + plan.openQty
|
||
// totalQty 或 openQty 任一不一致 → 需要更新
|
||
return !sameQty(localDetail.totalQty, expectedQty) || !sameQty(localDetail.openQty, plan.openQty)
|
||
}
|
||
```
|
||
|
||
`shouldApplyFetchedTaskDetail` —— 是否需要任何处理：
|
||
|
||
```groovy
|
||
private Boolean shouldApplyFetchedTaskDetail(FetchedTaskApplyPlan plan) {
|
||
return plan.remoteDetailMissing || plan.shouldUpdateQty || plan.shouldCheckPendingSerialNumbers
|
||
}
|
||
```
|
||
|
||
> 三个标志位任一为真才处理；若上游和本地完全一致，明细被跳过，减少无谓写入。
|
||
|
||
---
|
||
|
||
### 7.5 applyFetchedTaskReturnedDetail —— 上游有该明细：同步
|
||
|
||
```groovy
|
||
private void applyFetchedTaskReturnedDetail(receipt, localDetail, incoming, plan) {
|
||
if (plan.shouldUpdateQty) updateFetchedTaskDetailQty(localDetail.id, plan.openQty) // 改数量
|
||
if (plan.shouldCheckPendingSerialNumbers) {
|
||
clearFetchedTaskPendingSerialNumbers(receipt, localDetail, collectSerialNumbers(incoming.serialNumbers))
|
||
// 清理本地"待分配(CREATED)"状态的 UID，保留上游回传的 UID 列表
|
||
}
|
||
}
|
||
```
|
||
|
||
`updateFetchedTaskDetailQty` 的 SQL（一次性重算三个数量字段）：
|
||
|
||
```sql
|
||
update receipt_detail
|
||
set totalQty = coalesce(fulfillQty,0) + coalesce(rejectedQty,0) + :openQty,
|
||
quantity = coalesce(fulfillQty,0) + coalesce(rejectedQty,0) + :openQty,
|
||
openQty = :openQty,
|
||
version = version + 1
|
||
where id = :receiptDetailId
|
||
```
|
||
|
||
> `totalQty` 与 `quantity` 同步保持一致，`openQty` 为新的待上架量，版本号自增防并发。
|
||
|
||
---
|
||
|
||
### 7.6 applyFetchedTaskMissingDetail —— 上游无该明细：删 / 调
|
||
|
||
```groovy
|
||
private ResponseMessage applyFetchedTaskMissingDetail(receipt, localDetail, plan) {
|
||
if (isFetchedTaskDetailUnworked(localDetail)) { // 该明细"完全没动过"？
|
||
clearFetchedTaskPendingSerialNumbers(receipt, localDetail) // 先清 UID
|
||
ResponseMessage rsp = rdSvc.deleteEntity(localDetail) // 再删明细
|
||
if (rsp.hasError()) return rsp
|
||
return success([deleted: true])
|
||
}
|
||
// 已动过（收过货/有容器）→ 不能删，只能把 openQty 清零对齐上游
|
||
if (plan.shouldUpdateQty) updateFetchedTaskDetailQty(localDetail.id, plan.openQty) // openQty=0
|
||
return success([deleted: false])
|
||
}
|
||
```
|
||
|
||
`isFetchedTaskDetailUnworked` —— 判断明细是否"原封未动"：
|
||
|
||
```groovy
|
||
private Boolean isFetchedTaskDetailUnworked(ReceiptDetail d) {
|
||
return sameQty(d.fulfillQty, 0) // 未收货
|
||
&& sameQty(d.totalQty, toBigDecimal(d.openQty)) // totalQty == openQty（没收过也没拒过）
|
||
&& !existsReceiptContainer(d.receiptId, d.id) // 没有任何收货容器记录
|
||
}
|
||
```
|
||
|
||
> 设计意图：上游把明细删了，本地若完全没处理过就跟着删；若已经收过货（有容器/有数量），只能把待上架量清零，保留已收货事实，避免库存凭空消失。
|
||
|
||
---
|
||
|
||
### 7.7 shouldDeleteFetchedTaskReceipt —— 整单删除判断
|
||
|
||
```groovy
|
||
private Boolean shouldDeleteFetchedTaskReceipt(Long receiptId) {
|
||
Integer count = template().queryForObject(
|
||
'SELECT COUNT(1) FROM receipt_detail WHERE receiptId = ?', Integer.class, receiptId) ?: 0
|
||
return count == 0 // 明细全被删光 → 整单也删
|
||
}
|
||
```
|
||
|
||
`deleteFetchedTaskReceiptRelatedData` —— 删单前清理关联数据（顺序很重要）：
|
||
|
||
```sql
|
||
delete from receipt_container where receiptId = ?; -- 收货容器
|
||
delete from serial_number where receiptId = ?; -- 序列号
|
||
-- 池子里的不删记录，只解绑：
|
||
update serial_number_pool
|
||
set receiptId = 0, receiptDetailId = 0, receiptCode = null,
|
||
assignedAt = null, assignedBy = null, version = version + 1
|
||
where receiptId = ?;
|
||
```
|
||
|
||
> 容器、UID 先删，再删单头（`rhSvc.deleteEntity`）。`serial_number_pool` 采用**解绑而非删除**，保留池中 UID 供复用。
|
||
|
||
---
|
||
|
||
### 7.8 clearFetchedTaskPendingSerialNumbers —— UID 清理
|
||
|
||
清理本地 `CREATED`（待分配）状态的 UID，可选保留上游回传的 UID：
|
||
|
||
```groovy
|
||
private void clearFetchedTaskPendingSerialNumbers(receipt, localDetail, List<String> keepSerialNumbers = null) {
|
||
// 1. 查出要清的 UID（status=CREATED 且 非保留列表）
|
||
// keepCondition: 若 keepSerialNumbers 非空，加 "AND serialNumber NOT IN (:keep)"
|
||
List<String> clearSerialNumbers = query(...)
|
||
|
||
// 2. 物理删除
|
||
delete from serial_number
|
||
where receiptId = :receiptId and itemCode = :itemCode
|
||
and status = :createdStatus
|
||
and serialNumber in (:clearSerialNumbers)
|
||
}
|
||
```
|
||
|
||
只删 `CREATED` 状态，**不影响已收货/已上架的 UID**。
|
||
|
||
---
|
||
|
||
### 7.9 三层锁总览
|
||
|
||
| 层级 | 锁键 | 作用 |
|
||
|------|------|------|
|
||
| ① 任务领取 | `(receipt_header表, 'shopeeInboundSearch', whsCode, companyCode)` | 防多实例并发领取同一批单据 |
|
||
| ② 单据级 | `(warehouseCode, companyCode, code)` via `rhSvc.tryLockByCode` | 防同一入库单被并发反查/收货/上架 |
|
||
| ③ 明细级 | `rdSvc.getLockKey(session, detailId)` | 防同一明细被并发修改；锁内二次查证 |
|
||
|
||
任一层抢锁失败都直接返回 `MSG_GNRL_0003`（资源占用），不再继续。
|
||
|
||
---
|
||
|
||
### 7.10 落库结果数据流总结
|
||
|
||
```
|
||
List<ReceiptDataWrapper> (上游返回)
|
||
│ removeOutboundSerialNumbers 清洗
|
||
▼
|
||
for each receipt:
|
||
├─ tryLockByCode (单据锁)
|
||
│ ├─ findFirstEntity → 本地无单? → MSG_INBD_0003
|
||
│ ├─ checkIsAvailable → 不可用? → 错误
|
||
│ ├─ 明细键匹配 → 上游多余明细? → MSG_INBD_0004
|
||
│ └─ for each localDetail:
|
||
│ ├─ buildPlan (锁外快判) → 无变化? continue
|
||
│ ├─ getAndTryLock (明细锁) → 抢不到? → MSG_GNRL_0003
|
||
│ │ ├─ getEntity 重载 + buildPlan (锁内复判)
|
||
│ │ ├─ 上游有 → applyReturnedDetail (改数量/清UID) → syncedDetailIds
|
||
│ │ └─ 上游无 → applyMissingDetail (删明细 or openQty=0) → deletedDetailIds?
|
||
│ └─ unlock
|
||
├─ 明细全删? → deleteFetchedTaskReceiptRelatedData + deleteEntity → deleted:true
|
||
└─ else → updateStatus + updateStatistics → synced/deleted ids
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 请求 / 响应
|
||
|
||
### 8.1 HTTP 请求
|
||
|
||
`POST /api/wms/schedule/searchShopeeInboundOrderList`
|
||
|
||
请求体（JSON，query 参数同名亦可）：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `warehouseCode` | string | 否 | 仓库编码。**为空时遍历所有启用仓库**；指定时只处理单仓 |
|
||
| `companyCode` | string | 否 | 货主编码。用于过滤未完成任务领取范围 |
|
||
| `taskIdList` | array\<string\> | 否 | 显式指定要反查的任务号列表。**不传**则自动从本地未完成 Shopee 入库单中领取一批（默认 50 条） |
|
||
| `createdWithinMonths` | integer | 否 | 自动领取时只扫近 N 个月的单据，默认 6，非正数回退到 6 |
|
||
|
||
> 常见调用形态：
|
||
> - 定时任务：不传 `taskIdList`，由系统按节流策略自动领取。
|
||
> - 手工反查：传 `taskIdList` 精确反查某些任务号。
|
||
|
||
### 8.2 HTTP 响应
|
||
|
||
由于 Controller 仅投递异步消息，**HTTP 层固定立即返回成功**：
|
||
|
||
```json
|
||
{ "success": true, "code": "...", "msg": "..." }
|
||
```
|
||
|
||
> 实际反查/落库结果不会通过此 HTTP 响应返回，需通过 `ProcessHistory`（处理历史日志）或队列消费结果观察。日志类型 `ShopeeInboundOrderSearch`，级别 INFO/ERROR，内容包含仓库、货主、任务号数量、返回总数或错误信息。
|
||
|
||
### 8.3 业务层（消费端）返回结构（参考）
|
||
|
||
- 单仓成功：`applyFetchedInboundTaskResult` 返回 `{ total, results: [{code, success, message}] }`
|
||
- 多仓成功：`searchInboundOrderList` 返回 `[{warehouseCode, success, message, data}, ...]`
|
||
|
||
---
|
||
|
||
## 9. 关键设计点与约束
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| 异步化 | HTTP 入口只投递 `AisMessage`，重逻辑在 `wms.api.searchShopeeInboundOrderList` 队列消费端执行，避免计划任务超时 |
|
||
| 单次任务上限 | `MAX_SEARCH_TASK_COUNT = 2000`，超出返回 `MSG_BASE_0024` |
|
||
| 默认领取数 | `DEFAULT_CLAIM_TASK_COUNT = 50`（未指定 taskIdList 时每轮领取条数） |
|
||
| 反查节流 | 通过 `ReceiptHeader.customInboundSearchNextTime` 实现；领取后推进下次时间，降低重复反查 |
|
||
| 并发控制 | 三层锁：领取阶段 Redis 锁（按仓库+货主）；应用阶段按入库单号锁；明细应用阶段按明细锁 |
|
||
| 数据来源 | `sourceErp = SHOPEE` 过滤；仅处理 Shopee 来源单据 |
|
||
| 数据清洗 | 落库前 `removeOutboundSerialNumbers` 过滤已出库 UID，避免脏数据回写 |
|
||
| 容错 | 反查过程日志失败不影响主流程（`logInboundTaskSearchProcess` 内部 catch Throwable） |
|
||
| 上游协议 | Shopee `2_5_shopee_inbound_order_searchInboundOrderList`；请求体 `{whs_id, task_id_list}`；返回 `List<ReceiptDataWrapper>` |
|
||
| 边界 | 显式 `taskIdList` 查询且上游返回空 → 视为"未查询到入库任务"错误 |
|
||
|
||
---
|
||
|
||
## 10. 配套接口（同模块相关）
|
||
|
||
| 方法 | 用途 |
|
||
|------|------|
|
||
| `searchInboundOrderByCode` | 按单个本地入库单号反查并应用（封装成单元素 taskIdList） |
|
||
| `fetchInboundOrder` | 按搜索码（容器号/单号）向 Shopee 拉单，**只查不存** |
|
||
| `requestInboundOrder` | `fetchInboundOrder` + `save`，拉取并落库 |
|
||
| `searchInboundOrderListToWms` | 反向：Shopee 查询 WES 本地任务（Shopee 2.3 协议），查本地 `ReceiptHeader/Detail` 返回 |
|
||
| `submitPutaway` | 上架确认回传 Shopee（2.7 协议） |
|
||
| `checkUidList` | 批量校验待上架 UID（2.9 协议） |
|
||
| `applyUpdatedInboundOrder` | Shopee 下发入库单变更（2.2 协议） |
|
||
|
||
---
|
||
|
||
*文档基于源码生成，涉及类：`ScheduleApiController` / `SearchShopeeInboundOrderList` / `ShopeeInboundService` / `ReceiptInboundOrderService` / `EdiRouteReqService`。*
|