From 53e176ba7cb14f4905deef4578865cc014072673 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com>
Date: Sat, 14 Nov 2026 09:54:04 +0800
Subject: [PATCH] =?UTF-8?q?feat(phase-2):=20=E4=BA=AC=E4=B8=9C=E9=87=87?=
=?UTF-8?q?=E9=9B=86=E4=BB=BB=E5=8A=A1=E5=9F=9F=E2=80=94=E2=80=94=E5=BB=BA?=
=?UTF-8?q?=E5=8D=95/=E5=88=86=E7=89=87=E5=9B=9E=E4=BC=A0=E8=90=BD?=
=?UTF-8?q?=E5=BA=93/=E5=88=A4=E6=B4=BB=E6=8E=A5=E7=BA=BF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.../common/module/TaskModuleRegistry.java | 7 +-
.../jd/controller/JdCollectController.java | 82 ++++
.../model/dto/JdCollectTaskCreateRequest.java | 29 ++
.../jd/model/dto/JdIngestChunkRequest.java | 125 ++++++
.../modules/jd/model/vo/JdCollectTaskVo.java | 20 +
.../modules/jd/model/vo/JdIngestChunkVo.java | 26 ++
.../jd/service/JdCollectTaskHeartbeatSpi.java | 35 ++
.../jd/service/JdCollectTaskService.java | 162 ++++++++
.../jd/service/JdResultIngestService.java | 361 ++++++++++++++++++
.../jd/service/JdStaleTaskService.java | 164 ++++++++
.../jd/JdIngestPayloadContractTest.java | 2 -
.../jd/service/JdCollectTaskServiceTest.java | 108 ++++++
.../jd/service/JdProductSyncServiceTest.java | 319 ++++++++++++++++
.../jd/service/JdStaleTaskServiceTest.java | 123 ++++++
14 files changed, 1558 insertions(+), 5 deletions(-)
create mode 100644 backend-java/src/main/java/com/nanri/aiimage/modules/jd/controller/JdCollectController.java
create mode 100644 backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/dto/JdCollectTaskCreateRequest.java
create mode 100644 backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/dto/JdIngestChunkRequest.java
create mode 100644 backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/vo/JdCollectTaskVo.java
create mode 100644 backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/vo/JdIngestChunkVo.java
create mode 100644 backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdCollectTaskHeartbeatSpi.java
create mode 100644 backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdCollectTaskService.java
create mode 100644 backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdResultIngestService.java
create mode 100644 backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdStaleTaskService.java
create mode 100644 backend-java/src/test/java/com/nanri/aiimage/modules/jd/service/JdCollectTaskServiceTest.java
create mode 100644 backend-java/src/test/java/com/nanri/aiimage/modules/jd/service/JdProductSyncServiceTest.java
create mode 100644 backend-java/src/test/java/com/nanri/aiimage/modules/jd/service/JdStaleTaskServiceTest.java
diff --git a/backend-java/src/main/java/com/nanri/aiimage/common/module/TaskModuleRegistry.java b/backend-java/src/main/java/com/nanri/aiimage/common/module/TaskModuleRegistry.java
index 0a0bb4013..f553c647f 100644
--- a/backend-java/src/main/java/com/nanri/aiimage/common/module/TaskModuleRegistry.java
+++ b/backend-java/src/main/java/com/nanri/aiimage/common/module/TaskModuleRegistry.java
@@ -70,9 +70,10 @@ public final class TaskModuleRegistry {
new Module("BRAND", "品牌检测", true, false, true, false, Optional.empty()),
// v1.4 京东店铺采集(蓝图 §4 Phase 1):resultFileJob=false——不出 Excel 结果文件,
// 商品数据直接落 biz_jd_product(V193),导出由后管做;ageCleanup=true——任务行
- // 照常按天清理(商品行在 biz_jd_product 独立保留,不被清);判死巡检暂不并入
- // (Phase 2 落 JdStaleTaskService 时按其调度形态登记,登录态失效判死由它自管)。
- new Module("JD_SHOP_COLLECT", "京东店铺采集", false, true, false, false, Optional.empty())
+ // 照常按天清理(商品行在 biz_jd_product 独立保留,不被清);Phase 2 判死登记定型:
+ // JdStaleTaskService 自带 @Scheduled(60 分钟超时线,selfScheduledStaleCheck=true,
+ // 同 publish/collect-data 先例),京麦登录态失效判死由回传侧经它落终态。
+ new Module("JD_SHOP_COLLECT", "京东店铺采集", false, true, false, true, Optional.empty())
);
private TaskModuleRegistry() {
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/jd/controller/JdCollectController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/controller/JdCollectController.java
new file mode 100644
index 000000000..2ee2f3a66
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/controller/JdCollectController.java
@@ -0,0 +1,82 @@
+package com.nanri.aiimage.modules.jd.controller;
+
+import com.nanri.aiimage.common.api.ApiResponse;
+import com.nanri.aiimage.common.security.AdminAuthSupport;
+import com.nanri.aiimage.modules.jd.model.dto.JdCollectTaskCreateRequest;
+import com.nanri.aiimage.modules.jd.model.dto.JdIngestChunkRequest;
+import com.nanri.aiimage.modules.jd.model.vo.JdCollectTaskVo;
+import com.nanri.aiimage.modules.jd.model.vo.JdIngestChunkVo;
+import com.nanri.aiimage.modules.jd.service.JdCollectTaskService;
+import com.nanri.aiimage.modules.jd.service.JdResultIngestService;
+import com.nanri.aiimage.modules.task.model.dto.TaskHeartbeatRequest;
+import com.nanri.aiimage.modules.task.model.vo.TaskHeartbeatVo;
+import com.nanri.aiimage.modules.task.service.TaskHeartbeatPositionService;
+import com.nanri.aiimage.modules.task.service.TaskHeartbeatService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * 京东店铺采集任务面(v1.4 Phase 2,蓝图 §3.2)。
+ *
+ *
三个入口:建单(用户端登录用户,uid 按会话身份回填)、分片回传(本机采集器直调,
+ * 与货源查询 {@code /result} 同形无鉴权——采集端按 user_id 拉单,行归属以任务 owner 投影)、
+ * 心跳(委托 {@code TaskHeartbeatService} 全局通道,父任务终态时回 {@code alive=false},
+ * 沿用现有心跳语义;客户端下一跳收手)。全局 {@code /api/tasks/{taskId}/heartbeat} 同时保留可用,
+ * 本端点只是给采集器一个模块内聚的 URL。
+ */
+@RestController
+@RequiredArgsConstructor
+@Slf4j
+@RequestMapping("/api/jd-collect")
+@Tag(name = "京东店铺采集", description = "京麦后台店铺商品采集:建单 → 本机紫鸟窗口采集 → 分片回传落京东数据库。")
+public class JdCollectController {
+
+ private final JdCollectTaskService collectTaskService;
+ private final JdResultIngestService ingestService;
+ private final TaskHeartbeatService taskHeartbeatService;
+ private final TaskHeartbeatPositionService taskHeartbeatPositionService;
+ private final AdminAuthSupport adminAuthSupport;
+
+ @PostMapping("/tasks")
+ @Operation(summary = "创建京东店铺采集任务", description = "选择店铺 + 商品 Tab(在售/已下架)+ 采集范围建单;"
+ + "任务落 PENDING、执行通道显式 LOCAL(本机紫鸟执行)。返回 taskId/taskNo/collectChannel。")
+ public ApiResponse createTask(@Valid @RequestBody JdCollectTaskCreateRequest request,
+ HttpServletRequest httpRequest) {
+ // uid 不由请求体说了算:解析不出会话身份就 401(fail-closed,与货源查询同口径)。
+ request.setUserId(adminAuthSupport.requireOwnershipUserId(httpRequest, request.getUserId()));
+ return ApiResponse.success(collectTaskService.createTask(request,
+ adminAuthSupport.currentDeviceId(httpRequest)));
+ }
+
+ @PostMapping("/tasks/{taskId}/chunk")
+ @Operation(summary = "提交采集分片回传", description = "采集器按批次回传列表/详情/图片清单;"
+ + "游标合并写(缺件沿用前值)、行 upsert-only;isEnd=true 任务落 SUCCESS;"
+ + "error 字段按铁律 31 分档(京麦登录态失效整单 FAILED,非致命只记录)。")
+ public ApiResponse submitChunk(
+ @Parameter(description = "任务 ID", required = true, example = "33890")
+ @PathVariable Long taskId,
+ @RequestBody JdIngestChunkRequest request) {
+ return ApiResponse.success(ingestService.submitChunk(taskId, request));
+ }
+
+ @PostMapping("/tasks/{taskId}/heartbeat")
+ @Operation(summary = "上报采集心跳", description = "沿用全局任务心跳语义:任务终态时回 alive=false,"
+ + "采集端下一跳收手。处理位置一并记入心跳位置表供判死文案使用。")
+ public ApiResponse heartbeat(
+ @Parameter(description = "任务 ID", required = true, example = "33890")
+ @PathVariable Long taskId,
+ @RequestBody(required = false) TaskHeartbeatRequest request) {
+ taskHeartbeatPositionService.record(taskId, request);
+ return ApiResponse.success(taskHeartbeatService.heartbeat(taskId, request));
+ }
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/dto/JdCollectTaskCreateRequest.java b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/dto/JdCollectTaskCreateRequest.java
new file mode 100644
index 000000000..816e630d9
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/dto/JdCollectTaskCreateRequest.java
@@ -0,0 +1,29 @@
+package com.nanri.aiimage.modules.jd.model.dto;
+
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 京东店铺采集建单请求(蓝图 §3.2 建单契约)。
+ *
+ * 用户在用户端「京东采集」页选择店铺 + 商品 Tab(在售/已下架)+ 采集范围并提交。
+ * {@code shopName} 即京麦商家后台的店铺名,采集执行时客户端在已登录京麦的紫鸟窗口内
+ * 按它定位列表页;{@code listTabs} 对应京麦列表页的 Tab({@code ONSALE} 在售中 /
+ * {@code OFFSALE} 已下架,与 V193 {@code list_tab} 列同词表)。
+ */
+@Data
+public class JdCollectTaskCreateRequest {
+
+ /** 提交人 uid(Controller 侧按会话身份回填,请求体自带值不采信)。 */
+ private Long userId;
+
+ /** 京麦店铺名(AC-1:未选店铺时建单被拒并点名原因)。 */
+ private String shopName;
+
+ /** 要采集的商品 Tab(ONSALE/OFFSALE,至少一个)。 */
+ private List listTabs;
+
+ /** 采集范围上限(商品数);0/缺省=不设上限,采完整 Tab。 */
+ private Integer maxProducts;
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/dto/JdIngestChunkRequest.java b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/dto/JdIngestChunkRequest.java
new file mode 100644
index 000000000..f23f9facd
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/dto/JdIngestChunkRequest.java
@@ -0,0 +1,125 @@
+package com.nanri.aiimage.modules.jd.model.dto;
+
+import com.fasterxml.jackson.annotation.JsonFormat;
+import lombok.Data;
+
+import java.math.BigDecimal;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 京东采集分片回传请求(蓝图 §3.2 回传契约)。
+ *
+ * 顶层键集 {@code batchId / cursor / items / isEnd}(外加 {@code error} 失败上报),
+ * 行内键集 {@code productCode / summary / detail / images}——键名契约由
+ * {@code JdIngestPayloadContractTest} 以源码绊线钉住,改名必须同轮改判据并在蓝图 §5 登记。
+ *
+ *
{@code summary} 是列表页字段(键集见 {@link JdProductSummaryDto});
+ * {@code detail} 是详情页属性全集,服务端原样透传入 {@code attr_json},不裁剪不转写(AC-3);
+ * {@code images} 只登记键名与去向(tempKey 待位,Phase 4 预签名直传 + 登记对撞时才落
+ * {@code biz_jd_product_image}),本 Phase 不进图片字节。
+ */
+@Data
+public class JdIngestChunkRequest {
+
+ /** 批次号(客户端生成,如 JD20261114-0001),写进行的 collect_batch_id 供断点与差异核对。 */
+ private String batchId;
+
+ /**
+ * 断点游标(如 {@code {"tab":"ONSALE","page":3,"detailDone":120}})。
+ * 可缺:一次请求没带 cursor ≠ 没有游标,服务端沿用前值合并写(铁律 30 / B84-01)。
+ */
+ private Map cursor;
+
+ /** 本批商品行。 */
+ private List items;
+
+ /** true=本任务全部回传完成,任务落 SUCCESS。 */
+ private Boolean isEnd;
+
+ /**
+ * 客户端失败上报(非空时按铁律 31 分档:京麦登录态失效→整单 FAILED;
+ * 代理/LLM 凭据致命词→按 {@code CredentialFatalClassifier} 落终态;
+ * 其余(限流/超时/页面抖动)只记录不判死)。
+ */
+ private String error;
+
+ /** 单条商品回传行。 */
+ @Data
+ public static class JdIngestItemDto {
+
+ /** 京东商品编码(uk_company_shop_code 三元组之一,缺失的行跳过并计数,不落库)。 */
+ private String productCode;
+
+ /** 列表页字段(typed 键集见 {@link JdProductSummaryDto})。 */
+ private Map summary;
+
+ /** 详情页属性全集(原始 key/label/value,原样入 attr_json)。 */
+ private Map detail;
+
+ /** 图片清单(本 Phase 只消费键名与数量,字节面在 Phase 4 接)。 */
+ private List images;
+ }
+
+ /** 图片清单项(对象 key 由服务端预签名面生成,客户端不得自造,Phase 4 生效)。 */
+ @Data
+ public static class JdIngestImageDto {
+
+ /** MAIN / ATTR / DETAIL(V194 image_type 同词表)。 */
+ private String type;
+
+ /** 销售属性名(ATTR 图专用,如「上衣 / 半裙」)。 */
+ private String attrName;
+
+ private Integer sortNo;
+
+ private String objectKey;
+
+ private String sha256;
+
+ private Long bytes;
+ }
+
+ /** 列表页 summary 的 typed 键集(客户端按这些键名回传;未知键忽略不炸批,不在这里展开)。 */
+ @Data
+ @com.fasterxml.jackson.annotation.JsonIgnoreProperties(ignoreUnknown = true)
+ public static class JdProductSummaryDto {
+
+ private String shopId;
+
+ private String shopName;
+
+ private String title;
+
+ private String skuId;
+
+ private String brand;
+
+ private String brandId;
+
+ private String categoryPath;
+
+ private BigDecimal priceMin;
+
+ private BigDecimal priceMax;
+
+ private Integer stockTotal;
+
+ /** 上架中 / 已下架 / 审核中 / 草稿(京麦原值)。 */
+ private String saleStatus;
+
+ /** 采集来源 Tab(ONSALE/OFFSALE)。 */
+ private String listTab;
+
+ /** 京东侧创建时间(yyyy-MM-dd HH:mm:ss)。 */
+ @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+ private String jdCreatedAt;
+
+ /** 京东侧修改时间(yyyy-MM-dd HH:mm:ss)。 */
+ @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+ private String jdUpdatedAt;
+
+ /** 京东详情页 URL(仅作溯源,不作展示源)。 */
+ private String detailUrl;
+ }
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/vo/JdCollectTaskVo.java b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/vo/JdCollectTaskVo.java
new file mode 100644
index 000000000..13a812cce
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/vo/JdCollectTaskVo.java
@@ -0,0 +1,20 @@
+package com.nanri.aiimage.modules.jd.model.vo;
+
+import lombok.Data;
+
+/**
+ * 京东店铺采集建单回执(蓝图 §3.2:{@code → 200 { taskId, taskNo, collectChannel }})。
+ */
+@Data
+public class JdCollectTaskVo {
+
+ private Long taskId;
+
+ private String taskNo;
+
+ /**
+ * 执行通道,恒为 {@code LOCAL}——京东采集只能在本机 Windows + 紫鸟窗口执行,
+ * 建单时显式写库(铁律 19:/parse 建单入口必须写通道,不依赖默认值兜底)。
+ */
+ private String collectChannel;
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/vo/JdIngestChunkVo.java b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/vo/JdIngestChunkVo.java
new file mode 100644
index 000000000..8a78c9d22
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/model/vo/JdIngestChunkVo.java
@@ -0,0 +1,26 @@
+package com.nanri.aiimage.modules.jd.model.vo;
+
+import lombok.Data;
+
+/**
+ * 京东采集分片回传回执(蓝图 §3.2:{@code → 200 { accept, deduped, upserted, imagesRegistered }})。
+ *
+ * {@code deduped}=本批里缺商品编码/标题无法构成唯一键而跳过的行(服务端留日志点名声);
+ * {@code upserted}=进 {@code biz_jd_product} upsert 的行数(同一商品重复采集刷新原行,行数不增,AC-5);
+ * {@code imagesRegistered}=图片登记数,Phase 2 图片只记 tempKey 待位,恒 0,Phase 4 接预签名直传后生效。
+ */
+@Data
+public class JdIngestChunkVo {
+
+ /** false=本批未被受理(归属缺失 / 凭据致命已落终态),客户端应停止继续提交。 */
+ private boolean accept;
+
+ private int deduped;
+
+ private int upserted;
+
+ private int imagesRegistered;
+
+ /** 点名原因(accept=false 时给采集端与日志看)。 */
+ private String message;
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdCollectTaskHeartbeatSpi.java b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdCollectTaskHeartbeatSpi.java
new file mode 100644
index 000000000..815cb1cca
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdCollectTaskHeartbeatSpi.java
@@ -0,0 +1,35 @@
+package com.nanri.aiimage.modules.jd.service;
+
+import com.nanri.aiimage.modules.task.model.dto.TaskHeartbeatRequest;
+import com.nanri.aiimage.modules.task.spi.TaskModuleHeartbeatSpi;
+import org.springframework.stereotype.Component;
+
+/**
+ * 京东店铺采集的心跳 SPI 接线(v1.4 Phase 2)。
+ *
+ *
京东模块没有独立的任务缓存(进度由全局心跳位置表、{@code biz_task_scope_state} 台账与
+ * {@code biz_task_progress_snapshot} 承载),所以 {@link #touchHeartbeat} 是语义上的空实现——
+ * 挂这个 Bean 的目的有两个:① 心跳契约测试按注册表校验每个 moduleType 都有 SPI,缺了会红;
+ * ② 显式声明 {@code heartbeatNeedsFullTaskEntity()=false},心跳热路径不捞
+ * {@code request_json}/{@code result_json} 整行(AC-19 同款省钱口径)。
+ * 「父任务终态回 {@code alive=false}」由 {@code TaskHeartbeatService.touchFileTaskIfRunning}
+ * 的 {@code status != RUNNING} 分支免费提供,本类不重复实现。
+ */
+@Component
+public class JdCollectTaskHeartbeatSpi implements TaskModuleHeartbeatSpi {
+
+ @Override
+ public String moduleType() {
+ return JdCollectTaskService.MODULE_TYPE;
+ }
+
+ @Override
+ public void touchHeartbeat(Long taskId, TaskHeartbeatRequest request) {
+ // 京东无模块缓存可刷:进度快照由回传侧与判死侧写,心跳只走 task 侧的通用通道。
+ }
+
+ @Override
+ public boolean heartbeatNeedsFullTaskEntity() {
+ return false;
+ }
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdCollectTaskService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdCollectTaskService.java
new file mode 100644
index 000000000..5e1f9c0dd
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdCollectTaskService.java
@@ -0,0 +1,162 @@
+package com.nanri.aiimage.modules.jd.service;
+
+import cn.hutool.core.util.IdUtil;
+import cn.hutool.crypto.digest.DigestUtil;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.nanri.aiimage.common.exception.BusinessException;
+import com.nanri.aiimage.config.CollectRoutingProperties;
+import com.nanri.aiimage.modules.jd.model.dto.JdCollectTaskCreateRequest;
+import com.nanri.aiimage.modules.jd.model.vo.JdCollectTaskVo;
+import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
+import com.nanri.aiimage.modules.task.mapper.TaskScopeStateMapper;
+import com.nanri.aiimage.modules.task.model.CollectChannel;
+import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
+import com.nanri.aiimage.modules.task.model.entity.TaskScopeStateEntity;
+import com.nanri.aiimage.common.security.AdminAuthSupport;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+import java.util.Locale;
+import java.util.Set;
+
+/**
+ * 京东店铺采集建单(v1.4 Phase 2,蓝图 §3.2 建单契约)。
+ *
+ *
形状抄货源查询 {@code SimilarAsinTaskService#parseAndCreateTask} 的落库段:
+ * Mapper {@code insert} + taskNo={@code MODULE_TYPE-Snowflake} + 载荷整体进 {@code request_json}。
+ * 三处京东特有:① 执行通道恒 {@code LOCAL} 且建单显式写库(铁律 19:/parse 建单入口必须写
+ * 通道,不依赖 {@code CollectChannel#defaultFor} 的默认兜底);② 建单口不接
+ * {@code requireSubmitSecret}——本模块在 {@code TaskModuleRegistry} 登记为
+ * {@code Optional.empty()}(缺代理在本机执行类是「直连降级」不是注定失败,铁律 27 边界 c,
+ * 黄金测试 {@code JdCollectChannelGoldenTest} 钉死);③ 建单同时落一行
+ * {@code biz_task_scope_state}(scopeKey 绑店铺),回传落库侧的断点游标与批次台账合并写在这行上。
+ */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class JdCollectTaskService {
+
+ public static final String MODULE_TYPE = CollectRoutingProperties.MODULE_JD_SHOP_COLLECT;
+
+ private static final String STATUS_PENDING = com.nanri.aiimage.common.task.TaskStatuses.FileTask.PENDING;
+
+ /** 京麦商品列表 Tab 词表(与 V193 list_tab 列同词表)。 */
+ private static final Set VALID_LIST_TABS = Set.of("ONSALE", "OFFSALE");
+
+ /** scope 状态 JSON 的出厂形状:游标为空对象(合并写的"前值"从这里起步)。 */
+ private static final String INITIAL_SCOPE_STATE = "{\"cursor\":{},\"itemsReceived\":0,\"lastBatchId\":null}";
+
+ private final FileTaskMapper fileTaskMapper;
+ private final TaskScopeStateMapper taskScopeStateMapper;
+ private final ObjectMapper objectMapper;
+
+ public JdCollectTaskVo createTask(JdCollectTaskCreateRequest request, String deviceId) {
+ validate(request);
+ LocalDateTime now = LocalDateTime.now();
+ FileTaskEntity task = new FileTaskEntity();
+ task.setTaskNo(MODULE_TYPE + "-" + IdUtil.getSnowflakeNextIdStr());
+ task.setModuleType(MODULE_TYPE);
+ task.setTaskMode("PYTHON_QUEUE");
+ // 铁律 19:建单入口显式写通道。京东采集只能在本机 Windows + 紫鸟窗口执行,写 LOCAL
+ // 而不是 persistedValue(request.getCollectChannel())——这一类的执行方没有"界面选 ONLINE"的自由度。
+ task.setCollectChannel(CollectChannel.LOCAL.name());
+ task.setStatus(STATUS_PENDING);
+ task.setSourceFileCount(0);
+ task.setSuccessFileCount(0);
+ task.setFailedFileCount(0);
+ task.setCreatedBy("user:" + request.getUserId());
+ task.setUserId(request.getUserId());
+ task.setDeviceId(AdminAuthSupport.normalizeDeviceId(deviceId));
+ task.setCreatedAt(now);
+ task.setUpdatedAt(now);
+ try {
+ task.setRequestJson(objectMapper.writeValueAsString(request));
+ task.setResultJson("{}");
+ } catch (Exception ex) {
+ throw new BusinessException("序列化建单载荷失败", ex);
+ }
+ fileTaskMapper.insert(task);
+ insertScopeRow(task, request.getShopName(), now);
+
+ JdCollectTaskVo vo = new JdCollectTaskVo();
+ vo.setTaskId(task.getId());
+ vo.setTaskNo(task.getTaskNo());
+ vo.setCollectChannel(task.getCollectChannel());
+ log.info("[jd-collect] 建单成功 taskId={} taskNo={} shopName={} tabs={} userId={} channel={}",
+ task.getId(), task.getTaskNo(), request.getShopName(), request.getListTabs(),
+ request.getUserId(), task.getCollectChannel());
+ return vo;
+ }
+
+ private void validate(JdCollectTaskCreateRequest request) {
+ if (request.getUserId() == null || request.getUserId() <= 0) {
+ throw new BusinessException("user_id 不合法");
+ }
+ if (request.getShopName() == null || request.getShopName().isBlank()) {
+ throw new BusinessException("请选择要采集的京东店铺");
+ }
+ if (request.getListTabs() == null || request.getListTabs().isEmpty()) {
+ throw new BusinessException("请选择要采集的商品 Tab(在售中/已下架)");
+ }
+ for (String tab : request.getListTabs()) {
+ if (tab == null || !VALID_LIST_TABS.contains(tab.trim().toUpperCase(Locale.ROOT))) {
+ throw new BusinessException("商品 Tab 不识别: " + tab + "(只支持 ONSALE/OFFSALE)");
+ }
+ }
+ if (request.getMaxProducts() != null && request.getMaxProducts() < 0) {
+ throw new BusinessException("采集范围上限不能为负数");
+ }
+ }
+
+ /**
+ * 落回传侧要用的 scope 行(幂等:并发建单撞唯一键时复用先到的那行,不顶掉)。
+ * scopeKey 绑店铺,回传侧按 taskId 单 scope 读写断点游标与批次台账。
+ */
+ private void insertScopeRow(FileTaskEntity task, String shopName, LocalDateTime now) {
+ String scopeKey = "jd:" + shopName.trim();
+ TaskScopeStateEntity scope = new TaskScopeStateEntity();
+ scope.setTaskId(task.getId());
+ scope.setModuleType(MODULE_TYPE);
+ scope.setScopeKey(scopeKey);
+ scope.setScopeHash(DigestUtil.sha256Hex(scopeKey));
+ scope.setStateJson(INITIAL_SCOPE_STATE);
+ scope.setChunkTotal(0);
+ scope.setReceivedChunkCount(0);
+ scope.setCompleted(0);
+ scope.setCreatedAt(now);
+ scope.setUpdatedAt(now);
+ try {
+ taskScopeStateMapper.insert(scope);
+ } catch (DuplicateKeyException ex) {
+ log.info("[jd-collect] scope 行已存在(并发建单/重试),复用先到行 taskId={}", task.getId());
+ }
+ }
+
+ /** 回传侧读建单载荷(拿 shopName 落 shop_name 列);载荷缺失/损坏按异常拒绝回传,不静默兜。 */
+ public JdCollectTaskCreateRequest readCreateRequest(FileTaskEntity task) {
+ try {
+ JdCollectTaskCreateRequest request = objectMapper.readValue(task.getRequestJson(),
+ JdCollectTaskCreateRequest.class);
+ if (request == null || request.getShopName() == null || request.getShopName().isBlank()) {
+ throw new BusinessException("任务载荷缺少 shopName,无法定位店铺");
+ }
+ return request;
+ } catch (BusinessException ex) {
+ throw ex;
+ } catch (Exception ex) {
+ throw new BusinessException("任务载荷解析失败 taskId=" + task.getId(), ex);
+ }
+ }
+
+ /** 供测试与回传侧确认 scope 行形状(按 taskId 单 scope)。 */
+ public TaskScopeStateEntity findScopeRow(Long taskId) {
+ return taskScopeStateMapper.selectOne(new LambdaQueryWrapper()
+ .eq(TaskScopeStateEntity::getTaskId, taskId)
+ .eq(TaskScopeStateEntity::getModuleType, MODULE_TYPE)
+ .last("limit 1"));
+ }
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdResultIngestService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdResultIngestService.java
new file mode 100644
index 000000000..a66def4b2
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/jd/service/JdResultIngestService.java
@@ -0,0 +1,361 @@
+package com.nanri.aiimage.modules.jd.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.nanri.aiimage.common.mapper.AdminUserMapper;
+import com.nanri.aiimage.common.model.entity.AdminUserEntity;
+import com.nanri.aiimage.common.retry.CredentialFatalClassifier;
+import com.nanri.aiimage.common.task.TaskStatuses;
+import com.nanri.aiimage.common.exception.BusinessException;
+import com.nanri.aiimage.modules.jd.mapper.JdProductMapper;
+import com.nanri.aiimage.modules.jd.model.dto.JdCollectTaskCreateRequest;
+import com.nanri.aiimage.modules.jd.model.dto.JdIngestChunkRequest;
+import com.nanri.aiimage.modules.jd.model.entity.JdProductEntity;
+import com.nanri.aiimage.modules.jd.model.vo.JdIngestChunkVo;
+import com.nanri.aiimage.modules.task.mapper.FileTaskMapper;
+import com.nanri.aiimage.modules.task.mapper.TaskScopeStateMapper;
+import com.nanri.aiimage.modules.task.model.entity.FileTaskEntity;
+import com.nanri.aiimage.modules.task.model.entity.TaskScopeStateEntity;
+import com.nanri.aiimage.modules.task.service.CredentialFatalTaskCloser;
+import com.nanri.aiimage.modules.task.service.TaskProgressSnapshotService;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 京东采集分片回传落库(v1.4 Phase 2,蓝图 §3.2 回传契约)。
+ *
+ * 链路:客户端回传 chunk → 归属解析({@code task.user_id -> users.company_id},读不出跳过
+ * 不回填默认 1,铁律 30)→ 行 upsert(唯一出口 {@link JdProductMapper#upsertBatch},
+ * upsert-only 不 delete,B94-01)→ scope 台账合并写(断点游标 + 批次号 + 累计行数)→
+ * {@code isEnd=true} 时任务落 SUCCESS。图片只消费键名与数量(tempKey 待位),
+ * 预签名直传与登记对撞在 Phase 4 接 {@code JdProductImageIngestService}。
+ *
+ *
回传 payload 键集契约({@code JdIngestPayloadContractTest} 绊线钉住):顶层
+ * {@code batchId / cursor / items / isEnd}(+ {@code error} 失败上报),行内
+ * {@code productCode / summary / detail / images}——本服务逐键消费,改名必须同轮改判据。
+ *
+ *
失败上报按铁律 31 分档:京麦登录态失效(客户端报「京麦未登录 / 登录态失效」)→
+ * 整单 FAILED,心跳对采集端回 {@code alive=false} 停止为注定失败的行继续跑;代理/LLM 凭据
+ * 致命词 → {@link CredentialFatalTaskCloser} 落终态;限流/超时/页面抖动等非致命只记录不判死。
+ */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class JdResultIngestService {
+
+ public static final String MODULE_TYPE = JdCollectTaskService.MODULE_TYPE;
+
+ private static final String STATUS_RUNNING = TaskStatuses.FileTask.RUNNING;
+ private static final String STATUS_SUCCESS = TaskStatuses.FileTask.SUCCESS;
+ private static final String LOG_TAG = "jd-collect";
+
+ private final FileTaskMapper fileTaskMapper;
+ private final JdProductMapper jdProductMapper;
+ private final TaskScopeStateMapper taskScopeStateMapper;
+ private final AdminUserMapper adminUserMapper;
+ private final JdCollectTaskService collectTaskService;
+ private final JdStaleTaskService jdStaleTaskService;
+ private final TaskProgressSnapshotService taskProgressSnapshotService;
+ private final ObjectMapper objectMapper;
+
+ public JdIngestChunkVo submitChunk(Long taskId, JdIngestChunkRequest request) {
+ if (taskId == null || taskId <= 0) {
+ throw new BusinessException("taskId 不合法");
+ }
+ if (request == null) {
+ throw new BusinessException("回传请求体为空");
+ }
+ FileTaskEntity task = requireJdTask(taskId);
+ if (TaskStatuses.FileTask.TERMINAL.contains(task.getStatus())) {
+ throw new BusinessException("任务已结束(" + task.getStatus() + "),回传被拒");
+ }
+ if (request.getError() != null && !request.getError().isBlank()) {
+ return handleErrorReport(task, request.getError().trim());
+ }
+ if (!STATUS_RUNNING.equals(task.getStatus())) {
+ throw new BusinessException("任务不在运行中(" + task.getStatus() + "),回传被拒");
+ }
+ Long companyId = resolveCompanyId(task);
+ if (companyId == null) {
+ // 铁律 30:读不出归属不得回落默认 1——跳过该任务落库并留日志,让人工先修归属。
+ log.warn("[{}] 归属解析失败(owner userId={} 无 company_id),跳过落库 taskId={}",
+ LOG_TAG, task.getUserId(), taskId);
+ return reject("任务归属缺失,已跳过落库");
+ }
+ JdCollectTaskCreateRequest createRequest = collectTaskService.readCreateRequest(task);
+ TaskScopeStateEntity scope = requireScopeRow(taskId);
+
+ int deduped = 0;
+ int imageCount = 0;
+ List rows = new ArrayList<>();
+ if (request.getItems() != null) {
+ for (JdIngestChunkRequest.JdIngestItemDto item : request.getItems()) {
+ if (item == null || isBlank(item.getProductCode())) {
+ deduped++;
+ log.warn("[{}] 回传行缺商品编码,跳过 taskId={} batchId={}", LOG_TAG, taskId, request.getBatchId());
+ continue;
+ }
+ JdIngestChunkRequest.JdProductSummaryDto summary = toSummary(item.getSummary());
+ if (summary == null || isBlank(summary.getTitle())) {
+ deduped++;
+ log.warn("[{}] 回传行缺列表页标题,跳过 taskId={} productCode={}", LOG_TAG, taskId, item.getProductCode());
+ continue;
+ }
+ rows.add(buildRow(task, companyId, createRequest, item, summary, request.getBatchId(), scope));
+ // 图片本 Phase 只计数占位(tempKey 待位):预签名直传与登记对撞在 Phase 4 落 biz_jd_product_image。
+ imageCount += item.getImages() == null ? 0 : item.getImages().size();
+ }
+ }
+ if (!rows.isEmpty()) {
+ jdProductMapper.upsertBatch(rows);
+ }
+ int itemsReceived = mergeScopeState(scope, request, request.getItems() == null ? 0 : request.getItems().size());
+ if (Boolean.TRUE.equals(request.getIsEnd())) {
+ finalizeSuccess(task, itemsReceived);
+ }
+ JdIngestChunkVo vo = new JdIngestChunkVo();
+ vo.setAccept(true);
+ vo.setDeduped(deduped);
+ vo.setUpserted(rows.size());
+ vo.setImagesRegistered(0);
+ return vo;
+ }
+
+ /** 铁律 31 分档:京麦登录态失效 → 整单终态;代理/LLM 致命 → CredentialFatalTaskCloser;其余只记录。 */
+ private JdIngestChunkVo handleErrorReport(FileTaskEntity task, String error) {
+ if (JdStaleTaskService.isJdLoginStateFailure(error)) {
+ jdStaleTaskService.terminalizeOnJdLoginFatal(task, error);
+ return reject("京麦登录态失效,任务已终止,请在客户端重新登录京麦");
+ }
+ if (CredentialFatalClassifier.isFatal(error)) {
+ new CredentialFatalTaskCloser(LOG_TAG, fileTaskMapper, null).closeIfFatal(task, error);
+ return reject("凭据不可自愈(详见任务失败原因),任务已终止");
+ }
+ // 非致命(限流/超时/页面抖动):只补测不判死,记入 scope 台账后让客户端继续。
+ log.warn("[{}] 非致命失败上报,不判死 taskId={} err={}", LOG_TAG, task.getId(), error);
+ recordLastError(task.getId(), error);
+ JdIngestChunkVo vo = new JdIngestChunkVo();
+ vo.setAccept(true);
+ vo.setMessage("失败上报已记录(非致命)");
+ return vo;
+ }
+
+ private void recordLastError(Long taskId, String error) {
+ TaskScopeStateEntity scope = collectTaskService.findScopeRow(taskId);
+ if (scope == null) {
+ log.warn("[{}] scope 行缺失,失败上报无法记账 taskId={}", LOG_TAG, taskId);
+ return;
+ }
+ Map state = parseState(scope.getStateJson());
+ state.put("lastError", error);
+ scope.setStateJson(writeJson(state));
+ scope.setUpdatedAt(LocalDateTime.now());
+ taskScopeStateMapper.updateById(scope);
+ }
+
+ private void finalizeSuccess(FileTaskEntity task, int itemsReceived) {
+ int updated = fileTaskMapper.update(null, new LambdaUpdateWrapper()
+ .eq(FileTaskEntity::getId, task.getId())
+ .eq(FileTaskEntity::getStatus, STATUS_RUNNING)
+ .set(FileTaskEntity::getStatus, STATUS_SUCCESS)
+ .set(FileTaskEntity::getSuccessFileCount, itemsReceived)
+ .set(FileTaskEntity::getFailedFileCount, 0)
+ .set(FileTaskEntity::getUpdatedAt, LocalDateTime.now())
+ .set(FileTaskEntity::getFinishedAt, LocalDateTime.now()));
+ if (updated > 0) {
+ taskProgressSnapshotService.markTerminal(task.getId(), MODULE_TYPE, STATUS_SUCCESS, "京东采集完成");
+ log.info("[{}] 任务回传完成落 SUCCESS taskId={} itemsReceived={}", LOG_TAG, task.getId(), itemsReceived);
+ }
+ }
+
+ // ---------- scope 台账:断点游标合并写(铁律 30 / B84-01) ----------
+
+ /**
+ * 合并写 scope 台账:游标合并不整份覆写(本次请求没带 cursor = 沿用前值),
+ * 批次号与累计行数在此基础上推进。返回累计收到的 items 数(isEnd 时写 successFileCount)。
+ */
+ private int mergeScopeState(TaskScopeStateEntity scope, JdIngestChunkRequest request, int itemsInBatch) {
+ Map state = parseState(scope.getStateJson());
+ Map previousCursor = asMap(state.get("cursor"));
+ state.put("cursor", mergeCursor(previousCursor, request.getCursor()));
+ if (!isBlank(request.getBatchId())) {
+ state.put("lastBatchId", request.getBatchId().trim());
+ }
+ int itemsReceived = intVal(state.get("itemsReceived")) + itemsInBatch;
+ state.put("itemsReceived", itemsReceived);
+ scope.setStateJson(writeJson(state));
+ scope.setLastChunkAt(LocalDateTime.now());
+ scope.setReceivedChunkCount((scope.getReceivedChunkCount() == null ? 0 : scope.getReceivedChunkCount()) + 1);
+ scope.setUpdatedAt(LocalDateTime.now());
+ taskScopeStateMapper.updateById(scope);
+ return itemsReceived;
+ }
+
+ /**
+ * 游标合并(铁律 30 / B84-01 的判据本体):一次请求没带的键沿用前值,带了按键合并
+ * (同键以本次为准,嵌套 Map 递归合并);值为 null 的键视为「本次没带」,不抹掉前值。
+ * 包私有供 {@code JdProductSyncServiceTest} 直测合并语义。
+ */
+ static Map mergeCursor(Map previous, Map incoming) {
+ Map merged = previous == null ? new LinkedHashMap<>() : new LinkedHashMap<>(previous);
+ if (incoming == null || incoming.isEmpty()) {
+ return merged;
+ }
+ for (Map.Entry entry : incoming.entrySet()) {
+ if (entry.getValue() == null) {
+ continue;
+ }
+ Object prev = merged.get(entry.getKey());
+ if (entry.getValue() instanceof Map && prev instanceof Map) {
+ merged.put(entry.getKey(), mergeCursor(asMap(prev), asMap(entry.getValue())));
+ } else {
+ merged.put(entry.getKey(), entry.getValue());
+ }
+ }
+ return merged;
+ }
+
+ private Map parseState(String stateJson) {
+ if (stateJson == null || stateJson.isBlank()) {
+ return new LinkedHashMap<>();
+ }
+ try {
+ Map state = objectMapper.readValue(stateJson, STATE_TYPE);
+ return state == null ? new LinkedHashMap<>() : state;
+ } catch (Exception ex) {
+ throw new BusinessException("scope 台账解析失败(stateJson 损坏)", ex);
+ }
+ }
+
+ private String writeJson(Map value) {
+ try {
+ return objectMapper.writeValueAsString(value);
+ } catch (Exception ex) {
+ throw new BusinessException("JSON 序列化失败", ex);
+ }
+ }
+
+ // ---------- 行构建 ----------
+
+ private JdProductEntity buildRow(FileTaskEntity task, Long companyId,
+ JdCollectTaskCreateRequest createRequest,
+ JdIngestChunkRequest.JdIngestItemDto item,
+ JdIngestChunkRequest.JdProductSummaryDto summary,
+ String batchId,
+ TaskScopeStateEntity scope) {
+ JdProductEntity row = new JdProductEntity();
+ row.setCompanyId(companyId);
+ row.setUserId(task.getUserId());
+ row.setTaskId(task.getId());
+ String shopName = firstNonBlank(summary.getShopName(), createRequest.getShopName());
+ row.setShopId(firstNonBlank(summary.getShopId(), shopName));
+ row.setShopName(shopName);
+ row.setProductCode(item.getProductCode().trim());
+ row.setSkuId(summary.getSkuId());
+ row.setTitle(summary.getTitle().trim());
+ row.setBrand(summary.getBrand());
+ row.setBrandId(summary.getBrandId());
+ row.setCategoryPath(summary.getCategoryPath());
+ row.setPriceMin(summary.getPriceMin());
+ row.setPriceMax(summary.getPriceMax());
+ row.setStockTotal(summary.getStockTotal());
+ row.setSaleStatus(summary.getSaleStatus());
+ row.setListTab(firstNonBlank(summary.getListTab(), cursorTab(scope)));
+ row.setJdCreatedAt(parseJdTime(summary.getJdCreatedAt()));
+ row.setJdUpdatedAt(parseJdTime(summary.getJdUpdatedAt()));
+ row.setDetailUrl(summary.getDetailUrl());
+ // detail 原样透传入 attr_json(AC-3 保真防丢键),不裁剪不转写;键数进 attr_count 供质量核查。
+ row.setAttrJson(item.getDetail() == null ? null : writeJson(item.getDetail()));
+ row.setAttrCount(item.getDetail() == null ? 0 : item.getDetail().size());
+ row.setImageCount(0);
+ row.setCollectBatchId(batchId);
+ return row;
+ }
+
+ private JdIngestChunkRequest.JdProductSummaryDto toSummary(Map summary) {
+ if (summary == null || summary.isEmpty()) {
+ return null;
+ }
+ try {
+ return objectMapper.convertValue(summary, JdIngestChunkRequest.JdProductSummaryDto.class);
+ } catch (IllegalArgumentException ex) {
+ throw new BusinessException("回传 summary 字段形状不合法: " + ex.getMessage(), ex);
+ }
+ }
+
+ /** 京东侧时间口径 yyyy-MM-dd HH:mm:ss(容 ISO 的 T 分隔,归一后单格式解析;解析失败直接拒批,不静默置空)。 */
+ private static LocalDateTime parseJdTime(String raw) {
+ if (raw == null || raw.isBlank()) {
+ return null;
+ }
+ return LocalDateTime.parse(raw.trim().replace('T', ' '),
+ DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
+ }
+
+ private String cursorTab(TaskScopeStateEntity scope) {
+ Map state = parseState(scope.getStateJson());
+ Object tab = asMap(state.get("cursor")).get("tab");
+ return tab == null ? null : String.valueOf(tab);
+ }
+
+ // ---------- 公共小件 ----------
+
+ private FileTaskEntity requireJdTask(Long taskId) {
+ FileTaskEntity task = fileTaskMapper.selectById(taskId);
+ if (task == null || !MODULE_TYPE.equals(task.getModuleType())) {
+ throw new BusinessException("任务不存在");
+ }
+ return task;
+ }
+
+ private TaskScopeStateEntity requireScopeRow(Long taskId) {
+ TaskScopeStateEntity scope = collectTaskService.findScopeRow(taskId);
+ if (scope == null) {
+ throw new BusinessException("任务 scope 台账缺失,无法记账 taskId=" + taskId);
+ }
+ return scope;
+ }
+
+ /** 归属物化:task.user_id -> users.company_id;读不出返回 null(不回填默认 1,铁律 30)。 */
+ private Long resolveCompanyId(FileTaskEntity task) {
+ AdminUserEntity owner = task.getUserId() == null ? null : adminUserMapper.selectById(task.getUserId());
+ return owner == null ? null : owner.getCompanyId();
+ }
+
+ private static JdIngestChunkVo reject(String message) {
+ JdIngestChunkVo vo = new JdIngestChunkVo();
+ vo.setAccept(false);
+ vo.setMessage(message);
+ return vo;
+ }
+
+ private static boolean isBlank(String value) {
+ return value == null || value.isBlank();
+ }
+
+ private static String firstNonBlank(String primary, String fallback) {
+ return isBlank(primary) ? fallback : primary;
+ }
+
+ private static int intVal(Object value) {
+ return value instanceof Number number ? number.intValue() : 0;
+ }
+
+ @SuppressWarnings("unchecked")
+ private static Map asMap(Object value) {
+ return value instanceof Map ? (Map) value : new LinkedHashMap<>();
+ }
+
+ private static final com.fasterxml.jackson.core.type.TypeReference