ids = new LinkedHashSet<>();
+ for (Object item : items) {
+ long value;
+ if (item instanceof Number number) {
+ value = number.longValue();
+ } else if (item instanceof String text && text.matches("\\d+")) {
+ value = Long.parseLong(text);
+ } else {
+ throw new BusinessException(400, "结果文件参数无效");
+ }
+ if (value <= 0) {
+ throw new BusinessException(400, "结果文件参数无效");
+ }
+ ids.add(value);
+ }
+ return new ArrayList<>(ids);
+ }
+
+ private void requireShopDataCrawlTaskAccess(HttpServletRequest request) {
+ AdminUserEntity operator;
+ try {
+ operator = adminAuthSupport.requireAdmin(request);
+ } catch (BusinessException authFailure) {
+ operator = resolveInternalOperator(request);
+ if (operator == null) {
+ throw authFailure;
+ }
+ }
+ permissionMenuService.requireShopDataCrawlTaskAccess(operator);
+ }
+
+ private AdminUserEntity resolveInternalOperator(HttpServletRequest request) {
+ String suppliedToken = request.getHeader("X-Internal-Token");
+ if (!isTrustedInternalRequest(suppliedToken)) {
+ return null;
+ }
+ String rawOperatorId = request.getParameter("operatorId");
+ if (rawOperatorId == null || rawOperatorId.isBlank()) {
+ rawOperatorId = request.getParameter("operator_id");
+ }
+ if (rawOperatorId == null || rawOperatorId.isBlank()) {
+ return null;
+ }
+ try {
+ return permissionMenuService.requireAdminOperator(Long.parseLong(rawOperatorId.trim()));
+ } catch (NumberFormatException ex) {
+ return null;
+ }
+ }
+
+ private boolean isTrustedInternalRequest(String suppliedToken) {
+ String expectedToken = resolveExpectedInternalToken();
+ return !expectedToken.isBlank() && suppliedToken != null && !suppliedToken.isBlank()
+ && MessageDigest.isEqual(
+ expectedToken.getBytes(StandardCharsets.UTF_8),
+ suppliedToken.trim().getBytes(StandardCharsets.UTF_8));
+ }
+
+ private String resolveExpectedInternalToken() {
+ if (internalToken != null && !internalToken.isBlank()) {
+ return internalToken.trim();
+ }
+ Path path = resolveInternalTokenFile();
+ if (path == null || !Files.isRegularFile(path)) {
+ return "";
+ }
+ try {
+ return Files.readString(path, StandardCharsets.UTF_8).trim();
+ } catch (Exception ignored) {
+ return "";
+ }
+ }
+
+ private Path resolveInternalTokenFile() {
+ String configuredPath = internalTokenFile == null ? "" : internalTokenFile.trim();
+ if (!configuredPath.isEmpty()) {
+ if (configuredPath.equals("~") || configuredPath.startsWith("~/") || configuredPath.startsWith("~\\")) {
+ String userHome = System.getProperty("user.home", "").trim();
+ if (userHome.isEmpty()) {
+ return null;
+ }
+ configuredPath = configuredPath.length() == 1
+ ? userHome
+ : Path.of(userHome, configuredPath.substring(2)).toString();
+ }
+ Path configuredTokenPath = Path.of(configuredPath);
+ return configuredTokenPath.isAbsolute() ? configuredTokenPath.normalize() : null;
+ }
+ String userHome = System.getProperty("user.home", "").trim();
+ return userHome.isEmpty()
+ ? null
+ : Path.of(userHome, ".aiimage", "internal-token").toAbsolutePath().normalize();
+ }
+
+ private static int parseInt(String raw, int defaultValue, String errorMessage) {
+ if (raw == null || raw.isBlank()) {
+ return defaultValue;
+ }
+ try {
+ return Integer.parseInt(raw.trim());
+ } catch (NumberFormatException ex) {
+ throw new BusinessException(400, errorMessage);
+ }
+ }
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/mapper/ShopDataCrawlAdminTasksMapper.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/mapper/ShopDataCrawlAdminTasksMapper.java
new file mode 100644
index 00000000..8466498e
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/mapper/ShopDataCrawlAdminTasksMapper.java
@@ -0,0 +1,185 @@
+package com.nanri.aiimage.modules.shopdatacrawl.mapper;
+
+import com.nanri.aiimage.modules.shopdatacrawl.model.dto.ShopDataCrawlAdminFileJobBriefDto;
+import com.nanri.aiimage.modules.shopdatacrawl.model.dto.ShopDataCrawlAdminGroupLabelDto;
+import com.nanri.aiimage.modules.shopdatacrawl.model.dto.ShopDataCrawlAdminGroupRow;
+import com.nanri.aiimage.modules.shopdatacrawl.model.dto.ShopDataCrawlAdminRow;
+import com.nanri.aiimage.modules.shopdatacrawl.model.dto.ShopDataCrawlDownloadRowDto;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.SelectProvider;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 店铺数据抓取记录"按店铺分组列表"与批量下载的数据源查询，
+ * 语义逐条对照 Flask admin_api.py 中 list_shop_data_crawl_tasks /
+ * _load_shop_data_crawl_download_rows 的 SQL。
+ *
+ * 参数统一走单参 Map：筛选与分页字段用语义键（shopName/groupName/country/
+ * createdFrom/createdTo/pageLimit/pageOffset），IN 列表键 shopNames / resultIds，
+ * 占位元素键为 sn0..snN / ri0..riN（调用方在 Service 内按序铺平，避免动态列表绑定歧义）。
+ */
+@Mapper
+public interface ShopDataCrawlAdminTasksMapper {
+
+ /** 店铺分组总数（按 TRIM(source_filename) 去重后的组数）。 */
+ @SelectProvider(type = SqlProvider.class, method = "countShopGroups")
+ long countShopGroups(Map p);
+
+ /** 当前页店铺分组（每店最新归档时间）。 */
+ @SelectProvider(type = SqlProvider.class, method = "selectShopGroupPage")
+ List selectShopGroupPage(Map p);
+
+ /** 当前页每家店铺的最新结果行（窗口函数 row_number=1），需先铺平 shopNames。 */
+ @SelectProvider(type = SqlProvider.class, method = "selectLatestRowsForShops")
+ List selectLatestRowsForShops(Map p);
+
+ /** 店铺 → 分组名映射，需先铺平 shopNames。 */
+ @SelectProvider(type = SqlProvider.class, method = "selectGroupLabels")
+ List selectGroupLabels(Map p);
+
+ /** 每个结果文件最新一条 ASSEMBLE_RESULT 任务（按 job id 取最大），需先铺平 resultIds。 */
+ @SelectProvider(type = SqlProvider.class, method = "selectLatestAssembleJobs")
+ List selectLatestAssembleJobs(Map p);
+
+ /** 批量下载 zip 所需结果行，需先铺平 resultIds。 */
+ @SelectProvider(type = SqlProvider.class, method = "selectDownloadRows")
+ List selectDownloadRows(Map p);
+
+ class SqlProvider {
+
+ private static final String LATEST_TIME = "COALESCE(df.last_success_at, df.updated_at, "
+ + "t.finished_at, t.updated_at, t.created_at)";
+
+ private static final String SHOP_KEY = "TRIM(COALESCE(r.source_filename, ''))";
+
+ private static final String FROM_WHERE_BASE =
+ " FROM biz_file_result r "
+ + "JOIN biz_file_task t ON t.id = r.task_id "
+ + "LEFT JOIN biz_shop_data_crawl_daily_file df ON df.latest_result_id = r.id "
+ + "LEFT JOIN users u ON u.id = r.user_id "
+ + "WHERE r.module_type = 'SHOP_DATA_CRAWL' "
+ + "AND t.module_type = 'SHOP_DATA_CRAWL' "
+ + "AND TRIM(COALESCE(r.result_file_url, '')) <> ''";
+
+ public String countShopGroups(Map p) {
+ return "SELECT COUNT(*) AS total FROM (SELECT " + SHOP_KEY + " AS shopKey"
+ + FROM_WHERE_BASE + whereTail(p, "") + " GROUP BY " + SHOP_KEY + ") grouped_shops";
+ }
+
+ public String selectShopGroupPage(Map p) {
+ return "SELECT " + SHOP_KEY + " AS shopName, MAX(" + LATEST_TIME + ") AS latestCreatedAt"
+ + FROM_WHERE_BASE + whereTail(p, "")
+ + " GROUP BY " + SHOP_KEY
+ + " ORDER BY latestCreatedAt DESC, shopName ASC"
+ + " LIMIT #{pageLimit} OFFSET #{pageOffset}";
+ }
+
+ public String selectLatestRowsForShops(Map p) {
+ return "SELECT ranked.resultId, ranked.taskId, ranked.userId, ranked.username,"
+ + " ranked.shopName, ranked.shopId, ranked.resultFilename, ranked.resultFileUrl,"
+ + " ranked.resultFileSize, ranked.resultContentType, ranked.rowCount,"
+ + " ranked.resultSuccess, ranked.resultError, ranked.resultCreatedAt,"
+ + " ranked.taskNo, ranked.taskStatus, ranked.requestJson, ranked.taskError,"
+ + " ranked.createdAt, ranked.updatedAt, ranked.finishedAt,"
+ + " ranked.latestFileUpdatedAt, ranked.countryCodesJson, ranked.rowCountDisplay"
+ + " FROM (SELECT r.id AS resultId, r.task_id AS taskId, r.user_id AS userId,"
+ + " u.username AS username,"
+ + " r.source_filename AS shopName, r.source_file_url AS shopId,"
+ + " r.result_filename AS resultFilename, r.result_file_url AS resultFileUrl,"
+ + " r.result_file_size AS resultFileSize, r.result_content_type AS resultContentType,"
+ + " r.row_count AS rowCount, r.success AS resultSuccess,"
+ + " r.error_message AS resultError, r.created_at AS resultCreatedAt,"
+ + " t.task_no AS taskNo, t.status AS taskStatus, t.request_json AS requestJson,"
+ + " t.error_message AS taskError, t.created_at AS createdAt,"
+ + " t.updated_at AS updatedAt, t.finished_at AS finishedAt,"
+ + " " + LATEST_TIME + " AS latestFileUpdatedAt,"
+ + " df.country_codes_json AS countryCodesJson,"
+ + " COALESCE(df.row_count, r.row_count) AS rowCountDisplay,"
+ + " ROW_NUMBER() OVER (PARTITION BY " + SHOP_KEY
+ + " ORDER BY " + LATEST_TIME + " DESC, r.id DESC) AS rowNo"
+ + FROM_WHERE_BASE
+ + whereTail(p, " AND " + SHOP_KEY + " IN (" + inPlaceholders(p, "shopNames", "sn") + ")")
+ + ") ranked WHERE ranked.rowNo = 1"
+ + " ORDER BY ranked.latestFileUpdatedAt DESC, ranked.resultId DESC";
+ }
+
+ public String selectGroupLabels(Map p) {
+ return "SELECT TRIM(sm.shop_name) AS shopName,"
+ + " GROUP_CONCAT(DISTINCT COALESCE(NULLIF(g.group_name, ''), NULLIF(sm.group_name, ''))"
+ + " ORDER BY sm.id SEPARATOR '、') AS groupName"
+ + " FROM biz_shop_manage sm"
+ + " LEFT JOIN biz_shop_manage_group g ON g.id = sm.group_id"
+ + " WHERE TRIM(sm.shop_name) IN (" + inPlaceholders(p, "shopNames", "sn") + ")"
+ + " GROUP BY TRIM(sm.shop_name)";
+ }
+
+ public String selectLatestAssembleJobs(Map p) {
+ return "SELECT fj.result_id AS resultId, fj.id AS fileJobId,"
+ + " fj.status AS fileStatus, fj.error_message AS fileError"
+ + " FROM biz_task_file_job fj"
+ + " INNER JOIN (SELECT result_id, MAX(id) AS max_id FROM biz_task_file_job"
+ + " WHERE module_type = 'SHOP_DATA_CRAWL' AND job_type = 'ASSEMBLE_RESULT'"
+ + " AND result_id IN (" + inPlaceholders(p, "resultIds", "ri") + ")"
+ + " GROUP BY result_id) latest ON fj.id = latest.max_id";
+ }
+
+ public String selectDownloadRows(Map p) {
+ return "SELECT r.id AS resultId, r.task_id AS taskId, r.user_id AS userId,"
+ + " r.source_filename AS sourceFilename, r.result_filename AS resultFilename,"
+ + " r.result_file_url AS resultFileUrl, t.status AS taskStatus"
+ + " FROM biz_file_result r"
+ + " JOIN biz_file_task t ON t.id = r.task_id"
+ + " WHERE r.module_type = 'SHOP_DATA_CRAWL' AND t.module_type = 'SHOP_DATA_CRAWL'"
+ + " AND r.id IN (" + inPlaceholders(p, "resultIds", "ri") + ")";
+ }
+
+ /** 追加可选的店铺/分组/国家/时间筛选。 */
+ private static String whereTail(Map p, String extraCondition) {
+ StringBuilder sql = new StringBuilder(extraCondition == null ? "" : extraCondition);
+ String shopName = (String) p.get("shopName");
+ if (shopName != null && !shopName.isBlank()) {
+ sql.append(" AND r.source_filename LIKE CONCAT('%', #{shopName}, '%')");
+ }
+ String groupName = (String) p.get("groupName");
+ if (groupName != null && !groupName.isBlank()) {
+ sql.append(" AND EXISTS (SELECT 1 FROM biz_shop_manage sm"
+ + " LEFT JOIN biz_shop_manage_group g ON g.id = sm.group_id"
+ + " WHERE TRIM(COALESCE(sm.shop_name, '')) = "
+ + "TRIM(COALESCE(r.source_filename, ''))"
+ + " AND COALESCE(NULLIF(g.group_name, ''), NULLIF(sm.group_name, ''))"
+ + " LIKE CONCAT('%', #{groupName}, '%'))");
+ }
+ if (p.get("country") != null && !((String) p.get("country")).isBlank()) {
+ sql.append(" AND JSON_CONTAINS(COALESCE(df.country_codes_json,"
+ + " JSON_EXTRACT(t.request_json, '$.countryCodes'),"
+ + " JSON_EXTRACT(t.request_json, '$.country_codes'), '[]'),"
+ + " CONCAT('\"', #{country}, '\"'))");
+ }
+ if (p.get("createdFrom") != null) {
+ sql.append(" AND t.created_at >= #{createdFrom}");
+ }
+ if (p.get("createdTo") != null) {
+ sql.append(" AND t.created_at <= #{createdTo}");
+ }
+ return sql.toString();
+ }
+
+ /** 列表长度对应占位符 #{prefix0}, #{prefix1}...；空列表返回空字符串，调用方须保证非空。 */
+ private static String inPlaceholders(Map p, String listKey, String prefix) {
+ Object raw = p.get(listKey);
+ if (!(raw instanceof List items) || items.isEmpty()) {
+ return "";
+ }
+ StringBuilder sql = new StringBuilder();
+ for (int i = 0; i < items.size(); i++) {
+ if (i > 0) {
+ sql.append(", ");
+ }
+ sql.append("#{").append(prefix).append(i).append('}');
+ }
+ return sql.toString();
+ }
+ }
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminFileJobBriefDto.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminFileJobBriefDto.java
new file mode 100644
index 00000000..91797a69
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminFileJobBriefDto.java
@@ -0,0 +1,15 @@
+package com.nanri.aiimage.modules.shopdatacrawl.model.dto;
+
+import lombok.Data;
+
+/**
+ * 结果文件最近的 ASSEMBLE_RESULT 文件任务（按 job id 取最新，语义对齐 Flask）。
+ */
+@Data
+public class ShopDataCrawlAdminFileJobBriefDto {
+
+ private Long resultId;
+ private Long fileJobId;
+ private String fileStatus;
+ private String fileError;
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminGroupLabelDto.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminGroupLabelDto.java
new file mode 100644
index 00000000..70a199d7
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminGroupLabelDto.java
@@ -0,0 +1,13 @@
+package com.nanri.aiimage.modules.shopdatacrawl.model.dto;
+
+import lombok.Data;
+
+/**
+ * 店铺 → 分组名（g.group_name 优先于 sm.group_name，多分组「、」连接）。
+ */
+@Data
+public class ShopDataCrawlAdminGroupLabelDto {
+
+ private String shopName;
+ private String groupName;
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminGroupRow.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminGroupRow.java
new file mode 100644
index 00000000..6008fdb0
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminGroupRow.java
@@ -0,0 +1,15 @@
+package com.nanri.aiimage.modules.shopdatacrawl.model.dto;
+
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 按店铺分组列表的一行（店铺名 + 该店全部匹配结果中最新的归档时间），用于分页组集合。
+ */
+@Data
+public class ShopDataCrawlAdminGroupRow {
+
+ private String shopName;
+ private LocalDateTime latestCreatedAt;
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminRow.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminRow.java
new file mode 100644
index 00000000..94d63694
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlAdminRow.java
@@ -0,0 +1,41 @@
+package com.nanri.aiimage.modules.shopdatacrawl.model.dto;
+
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 管理列表"每店最新结果行"（窗口函数 row_number=1 结果），字段对齐 Flask
+ * _SHOP_DATA_CRAWL_ADMIN_COLUMNS 的列集。
+ */
+@Data
+public class ShopDataCrawlAdminRow {
+
+ private Long resultId;
+ private Long taskId;
+ private Long userId;
+ private String username;
+ /** r.source_filename 原始值（可能带首尾空格，展示用，与 Flask 一致）。 */
+ private String shopName;
+ /** r.source_file_url，语义为店铺页 URL。 */
+ private String shopId;
+ private String resultFilename;
+ private String resultFileUrl;
+ private Long resultFileSize;
+ private String resultContentType;
+ private Integer rowCount;
+ /** 结果成功标志：-1 处理中 / 0 失败 / 1 成功。 */
+ private Integer resultSuccess;
+ private String resultError;
+ private LocalDateTime resultCreatedAt;
+ private String taskNo;
+ private String taskStatus;
+ private String requestJson;
+ private String taskError;
+ private LocalDateTime createdAt;
+ private LocalDateTime updatedAt;
+ private LocalDateTime finishedAt;
+ private LocalDateTime latestFileUpdatedAt;
+ private String countryCodesJson;
+ private Integer rowCountDisplay;
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlDownloadRowDto.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlDownloadRowDto.java
new file mode 100644
index 00000000..2c0ca318
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/model/dto/ShopDataCrawlDownloadRowDto.java
@@ -0,0 +1,18 @@
+package com.nanri.aiimage.modules.shopdatacrawl.model.dto;
+
+import lombok.Data;
+
+/**
+ * 批量下载 zip 需要的行数据（等价 Flask _load_shop_data_crawl_download_rows）。
+ */
+@Data
+public class ShopDataCrawlDownloadRowDto {
+
+ private Long resultId;
+ private Long taskId;
+ private Long userId;
+ private String sourceFilename;
+ private String resultFilename;
+ private String resultFileUrl;
+ private String taskStatus;
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/service/ShopDataCrawlAdminTasksService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/service/ShopDataCrawlAdminTasksService.java
new file mode 100644
index 00000000..c2f54aa9
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/shopdatacrawl/service/ShopDataCrawlAdminTasksService.java
@@ -0,0 +1,333 @@
+package com.nanri.aiimage.modules.shopdatacrawl.service;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.nanri.aiimage.common.exception.BusinessException;
+import com.nanri.aiimage.modules.shopdatacrawl.mapper.ShopDataCrawlAdminTasksMapper;
+import com.nanri.aiimage.modules.shopdatacrawl.model.dto.ShopDataCrawlAdminFileJobBriefDto;
+import com.nanri.aiimage.modules.shopdatacrawl.model.dto.ShopDataCrawlAdminGroupLabelDto;
+import com.nanri.aiimage.modules.shopdatacrawl.model.dto.ShopDataCrawlAdminGroupRow;
+import com.nanri.aiimage.modules.shopdatacrawl.model.dto.ShopDataCrawlAdminRow;
+import com.nanri.aiimage.modules.shopdatacrawl.model.dto.ShopDataCrawlDownloadRowDto;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * 店铺数据抓取记录管理端查询组装：按店铺分组、每店取最新结果（等价 Flask
+ * admin_api.py list_shop_data_crawl_tasks），以及批量 zip 的行数据加载。
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class ShopDataCrawlAdminTasksService {
+
+ private static final DateTimeFormatter ADMIN_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+ private static final Set SUPPORTED_COUNTRIES = Set.of("DE", "UK", "FR", "IT", "ES");
+
+ private final ShopDataCrawlAdminTasksMapper adminTasksMapper;
+ private final ObjectMapper objectMapper;
+
+ /**
+ * 分页列表组装（组总数 → 当前页店铺组 → 每店最新结果行 + 文件任务/分组名补充）。
+ */
+ public Map listShopGroups(int page, int pageSize, String shopName, String groupName,
+ String country, String createdFromRaw, String createdToRaw) {
+ LocalDateTime createdFrom = parseAdminDateTime("created_from", createdFromRaw);
+ LocalDateTime createdTo = parseAdminDateTime("created_to", createdToRaw);
+ String countryFilter = blankToNull(country);
+ if (countryFilter != null) {
+ countryFilter = countryFilter.trim().toUpperCase(Locale.ROOT);
+ if (!SUPPORTED_COUNTRIES.contains(countryFilter)) {
+ throw new BusinessException(400, "不支持的国家代码: " + countryFilter);
+ }
+ }
+ Map p = new HashMap<>();
+ p.put("shopName", blankToNull(shopName));
+ p.put("groupName", blankToNull(groupName));
+ p.put("country", countryFilter);
+ p.put("createdFrom", createdFrom);
+ p.put("createdTo", createdTo);
+
+ long total = adminTasksMapper.countShopGroups(p);
+ List> items = new ArrayList<>();
+ if (total > 0) {
+ p.put("pageLimit", pageSize);
+ p.put("pageOffset", (page - 1) * pageSize);
+ List groups = adminTasksMapper.selectShopGroupPage(p);
+ if (!groups.isEmpty()) {
+ items = assembleGroupItems(p, groups);
+ }
+ }
+ Map payload = new LinkedHashMap<>();
+ payload.put("items", items);
+ payload.put("total", total);
+ payload.put("page", page);
+ payload.put("page_size", pageSize);
+ return payload;
+ }
+
+ /** 批量下载 zip 所需结果行（仅存在行，缺失 id 由调用方自行记为部分失败）。 */
+ public List loadDownloadRows(List resultIds) {
+ if (resultIds == null || resultIds.isEmpty()) {
+ return List.of();
+ }
+ Map p = new HashMap<>();
+ flattenList(p, resultIds, "resultIds", "ri");
+ return adminTasksMapper.selectDownloadRows(p);
+ }
+
+ private List> assembleGroupItems(Map p, List groups) {
+ List shopNames = new ArrayList<>();
+ for (ShopDataCrawlAdminGroupRow group : groups) {
+ shopNames.add(group.getShopName() == null ? "" : group.getShopName());
+ }
+ flattenList(p, shopNames, "shopNames", "sn");
+
+ // 分组名：店铺 → 分组（group_name 优先，多分组连接）
+ Map labelByShop = new HashMap<>();
+ for (ShopDataCrawlAdminGroupLabelDto label : adminTasksMapper.selectGroupLabels(p)) {
+ labelByShop.put(normalizeShopKey(label.getShopName()), label.getGroupName() == null ? "" : label.getGroupName());
+ }
+
+ // 当前页每家店铺最新结果行，按店铺归一化名聚组
+ List rows = adminTasksMapper.selectLatestRowsForShops(p);
+ Map> rowsByShop = new LinkedHashMap<>();
+ for (ShopDataCrawlAdminRow row : rows) {
+ rowsByShop.computeIfAbsent(normalizeShopKey(row.getShopName()), key -> new ArrayList<>()).add(row);
+ }
+
+ // 结果文件最近一次 ASSEMBLE_RESULT 任务（文件组装状态/错误）
+ Map jobByResult = loadAssembleJobMap(rows);
+
+ List> items = new ArrayList<>(groups.size());
+ for (ShopDataCrawlAdminGroupRow group : groups) {
+ List children = rowsByShop.getOrDefault(
+ normalizeShopKey(group.getShopName()), List.of());
+ List> results = new ArrayList<>();
+ if (!children.isEmpty()) {
+ results.add(toItemMap(children.get(0), jobByResult.get(children.get(0).getResultId()),
+ labelByShop));
+ }
+ LocalDateTime latest = group.getLatestCreatedAt();
+ if (latest == null && !children.isEmpty()) {
+ latest = children.get(0).getLatestFileUpdatedAt();
+ }
+ if (latest == null && !children.isEmpty()) {
+ latest = children.get(0).getResultCreatedAt();
+ }
+ Map groupItem = new LinkedHashMap<>();
+ groupItem.put("shop_name", isBlank(group.getShopName()) ? "未命名" : group.getShopName());
+ groupItem.put("shop_id", results.isEmpty()
+ ? "" : results.get(0).getOrDefault("shop_id", ""));
+ groupItem.put("group_name", groupLabel(labelByShop, group.getShopName()));
+ groupItem.put("latest_created_at", formatAdminTime(latest));
+ groupItem.put("results", results);
+ items.add(groupItem);
+ }
+ return items;
+ }
+
+ private Map loadAssembleJobMap(List rows) {
+ if (rows.isEmpty()) {
+ return Map.of();
+ }
+ List resultIds = new ArrayList<>();
+ for (ShopDataCrawlAdminRow row : rows) {
+ if (row.getResultId() != null && row.getResultId() > 0) {
+ resultIds.add(row.getResultId());
+ }
+ }
+ List distinctIds = new ArrayList<>(new LinkedHashSet<>(resultIds));
+ if (distinctIds.isEmpty()) {
+ return Map.of();
+ }
+ Map p = new HashMap<>();
+ flattenList(p, distinctIds, "resultIds", "ri");
+ Map jobByResult = new HashMap<>();
+ for (ShopDataCrawlAdminFileJobBriefDto job : adminTasksMapper.selectLatestAssembleJobs(p)) {
+ if (job.getResultId() != null) {
+ jobByResult.put(job.getResultId(), job);
+ }
+ }
+ return jobByResult;
+ }
+
+ /** 单个"最新结果行"→ 前端字段 Map（键 snake_case，对齐 Flask _shop_data_crawl_admin_item）。 */
+ private Map toItemMap(ShopDataCrawlAdminRow row,
+ ShopDataCrawlAdminFileJobBriefDto job,
+ Map labelByShop) {
+ boolean fileReady = row.getResultFileUrl() != null && !row.getResultFileUrl().isBlank();
+ Map m = new LinkedHashMap<>();
+ m.put("task_id", row.getTaskId());
+ m.put("task_no", defaultText(row.getTaskNo()));
+ m.put("result_id", row.getResultId());
+ m.put("user_id", row.getUserId());
+ m.put("username", defaultText(row.getUsername()));
+ m.put("shop_name", defaultText(row.getShopName()));
+ m.put("shop_id", defaultText(row.getShopId()));
+ m.put("group_name", groupLabel(labelByShop, row.getShopName()));
+ m.put("status", defaultText(row.getTaskStatus()));
+ Integer success = row.getResultSuccess();
+ m.put("success", success == null || success < 0 ? null : Integer.valueOf(1).equals(success));
+ m.put("error", firstNonBlank(row.getResultError(), row.getTaskError(),
+ job == null ? null : job.getFileError()));
+ m.put("country_codes", countryCodesOf(row.getCountryCodesJson(), row.getRequestJson()));
+ m.put("output_filename", defaultText(row.getResultFilename()));
+ m.put("result_file_url", defaultText(row.getResultFileUrl()));
+ m.put("file_ready", fileReady);
+ m.put("file_job_id", job == null ? null : job.getFileJobId());
+ m.put("file_status", fileStatusOf(job, fileReady));
+ m.put("file_error", job == null || job.getFileError() == null ? "" : job.getFileError());
+ m.put("file_size", row.getResultFileSize() == null ? 0L : row.getResultFileSize());
+ Integer displayRowCount = row.getRowCountDisplay() == null ? row.getRowCount() : row.getRowCountDisplay();
+ m.put("row_count", displayRowCount == null ? 0 : displayRowCount);
+ m.put("created_at", formatAdminTime(
+ row.getCreatedAt() == null ? row.getResultCreatedAt() : row.getCreatedAt()));
+ m.put("updated_at", formatAdminTime(row.getUpdatedAt()));
+ m.put("finished_at", formatAdminTime(row.getFinishedAt()));
+ return m;
+ }
+
+ private String fileStatusOf(ShopDataCrawlAdminFileJobBriefDto job, boolean fileReady) {
+ if (job != null && job.getFileStatus() != null && !job.getFileStatus().isBlank()) {
+ return job.getFileStatus();
+ }
+ return fileReady ? "SUCCESS" : "";
+ }
+
+ private String groupLabel(Map labelByShop, String shopName) {
+ String value = labelByShop.get(normalizeShopKey(shopName));
+ return value == null ? "" : value;
+ }
+
+ /** 店铺 key 归一化：trim + 小写（Flask casefold 语义，兼容 DB 内尾随空白差异）。 */
+ private static String normalizeShopKey(String shopName) {
+ return (shopName == null ? "" : shopName.trim().toLowerCase(Locale.ROOT));
+ }
+
+ /** 国家代码解析：df.country_codes_json 优先，空则回退 request_json 的 countryCodes/country_codes。 */
+ private List countryCodesOf(String countryCodesJson, String requestJson) {
+ List codes = parseStringArray(countryCodesJson);
+ if (codes.isEmpty()) {
+ codes = requestCountryCodes(requestJson);
+ }
+ return codes;
+ }
+
+ private List requestCountryCodes(String requestJson) {
+ if (requestJson == null || requestJson.isBlank()) {
+ return List.of();
+ }
+ try {
+ JsonNode root = objectMapper.readTree(requestJson);
+ if (root == null || !root.isObject()) {
+ return List.of();
+ }
+ JsonNode array = root.get("countryCodes");
+ if (array == null) {
+ array = root.get("country_codes");
+ }
+ if (array == null || !array.isArray()) {
+ return List.of();
+ }
+ return parseArrayNodes(array);
+ } catch (Exception ex) {
+ log.warn("[shop-data-crawl-admin] request_json 国家代码解析失败: {}", ex.getMessage());
+ return List.of();
+ }
+ }
+
+ private List parseStringArray(String json) {
+ if (json == null || json.isBlank()) {
+ return List.of();
+ }
+ try {
+ JsonNode array = objectMapper.readTree(json);
+ return array != null && array.isArray() ? parseArrayNodes(array) : List.of();
+ } catch (Exception ex) {
+ log.warn("[shop-data-crawl-admin] country_codes_json 解析失败: {}", ex.getMessage());
+ return List.of();
+ }
+ }
+
+ private List parseArrayNodes(JsonNode array) {
+ List codes = new ArrayList<>();
+ for (JsonNode node : array) {
+ if (!node.isContainerNode()) {
+ String code = node.asText("").trim().toUpperCase(Locale.ROOT);
+ if (!code.isEmpty()) {
+ codes.add(code);
+ }
+ }
+ }
+ return codes;
+ }
+
+ /** 时间参数解析：兼容空格/T 分隔、可选秒/时、尾随 Z，失败时给出与 Flask 一致的提示。 */
+ private static LocalDateTime parseAdminDateTime(String name, String raw) {
+ String value = raw == null ? "" : raw.trim();
+ if (value.isEmpty()) {
+ return null;
+ }
+ String normalized = value.replace('T', ' ').replaceAll("[Zz]$", "").replaceAll("\\.\\d+$", "").trim();
+ for (DateTimeFormatter formatter : List.of(
+ DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"),
+ DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm"),
+ DateTimeFormatter.ofPattern("yyyy-MM-dd HH"),
+ DateTimeFormatter.ofPattern("yyyy-MM-dd"))) {
+ try {
+ return LocalDateTime.parse(normalized, formatter);
+ } catch (DateTimeParseException ignored) {
+ // 尝试下一种格式
+ }
+ }
+ throw new BusinessException(400, name + " 时间格式无效");
+ }
+
+ private static String formatAdminTime(LocalDateTime value) {
+ return value == null ? "" : value.format(ADMIN_TIME);
+ }
+
+ private static String firstNonBlank(String first, String... others) {
+ String cursor = first;
+ for (String other : others) {
+ if (cursor == null || cursor.isBlank()) {
+ cursor = other;
+ }
+ }
+ return cursor == null ? "" : cursor;
+ }
+
+ private static String defaultText(String value) {
+ return value == null ? "" : value;
+ }
+
+ private static String blankToNull(String value) {
+ return (value == null || value.isBlank()) ? null : value.trim();
+ }
+
+ private static boolean isBlank(String value) {
+ return value == null || value.isBlank();
+ }
+
+ /** 将列表铺平为 "#{prefix0}..#{prefixN}" 可用的占位键，避免动态列表绑定歧义。 */
+ private static void flattenList(Map p, List values, String listKey, String prefix) {
+ p.put(listKey, values);
+ for (int i = 0; i < values.size(); i++) {
+ p.put(prefix + i, values.get(i));
+ }
+ }
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/controller/SoftwareVersionAdminController.java b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/controller/SoftwareVersionAdminController.java
new file mode 100644
index 00000000..293a3347
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/controller/SoftwareVersionAdminController.java
@@ -0,0 +1,56 @@
+package com.nanri.aiimage.modules.softwareversion.controller;
+
+import com.nanri.aiimage.common.api.ApiResponse;
+import com.nanri.aiimage.modules.admin.support.AdminAuthSupport;
+import com.nanri.aiimage.modules.permission.model.entity.AdminUserEntity;
+import com.nanri.aiimage.modules.softwareversion.service.SoftwareVersionService;
+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 lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.MediaType;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+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.multipart.MultipartFile;
+
+import java.util.Map;
+
+/**
+ * 客户端软件版本管理（替代 Flask /api/admin/versions、/api/admin/version 本地实现）。
+ * 读写旧表 web_config；"数字人版本"走 digitalhuman 模块（/api/digital-human/versions），与本接口无关。
+ */
+@Slf4j
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/api/admin")
+@Tag(name = "客户端软件版本管理", description = "桌面客户端软件安装包版本管理：列表与上传，数据落 web_config 表")
+public class SoftwareVersionAdminController {
+
+ private final SoftwareVersionService softwareVersionService;
+ private final AdminAuthSupport adminAuthSupport;
+
+ @GetMapping("/versions")
+ @Operation(summary = "客户端软件版本列表", description = "按创建时间倒序返回全部版本（旧 web_config 表）")
+ public ApiResponse> listVersions(HttpServletRequest request) {
+ AdminUserEntity operator = adminAuthSupport.requireAdminOrInternal(request);
+ log.info("[software-version] 管理端查询客户端软件版本列表 operator={}", operator.getUsername());
+ return ApiResponse.success(Map.of("items", softwareVersionService.listSoftwareVersions()));
+ }
+
+ @PostMapping(value = "/version", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+ @Operation(summary = "上传客户端软件版本", description = "multipart 表单：version 版本号 + file zip 安装包，上传 MinIO 并写入 web_config")
+ public ApiResponse> uploadVersion(
+ HttpServletRequest request,
+ @Parameter(description = "版本号，如 1.0.46") @RequestParam(value = "version", required = false) String version,
+ @Parameter(description = "zip 安装包文件") @RequestParam(value = "file", required = false) MultipartFile file) {
+ AdminUserEntity operator = adminAuthSupport.requireAdminOrInternal(request);
+ log.info("[software-version] 管理端上传客户端软件版本开始 operator={} version={}", operator.getUsername(), version);
+ Map result = softwareVersionService.uploadSoftwareVersion(version, file);
+ return ApiResponse.success("上传成功", result);
+ }
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/mapper/SoftwareVersionMapper.java b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/mapper/SoftwareVersionMapper.java
new file mode 100644
index 00000000..bc0cd248
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/mapper/SoftwareVersionMapper.java
@@ -0,0 +1,9 @@
+package com.nanri.aiimage.modules.softwareversion.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.nanri.aiimage.modules.softwareversion.model.entity.SoftwareVersionEntity;
+import org.apache.ibatis.annotations.Mapper;
+
+@Mapper
+public interface SoftwareVersionMapper extends BaseMapper {
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/model/entity/SoftwareVersionEntity.java b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/model/entity/SoftwareVersionEntity.java
new file mode 100644
index 00000000..36943f04
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/model/entity/SoftwareVersionEntity.java
@@ -0,0 +1,29 @@
+package com.nanri.aiimage.modules.softwareversion.model.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/**
+ * 客户端软件版本记录（对应旧表 web_config，桌面客户端"检测更新"与 Flask 时代共用同一张表）。
+ * 注意：本表不是"数字人版本"（数字人走 biz_digital_human_version，勿混淆）。
+ */
+@Data
+@TableName("web_config")
+public class SoftwareVersionEntity {
+
+ @TableId(type = IdType.AUTO)
+ private Long id;
+
+ /** 版本号，如 1.0.46 */
+ private String version;
+
+ /** 安装包可公开访问的下载链接（MinIO path-style 直链） */
+ private String fileUrl;
+
+ /** 创建时间，由数据库 CURRENT_TIMESTAMP 兜底 */
+ private LocalDateTime createdAt;
+}
diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/service/SoftwareVersionService.java b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/service/SoftwareVersionService.java
new file mode 100644
index 00000000..53e3c62d
--- /dev/null
+++ b/backend-java/src/main/java/com/nanri/aiimage/modules/softwareversion/service/SoftwareVersionService.java
@@ -0,0 +1,149 @@
+package com.nanri.aiimage.modules.softwareversion.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.nanri.aiimage.common.exception.BusinessException;
+import com.nanri.aiimage.modules.file.service.oss.OssStorageService;
+import com.nanri.aiimage.modules.softwareversion.mapper.SoftwareVersionMapper;
+import com.nanri.aiimage.modules.softwareversion.model.entity.SoftwareVersionEntity;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.web.multipart.MultipartFile;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.regex.Pattern;
+
+/**
+ * 客户端软件（桌面 ShuFuAI.exe）版本管理服务：读写 web_config 表，
+ * 与 Flask 时代 /api/admin/versions、/api/admin/version 行为对齐（读取/追加写，无覆盖、无删除）。
+ */
+@Service
+@RequiredArgsConstructor
+@Slf4j
+public class SoftwareVersionService {
+
+ /** MinIO 对象 key 前缀，对齐 Flask bucket_path(oss_bucket_path 默认 nanri-image/) 的历史约定 */
+ public static final String STORAGE_PATH_PREFIX = "nanri-image/versions/";
+
+ /** 与 Flask VERSION_UPLOAD_MAX_BYTES（默认 512MB）保持一致 */
+ private static final long MAX_UPLOAD_BYTES = 512L * 1024 * 1024;
+
+ private static final DateTimeFormatter CREATED_AT_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm");
+
+ /** 对齐 Python re.sub(r'[^\w.\-]', '_')（\w 含中文等 Unicode 字符），仅版本号片段防注入 */
+ private static final Pattern UNSAFE_KEY_CHARS =
+ Pattern.compile("[^\\w.\\-]", Pattern.UNICODE_CHARACTER_CLASS);
+
+ private final SoftwareVersionMapper softwareVersionMapper;
+ private final OssStorageService ossStorageService;
+
+ /**
+ * 版本列表：web_config 全量按创建时间倒序，与 Flask 返回结构一致
+ * （items 内为 id / version / file_url / created_at）。
+ */
+ public List> listSoftwareVersions() {
+ List entities = softwareVersionMapper.selectList(
+ new LambdaQueryWrapper()
+ .orderByDesc(SoftwareVersionEntity::getCreatedAt)
+ .orderByDesc(SoftwareVersionEntity::getId));
+ log.info("[software-version] 查询客户端软件版本列表 count={}", entities.size());
+ List> items = new ArrayList<>(entities.size());
+ for (SoftwareVersionEntity entity : entities) {
+ Map item = new LinkedHashMap<>();
+ item.put("id", entity.getId());
+ item.put("version", entity.getVersion() == null ? "" : entity.getVersion());
+ item.put("file_url", entity.getFileUrl() == null ? "" : entity.getFileUrl());
+ item.put("created_at", entity.getCreatedAt() == null
+ ? "" : entity.getCreatedAt().format(CREATED_AT_FORMATTER));
+ items.add(item);
+ }
+ return items;
+ }
+
+ /**
+ * 上传客户端软件安装包：zip 上传 MinIO（key：nanri-image/versions/{安全版本号}.zip），
+ * 并向 web_config 追加一条记录（不做"设为最新"，桌面端按 created_at 倒序取第一条）。
+ */
+ public Map uploadSoftwareVersion(String version, MultipartFile file) {
+ String normalizedVersion = version == null ? "" : version.trim();
+ if (normalizedVersion.isEmpty()) {
+ throw new BusinessException("请填写版本号");
+ }
+ if (file == null || file.getOriginalFilename() == null || file.getOriginalFilename().trim().isEmpty()) {
+ throw new BusinessException("请选择要上传的 zip 压缩包");
+ }
+ String originalFilename = file.getOriginalFilename().trim();
+ if (!originalFilename.toLowerCase(Locale.ROOT).endsWith(".zip")) {
+ throw new BusinessException("仅支持 .zip 格式");
+ }
+ long fileSize = file.getSize();
+ if (fileSize <= 0) {
+ throw new BusinessException("文件为空");
+ }
+ if (fileSize > MAX_UPLOAD_BYTES) {
+ throw new BusinessException("文件超过允许的大小限制");
+ }
+
+ long startedAt = System.nanoTime();
+ log.info("[software-version] 上传客户端软件版本开始 version={} filename={} requestFileSize={}",
+ normalizedVersion, originalFilename, fileSize);
+
+ File tempFile = null;
+ try {
+ tempFile = Files.createTempFile("software-version-", ".zip").toFile();
+ file.transferTo(tempFile);
+ log.info("[software-version] 临时文件已保存 version={} bytes={} elapsedMs={}",
+ normalizedVersion, tempFile.length(), elapsedMs(startedAt));
+
+ String safeKey = safeVersionKey(normalizedVersion);
+ String objectKey = STORAGE_PATH_PREFIX + safeKey + ".zip";
+ // 上传后返回可直接公开下载的 URL，与桌面端"检测更新"返回的 file_url 格式一致
+ String fileUrl = ossStorageService.uploadSoftwareVersionPackage(tempFile, objectKey);
+ log.info("[software-version] MinIO 上传成功 version={} objectKey={} bytes={} url={} elapsedMs={}",
+ normalizedVersion, objectKey, tempFile.length(), fileUrl, elapsedMs(startedAt));
+
+ SoftwareVersionEntity entity = new SoftwareVersionEntity();
+ entity.setVersion(normalizedVersion);
+ entity.setFileUrl(fileUrl);
+ // 不显式写 created_at，走数据库 CURRENT_TIMESTAMP 默认值（与 Flask 行为一致）
+ softwareVersionMapper.insert(entity);
+ log.info("[software-version] 版本记录已写入 web_config id={} version={} elapsedMs={}",
+ entity.getId(), normalizedVersion, elapsedMs(startedAt));
+
+ Map result = new LinkedHashMap<>();
+ result.put("version", normalizedVersion);
+ result.put("file_url", fileUrl);
+ return result;
+ } catch (IOException e) {
+ log.error("[software-version] 上传客户端软件版本文件处理失败 version={} filename={} err={}",
+ normalizedVersion, originalFilename, e.getMessage(), e);
+ throw new BusinessException("文件处理失败：" + e.getMessage());
+ } catch (RuntimeException e) {
+ log.error("[software-version] 上传客户端软件版本失败 version={} filename={} elapsedMs={} err={}",
+ normalizedVersion, originalFilename, elapsedMs(startedAt), e.getMessage(), e);
+ throw e;
+ } finally {
+ if (tempFile != null && tempFile.exists() && !tempFile.delete()) {
+ log.warn("[software-version] 清理临时文件失败 path={}", tempFile.getAbsolutePath());
+ }
+ }
+ }
+
+ private long elapsedMs(long startedAt) {
+ return (System.nanoTime() - startedAt) / 1_000_000L;
+ }
+
+ /** 将版本号转换为安全的 OSS 对象名片段：保留中文/字母/数字/._-，其余替换为 _，空则 unknown（对齐 Flask _safe_version_key）。 */
+ private String safeVersionKey(String version) {
+ String replaced = UNSAFE_KEY_CHARS.matcher(version).replaceAll("_");
+ return replaced.isEmpty() ? "unknown" : replaced;
+ }
+}