perf(F5+): 行数据按需拉取(结果行版本信号)+ 修复 progress/light 恒判 missing

行数据按需拉取(审查 F5 后续):
- V125 给 biz_file_result 补 updated_at(DEFAULT/ON UPDATE 由数据库维护,
  实体标注 insertStrategy/updateStrategy=NEVER —— 否则 selectById→updateById 的
  写回会把旧值写回去、ON UPDATE 不触发,版本信号静默冻结)
- 装配器回传 rowsVersion=「最后变更时间毫秒#行数」,5 个品牌工具页版本未变即跳过
  带行明细的重型 batch;前端变更信号为 rowsVersion + status/fileStatus/fileReady 复合
  (任务收尾常见「行早写完、之后才置成功」,只看行版本会把界面卡在旧状态)

修复线上缺陷(同一功能验证时暴露):
- TaskProgressLightAssembler 列裁剪漏选 module_type 却用它做模块过滤 →
  getModuleType() 恒为 null → light 恒把任务判成 missing;第七批把 light 接进
  跟价/定时匹配/商品风险的轮询后,消费方会把运行中任务判为 FAILED
- 补选中列 + 守卫用例 taskQueryMustSelectModuleType(已反向验证:去掉修复即红)
- 前端 lightClaimsAllTasksMissing:整体性 missing 结论用重型端点复核后再采信

契约与文档:light 白名单补 rowsVersion(Java 契约测试 / spec 06 §2 / 12 个端点描述)
测试:mvn test 2901 全绿;前端 npm test 765 全绿
This commit is contained in:
2026-09-14 12:08:25 +08:00
parent 9166656673
commit 5ea52e5291
32 changed files with 641 additions and 36 deletions
@@ -42,6 +42,8 @@ export interface TaskProgressLightItem {
fileError?: string | null
fileReady?: boolean | null
updatedAt?: string | null
/** 结果行版本(「最后变更时间毫秒#行数」):未变说明行数据没动过,可跳过重型 batch。 */
rowsVersion?: string | null
}
export interface GetModuleProgressLightOptions {
@@ -61,6 +61,77 @@ export interface PollingBatchLike<T> {
missingTaskIds?: number[]
}
/**
* 行数据按需拉取(审查 F5 后续):
* 轻量响应里的 rowsVersion 是该任务**结果行**的版本(最后变更时间毫秒 + 行数,后端一次 GROUP BY 查出)。
* 版本没变说明行数据没动过,就不必再拉带行明细的重型 batch。
*
* 变更信号是**复合**的:行版本之外还看 status / fileStatus / fileReady——任务收尾时常见
* 「行已经写完、之后任务才置成功」或「结果文件才就绪」,只看行版本会把界面卡在旧状态。
*
* 安全兜底(保证零回归):
* - 四项信号全空(老后端 / 字段缺失)→ 视为拿不到信号,该任务照旧每轮拉取;
* - 轻量请求本身失败时调用方回退为全量拉取(见各页 catch 分支)。
*/
export interface TaskProgressChangeSignal {
taskId?: number
rowsVersion?: string | null
status?: string | null
fileStatus?: string | null
fileReady?: boolean | null
}
/** 组装变更信号;taskId 非法或四项信号全空时返回 null(= 拿不到信号,必须拉取)。 */
function changeSignatureOf(raw: unknown): { taskId: number; signature: string } | null {
const item = raw as TaskProgressChangeSignal | null
if (!item || typeof item.taskId !== 'number' || !(item.taskId > 0)) return null
const rowsVersion = typeof item.rowsVersion === 'string' ? item.rowsVersion : ''
const status = typeof item.status === 'string' ? item.status : ''
const fileStatus = typeof item.fileStatus === 'string' ? item.fileStatus : ''
const fileReady = item.fileReady === true ? '1' : item.fileReady === false ? '0' : ''
if (!rowsVersion && !status && !fileStatus && !fileReady) return null
return { taskId: item.taskId, signature: [rowsVersion, status, fileStatus, fileReady].join('|') }
}
export function createRowsVersionTracker() {
const seen = new Map<number, string>()
return {
/**
* 返回"需要拉取行明细"的任务 id(信号变化 / 拿不到信号的)。
* 同时记录本轮看到的信号(便于下轮比较)。
*/
selectTasksNeedingRows(items: unknown[] | null | undefined, requestedIds: number[]): number[] {
const signatureById = new Map<number, string>()
for (const raw of items || []) {
const parsed = changeSignatureOf(raw)
if (parsed) signatureById.set(parsed.taskId, parsed.signature)
}
const needRows: number[] = []
for (const taskId of requestedIds) {
const signature = signatureById.get(taskId)
if (signature === undefined) {
needRows.push(taskId)
continue
}
if (seen.get(taskId) !== signature) {
needRows.push(taskId)
}
}
for (const [taskId, signature] of signatureById) {
seen.set(taskId, signature)
}
return needRows
},
/** 任务结束/被删除时清掉记录,避免 Map 无界增长。 */
forget(taskId: number): void {
seen.delete(taskId)
},
reset(): void {
seen.clear()
},
}
}
export interface PollingProgressOptions<TBatch> {
/** 重型端点兜底(轻量端点异常或返回空时调用),不传则不兜底 */
fallback?: () => Promise<TBatch>
@@ -83,6 +154,23 @@ export function pickPollingBatch<T>(
return { items: items as unknown as T[], missingTaskIds: missing }
}
/**
* light 是否把**全部**请求任务都判成"不存在"。
*
* <p>整体性结论风险最大:消费方把 missing 当"任务已消失"(跟价页直接返回 FAILED)。
* 2026-09-14 线上即出现过 light 因后端漏选过滤字段而恒判 missing,故这种结论要用重型端点复核。
*/
export function lightClaimsAllTasksMissing(
picked: PollingBatchLike<unknown> | null | undefined,
requestedIds: number[],
): boolean {
const ids = (requestedIds || []).filter((id) => typeof id === 'number' && id > 0)
if (!ids.length) return false
if ((picked?.items || []).length) return false
const missing = picked?.missingTaskIds || []
return ids.every((id) => missing.includes(id))
}
/**
* 取任务进度:轻量端点优先,异常/空结果时回退重型端点。
* 轻量端点返回 empty(既没有 items 也没有 missingTaskIds)时也走兜底——
@@ -98,6 +186,10 @@ export async function getPollingProgressBatch<TBatch extends PollingBatchLike<un
const light = await getModuleProgressLight(module, taskIds)
const picked = pickPollingBatch<unknown>(light.items, light.missingTaskIds)
if (picked) {
if (fallback && lightClaimsAllTasksMissing(picked, taskIds)) {
// 复核:以重型端点为准(它若也判不存在,结论一致;若返回了条目,说明 light 错了)
return fallback()
}
return picked as TBatch
}
} catch {