后端架构更新

2026-04-27 09:18:10 +08:00
parent 0caf62c3d2
commit 995e2ee65a
141 changed files with 6957 additions and 772 deletions
@@ -0,0 +1,156 @@
+package com.nanri.aiimage.modules.appearancepatent.client;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.nanri.aiimage.config.AppearancePatentProperties;
+import com.nanri.aiimage.modules.appearancepatent.model.dto.AppearancePatentResultRowDto;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.MediaType;
+import org.springframework.http.client.SimpleClientHttpRequestFactory;
+import org.springframework.stereotype.Component;
+import org.springframework.web.client.RestClient;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+@Component
+@RequiredArgsConstructor
+@Slf4j
+public class AppearancePatentCozeClient {
+
+    private final AppearancePatentProperties properties;
+    private final ObjectMapper objectMapper;
+
+    public List<AppearancePatentResultRowDto> inspect(List<AppearancePatentResultRowDto> rows, String prompt) {
+        if (rows == null || rows.isEmpty()) {
+            return List.of();
+        }
+        if (properties.getCozeToken() == null || properties.getCozeToken().isBlank()) {
+            log.warn("[appearance-patent] coze token not configured, keep raw rows size={}", rows.size());
+            return rows.stream().map(this::copy).toList();
+        }
+        try {
+            String raw = postWorkflow(rows, prompt);
+            List<CozeResult> results = parseResults(raw);
+            List<AppearancePatentResultRowDto> merged = new ArrayList<>();
+            for (int i = 0; i < rows.size(); i++) {
+                AppearancePatentResultRowDto row = copy(rows.get(i));
+                if (i < results.size()) {
+                    CozeResult result = results.get(i);
+                    row.setTitleRisk(result.title());
+                    row.setAppearanceRisk(result.appearance());
+                    row.setPatentRisk(result.patent());
+                    row.setConclusion(result.result());
+                }
+                merged.add(row);
+            }
+            return merged;
+        } catch (Exception ex) {
+            log.warn("[appearance-patent] coze batch failed size={} err={}", rows.size(), ex.getMessage());
+            return rows.stream().map(this::copy).toList();
+        }
+    }
+
+    private String postWorkflow(List<AppearancePatentResultRowDto> rows, String prompt) {
+        Map<String, Object> parameters = new LinkedHashMap<>();
+        parameters.put("title_list", rows.stream().map(row -> nonBlank(row.getTitle(), row.getAsin())).toList());
+        parameters.put("url_list", rows.stream().map(row -> nonBlank(row.getUrl(), "")).toList());
+        parameters.put("prompt", prompt == null ? "" : prompt);
+
+        Map<String, Object> body = new LinkedHashMap<>();
+        body.put("workflow_id", properties.getCozeWorkflowId());
+        body.put("parameters", parameters);
+
+        RestClient.RequestBodySpec request = restClient().post()
+                .uri(joinUrl(properties.getCozeBaseUrl(), properties.getCozeWorkflowPath()))
+                .headers(headers -> {
+                    headers.setBearerAuth(stripBearer(properties.getCozeToken()));
+                    headers.setContentType(MediaType.APPLICATION_JSON);
+                });
+        request.body(body);
+        return request.retrieve().body(String.class);
+    }
+
+    private List<CozeResult> parseResults(String raw) throws Exception {
+        JsonNode root = objectMapper.readTree(raw);
+        if (root.path("code").asInt(-1) != 0) {
+            throw new IllegalStateException(root.path("msg").asText("Coze response code is not 0"));
+        }
+        String dataText = root.path("data").asText("");
+        if (dataText.isBlank()) {
+            return List.of();
+        }
+        JsonNode dataRoot = objectMapper.readTree(dataText);
+        JsonNode array = dataRoot.path("data");
+        List<CozeResult> results = new ArrayList<>();
+        if (array.isArray()) {
+            for (JsonNode node : array) {
+                results.add(new CozeResult(
+                        text(node.get("title")),
+                        text(node.get("appearance")),
+                        text(firstNonNull(node.get("patent"), node.get("patent "))),
+                        text(node.get("result"))
+                ));
+            }
+        }
+        return results;
+    }
+
+    private RestClient restClient() {
+        SimpleClientHttpRequestFactory requestFactory = new SimpleClientHttpRequestFactory();
+        requestFactory.setConnectTimeout(10000);
+        requestFactory.setReadTimeout(60000);
+        return RestClient.builder().requestFactory(requestFactory).build();
+    }
+
+    private AppearancePatentResultRowDto copy(AppearancePatentResultRowDto source) {
+        AppearancePatentResultRowDto row = new AppearancePatentResultRowDto();
+        row.setId(source.getId());
+        row.setAsin(source.getAsin());
+        row.setCountry(source.getCountry());
+        row.setUrl(source.getUrl());
+        row.setTitle(source.getTitle());
+        row.setError(source.getError());
+        row.setDone(source.getDone());
+        row.setTitleRisk(source.getTitleRisk());
+        row.setAppearanceRisk(source.getAppearanceRisk());
+        row.setPatentRisk(source.getPatentRisk());
+        row.setConclusion(source.getConclusion());
+        return row;
+    }
+
+    private JsonNode firstNonNull(JsonNode left, JsonNode right) {
+        return left == null || left.isNull() ? right : left;
+    }
+
+    private String text(JsonNode node) {
+        return node == null || node.isNull() ? null : node.asText();
+    }
+
+    private String nonBlank(String value, String fallback) {
+        return value == null || value.isBlank() ? fallback : value;
+    }
+
+    private String stripBearer(String token) {
+        String normalized = token == null ? "" : token.trim();
+        return normalized.regionMatches(true, 0, "Bearer ", 0, 7) ? normalized.substring(7).trim() : normalized;
+    }
+
+    private String joinUrl(String baseUrl, String path) {
+        String base = baseUrl == null ? "" : baseUrl.trim();
+        String suffix = path == null ? "" : path.trim();
+        if (base.endsWith("/") && suffix.startsWith("/")) {
+            return base + suffix.substring(1);
+        }
+        if (!base.endsWith("/") && !suffix.startsWith("/")) {
+            return base + "/" + suffix;
+        }
+        return base + suffix;
+    }
+
+    private record CozeResult(String title, String appearance, String patent, String result) {
+    }
+}
@@ -0,0 +1,143 @@
+package com.nanri.aiimage.modules.appearancepatent.controller;
+
+import com.nanri.aiimage.common.api.ApiResponse;
+import com.nanri.aiimage.modules.appearancepatent.model.dto.AppearancePatentParseRequest;
+import com.nanri.aiimage.modules.appearancepatent.model.dto.AppearancePatentSubmitResultRequest;
+import com.nanri.aiimage.modules.appearancepatent.model.dto.AppearancePatentTaskBatchRequest;
+import com.nanri.aiimage.modules.appearancepatent.model.vo.AppearancePatentDashboardVo;
+import com.nanri.aiimage.modules.appearancepatent.model.vo.AppearancePatentHistoryVo;
+import com.nanri.aiimage.modules.appearancepatent.model.vo.AppearancePatentParseVo;
+import com.nanri.aiimage.modules.appearancepatent.model.vo.AppearancePatentTaskBatchVo;
+import com.nanri.aiimage.modules.appearancepatent.service.AppearancePatentTaskService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpStatus;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+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.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.io.InputStream;
+import java.net.URI;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/api/appearance-patent")
+@Tag(name = "外观专利检测", description = "外观专利检测任务接口。前端上传 Excel 后由 Java 解析并创建任务；Python 回传商品数据；Java 负责攒批调用 Coze、补齐子行、生成最终 xlsx 并上传 OSS。")
+public class AppearancePatentController {
+
+    private final AppearancePatentTaskService service;
+
+    @PostMapping("/parse")
+    @Operation(summary = "解析 Excel 并创建任务", description = "解析上传后的 Excel 文件，提取 id、ASIN、国家、URL、标题等字段。返回给前端的数据只包含整数 id 和 n_1 行；n_2、n_3 等子行会保存在 OSS 解析载荷中，用于最终结果补齐。创建后的任务状态为 PENDING，不会自动推送 Python。")
+    public ApiResponse<AppearancePatentParseVo> parse(@Valid @RequestBody AppearancePatentParseRequest request) {
+        return ApiResponse.success(service.parseAndCreateTask(request));
+    }
+
+    @GetMapping("/dashboard")
+    @Operation(summary = "查询外观专利检测总览", description = "查询当前用户的运行中、成功、失败和已结束任务数量。页面进入时请求一次即可，不需要持续轮询。")
+    public ApiResponse<AppearancePatentDashboardVo> dashboard(
+            @Parameter(description = "当前用户 ID，用于隔离不同用户的任务和历史记录。", required = true, example = "1")
+            @RequestParam("user_id") Long userId) {
+        return ApiResponse.success(service.dashboard(userId));
+    }
+
+    @GetMapping("/history")
+    @Operation(summary = "查询外观专利检测历史", description = "查询当前用户最近的外观专利检测历史记录，包含源文件名、任务状态、行数、错误信息和最终 xlsx 下载地址。")
+    public ApiResponse<AppearancePatentHistoryVo> history(
+            @Parameter(description = "当前用户 ID，用于查询该用户自己的历史记录。", required = true, example = "1")
+            @RequestParam("user_id") Long userId) {
+        return ApiResponse.success(service.history(userId));
+    }
+
+    @PostMapping("/tasks/progress/batch")
+    @Operation(summary = "批量查询任务进度", description = "前端只对活跃任务调用该接口，建议 6 秒一次。接口只返回轻量任务状态，不返回明细结果。")
+    public ApiResponse<AppearancePatentTaskBatchVo> progress(@Valid @RequestBody AppearancePatentTaskBatchRequest request) {
+        return ApiResponse.success(service.progressBatch(request.getTaskIds()));
+    }
+
+    @PostMapping("/tasks/{taskId}/activate")
+    @Operation(summary = "激活任务", description = "前端手动推送 Python 队列成功后调用，将任务从 PENDING 改为 RUNNING，并记录后端内部活跃时间。后续活跃时间由 Python 回传结果接口自动刷新，不需要单独心跳接口。")
+    public ApiResponse<Void> activate(
+            @Parameter(description = "外观专利检测任务 ID，即解析接口返回的 taskId。", required = true, example = "3938")
+            @PathVariable Long taskId,
+            @Parameter(description = "当前用户 ID，必须与创建任务的用户一致。", required = true, example = "1")
+            @RequestParam("user_id") Long userId) {
+        service.activateTask(taskId, userId);
+        return ApiResponse.success(null);
+    }
+
+    @PostMapping("/tasks/{taskId}/result")
+    @Operation(summary = "提交 Python 回传结果", description = "Python 回传商品数据接口。items 可以是一条或多条；Java 先原样保存回传数据，再内部攒够 10 条调用 Coze。done=true 表示 Python 已完成全部回传，Java 会强制处理剩余不足 10 条的数据并生成最终 xlsx。")
+    public ApiResponse<Void> result(
+            @Parameter(description = "外观专利检测任务 ID。任务必须处于 RUNNING 状态。", required = true, example = "3938")
+            @PathVariable Long taskId,
+            @Valid @RequestBody AppearancePatentSubmitResultRequest request) {
+        service.submitResult(taskId, request);
+        return ApiResponse.success(null);
+    }
+
+    @DeleteMapping("/tasks/{taskId}")
+    @Operation(summary = "删除任务", description = "删除当前用户的一条外观专利检测任务，同时清理任务结果、scope 状态和分片记录。")
+    public ApiResponse<Void> deleteTask(
+            @Parameter(description = "外观专利检测任务 ID。", required = true, example = "3938")
+            @PathVariable Long taskId,
+            @Parameter(description = "当前用户 ID，必须与创建任务的用户一致。", required = true, example = "1")
+            @RequestParam("user_id") Long userId) {
+        service.deleteTask(taskId, userId);
+        return ApiResponse.success(null);
+    }
+
+    @DeleteMapping("/history/{resultId}")
+    @Operation(summary = "删除历史记录", description = "删除当前用户的一条外观专利检测历史记录。只删除 biz_file_result 记录，不主动删除任务主记录。")
+    public ApiResponse<Void> deleteHistory(
+            @Parameter(description = "历史结果记录 ID，即 history 接口返回的 resultId。", required = true, example = "1001")
+            @PathVariable Long resultId,
+            @Parameter(description = "当前用户 ID。", required = true, example = "1")
+            @RequestParam("user_id") Long userId) {
+        service.deleteHistory(resultId, userId);
+        return ApiResponse.success(null);
+    }
+
+    @GetMapping("/results/{resultId}/download")
+    @Operation(summary = "下载外观专利检测结果文件")
+    public void downloadResult(
+            @Parameter(description = "结果记录 ID", required = true, example = "1001")
+            @PathVariable Long resultId,
+            @Parameter(description = "当前用户 ID", required = true, example = "1")
+            @RequestParam("user_id") Long userId,
+            jakarta.servlet.http.HttpServletResponse response) {
+        String url = service.resolveResultDownloadUrl(resultId, userId);
+        String filename = service.resolveResultDownloadFilename(resultId, userId);
+        if (url == null || url.isBlank()) {
+            throw new ResponseStatusException(HttpStatus.NOT_FOUND, "暂无可下载结果");
+        }
+        try {
+            String encodedFilename = URLEncoder.encode(filename, StandardCharsets.UTF_8).replace("+", "%20");
+            response.setContentType("application/octet-stream");
+            response.setHeader(HttpHeaders.CONTENT_DISPOSITION,
+                    "attachment; filename=\"" + filename + "\"; filename*=UTF-8''" + encodedFilename);
+            try (InputStream in = URI.create(url).toURL().openStream()) {
+                byte[] buffer = new byte[65536];
+                int read;
+                while ((read = in.read(buffer)) != -1) {
+                    response.getOutputStream().write(buffer, 0, read);
+                }
+                response.getOutputStream().flush();
+            }
+        } catch (Exception ex) {
+            throw new ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "下载失败");
+        }
+    }
+}
@@ -0,0 +1,28 @@
+package com.nanri.aiimage.modules.appearancepatent.model.dto;
+
+import com.fasterxml.jackson.annotation.JsonAlias;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
+import lombok.Data;
+
+import java.util.List;
+
+@Data
+@Schema(description = "外观专利检测解析请求")
+public class AppearancePatentParseRequest {
+    @JsonProperty("user_id")
+    @NotNull
+    @Schema(description = "当前用户 ID。后端会把创建的任务、历史记录和结果文件归属到该用户。", example = "1", requiredMode = Schema.RequiredMode.REQUIRED)
+    private Long userId;
+
+    @NotEmpty
+    @Schema(description = "已上传的 Excel 文件列表。当前外观专利检测只读取第一个文件；文件对象来自统一上传接口返回值。", requiredMode = Schema.RequiredMode.REQUIRED)
+    private List<AppearancePatentSourceFileDto> files;
+
+    @JsonProperty("ai_prompt")
+    @JsonAlias({"aiPrompt", "prompt"})
+    @Schema(description = "AI 提示词。非必填；为空时前端会使用默认提示词。后端会保存该提示词，并在调用 Coze workflow 时作为 prompt 参数传入。", example = "请排查这些亚马逊商品在英国及欧洲地区是否存在知识产权侵权风险。")
+    private String aiPrompt;
+}
@@ -0,0 +1,21 @@
+package com.nanri.aiimage.modules.appearancepatent.model.dto;
+
+import com.nanri.aiimage.modules.appearancepatent.model.vo.AppearancePatentParsedRowVo;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+@Data
+@Schema(description = "外观专利检测解析载荷。通常保存到 OSS，数据库只保存 oss 指针。")
+public class AppearancePatentParsedPayloadDto {
+    @Schema(description = "AI 提示词。")
+    private String aiPrompt;
+    @Schema(description = "Excel 原始表头列表。")
+    private List<String> headers = new ArrayList<>();
+    @Schema(description = "返回前端和推给 Python 的代表行，只包含整数 id 和 n_1 行。")
+    private List<AppearancePatentParsedRowVo> items = new ArrayList<>();
+    @Schema(description = "完整有效行，包含 n_2、n_3 等解析后被前端过滤但最终需要补回的子行。")
+    private List<AppearancePatentParsedRowVo> allItems = new ArrayList<>();
+}
@@ -0,0 +1,33 @@
+package com.nanri.aiimage.modules.appearancepatent.model.dto;
+
+import com.fasterxml.jackson.annotation.JsonAlias;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@Schema(description = "外观专利检测单行商品数据")
+public class AppearancePatentResultRowDto {
+    @Schema(description = "Excel 中的 id。代表行通常是整数 id 或 n_1，例如 2_1；最终生成 xlsx 时，2_2、2_3 会复用同组 2_1 的 Coze 检测结果。", example = "2_1")
+    private String id;
+    @Schema(description = "亚马逊 ASIN。后端会统一按大写处理和匹配。", example = "B0CJ8SNXXV")
+    private String asin;
+    @Schema(description = "站点或国家。来自 Excel 的国家列，例如英国、德国、法国。", example = "英国")
+    private String country;
+    @Schema(description = "商品主图或待检测图片 URL。Java 调用 Coze 时会放入 url_list。", example = "https://webstatic.aiproxy.vip/output/20260425/103322/demo.jpg")
+    private String url;
+    @Schema(description = "商品标题。Java 调用 Coze 时会放入 title_list；为空时会回退使用 ASIN。", example = "Women Floral Dress Summer Casual")
+    private String title;
+    @Schema(description = "单行错误信息。通常用于记录 Python 单行处理异常；Coze 失败时后端会尽量保留原始行，不强行写入风险结果。", example = "图片地址为空")
+    private String error;
+    @Schema(description = "单行完成标记。当前主要使用请求体顶层 done 控制任务收尾，该字段仅作兼容。", example = "true")
+    private Boolean done;
+    @Schema(description = "Java 调用 Coze 后生成的标题维度检测结果，对应最终 xlsx 的“标题维度（商标）”列。Python 回传请求不要传该字段；即使传入，后端也会以 Java/Coze 处理结果为准。", example = "标题未发现明显商标侵权风险。", accessMode = Schema.AccessMode.READ_ONLY)
+    private String titleRisk;
+    @Schema(description = "Java 调用 Coze 后生成的外观维度检测结果，对应最终 xlsx 的“外观维度（外观设计专利）”列。Python 回传请求不要传该字段。", example = "未发现明显外观设计专利侵权风险。", accessMode = Schema.AccessMode.READ_ONLY)
+    private String appearanceRisk;
+    @JsonAlias({"patent ", "patent"})
+    @Schema(description = "Java 调用 Coze 后生成的专利维度检测结果，对应最终 xlsx 的“专利维度（发明/实用新型专利）”列。兼容 Coze 返回字段 patent 和 patent 后带空格的情况；Python 回传请求不要传该字段。", example = "未发现明显发明或实用新型专利侵权风险。", accessMode = Schema.AccessMode.READ_ONLY)
+    private String patentRisk;
+    @Schema(description = "Java 调用 Coze 后生成的最终结论，对应最终 xlsx 的“结论”列。Python 回传请求不要传该字段。", example = "未发现明显侵权风险", accessMode = Schema.AccessMode.READ_ONLY)
+    private String conclusion;
+}
@@ -0,0 +1,15 @@
+package com.nanri.aiimage.modules.appearancepatent.model.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@Schema(description = "外观专利检测源文件信息")
+public class AppearancePatentSourceFileDto {
+    @Schema(description = "上传接口返回的临时文件 key。后端根据该 key 查找本地临时 Excel 文件并解析。", example = "uploads/20260426/appearance_patent_17.xlsx", requiredMode = Schema.RequiredMode.REQUIRED)
+    private String fileKey;
+    @Schema(description = "原始文件名。用于历史记录展示和最终结果文件命名。", example = "17.xlsx")
+    private String originalFilename;
+    @Schema(description = "相对目录路径。当前仅记录来源，外观专利检测不依赖该字段处理。", example = "xlsx/17.xlsx")
+    private String relativePath;
+}
@@ -0,0 +1,24 @@
+package com.nanri.aiimage.modules.appearancepatent.model.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+@Data
+@Schema(description = "Python 回传外观专利检测结果请求")
+public class AppearancePatentSubmitResultRequest {
+    @Schema(description = "本次 Python 回传的提交批次标识。建议同一个任务固定使用同一个值，例如 appearance-patent-{taskId}；后端会结合该值和 chunkIndex 做分片幂等。", example = "appearance-patent-3938")
+    private String submissionId;
+    @Schema(description = "当前回传分片序号。建议从 1 开始递增；同一个 submissionId 下相同 chunkIndex 重复提交会被后端识别为重复分片并跳过重复处理。", example = "1")
+    private Integer chunkIndex;
+    @Schema(description = "本任务预计总分片数。如果 Python 是一条一条回传，可设置为总商品数；如果无法预估，可传 0 或 1，最终以 done=true 触发收尾。", example = "458")
+    private Integer chunkTotal;
+    @Schema(description = "是否为最后一次回传。true 表示 Python 已完成该任务全部数据回传；Java 会处理剩余不足 10 条的数据、组装最终 xlsx、上传 OSS 并收尾任务。", example = "false")
+    private Boolean done;
+    @Schema(description = "Python 侧任务级错误信息。非空时 Java 会记录错误并按失败任务收尾；普通单行 Coze 失败不建议写这里。", example = "浏览器执行异常，任务提前结束")
+    private String error;
+    @Schema(description = "本次回传的商品原始数据列表。可以一条一条传，也可以一次多条传；Python 只需要传 id、asin、country、url、title、error、done 等原始/执行字段。titleRisk、appearanceRisk、patentRisk、conclusion 由 Java 攒够 10 条调用 Coze 后生成，Python 不要传。")
+    private List<AppearancePatentResultRowDto> items = new ArrayList<>();
+}
@@ -0,0 +1,15 @@
+package com.nanri.aiimage.modules.appearancepatent.model.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotEmpty;
+import lombok.Data;
+
+import java.util.List;
+
+@Data
+@Schema(description = "外观专利检测批量进度查询请求")
+public class AppearancePatentTaskBatchRequest {
+    @NotEmpty
+    @Schema(description = "需要查询进度的任务 ID 列表。前端只传正在轮询的活跃任务；后端会批量查询，避免每个任务单独请求。", example = "[3938,3939]", requiredMode = Schema.RequiredMode.REQUIRED)
+    private List<Long> taskIds;
+}
@@ -0,0 +1,17 @@
+package com.nanri.aiimage.modules.appearancepatent.model.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@Schema(description = "外观专利检测总览统计")
+public class AppearancePatentDashboardVo {
+    @Schema(description = "运行中任务数量。这里统计 RUNNING 状态任务。", example = "1")
+    private Long pendingTaskCount;
+    @Schema(description = "已结束任务数量，等于成功任务数加失败任务数。", example = "12")
+    private Long processedTaskCount;
+    @Schema(description = "成功任务数量。", example = "10")
+    private Long successTaskCount;
+    @Schema(description = "失败任务数量。", example = "2")
+    private Long failedTaskCount;
+}
@@ -0,0 +1,33 @@
+package com.nanri.aiimage.modules.appearancepatent.model.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@Schema(description = "外观专利检测历史记录项")
+public class AppearancePatentHistoryItemVo {
+    @Schema(description = "结果记录 ID。删除历史、下载结果时使用。", example = "1001")
+    private Long resultId;
+    @Schema(description = "任务 ID。", example = "3938")
+    private Long taskId;
+    @Schema(description = "源 Excel 文件名。", example = "17.xlsx")
+    private String sourceFilename;
+    @Schema(description = "最终结果文件名。任务完成并生成 xlsx 后返回。", example = "17-result.xlsx")
+    private String resultFilename;
+    @Schema(description = "最终结果文件下载地址。后端基于 OSS objectKey 生成的新鲜预签名 URL。", example = "https://bucket.oss-cn-hangzhou.aliyuncs.com/result/appearance_patent/xxx/17-result.xlsx?Expires=...")
+    private String downloadUrl;
+    private Long fileJobId;
+    private String fileStatus;
+    private String fileError;
+    private Boolean fileReady;
+    @Schema(description = "任务状态：PENDING=已解析待推送，RUNNING=执行中，SUCCESS=成功，FAILED=失败。", example = "SUCCESS")
+    private String taskStatus;
+    @Schema(description = "结果是否成功。true 表示任务完成并生成结果文件；false 表示失败或未完成。", example = "true")
+    private Boolean success;
+    @Schema(description = "错误信息。任务失败时返回，例如 Python 超时、结果文件生成失败等。", example = "Python interrupted before uploading final appearance patent result")
+    private String error;
+    @Schema(description = "最终结果行数。包含解析阶段被过滤但最终需要补回的 2_2、2_3 等子行。", example = "716")
+    private Integer rowCount;
+    @Schema(description = "历史记录创建时间，ISO 本地时间字符串。", example = "2026-04-26T10:30:00")
+    private String createdAt;
+}
@@ -0,0 +1,14 @@
+package com.nanri.aiimage.modules.appearancepatent.model.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+@Data
+@Schema(description = "外观专利检测历史记录列表")
+public class AppearancePatentHistoryVo {
+    @Schema(description = "历史记录项列表，默认返回最近 100 条。")
+    private List<AppearancePatentHistoryItemVo> items = new ArrayList<>();
+}
@@ -0,0 +1,26 @@
+package com.nanri.aiimage.modules.appearancepatent.model.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+@Data
+@Schema(description = "外观专利检测解析结果")
+public class AppearancePatentParseVo {
+    @Schema(description = "新创建的任务 ID。后续手动推 Python、激活任务、回传结果、查询进度都使用该 ID。", example = "3938")
+    private Long taskId;
+    @Schema(description = "源 Excel 文件名。", example = "17.xlsx")
+    private String sourceFilename;
+    @Schema(description = "Excel 中检测到的有效数据总行数，不含空行。", example = "716")
+    private Integer totalRows;
+    @Schema(description = "返回前端并准备推给 Python 的代表行数量。只包含整数 id 和 n_1 行。", example = "458")
+    private Integer acceptedRows;
+    @Schema(description = "解析时被过滤或缺少必要字段的行数。n_2、n_3 等子行会计入过滤数，但仍会保存在 OSS 解析载荷中用于最终补齐。", example = "258")
+    private Integer droppedRows;
+    @Schema(description = "本任务最终使用的 AI 提示词。", example = "请排查这些亚马逊商品在英国及欧洲地区是否存在知识产权侵权风险。")
+    private String aiPrompt;
+    @Schema(description = "返回前端的代表行列表。前端只展示样例，不展示完整明细；完整 allItems 已保存在 OSS 解析载荷中。")
+    private List<AppearancePatentParsedRowVo> items = new ArrayList<>();
+}
@@ -0,0 +1,28 @@
+package com.nanri.aiimage.modules.appearancepatent.model.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+@Data
+@Schema(description = "外观专利检测解析出的单行数据")
+public class AppearancePatentParsedRowVo {
+    @Schema(description = "Excel 原始行号，从 1 开始。", example = "2")
+    private Integer rowIndex;
+    @Schema(description = "Excel 中原始 id 值。", example = "2_1")
+    private String sourceId;
+    @Schema(description = "前端展示和 Python 回传使用的 id。整数 id 原样保留，子数据第一条如 2_1 原样保留。", example = "2_1")
+    private String displayId;
+    @Schema(description = "亚马逊 ASIN。", example = "B0CJ8SNXXV")
+    private String asin;
+    @Schema(description = "国家或站点。", example = "英国")
+    private String country;
+    @Schema(description = "商品图片 URL 或商品 URL，供 Coze 检测使用。", example = "https://webstatic.aiproxy.vip/output/demo.jpg")
+    private String url;
+    @Schema(description = "商品标题。", example = "Women Floral Dress Summer Casual")
+    private String title;
+    @Schema(description = "该 Excel 行的原始列值映射。最终生成 xlsx 时可从这里读取价格等字段。", example = "{\"id\":\"2_1\",\"asin\":\"B0CJ8SNXXV\",\"国家\":\"英国\",\"价格\":\"12.99\"}")
+    private Map<String, String> values = new LinkedHashMap<>();
+}
@@ -0,0 +1,16 @@
+package com.nanri.aiimage.modules.appearancepatent.model.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+@Data
+@Schema(description = "外观专利检测批量进度响应")
+public class AppearancePatentTaskBatchVo {
+    @Schema(description = "查询到的任务详情列表。顺序按请求 taskIds 处理。")
+    private List<AppearancePatentTaskDetailVo> items = new ArrayList<>();
+    @Schema(description = "未找到或不属于外观专利检测模块的任务 ID 列表。", example = "[99999]")
+    private List<Long> missingTaskIds = new ArrayList<>();
+}
@@ -0,0 +1,16 @@
+package com.nanri.aiimage.modules.appearancepatent.model.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.util.ArrayList;
+import java.util.List;
+
+@Data
+@Schema(description = "外观专利检测任务进度详情")
+public class AppearancePatentTaskDetailVo {
+    @Schema(description = "任务主记录轻量信息。")
+    private AppearancePatentTaskItemVo task;
+    @Schema(description = "预留的任务明细列表。当前进度接口主要返回任务轻量状态，不返回完整结果明细。")
+    private List<AppearancePatentHistoryItemVo> items = new ArrayList<>();
+}
@@ -0,0 +1,23 @@
+package com.nanri.aiimage.modules.appearancepatent.model.vo;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+@Data
+@Schema(description = "外观专利检测任务轻量信息")
+public class AppearancePatentTaskItemVo {
+    @Schema(description = "任务 ID。", example = "3938")
+    private Long id;
+    @Schema(description = "任务编号，后端自动生成。", example = "APPEARANCE_PATENT-1780000000000000000")
+    private String taskNo;
+    @Schema(description = "任务状态：PENDING=已解析待推送，RUNNING=执行中，SUCCESS=成功，FAILED=失败。", example = "RUNNING")
+    private String status;
+    @Schema(description = "任务级错误信息。失败时返回。", example = "生成外观专利检测结果失败")
+    private String errorMessage;
+    @Schema(description = "创建时间，ISO 本地时间字符串。", example = "2026-04-26T10:00:00")
+    private String createdAt;
+    @Schema(description = "最后更新时间，通常由 Python 回传结果或任务收尾更新。", example = "2026-04-26T10:05:00")
+    private String updatedAt;
+    @Schema(description = "完成时间。任务未结束时为空。", example = "2026-04-26T10:10:00")
+    private String finishedAt;
+}
@@ -0,0 +1,144 @@
+package com.nanri.aiimage.modules.appearancepatent.service;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.nanri.aiimage.modules.appearancepatent.model.dto.AppearancePatentResultRowDto;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.stereotype.Service;
+
+import java.time.Duration;
+import java.time.Instant;
+import java.util.ArrayList;
+import java.util.List;
+
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class AppearancePatentTaskCacheService {
+
+    private static final long TTL_HOURS = 24;
+
+    private final StringRedisTemplate stringRedisTemplate;
+    private final ObjectMapper objectMapper;
+
+    public void appendPendingRow(Long taskId, Integer chunkIndex, AppearancePatentResultRowDto row) {
+        if (taskId == null || taskId <= 0 || chunkIndex == null || row == null) {
+            return;
+        }
+        try {
+            stringRedisTemplate.opsForList().rightPush(
+                    pendingRowsKey(taskId),
+                    objectMapper.writeValueAsString(new PendingRow(chunkIndex, row))
+            );
+            stringRedisTemplate.expire(pendingRowsKey(taskId), Duration.ofHours(TTL_HOURS));
+            touchTaskHeartbeat(taskId);
+        } catch (Exception ignored) {
+        }
+    }
+
+    public long pendingRowCount(Long taskId) {
+        Long size;
+        try {
+            size = stringRedisTemplate.opsForList().size(pendingRowsKey(taskId));
+        } catch (Exception ex) {
+            log.warn("[appearance-patent-cache] pending row count degraded taskId={} msg={}", taskId, ex.getMessage());
+            return 0L;
+        }
+        return size == null ? 0L : size;
+    }
+
+    public List<PendingRow> drainPendingRows(Long taskId, int limit) {
+        if (taskId == null || taskId <= 0 || limit <= 0) {
+            return List.of();
+        }
+        String key = pendingRowsKey(taskId);
+        List<String> values;
+        try {
+            values = stringRedisTemplate.opsForList().range(key, 0, limit - 1L);
+        } catch (Exception ex) {
+            log.warn("[appearance-patent-cache] drain range degraded taskId={} msg={}", taskId, ex.getMessage());
+            return List.of();
+        }
+        if (values == null || values.isEmpty()) {
+            return List.of();
+        }
+        try {
+            stringRedisTemplate.opsForList().trim(key, values.size(), -1);
+        } catch (Exception ex) {
+            log.warn("[appearance-patent-cache] drain trim degraded taskId={} msg={}", taskId, ex.getMessage());
+            return List.of();
+        }
+        List<PendingRow> rows = new ArrayList<>();
+        for (String value : values) {
+            if (value == null || value.isBlank()) {
+                continue;
+            }
+            try {
+                rows.add(objectMapper.readValue(value, PendingRow.class));
+            } catch (Exception ignored) {
+            }
+        }
+        touchTaskHeartbeat(taskId);
+        return rows;
+    }
+
+    public void touchTaskHeartbeat(Long taskId) {
+        if (taskId == null || taskId <= 0) {
+            return;
+        }
+        try {
+            stringRedisTemplate.opsForValue().set(
+                    heartbeatKey(taskId),
+                    String.valueOf(Instant.now().toEpochMilli()),
+                    Duration.ofHours(TTL_HOURS)
+            );
+        } catch (Exception ex) {
+            log.warn("[appearance-patent-cache] touch heartbeat degraded taskId={} msg={}", taskId, ex.getMessage());
+        }
+    }
+
+    public long getTaskHeartbeatMillis(Long taskId) {
+        if (taskId == null || taskId <= 0) {
+            return 0L;
+        }
+        String raw;
+        try {
+            raw = stringRedisTemplate.opsForValue().get(heartbeatKey(taskId));
+        } catch (Exception ex) {
+            log.warn("[appearance-patent-cache] get heartbeat degraded taskId={} msg={}", taskId, ex.getMessage());
+            return 0L;
+        }
+        if (raw == null || raw.isBlank()) {
+            return 0L;
+        }
+        try {
+            return Long.parseLong(raw);
+        } catch (NumberFormatException ignored) {
+            return 0L;
+        }
+    }
+
+    public void deleteTaskCache(Long taskId) {
+        if (taskId == null || taskId <= 0) {
+            return;
+        }
+        try {
+            stringRedisTemplate.delete(pendingRowsKey(taskId));
+            stringRedisTemplate.delete(heartbeatKey(taskId));
+        } catch (Exception ex) {
+            log.warn("[appearance-patent-cache] delete degraded taskId={} msg={}", taskId, ex.getMessage());
+        }
+    }
+
+    private String pendingRowsKey(Long taskId) {
+        return "appearance-patent:task:pending-rows:" + taskId;
+    }
+
+    private String heartbeatKey(Long taskId) {
+        return "appearance-patent:task:heartbeat:" + taskId;
+    }
+
+    public record PendingRow(Integer chunkIndex, AppearancePatentResultRowDto row) {
+    }
+}