看板(心跳位置补进度): 跟价/定时匹配这类无快照的行不再恒画「—」

客户端心跳位置此前只喂 progress/light(客户端进度条),后台任务中心的进度列仍按 10-04 那条
「没分母就画 —」走,于是同一个在跑的跟价任务,客户端有条、看板是「—」。

- TaskCenterQueryService 注入位置服务:只对「无快照 + 不是行内已计数的三个模块 + 非终态」的行
  批量读位置;这个判据抽成 wantsHeartbeatPosition 一处共用——收集与填充各写一遍的话,
  改一处就会让另一处静默拿到 null,又退成「安静地没有条」
- 封顶与页大小同源(BOARD_POSITION_LOOKUPS=100):沿用 light 那个 20 的话,第 21 行之后的
  在跑任务永远读不到进度
- 心跳新增 progressGrain 一并入库;看板按它把 units 的「国家数×1000 摊平当量」折算回自然计数,
  否则管理员会读到「已完成 1222 / 总 5000」。客户端那条仍吃原始千分位(要的是平滑),
  所以折算做成 Position#displayUnits() 显式一步,不是一处改两边
- 快照优先不变:位置只是执行器自述,服务端算出来的快照更权威
- 用例:displayUnits 折算/钳位/分母不塌 0、grain 存取、老客户端不报粒度按自然计数原样通过;
  看板三例(在跑行用心跳、终态一次都不读、有快照不许被覆盖)。TaskCenterQueryServiceTest 37 例绿
This commit is contained in:
2026-10-10 23:40:50 +08:00
parent 3d12689349
commit 96d4e40a77
5 changed files with 256 additions and 9 deletions
@@ -42,4 +42,8 @@ public class TaskHeartbeatRequest {
@Schema(description = "客户端归一化后的当前处理位置描述(如「店铺 张三(2/10),国家 德国(1/3)」),"
+ "用于判死日志与排查;老客户端不传,服务端不得以位置为空作为判死依据", example = "店铺 魏振峰(2/10)")
private String progressText;
@Schema(description = "客户端实际采用的进度粒度:asins/shops/countries/items/rows/units。"
+ "units 表示 current/total 是「国家数×1000」的摊平当量,展示前要折算", example = "countries")
private String progressGrain;
}
@@ -32,6 +32,8 @@ public class TaskHeartbeatPositionService {
private static final int POSITION_LABEL_MAX_LEN = 60;
/** 单次 light 轮询最多读多少个任务的心跳位置(Redis 往返上限,见 {@link #readDrawablePositions})。 */
public static final int MAX_POSITION_LOOKUPS_PER_CALL = 20;
/** 客户端 {@code config.PROGRESS_UNIT_SCALE} 的服务端镜像:units 粒度下 1 个自然单位 = 1000。 */
public static final int PROGRESS_UNIT_SCALE = 1000;
private final StringRedisTemplate stringRedisTemplate;
@@ -53,7 +55,12 @@ public class TaskHeartbeatPositionService {
* 结构化位置读数。{@code current}/{@code total} 可能为 null——客户端只发了文本、
* 没发计数(老版本按四级 key 归一化时 total 全为 0 就不发)。
*/
public record Position(Integer current, Integer total, String label) {
public record Position(Integer current, Integer total, String label, String grain) {
/** 老客户端没报粒度:grain 留空,调用方按「自然计数」处理。 */
public Position(Integer current, Integer total, String label) {
this(current, total, label, "");
}
/**
* 归一化成「能画」的读数:total 非正数即视为没有进度(返回 null),
@@ -67,7 +74,26 @@ public class TaskHeartbeatPositionService {
return null;
}
int safeCurrent = current == null || current < 0 ? 0 : Math.min(current, total);
return new Position(safeCurrent, total, label);
return new Position(safeCurrent, total, label, grain);
}
/**
* 折算成「可以直接显示」的当量,供后台任务中心看板使用。
*
* <p>看板那一列的文案是「已完成 X / 总 Y」(2026-10-04 定的口径),而 {@code units} 这一档
* 的 current/total 是客户端为「翻页进度单调不减」摊平出来的 国家数×1000——照原样显示会读成
* 「已完成 1222 / 总 5000」,管理员只会问 5000 是什么。折算回国家当量后数字可读,
* 代价是看板的条子比客户端粗一档(20% 对 24%),这个取舍是值得的。
*
* <p>客户端进度条不吃这个方法:它走 progress/light 拿原始千分位,要的是平滑。
*/
public Position displayUnits() {
if (!"units".equals(grain) || total == null || total <= 0) {
return this;
}
int shownTotal = Math.max(1, total / PROGRESS_UNIT_SCALE);
int shownCurrent = current == null ? 0 : Math.min(shownTotal, current / PROGRESS_UNIT_SCALE);
return new Position(shownCurrent, shownTotal, label, grain);
}
}
@@ -89,6 +115,7 @@ public class TaskHeartbeatPositionService {
values.put("current", request.getCurrent() == null ? "" : String.valueOf(request.getCurrent()));
values.put("total", request.getTotal() == null ? "" : String.valueOf(request.getTotal()));
values.put("progressText", progressText);
values.put("grain", request.getProgressGrain() == null ? "" : request.getProgressGrain().trim());
values.put("at", String.valueOf(Instant.now().toEpochMilli()));
String key = KEY_PREFIX + taskId;
stringRedisTemplate.opsForHash().putAll(key, values);
@@ -161,7 +188,7 @@ public class TaskHeartbeatPositionService {
if (current == null && total == null) {
return null;
}
return new Position(current, total, trimLabel(value(entries, "progressText")));
return new Position(current, total, trimLabel(value(entries, "progressText")), value(entries, "grain"));
}
/**
@@ -176,13 +203,24 @@ public class TaskHeartbeatPositionService {
* @return taskId → 可画读数;读不到位置或分母非正数的任务不出现在结果里
*/
public Map<Long, Position> readDrawablePositions(Collection<Long> taskIds) {
if (taskIds == null || taskIds.isEmpty()) {
return readDrawablePositions(taskIds, MAX_POSITION_LOOKUPS_PER_CALL);
}
/**
* 同上,但由调用方给封顶值。
*
* <p>封顶必须跟着调用面的规模走:progress/light 一次最多 200 个 id、每 10 秒一轮,20 次够;
* 后台看板一页可到 {@code MAX_PAGE_SIZE=100}、每 30 秒一轮,沿用 20 就会让第 21 行之后的任务
* 永远读不到进度(还是那个「安静地没有条」的老形态)。
*/
public Map<Long, Position> readDrawablePositions(Collection<Long> taskIds, int maxLookups) {
if (taskIds == null || taskIds.isEmpty() || maxLookups <= 0) {
return Map.of();
}
Map<Long, Position> result = new LinkedHashMap<>();
int attempts = 0;
for (Long taskId : taskIds) {
if (attempts >= MAX_POSITION_LOOKUPS_PER_CALL) {
if (attempts >= maxLookups) {
break;
}
attempts++;