feat(phase-5): AC-19/AC-21 读路径时间窗与 keyset、心跳瘦读、菜单缓存、去 RAND、MDC 与补检限流

AC-19(P1-B1/B2/B3/B4)
- 任务中心(P1-B1):TaskCenterQueryService.tasks() 不带 startTime 时补 90 天默认窗口
  (startOfDefaultWindow),不再把 null 透传给 12 模块 UNION 扫全历史;selectTaskPage 的
  `LIMIT ? OFFSET ?` 改成 (createdAt,id) 游标,深翻页的 skip 挪进新语句
  selectTaskPageAnchor——它只投影 (id,createdAt) 两列。宽/窄两份 UNION 共用同一对筛选片段
  (taskFilterT/taskFilterB),锚点与页查询筛的行集在结构上不可能漂;页码语义、total、
  响应结构与前端全部不变。
- 关键词抽词(P1-B2):selectRandomUnused 不再 ORDER BY RAND()(全表 filesort)。
  服务层先 countHit 数命中集、再把窗口起点掷在 [0, total-limit],按 k.id 有序取一段后
  在内存洗牌。分布口径变了(连续 id 的一段 vs 逐行独立随机),已如实登记。
- 心跳(P1-B3):selectFileTask 只捞 id/moduleType/status/userId/updatedAt 五列;
  需要整实体的模块由新 SPI 默认方法 heartbeatNeedsFullTaskEntity()(默认 true=保守)
  声明后补一次主键读,collect-data/similar-asin/appearance-patent 三个只用
  task.getId() 的显式豁免。半行进 saveTaskCache 会写出坏缓存,比多读一次列难查得多。
  markInterrupted 改走整实体读(要 errorMessage 并同步模块缓存/快照)。
- 权限菜单(P1-B4):loadMenus 加 (companyId,menuType) 短 TTL(30s) 快照缓存,
  五处目录写路径 create/update/delete/reorder/copyTreeFromTemplate 全部写时失效;
  只缓存目录本体、不缓存用户授权行——撤权必须下一请求就生效。

AC-21(审计 §5/PERF §6)
- RequestTraceFilter 把已解析却只进日志参数的 requestId 写入 MDC(缺失写 "-"),
  finally 里 MDC.clear()(tomcat 线程复用,不清就把上一条的 id 带给下一条日志);
  logback-spring.xml 的两条 pattern 默认值 + application.yml 显式设的 file/console
  两条同批改带 [%X{requestId}]——本文件那两条会盖掉默认值,漏一处线上照样看不见。
- AppearancePatentDeliverySupport.requestRecheckForMissingRows 的补检轮 WARN 按任务限流:
  5 分钟窗口内首条 WARN(带 suppressedInLastWindow 汇总),其余降 DEBUG。刻意不吃
  recheckRounds/countRecheckRound 那对轮次计数——那是 scheduleFallbackRecheck 的补检预算,
  从日志路径再计一次会让"限流"吃掉业务预算、任务更早被判补检耗尽。
  "补检排不上队"那条不受限流(要人处置的信号不许压)。

契约激活与判据变更
- PendingPhase5ReadPathTest 5 例、PendingPhase5LogVolumeAndMdcTest 3 例全部去 @Disabled 转绿;
  后者预置的 logback 路径层级写错(mainSourcesRoot() 已是 src/main/java),激活时修正,
  并补一条 application.yml 的 pattern 判据(只增不减)。
- 新增 AppearancePatentRecheckWarnThrottleTest 3 例:钉实跑读数(6 轮只留 1 条 WARN + 5 条
  DEBUG、按任务隔离、排不上队仍出声),形状尺子之外的行为证据。
- TaskCenterQueryMapperSqlTest +2 例(锚点窄投影、游标收窄两分支)、
  TaskCenterQueryServiceTest +3 例(默认窗口、第一页不付锚点钱、页码越界返回空页)。
- 三处既有判据按新契约反转,一支没注释掉:selectTaskPage 的 `LIMIT ? OFFSET ?`→游标、
  分页参数绑定数 2→1/16→18/8→7;tasks() 三处 isNull()→notNull()(默认窗口生效本身成为断言)。
- 棘轮登记:SQL 分层语句总数 143→144(新语句点名),MigratedSqlEquivalenceTest
  XML_SELECT_TOTAL 99→100、LEDGER_ROWS 85→84、LEDGER_SELECTS 60→59——
  selectTaskPage 那一行整条摘出基准账本并点名进 NOT_MIGRATED,因为基准是"搬迁前的注解原文",
  改写它等于让等价性测试替新 SQL 背书。
- application.yml 走 hash-object+update-index 只提交本轮 pattern 那一格(4/2),
  另一路会话在飞的 client-task-pull 注释格原样留在工作树未提交。

读数:后端 mvn -o test 5,021 例/0 Failures/0 Errors/19 skipped(6:21 min,
较 Phase 4 的 5,013 净增 8 例=激活 8 例预置后新增 8 例判据);fat jar 实起,落盘行带出
`[main] INFO  [] c.nanri.aiimage.AiImageApplication - Starting...` 证明 MDC 位真在渲染;
本机无 MySQL ⇒ Hikari 反复 Starting、Tomcat 未监听,请求级 requestId 关联与现网四样本顺延 Phase 6。
This commit is contained in:
2026-10-29 16:32:46 +08:00
parent ef0bc51fa2
commit 217f5eec62
23 changed files with 630 additions and 62 deletions
@@ -50,6 +50,12 @@ public class AppearancePatentTaskHeartbeatSpi implements TaskModuleHeartbeatSpi
task.getId(), moduleType(), jobTouchIntervalMillis());
}
/** 只把 {@code task.getId()} 交给作业续期,不写模块缓存 ⇒ 心跳可以吃瘦读(AC-19/P1-B3)。 */
@Override
public boolean heartbeatNeedsFullTaskEntity() {
return false;
}
private long jobTouchIntervalMillis() {
return Math.max(1_000L, appearancePatentProperties.getDbJobTouchIntervalMillis());
}
@@ -17,6 +17,8 @@ import lombok.extern.slf4j.Slf4j;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;
/**
* 外观专利的交付闸门与补检(E 聚类之一),从 {@code AppearancePatentTaskService} <b>原样搬移</b>
@@ -30,6 +32,20 @@ public class AppearancePatentDeliverySupport {
private static final String STATUS_FAILED = TaskStatuses.FileTask.FAILED;
/**
* AC-21(审计 §5、PERF_REPORT §6):交付缺口补检 WARN 的按任务限流窗口。
*
* <p>现网实录 task 32609/job 23345 三分钟 478 条(≈9,560 条/小时):结果文件作业每 15s
* 被 claim 一轮,同一批缺口行每轮原样再报一次,字段一字不差,日志里没有新信息,只有量。
*
* <p>本类按调用现取(不是 Spring bean,{@code AppearancePatentTaskService#deliverySupport()}
* 每次 new 一只),所以限流态只能挂静态:一个 JVM 一份,两台实例各打各的,不互相吞计数。
* 条目数由 {@link #WARN_TASKS_MAX} 兜住,超了就先把窗口已过期的清出去。
*/
static final long RECHECK_WARN_WINDOW_MILLIS = 300_000L;
static final int WARN_TASKS_MAX = 1024;
private static final ConcurrentHashMap<Long, RecheckWarnWindow> RECHECK_WARN_WINDOWS = new ConcurrentHashMap<>();
private final String moduleType;
private final AppearancePatentProperties properties;
private final AppearancePatentTaskCacheService taskCacheService;
@@ -120,8 +136,7 @@ public class AppearancePatentDeliverySupport {
boolean requeued = taskFileJobService.requeue(job.getId(),
"有 " + facts.missingRows() + " 行未完成检测,补检一轮后重新组装结果文件");
if (requeued) {
log.warn("[appearance-patent] 交付缺口触发补检轮 taskId={} jobId={} missingRows={} keys={} noDataRows={}",
task.getId(), job.getId(), facts.missingRows(), keys.size(), facts.noDataRows());
throttleRecheckWarning(task, job, facts);
return true;
}
log.warn("[appearance-patent] 交付缺口补检排不上队,转失败兜底出口按补检预算处置 taskId={} jobId={} missingRows={}",
@@ -129,6 +144,47 @@ public class AppearancePatentDeliverySupport {
throw new BusinessException("有 " + facts.missingRows() + " 行未完成检测,等待补检轮");
}
/**
* 补检轮 WARN 的限流出口(AC-21):同一任务在一个窗口内只留一条 WARN,窗口里被压掉的条数
* 随下一条 WARN 一起汇总出去({@code suppressedInLastWindow}),窗口内的重复轮次降 DEBUG。
*
* <p>刻意不去碰 {@code taskCacheService.recheckRounds/countRecheckRound} 那对轮次计数:
* 那是 {@link #scheduleFallbackRecheck} 的补检预算({@code recheckMaxRounds})。从这条路径
* 再计一次,会让「日志限流」吃掉业务预算,任务更早被判「补检已耗尽」——那是行为变更,不是治理。
*
* <p>并发口径:读-判-写三步之间有竞争,最坏情况是同窗口多打一条 WARN。限流是为了压日志量,
* 不是为了恰好一条,不值得为它加锁或把整张表串行化。
*/
private void throttleRecheckWarning(FileTaskEntity task, TaskFileJobEntity job,
AppearancePatentRowOutcome.Facts facts) {
long now = System.currentTimeMillis();
RecheckWarnWindow current = RECHECK_WARN_WINDOWS.get(task.getId());
if (current != null && now - current.startedAtMillis < RECHECK_WARN_WINDOW_MILLIS) {
log.debug("[appearance-patent] 交付缺口触发补检轮 taskId={} jobId={} missingRows={} keys={}(限流:窗口内第 {} 条)",
task.getId(), job.getId(), facts.missingRows(), facts.missingKeys().size(),
current.suppressed.incrementAndGet());
return;
}
log.warn("[appearance-patent] 交付缺口触发补检轮 taskId={} jobId={} missingRows={} keys={} noDataRows={} suppressedInLastWindow={}",
task.getId(), job.getId(), facts.missingRows(), facts.missingKeys().size(),
facts.noDataRows(), current == null ? 0L : current.suppressed.get());
if (RECHECK_WARN_WINDOWS.size() >= WARN_TASKS_MAX) {
RECHECK_WARN_WINDOWS.entrySet().removeIf(entry ->
now - entry.getValue().startedAtMillis >= RECHECK_WARN_WINDOW_MILLIS);
}
RECHECK_WARN_WINDOWS.put(task.getId(), new RecheckWarnWindow(now));
}
/** 一个任务在一个限流窗口里的补检告警态:窗口起始时刻 + 窗口内被压到 DEBUG 的条数。 */
private static final class RecheckWarnWindow {
private final long startedAtMillis;
private final AtomicLong suppressed = new AtomicLong();
private RecheckWarnWindow(long startedAtMillis) {
this.startedAtMillis = startedAtMillis;
}
}
/**
* 只量行账、不出表。补检的决定必须做在 {@code assembleResultWorkbook} 之前,而那一跑完就把
* 成品传上 OSS 并挂好了 {@code resultFileUrl}。判据与出表共用