refactor(phase-4): 解散万能 util——similarasin/util 与 common/util 按域归位

similarasin/util 7 支:
- 域内件(SimilarAsinImageEmbedder/PuzzleImageMerger/SimilarAsinLogSupport/
  BoundedImageCache)并入既有 service/support 先例;
- 通用 Excel 件(ExcelCellImageWriter/WpsCellImageWriter)归 common/excel;
- 仅测试用的 SimilarAsinPerfFixture 移出生产源到 src/test。

common/util 13 支解散为四个关注点包:excel(读/写/单元格图片)、
text(BrandLabel/SecretMasking/UserMessages)、task(行过滤/分组传播/判死文案/
删除台账/锁跳过留痕)、support(LRU/下载头/线程池)。老 util 目录不再存在。

纯粹的包搬迁与 import 重写(diff 219 增 / 217 删),零行为改动:
搬迁前后由 SimilarAsinCreateTaskSnapshotTest 的建单入口 golden 对撞相等;
新增 MovedComponentScanTest 钉住三枚 @Component 仍被根包扫描发现、老包零残留。
This commit is contained in:
2026-10-23 00:59:53 +08:00
parent 8f6913fb4a
commit dbe35dfcb5
162 changed files with 282 additions and 217 deletions
@@ -0,0 +1,114 @@
package com.nanri.aiimage.common.task;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.Set;
import java.util.function.Function;
import java.util.function.Predicate;
public final class FailedStatusRowFilter {
private static final String STATUS_HEADER_CN = "状态";
private static final String FAILED_STATUS_ERROR = "错误";
private static final String FAILED_STATUS_FAILED_CN = "失败";
private static final String FAILED_STATUS_FAILED_EN = "failed";
private static final String NO_MATCHED_ROWS_MESSAGE =
"状态列过滤后未找到 错误/失败/FAILED 数据";
private static final Set<String> STATUS_HEADER_ALIASES = Set.of(
normalizeHeader(STATUS_HEADER_CN),
normalizeHeader("status")
);
private static final Set<String> FAILED_STATUS_VALUES = Set.of(
normalizeValue(FAILED_STATUS_ERROR),
normalizeValue(FAILED_STATUS_FAILED_CN),
normalizeValue(FAILED_STATUS_FAILED_EN)
);
private FailedStatusRowFilter() {
}
public static int findStatusColumnIndex(List<String> headers) {
if (headers == null || headers.isEmpty()) {
return -1;
}
for (int i = 0; i < headers.size(); i++) {
if (STATUS_HEADER_ALIASES.contains(normalizeHeader(headers.get(i)))) {
return i;
}
}
return -1;
}
public static boolean matchesFailedStatus(String value) {
return FAILED_STATUS_VALUES.contains(normalizeValue(value));
}
public static boolean isBlankStatus(String value) {
return normalizeValue(value).isBlank();
}
public static String noMatchedRowsMessage() {
return NO_MATCHED_ROWS_MESSAGE;
}
/**
* 暴露表头归一化逻辑给其它模块复用,避免每个模块各自维护一份规则。
* 处理:去 BOM、全角空格转半角、首尾 trim、连续空白合并、转小写,
* 并剔除常见分隔符(含中文全角括号、方括号、冒号)。
*/
public static String canonicalizeHeader(String value) {
return normalizeHeader(value);
}
public static <T> FilterResult<T> retainFailedRows(List<T> rows,
boolean statusFilteringEnabled,
Function<T, String> statusReader) {
return retainRows(rows, statusFilteringEnabled, statusReader, FailedStatusRowFilter::matchesFailedStatus);
}
public static <T> FilterResult<T> retainRows(List<T> rows,
boolean statusFilteringEnabled,
Function<T, String> statusReader,
Predicate<String> statusMatcher) {
List<T> safeRows = rows == null ? List.of() : rows;
if (!statusFilteringEnabled) {
return new FilterResult<>(false, safeRows, 0);
}
List<T> filteredRows = new ArrayList<>();
int filteredCount = 0;
for (T row : safeRows) {
String status = statusReader == null ? "" : statusReader.apply(row);
boolean matched = statusMatcher != null && statusMatcher.test(status);
if (matched) {
filteredRows.add(row);
} else {
filteredCount++;
}
}
return new FilterResult<>(true, filteredRows, filteredCount);
}
private static String normalizeHeader(String value) {
// 兼容中文全角括号()、中文方括号【】、中文冒号:,
// 避免“状态(结果)”“标题维度(商标)”等表头识别失败。
return normalizeValue(value).replaceAll("[\\s_\\-()\\[\\]{}::()【】]+", "");
}
private static String normalizeValue(String value) {
if (value == null) {
return "";
}
return value
.replace(String.valueOf((char) 0xFEFF), "")
.replace((char) 0x3000, ' ')
.trim()
.replaceAll("\\s+", " ")
.toLowerCase(Locale.ROOT);
}
public record FilterResult<T>(boolean filterApplied, List<T> rows, int filteredCount) {
}
}
@@ -0,0 +1,216 @@
package com.nanri.aiimage.common.task;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.function.BiConsumer;
import java.util.function.Function;
/**
* LLM 回流数据按 ID 分组传播工具。
*
* <p>业务背景:
* 解析行按 Excel 行顺序排列,ID 形如 "1"、"1_1"、"1_2"、"2"、"2_1"。
* 同一 baseId(第一个下划线 '_' 之前的部分)的连续行视为同一组——即所谓
* "分组只看下一行数据":按行顺序、相邻同 baseId 行才是同组,遇到不同 baseId 立即开新组。
*
* <p>传播规则:
* <ol>
* <li>单行组(孤立 baseId)跳过,不做任何处理。</li>
* <li>组内任一行的目标字段值"包含" {@code hitValues} 中某个候选值,
* 则把该组所有行的目标字段统一覆盖为该候选值(标准值)。</li>
* <li>多个候选值同时命中时,按 {@code hitValues} 列表顺序优先匹配
* (列表越靠前优先级越高,比如专利场景把"已侵权"放在"侵权"前面,
* 避免短串先命中导致丢失"已"字)。</li>
* <li>无法解析到对应 result 行(resolver 返回 null)的 parsed 行不参与
* 组内匹配,但仍占据分组位置——不会打断同 baseId 的连续性,
* 也不会被强行写入。</li>
* </ol>
*
* <p>使用方式:
* <pre>
* // 专利结论列:组内任一行结论命中 "已侵权" 或 "侵权",组内都改为该标准值
* GroupResultPropagator.propagateByGroup(
* receivedRows,
* AppearancePatentParsedRowVo::getDisplayId,
* row -&gt; findResultRow(row, resultMap),
* AppearancePatentResultRowDto::getConclusion,
* AppearancePatentResultRowDto::setConclusion,
* List.of("已侵权", "侵权"),
* "[appearance-patent] taskId=" + task.getId()
* );
* </pre>
*/
public final class GroupResultPropagator {
private static final Logger log = LoggerFactory.getLogger(GroupResultPropagator.class);
/**
* 否定前缀关键字。若当前值同时包含 standard 和这些关键字之一,则不视为命中。
* 用于规避"没有侵权""无侵权""不侵权""未发现明显侵权风险"等被 contains 误判为命中"侵权"的情况。
*/
private static final List<String> NEGATIVE_KEYWORDS = Arrays.asList("没有", "无", "不", "未");
private GroupResultPropagator() {
}
/**
* 按 baseId 连续分组、命中即组内传播。无日志上下文标签的便捷重载。
*/
public static <P, R> int propagateByGroup(List<P> parsedRows,
Function<P, String> displayIdGetter,
Function<P, R> resultRowResolver,
Function<R, String> fieldGetter,
BiConsumer<R, String> fieldSetter,
List<String> hitValues) {
return propagateByGroup(parsedRows, displayIdGetter, resultRowResolver,
fieldGetter, fieldSetter, hitValues, null);
}
/**
* 按 baseId 连续分组、命中即组内传播。
*
* @param parsedRows 解析行(按 Excel 行顺序)
* @param displayIdGetter parsed 行 → ID 字符串(用于计算 baseId)
* @param resultRowResolver parsed 行 → 对应的 result DTO(找不到返回 null)
* @param fieldGetter result DTO → 当前目标字段值
* @param fieldSetter result DTO ← 新目标字段值
* @param hitValues 需要传播的标准值列表,靠前优先匹配(包含语义)
* @param logTag 日志前缀(如 "[appearance-patent] taskId=9975"),null 则只在汇总层打日志
* @param <P> parsed 行类型
* @param <R> result DTO 类型
* @return 实际被改写的 result 行数(用于上层日志埋点)
*/
public static <P, R> int propagateByGroup(List<P> parsedRows,
Function<P, String> displayIdGetter,
Function<P, R> resultRowResolver,
Function<R, String> fieldGetter,
BiConsumer<R, String> fieldSetter,
List<String> hitValues,
String logTag) {
if (parsedRows == null || parsedRows.isEmpty()
|| displayIdGetter == null || resultRowResolver == null
|| fieldGetter == null || fieldSetter == null
|| hitValues == null || hitValues.isEmpty()) {
return 0;
}
String tagPrefix = (logTag == null || logTag.isEmpty()) ? "" : logTag + " ";
int totalUpdated = 0;
int n = parsedRows.size();
int i = 0;
while (i < n) {
String currentBaseId = baseId(displayIdGetter.apply(parsedRows.get(i)));
int groupStart = i;
int j = i + 1;
// 连续同 baseId 视为一组
while (j < n && currentBaseId.equals(baseId(displayIdGetter.apply(parsedRows.get(j))))) {
j++;
}
int groupEnd = j; // 半开区间 [groupStart, groupEnd)
i = j;
// 单行组跳过
if (groupEnd - groupStart < 2) {
continue;
}
// 收集组内所有能解析到 result DTO 的行,同时记录显示 ID 方便日志
List<R> groupResults = new ArrayList<>(groupEnd - groupStart);
List<String> groupDisplayIds = new ArrayList<>(groupEnd - groupStart);
for (int k = groupStart; k < groupEnd; k++) {
P parsedRow = parsedRows.get(k);
R resultRow = resultRowResolver.apply(parsedRow);
if (resultRow != null) {
groupResults.add(resultRow);
groupDisplayIds.add(displayIdGetter.apply(parsedRow));
}
}
if (groupResults.isEmpty()) {
continue;
}
// 按 hitValues 顺序检测组内是否有命中(包含语义),命中即定下"标准值"。
// 命中需同时满足:当前值包含 standard 且不含任何否定关键字("没有"/"无"/"不"/"未"),
// 避免"没有侵权""无侵权""不侵权""未发现明显侵权风险"这类被 contains 误判为命中。
String matchedStandardValue = null;
outer:
for (String standard : hitValues) {
if (standard == null || standard.isEmpty()) {
continue;
}
for (int k = 0; k < groupResults.size(); k++) {
R row = groupResults.get(k);
String currentValue = fieldGetter.apply(row);
if (currentValue == null || !currentValue.contains(standard)) {
continue;
}
if (containsNegative(currentValue)) {
log.debug("{}group-propagate skip negative baseId={} displayId={} currentValue={} candidate={}",
tagPrefix, currentBaseId, groupDisplayIds.get(k), currentValue, standard);
continue;
}
matchedStandardValue = standard;
break outer;
}
}
if (matchedStandardValue == null) {
continue;
}
// 把组内所有 result DTO 的目标字段统一覆盖为标准值,并逐行打日志
int groupUpdated = 0;
for (int idx = 0; idx < groupResults.size(); idx++) {
R row = groupResults.get(idx);
String currentValue = fieldGetter.apply(row);
if (matchedStandardValue.equals(currentValue)) {
continue;
}
fieldSetter.accept(row, matchedStandardValue);
groupUpdated++;
totalUpdated++;
log.info("{}group-propagate row baseId={} displayId={} oldValue={} newValue={}",
tagPrefix, currentBaseId, groupDisplayIds.get(idx),
currentValue, matchedStandardValue);
}
if (groupUpdated > 0) {
log.info("{}group-propagate group hit baseId={} groupSize={} standardValue={} updatedRows={}",
tagPrefix, currentBaseId, groupResults.size(),
matchedStandardValue, groupUpdated);
}
}
return totalUpdated;
}
/**
* 判断当前值是否含任意否定关键字。命中关键字即视为"未发生"语义,
* 上层应跳过该值,避免被 {@link String#contains(CharSequence)} 误判命中标准值。
*/
private static boolean containsNegative(String value) {
if (value == null || value.isEmpty()) {
return false;
}
for (String neg : NEGATIVE_KEYWORDS) {
if (value.contains(neg)) {
return true;
}
}
return false;
}
/**
* 取 ID 中第一个 '_' 之前的部分。例如 "1" → "1","1_2" → "1",null → ""。
* 与两个 TaskService 内的 {@code baseId} 实现保持一致。
*/
private static String baseId(String id) {
if (id == null) {
return "";
}
String s = id.trim();
int idx = s.indexOf('_');
return idx > 0 ? s.substring(0, idx) : s;
}
}
@@ -0,0 +1,182 @@
package com.nanri.aiimage.common.task;
import io.micrometer.core.instrument.Gauge;
import io.micrometer.core.instrument.MeterRegistry;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
import java.util.concurrent.atomic.AtomicLong;
/**
* 分布式锁「没拿到就跳过」的可聚合出口(2026-10-09 评审「稳定 5.5」项)。
*
* <p>此前 {@code if (lockHandle == null) { continue; }} 在全树有 <b>28</b> 处(11 个文件),
* 一处日志都不留。表现是:巡检任务每轮都跑、锁竞争越激烈被跳过的任务越多,而现网看不出任何痕迹
* ——卡死任务没被收尾、结果作业没被续跑,日志里连一行都没有,只能靠人肉反推。跟
* {@code TaskFileJobPublisher} 的 MQ 降级是同一个病:那条已经补了 {@code task.file.job.mq.degraded}
* 计数出口,这批锁跳过出口是它的同类。
*
* <p>所以这里定的不是"把级别调大",而是<b>可聚合</b>:
* <ul>
* <li>锚点 {@value #ANCHOR}:一条 grep 得动的字面量,{@code point=}/{@code outcome=} 给聚合维度;</li>
* <li>进程内台账 {@link #countOf}:按 point 累计,供判据与巡检直接读;</li>
* <li>Micrometer 指标 {@value #METRIC}(可选,注册表缺席时只留日志与本地台账,判定一字不动,
* 与 {@code TaskFileJobPublisher} 同一口径)。</li>
* </ul>
*
* <p>{@code point} 是<b>稳定字面量</b>(形如 {@code brand:stale-running-scan}),不锚行号:
* 方法搬家、加几行注释都不该让一条已经在响的告警变成孤儿。新增调用点请同步
* {@code LockSkipWitnessTest} 里的点位台账。
*
* <p>静态 API 是有意的:这 12 个 Service 清一色 {@code @RequiredArgsConstructor},
* 塞一个实例字段等于改 12 个构造器签名、打断几十支 {@code new XxxService(...)} 的既有判据。
* 注册表由 Spring 在启动时绑一次({@link #LockSkipWitness});没起 Spring 的单测照样能调
* {@link #record},台账与日志都不依赖容器。
*/
@Slf4j
@Component
public class LockSkipWitness {
/** 巡检/判据用的日志锚点。改这条字面量等于把现网告警规则删掉,动之前先对巡检。 */
public static final String ANCHOR = "[lock-skip]";
/** 指标名:tag {@code point}/{@code outcome}/{@code moduleType}。 */
public static final String METRIC = "aiimage.distributed.lock.skip";
/** outcome:循环里跳过这一项,后面还有别的(巡检批量扫描)。 */
public static final String OUTCOME_SKIPPED = "skipped";
/** outcome:整次调用直接返回,本轮什么都没用做(含 try-with-resources 里锁没拿到)。 */
public static final String OUTCOME_ABANDONED = "abandoned";
/** outcome:调用方没给结果类型——单独成桶,不折叠进上面两个真桶。 */
public static final String OUTCOME_UNKNOWN = "unknown";
/** 台账键上限:point 是有限集合(调用点数),超上限后不再新增键,防无界增长。 */
static final int LEDGER_KEYS_MAX = 256;
private static final ConcurrentMap<String, AtomicLong> LEDGER = new ConcurrentHashMap<>();
private static final AtomicLong TOTAL = new AtomicLong();
/** 可为 null:没配 Micrometer 注册表时只留日志 + 本地台账。 */
private static volatile MeterRegistry registry;
public LockSkipWitness() {
}
/** 生产接线:注册表可选,缺席时不影响跳过语义与日志。 */
@Autowired
public LockSkipWitness(ObjectProvider<MeterRegistry> meterRegistryProvider) {
bind(meterRegistryProvider == null ? null : meterRegistryProvider.getIfAvailable());
}
/** 供 Spring 构造与单测显式接线;null 表示只用日志与本地台账。 */
public static void bind(MeterRegistry meterRegistry) {
registry = meterRegistry;
if (meterRegistry != null) {
// 计数器按 point 现建现取,注册一次总览 gauge,便于「一个 point 都没命中」也能看到 0。
Gauge.builder(METRIC + ".total", TOTAL, AtomicLong::get).register(meterRegistry);
}
}
/**
* 记一次「没拿到锁所以跳过/放弃」。
*
* @param point 稳定点位字面量(不要用行号/方法名+行号拼)
* @param outcome {@link #OUTCOME_SKIPPED} 或 {@link #OUTCOME_ABANDONED}
* @param moduleType 业务模块类型,可为 null(归一为 unknown)
* @param taskId 任务 id,可为 null
*/
public static void record(String point, String outcome, String moduleType, Long taskId) {
String key = point == null || point.isBlank() ? "unpointed" : point.trim();
// outcome 缺失归一到 unknown 而不是猜一个真桶:折叠进 skipped/abandoned 会让聚合面说谎。
String normalizedOutcome = outcome == null || outcome.isBlank() ? OUTCOME_UNKNOWN : outcome.trim();
String normalizedModule = moduleType == null || moduleType.isBlank() ? "unknown" : moduleType.trim();
long count = ledgerOf(key).incrementAndGet();
long total = TOTAL.incrementAndGet();
MeterRegistry current = registry;
if (current != null) {
current.counter(METRIC,
"point", key,
"outcome", normalizedOutcome,
"moduleType", normalizedModule)
.increment();
}
log.warn("{} point={} outcome={} moduleType={} taskId={} skippedSoFar={} total={} —— "
+ "未拿到分布式锁,本轮跳过(锁被其它实例持有或锁名不可用)",
ANCHOR, key, normalizedOutcome, normalizedModule, taskId, count, total);
}
/** 最省事的写法:跳过(skipped)结果 + 不带模块上下文。 */
public static void recordSkip(String point, String moduleType, Long taskId) {
record(point, OUTCOME_SKIPPED, moduleType, taskId);
}
/** 最省事的写法:整次放弃(abandoned)结果 + 不带模块上下文。 */
public static void recordAbandoned(String point, String moduleType, Long taskId) {
record(point, OUTCOME_ABANDONED, moduleType, taskId);
}
/** 定时任务级作业锁没抢到:整轮直接返回,没有模块/任务上下文。 */
public static void skipped(String point) {
record(point, OUTCOME_SKIPPED, null, null);
}
/** 定时任务级作业锁没抢到且方法直接返回:本轮什么都没做。 */
public static void abandoned(String point) {
record(point, OUTCOME_ABANDONED, null, null);
}
private static AtomicLong ledgerOf(String key) {
AtomicLong existing = LEDGER.get(key);
if (existing != null) {
return existing;
}
if (LEDGER.size() >= LEDGER_KEYS_MAX) {
// 超出上限:仍计入总量与日志,只是不再为未知点位开新键。
return LEDGER.computeIfAbsent("overflow", k -> new AtomicLong());
}
return LEDGER.computeIfAbsent(key, k -> new AtomicLong());
}
/** 某个点位累计跳过次数;没记过就是 0。 */
public static long countOf(String point) {
AtomicLong value = LEDGER.get(point);
return value == null ? 0L : value.get();
}
/** 全部点位的累计台账快照(不可变副本,按点位名排序)。 */
public static Map<String, Long> snapshot() {
Map<String, Long> out = new LinkedHashMap<>();
LEDGER.entrySet().stream()
.sorted(Map.Entry.comparingByKey())
.forEach(e -> out.put(e.getKey(), e.getValue().get()));
return Collections.unmodifiableMap(out);
}
/** 全部点位合计。 */
public static long total() {
return TOTAL.get();
}
/**
* 测试专用:清空台账,返回清理前的快照。
*
* <p>生产代码不要调——它会把巡检窗口里的计数抹平,看起来像"这段时间没人被锁挡"。
* 之所以留着:判据要能钉住"走到这个分支留下了可查记录",而点位是全局静态计数,
* 不清就测不出单次增量(用 delta 也能测,但 27 个点位共用一张表,清一次比 27 处读基线更好读)。
*/
public static Map<String, Long> resetLedgerForTests() {
Map<String, Long> before = snapshot();
LEDGER.clear();
TOTAL.set(0L);
return before;
}
}
@@ -0,0 +1,138 @@
package com.nanri.aiimage.common.task;
import lombok.extern.slf4j.Slf4j;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.nio.file.StandardOpenOption;
import java.util.ArrayList;
import java.util.Collection;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Set;
/**
* 待删对象队列的本地落盘日志:进程重启后仍能恢复「待删除对象」清单。
*
* <p>使用场景:对象存储删除失败后的补偿队列原本只在节点内存里,重启即丢,
* 对应对象会一直残留在桶里直到生命周期规则过期。这里用一行一个 objectKey 的
* 追加日志做最小持久化——入队追加、队列收敛后整体重写、启动时回放。
*
* <p>并发:所有方法内部同步,调用方无需额外加锁;文件损坏/读写异常只记日志不抛出,
* 保证补偿链路本身不会因为落盘失败而中断业务。
*
* <p>上限:{@code maxEntries} 用于防止日志在异常堆积时无界增长(超出后丢弃最早的记录,
* 与内存队列的容量准入语义一致——丢的是「待删对象」,最坏结果是对象残留)。
*/
@Slf4j
public final class PendingDeleteJournal {
private final Path path;
private final int maxEntries;
private final Object lock = new Object();
public PendingDeleteJournal(Path path, int maxEntries) {
this.path = path;
this.maxEntries = Math.max(1, maxEntries);
}
public Path getPath() {
return path;
}
/** 追加一条待删对象(重复追加由回放时的 Set 语义去重)。 */
public void record(String objectKey) {
if (objectKey == null || objectKey.isBlank()) {
return;
}
synchronized (lock) {
try {
Path parent = path.getParent();
if (parent != null) {
Files.createDirectories(parent);
}
Files.writeString(path, sanitize(objectKey) + System.lineSeparator(),
StandardCharsets.UTF_8, StandardOpenOption.CREATE, StandardOpenOption.APPEND);
} catch (Exception ex) {
log.warn("[delete-journal] 追加待删对象失败 path={} msg={}", path, ex.getMessage());
}
}
}
/** 启动回放:返回日志中的待删对象(按首次出现顺序去重)。 */
public List<String> readAll() {
synchronized (lock) {
if (!Files.isRegularFile(path)) {
return List.of();
}
List<String> lines;
try {
lines = Files.readAllLines(path, StandardCharsets.UTF_8);
} catch (Exception ex) {
log.warn("[delete-journal] 读取待删对象日志失败 path={} msg={}", path, ex.getMessage());
return List.of();
}
Set<String> unique = new LinkedHashSet<>();
for (String line : lines) {
if (line == null) {
continue;
}
String key = line.trim();
if (!key.isEmpty()) {
unique.add(key);
}
}
return new ArrayList<>(unique);
}
}
/** 队列收敛(成功删除/引用仍在)后整体重写为剩余的待删对象;剩余为空则删除日志。 */
public void rewrite(Collection<String> remaining) {
synchronized (lock) {
Set<String> keep = new LinkedHashSet<>();
if (remaining != null) {
for (String key : remaining) {
if (key != null && !key.isBlank()) {
keep.add(sanitize(key));
if (keep.size() >= maxEntries) {
break;
}
}
}
}
try {
if (keep.isEmpty()) {
Files.deleteIfExists(path);
return;
}
Path parent = path.getParent();
if (parent != null) {
Files.createDirectories(parent);
}
Path tmp = path.resolveSibling(path.getFileName() + ".tmp");
StringBuilder content = new StringBuilder();
for (String key : keep) {
content.append(key).append(System.lineSeparator());
}
Files.writeString(tmp, content.toString(), StandardCharsets.UTF_8,
StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING);
try {
Files.move(tmp, path, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE);
} catch (IOException atomicUnsupported) {
// 少数文件系统不支持 ATOMIC_MOVE,退化为普通替换
Files.move(tmp, path, StandardCopyOption.REPLACE_EXISTING);
}
} catch (Exception ex) {
log.warn("[delete-journal] 重写待删对象日志失败 path={} msg={}", path, ex.getMessage());
}
}
}
/** 单行一条记录:去掉换行避免破坏行结构。 */
private static String sanitize(String objectKey) {
return objectKey.replace('\n', ' ').replace('\r', ' ').trim();
}
}
@@ -0,0 +1,54 @@
package com.nanri.aiimage.common.task;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.List;
/**
* 客户端型任务(外观专利 / 货源)心跳判死文案:只写证据支持的话。
*
* <p>历史上这里固定写 "Python interrupted before uploading final result",而 2026-10-01 线上三条
* 外观任务其实一行业务结果都没回传过——Linux worker 一次领 5 条却只有 2 个采集槽,多出来的任务
* 状态是 RUNNING、零心跳零分片,两小时后被写成「Python 中断」。「没开工」被说成「跑挂了」,
* 排查方向被带偏过一次,故文案按证据分述,并把客户端最后一次上报的位置一起带出来
* (排队中的任务会上报「排队等待空闲槽位」,与真在采集是两种成因)。
*
* @param chunkCount 已落库的结果分片数(biz_task_chunk)
* @param lastChunkAt 最后一次结果分片回传时间,从未回传时为 null
* @param lastHeartbeatAt 最后一次客户端心跳时间,Redis 无记录时为 null
* @param lastProgress 客户端最后一次上报的位置/阶段文本,老客户端或无位置信息时为 null
* @param fileJobExhausted 结果文件作业是否已重试耗尽(true 时责任不在客户端回传)
* @param timeoutMinutes 判死阈值(分钟)
*/
public record StaleTaskDeathReason(long chunkCount,
LocalDateTime lastChunkAt,
LocalDateTime lastHeartbeatAt,
String lastProgress,
boolean fileJobExhausted,
int timeoutMinutes) {
private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("MM-dd HH:mm");
public String describe() {
if (chunkCount > 0 && fileJobExhausted) {
return "已收到 " + chunkCount + " 个结果分片,但结果文件生成多次失败,任务已自动结束";
}
String headline = chunkCount <= 0L
? "客户端未回传任何检测结果,超过 " + Math.max(1, timeoutMinutes) + " 分钟无进展"
: "客户端回传中断";
List<String> evidence = new ArrayList<>();
if (chunkCount > 0L) {
evidence.add("已收到 " + chunkCount + " 个分片,最后一次 " + at(lastChunkAt));
}
evidence.add("最后心跳 " + at(lastHeartbeatAt));
if (lastProgress != null && !lastProgress.isBlank()) {
evidence.add("最后上报 " + lastProgress.trim());
}
return headline + ",任务已自动结束(" + String.join(";", evidence) + ")";
}
private static String at(LocalDateTime time) {
return time == null ? "时间未知" : time.format(TIME);
}
}