feat(selfop): add bounded inventory flow diagnostic through account egress

2026-10-15 11:37:49 +08:00
parent e19d303a76
commit d81d9cbda4
16 changed files with 365 additions and 5 deletions
@@ -78,6 +78,15 @@ public class LingxingInternalController {
        return ApiResponse.success(client.queryDetail(request, context(context)));
    }

+    @Operation(summary = "单SKU最多31日库存流水诊断，仅第一页最多1000条")
+    @PostMapping("/inventory-flow/query")
+    public ApiResponse<QueryPage<InventoryFlow>> inventoryFlow(
+        @RequestHeader(value="X-Internal-Service-Token",required=false) String token,
+        @RequestHeader(value="X-Lingxing-Egress-Context",required=false) String context,
+        @Valid @RequestBody InventoryFlowRequest request) {
+        tokenGuard.verify(token);return ApiResponse.success(client.queryInventoryFlow(request,context(context)));
+    }
+
    @Operation(summary = "读取单仓全部货主、全部品质且保留零库存的产品库存单页")
    @PostMapping("/product-inventory/query")
    public ApiResponse<QueryPage<ProductStock>> inventory(
@@ -6,7 +6,7 @@ import java.time.Instant;
 public final class LingxingEgressDtos {
    private LingxingEgressDtos() { }
    public enum CollectionMode { OFF, VALIDATION, BUSINESS }
-    public enum Operation { WAREHOUSES, OUTBOUND_QUERY, OUTBOUND_LOCATE, OUTBOUND_DETAIL, PRODUCT_INVENTORY, CUSTOMERS, PRODUCTS }
+    public enum Operation { WAREHOUSES, OUTBOUND_QUERY, OUTBOUND_LOCATE, OUTBOUND_DETAIL, PRODUCT_INVENTORY, CUSTOMERS, PRODUCTS, INVENTORY_FLOW }
    public record EgressContext(String sourceAccount, CollectionMode executionPurpose, String rootTaskId,
                                String sessionId, String attemptId, String exclusiveGrantId) {
        public boolean wellFormed() {
@@ -20,6 +20,12 @@ public final class LingxingWmsDtos {

    public record WarehouseQueryRequest(@Min(1) int current, @Min(1) @Max(1000) int size) { }
    public record ProductQueryRequest(@Min(1) int current, @Min(1) @Max(100) int size) { }
+    public record InventoryFlowRequest(@NotBlank @Size(max=64) String warehouseCode,
+        @NotBlank @Size(max=64) String customerCode, @NotBlank @Size(max=128) String sku,
+        @NotNull LocalDateTime startTime, @NotNull LocalDateTime endTime) { }
+    public record InventoryFlow(String id, String customerCode, String whCode, String productSku,
+        String cellNo, String innerBatchNo, String billNo, String billType, Integer productQuality,
+        BigDecimal bookQty, String bookChangQty, BigDecimal closeQty, String createTime) { }
    public record Customer(String customerCode, String customerName, String status) { }
    public record Product(String customerCode, String sku, String productName,
                          BigDecimal length, BigDecimal width, BigDecimal height, String sizeUnit,
@@ -162,6 +162,30 @@ public final class LingxingWmsClient {
            (data, metadata) -> inventory(data, request, metadata));
    }

+    /** Single bounded diagnostic page; never changes the current-inventory collection protocol. */
+    public QueryPage<InventoryFlow> queryInventoryFlow(InventoryFlowRequest request, EgressContext context) {
+        if(request==null)throw badRequest();
+        requireInput(request.warehouseCode(),64);requireInput(request.customerCode(),64);requireInput(request.sku(),128);
+        if(request.startTime()==null||request.endTime()==null||!request.startTime().isBefore(request.endTime())
+            ||request.endTime().isAfter(request.startTime().plusDays(31)))throw badRequest();
+        Map<String,Object> body=pagination(1,1000);
+        body.put("whCode",request.warehouseCode());body.put("customerCode",request.customerCode());
+        body.put("barcodeAccurate",request.sku());body.put("startTime",SOURCE_TIME.format(request.startTime()));
+        body.put("endTime",SOURCE_TIME.format(request.endTime()));body.put("sortName","createTime");body.put("sortOrder","asc");
+        return execute("/openapi/v2/stock/stockCellBook/page",body,context,Operation.INVENTORY_FLOW,
+            (data,metadata)->mappedPage(data,1,1000,"current","size",false,metadata,row->{
+                if(!request.warehouseCode().equals(requiredText(row,"whCode",64))
+                    ||!request.customerCode().equals(requiredText(row,"customerCode",64))
+                    ||!request.sku().equals(requiredText(row,"productSku",128)))throw invalidResponse("FLOW_IDENTITY_MISMATCH",200);
+                JsonNode id=row.get("id");
+                if(id==null||!id.isIntegralNumber())throw invalidResponse("FLOW_ID_MISSING",200);
+                return new InventoryFlow(id.asText(),request.customerCode(),request.warehouseCode(),request.sku(),
+                    optionalText(row,"cellNo"),optionalText(row,"innerBatchNo"),optionalText(row,"billNo"),optionalText(row,"billType"),
+                    requiredInt(row.get("productQuality"),"PRODUCT_QUALITY"),quantity(row.get("bookQty")),
+                    optionalText(row,"bookChangQty"),quantity(row.get("closeQty")),optionalText(row,"createTime"));
+            }));
+    }
+
    private QueryPage<ProductStock> inventory(JsonNode data, InventoryQueryRequest request, AttemptMetadata metadata) {
        Set<List<Object>> keys = new HashSet<>();
        return mappedPage(data, request.current(), request.size(), "current", "size", false, metadata, row -> {
@@ -203,6 +227,9 @@ public final class LingxingWmsClient {
            JsonNode json;
            try { json = envelope(response.body()); }
            catch (LingxingWmsException error) {
+                // This optional endpoint may lack permission while ordinary collection remains authorized.
+                if(operation==Operation.INVENTORY_FLOW&&Integer.valueOf(11008).equals(error.sourceCode()))
+                    throw upstreamFailure("FLOW_PERMISSION_DENIED","当前账号没有库存流水接口权限",false,200,11008);
                if (Integer.valueOf(31001).equals(error.sourceCode()) || Integer.valueOf(429).equals(error.sourceCode())) {
                    handle.rateLimited(retryAfter(response));
                }
@@ -51,6 +51,32 @@ x-lastleg-egress-coordination:
 security:
  - InternalServiceToken: []
 paths:
+  /internal/integrations/lingxing/wms/inventory-flow/query:
+    post:
+      summary: One SKU inventory-flow diagnostic page
+      description: >-
+        Calls stock/stockCellBook/page through the existing INVENTORY_FLOW permit. Exact warehouse/customer/SKU,
+        at most 31 days, current=1 and size=1000 fixed. No automatic next page or retry. Source quality and signed
+        quantities are preserved, not translated to inventory-snapshot quality. Source 11008 only rejects this optional
+        operation; authentication, rate-limit and uncertain-result account protection remain effective.
+      parameters:
+        - {$ref: '#/components/parameters/LingxingEgressContext'}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [warehouseCode, customerCode, sku, startTime, endTime]
+              properties:
+                warehouseCode: {type: string, maxLength: 64}
+                customerCode: {type: string, maxLength: 64}
+                sku: {type: string, maxLength: 128}
+                startTime: {type: string, format: date-time, description: Beijing local datetime without offset}
+                endTime: {type: string, format: date-time, description: Beijing local datetime without offset}
+      responses:
+        '200':
+          description: Standard envelope with QueryPage or sanitized ProviderFailure. Flow rows retain id as string, customerCode, whCode, productSku, cellNo, innerBatchNo, billNo, billType, productQuality, numeric bookQty/closeQty, string bookChangQty/createTime. Unknown source fields remain null; no calculated inventory is published.
  /internal/integrations/lingxing/wms/customers/query:
    post:
      summary: Query one page of customers using the existing account egress permit
@@ -315,7 +341,7 @@ components:
        {"current":1,"size":2,"whCode":"WH-DEMO","isHideInventory":0}
    EgressOperation:
      type: string
-      enum: [WAREHOUSES, OUTBOUND_QUERY, OUTBOUND_LOCATE, OUTBOUND_DETAIL, PRODUCT_INVENTORY, CUSTOMERS, PRODUCTS]
+      enum: [WAREHOUSES, OUTBOUND_QUERY, OUTBOUND_LOCATE, OUTBOUND_DETAIL, PRODUCT_INVENTORY, CUSTOMERS, PRODUCTS, INVENTORY_FLOW]
    EgressMetadata:
      type: object
      required: [attemptId, actualHttpAttempts, accountPaused]
@@ -311,6 +311,38 @@ class LingxingWmsClientTest {
        response.set(page("current", "size", 1, 1, 1, 1, ORDER).replace("\"code\":200", "\"code\":200,\"success\":" + success));
        assertThrows(LingxingWmsException.class, () -> client().queryPage(query(1, 1), context()));
    }
+    private InventoryFlowRequest flow() {return new InventoryFlowRequest("W-DEMO","C-DEMO","SKU-DEMO",
+        LocalDateTime.of(2026,9,14,8,0),LocalDateTime.of(2026,10,14,8,0));}
+    @Test void flowUsesExactScopeSinglePageAndPreservesSignedChangeAndLargeId() throws Exception {
+        response.set(page("current","size",1,1000,1,1,"""
+            {"id":9223372036854775806,"customerCode":"C-DEMO","whCode":"W-DEMO","productSku":"SKU-DEMO",
+             "productQuality":1,"bookQty":-3,"bookChangQty":"-3","closeQty":17,"createTime":"2026-10-13 12:00:00"}
+            """));
+        var result=client().queryInventoryFlow(flow(),context());
+        assertThat(path.get()).isEqualTo("/openapi/v2/stock/stockCellBook/page");
+        var sent=mapper.readTree(body.get()).path("data");
+        assertThat(sent.path("barcodeAccurate").asText()).isEqualTo("SKU-DEMO");
+        assertThat(sent.path("size").asInt()).isEqualTo(1000);assertThat(sent.has("productQuality")).isFalse();
+        assertThat(result.records().get(0).id()).isEqualTo("9223372036854775806");
+        assertThat(result.records().get(0).bookQty()).isEqualByComparingTo("-3");
+        assertThat(result.records().get(0).bookChangQty()).isEqualTo("-3");assertThat(calls.get()).isEqualTo(1);
+        assertThat(completion.get().operation()).isEqualTo(Operation.INVENTORY_FLOW);
+    }
+    @Test void flowPermissionDenialIsScopedAndDoesNotStopOrdinaryQueries() {
+        var c=client();response.set("{\"code\":11008,\"msg\":\"private\"}");
+        var error=assertThrows(LingxingWmsException.class,()->c.queryInventoryFlow(flow(),context()));
+        assertThat(error.code()).isEqualTo("LINGXING_WMS_FLOW_PERMISSION_DENIED");
+        assertThat(completion.get().accountPaused()).isFalse();
+        response.set(page("current","size",1,1,1,1,ORDER));
+        assertThat(c.queryPage(query(1,1),context()).records()).hasSize(1);assertThat(calls.get()).isEqualTo(2);
+    }
+    @Test void flowRejectsUnboundedWindowBeforeSendingAndWrongSkuAfterResponse() {
+        var q=flow();var c=client();
+        assertThrows(LingxingWmsException.class,()->c.queryInventoryFlow(new InventoryFlowRequest(q.warehouseCode(),q.customerCode(),q.sku(),q.startTime(),q.startTime().plusDays(32)),context()));
+        assertThat(calls.get()).isZero();
+        response.set(page("current","size",1,1000,1,1,"{\"whCode\":\"W-DEMO\",\"customerCode\":\"C-DEMO\",\"productSku\":\"OTHER\"}"));
+        contract(()->c.queryInventoryFlow(q,context()),"FLOW_IDENTITY_MISMATCH");
+    }
    private LingxingWmsClient client() { return client(CollectionMode.BUSINESS, true, true); }
    private LingxingWmsClient client(CollectionMode mode, boolean grant, boolean budget) {
        var clock = new LingxingEgressGateTest.MutableClock(NOW);