`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
15 KiB
品牌检测失败自动补测(requeue)实现计划
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: 采集数据(COLLECT_DATA)任务里品牌检测"查询失败"的行(WIPO 限流/上游抖动期间),在任务收尾后由后端自动排队补测;补测出结论后把行自动补进结果文件(或判进无效品牌表),用户收到补测结果通知——替代现状"通知里让人手工重跑,且用户根本拿不到失败 ASIN 清单"。
Background(2026-10-02 实证): WIPO 全球商标库限流 10:00–21:00 持续 11 小时,两台 java brand-check 重试耗尽 共 2778 次(约 8 成 query_faild_data 持续非空,2 成 header parser received no bytes),当日 22 条「部分结果缺失」通知(单任务最高 111 行)。queryFailed 行按设计不进结果也不落无效品牌表(task-27265 教训:误杀不可逆),但现状除一条计数通知外无任何出口。客户端单品牌重试 10 次≈45s、批预算 90s,扛不过小时级限流窗口——补测把"重试"从同步调用里拆出来放到任务收尾之后。
Architecture: 分片回传时把 queryFailed 的品牌写进补测队列表 biz_collectdata_brand_recheck(task_id+brand 唯一,行数据不落表、注入时从既有 chunk 全量 payload 回读)。新调度器 CollectDataBrandRecheckScheduler 按 Redis 分布式锁轮询(复用 NotificationScanScheduler 的锁与节流写法):只处理任务已终态(SUCCESS/FAILED)且到 next_attempt_at 的条目,按批调既有 BrandCheckClient.checkAll;单轮失败率超阈值立即熔断整轮顺延。补测出结论后注入:accepted → 走 dedupe 复查(first-writer-wins)+ resultItemBatchWriter.upsertAccepted 落结果;rejected → invalidAsinBatchWriter.writeBatch 落无效品牌表;随后复用 enqueueAssembleResult 异步重建结果文件,并向用户推补测结果通知。指数退避 30m→16h 共 6 轮,覆盖 ≈31h 的限流窗口。
Tech Stack: Java 21 / Spring Boot 3.3.9 / MyBatis-Plus / Flyway;JUnit5 + Mockito。
Spec: 内嵌于本文「行为规格」一节(实现期如需可拆 docs/specs/17-brand-check-requeue.md)。
复用清单(全部已存在,勿重写):
| 能力 | 位置 |
|---|---|
| 品牌批量检测(含重试/预算) | BrandCheckClient.checkAll(modules/brand/client/BrandCheckClient.java:96) |
| chunk 全量行回读(RustFS 指针解析 + JSON 解码) | CollectDataService.streamRawRows(CollectDataService.java:1215),transientPayloadStorageService.resolvePayload |
| 去重/无效品牌过滤 | CollectDataBatchQuery.filter(collectdata/util/CollectDataBatchQuery.java) |
| 结果行落库(幂等 upsert,返回新增数) | CollectDataResultItemBatchWriter.upsertAccepted(CollectDataResultItemBatchWriter.java:65) |
| 结果明细对象编码 | CollectDataResultDetailCodec.encodeChunk(CollectDataResultDetailCodec.java:87) |
| 无效品牌落表 | invalidAsinBatchWriter.writeBatch(CollectDataService.java:893 用法) |
| 结果文件异步重建(幂等,重算 finalRowCount) | TaskFileJobService.enqueueAssembleResult(TaskFileJobService.java:34)→ CollectDataService.processResultFileJob |
| 品牌结论缓存写入 | CollectDataService.writeAsinCacheOutsideLock(CollectDataService.java:840) |
| 用户侧通知 | NotificationDispatchService(pushPartialResult 同款形态,NotificationDispatchService.java:116) |
| 定时轮询 + Redis 锁 | NotificationScanScheduler(notification/service/NotificationScanScheduler.java:78-103)写法 |
Global Constraints
- Flyway 只能新增
V140__*.sql(V138/V139 已被占用);历史迁移一字不改;backend-java/docs/migration-inventory.md同步(MigrationInventoryTest会断言)。 - 生产红线(记忆):生产写操作只交付命令不自行执行;发布前跑三条取证;只
git add自己的文件。 - 补测注入只允许发生在任务终态之后(SUCCESS/FAILED);RUNNING/PENDING 任务一律跳过本轮,避免与分片重提竞态。
- 注入必须幂等:同一 (task_id, brand) 的行重复补测不得产生重复结果行(靠
uk_task_scope_itemupsert 的 payload_hash 跳过语义)。 - 新增开关默认开启但可用配置关闭(
aiimage.collect-data.brand-recheck.enabled);首轮调度延迟 ≥30 分钟,绝不与任务收尾抢上游。 - Java 测试 JUnit5 + Mockito(
@ExtendWith(MockitoExtension.class));命令cd backend-java && mvn -o test -Dtest=XxxTest。 - 范围 V1 只做 COLLECT_DATA;BRAND 模块的 queryFailedBrands 已有「查询失败品牌」Excel sheet 出口,不在本期。
行为规格(Spec)
- 入队:
submitResult锁外拿到brandOutcome.queryFailed()后,对每个失败品牌INSERT ... ON DUPLICATE KEY UPDATE(唯一键 task_id+brand;重复失败不刷新首次时间、不改状态);next_attempt_at = now + firstDelayMinutes;只在条目当前为 PENDING 时写入。入队失败只记日志,绝不影响分片回传主流程。 - 轮询:调度器每 5 分钟一轮(与通知扫描同节拍),取
status='PENDING' AND next_attempt_at<=now的条目,按 task 聚组、组内品牌批量检测。任务非终态或已删除 → 条目顺延(next_attempt_at += intervalBase,不计尝试次数)。 - 熔断:单轮内「仍查询失败」占比 >
failRateThreshold(默认 0.5)且本轮已测 ≥3 个品牌时,中止本轮剩余条目并把本轮已测条目的attempt_count+1、其余条目不动(下轮再试)。中止时记 warn 日志。 - 退避与终态:每次实测失败后
next_attempt_at = now + intervalBase × 2^attempt(30m→1h→2h→4h→8h→16h,封顶 16h);attempt_count ≥ maxAttempts(默认 6)→ 状态EXHAUSTED,该 task 的 PENDING 条目全部出队后向用户推一条「补测未能完成」通知(当天聚合一次)。 - 注入(某品牌检测出结论时):
- 全量扫该 task 的 chunk payload(复用 streamRawRows 逻辑),收集 brand 归一化等于该品牌的行;
- 行集过
CollectDataBatchQuery.filter复查 dedupe/无效品牌(期间该 ASIN 可能已被其他任务采走 → first-writer-wins,被滤掉属预期); - 结论无侵权命中 → 存 chunk 级明细对象(
encodeChunk+storeResultPayload,key 用recheck-chunk-<n>防覆盖原 chunk 明细)后upsertAccepted进结果;结论有侵权命中(faild_data 非空)→invalidAsinBatchWriter.writeBatch,行不进结果; - 补测结论同样写入 ASIN 结论缓存(
writeAsinCacheOutsideLock同款),后续任务受益; - 该 task 注入批结束后
enqueueAssembleResult重建结果文件(worker 会重算并持久化 finalRowCount)。
- 通知:一轮注入产生实际变化(新增结果行 >0 或新判无效 >0)→ 推用户通知「任务 {taskNo} 品牌补测完成:新增结果 X 行、判定无效品牌 Y 行、仍失败 Z 行」;同一 task 同一自然日只推一条(dedupe_key 带自然日,复用
pushOrRefresh)。 - 并发:调度器全局单飞(Redis 锁);注入期间持任务分布式锁(
TaskDistributedLockService),拿不到就整组顺延。
Task 1: V140 迁移(补测队列表)+ 迁移盘点同步
Files:
- Create:
backend-java/src/main/resources/db/V140__collectdata_brand_recheck.sql - Modify:
backend-java/docs/migration-inventory.md
Interfaces:
- Produces: 表
biz_collectdata_brand_recheck:id BIGINT PK AI、task_id BIGINT NOT NULL、task_no VARCHAR(64)、user_id BIGINT NOT NULL、brand VARCHAR(255) NOT NULL(归一化后)、status VARCHAR(16) NOT NULL DEFAULT 'PENDING'(PENDING/INJECTED/REJECTED/EXHAUSTED)、attempt_count INT NOT NULL DEFAULT 0、last_error VARCHAR(500)、next_attempt_at DATETIME NOT NULL、created_at/updated_at DATETIME;唯一键uk_recheck_task_brand(task_id, brand)、索引idx_recheck_status_next(status, next_attempt_at)。
Steps:
- Step 1: 写迁移(幂等写法对齐 V138:information_schema 判存 + PREPARE/EXECUTE;文件尾注释回滚语句)
- Step 2:
migration-inventory.md追加 V140 行;跑MigrationInventoryTest通过
Task 2: 队列实体/Mapper + 入队写入(分片回传侧)
Files:
- Create:
modules/collectdata/model/entity/CollectDataBrandRecheckEntity.java、modules/collectdata/mapper/CollectDataBrandRecheckMapper.java - Create:
modules/collectdata/service/CollectDataBrandRecheckService.java(入队 + 取出 + 状态推进的 DB 语义都收在这) - Modify:
CollectDataService.java(submitResult锁外,brandOutcome计算后、writeAsinCacheOutsideLock附近调recheckService.enqueue(taskId, taskNo, userId, brandOutcome.queryFailedBrands());包 try-catch 只记日志) - Test:
CollectDataBrandRecheckServiceTest
Steps:
- Step 1: entity/mapper(MyBatis-Plus 注解,对齐同包既有写法)
- Step 2:
enqueue:品牌归一化复用BrandCheckClient同款 trim 规则;INSERT ... ON DUPLICATE KEY UPDATE(命中已有行且状态非 PENDING 时不改写);空列表零写入 - Step 3: 接入
submitResult,测试:queryFailed 为空不写库、重复失败不刷新首次时间、入队抛错不影响回传返回值
Task 3: 补测配置项
Files:
- Create:
config/CollectDataBrandRecheckProperties.java(prefixaiimage.collect-data.brand-recheck) - Modify:
application.yml(如该前缀需显式登记;对齐aiimage.collect-data.brand-check-batch-size的登记方式)
Interfaces:
enabled=true、scanIntervalMs=5min、firstDelayMinutes=30、intervalBaseMinutes=30、maxAttempts=6、roundBatchSize=200(单轮品牌数上限)、probeBatchSize=10(复用 brand-check-batch-size)、failRateThreshold=0.5、failRateMinProbe=3
Steps:
- Step 1: Properties 类 + 默认值 + relaxed binding 验证用单测
Task 4: 调度器(轮询 + 熔断 + 退避)
Files:
- Create:
modules/collectdata/service/CollectDataBrandRecheckScheduler.java(@Scheduled+ Redis 锁,写法对齐NotificationScanScheduler) - Test:
CollectDataBrandRecheckSchedulerTest
Steps:
- Step 1: 轮询入口:取到期 PENDING(limit roundBatchSize),按 task_id 聚组;task 非终态/不存在 → 顺延不计次
- Step 2: 组内调
brandCheckClient.checkAll(brands, defaultStrategy);把结论分派给注入服务(Task 5) - Step 3: 熔断与退避(按行为规格 3/4);
EXHAUSTED收口 + 聚合通知挂到 Task 6 一起做 - Step 4: 测试:非终态顺延不计次、退避序列 30m/1h/2h/4h/8h/16h、maxAttempts 收口、熔断后未测条目不计次
Task 5: 注入路径(结论 → 结果行/无效品牌 → 文件重建)
Files:
- Create:
modules/collectdata/service/CollectDataBrandRecheckInjector.java - Modify:
CollectDataService.java(把streamRawRows提为包内可复用,或抽CollectDataChunkReader;processResultFileJob/装配路径不动) - Test:
CollectDataBrandRecheckInjectorTest
Steps:
- Step 1: 按 task 持任务锁(拿不到整组顺延);读 chunk payload 收集目标品牌行(复用 streamRawRows 语义)
- Step 2: dedupe 复查(
CollectDataBatchQuery.filter)→ 分流:accepted→明细对象(keyrecheck-chunk-<n>,不得覆盖原 chunk 明细)+upsertAccepted;rejected→invalidAsinBatchWriter.writeBatch - Step 3: 结论写 ASIN 缓存;组内全部条目处理完 →
enqueueAssembleResult(仅当本轮有实际写入) - Step 4: 幂等验证测试:同 (task,brand) 二次注入
newlyInserted=0;rejected 品牌行不进结果;任务锁竞争时零写入 - Step 5: 边界:chunk payload 丢失/解码失败只跳过该 chunk 并记 warn,不中断注入
Task 6: 用户通知
Files:
- Modify:
NotificationDispatchService.java(新增pushRecheckCompleted(userId, taskNo, injected, rejected, pending),形态对齐pushPartialResult;dedupe_keycollect_recheck:{taskId}:{yyyyMMdd}) - Test:
NotificationDispatchServiceTest补用例
Steps:
- Step 1: 实现通知 + 文案(X 行新增 / Y 判无效 / Z 仍失败);EXHAUSTED 收口通知同函数复用
- Step 2: 同 task 同日只推一条测试(
pushOrRefresh语义)
Task 7: 全量回归 + 交付部署(只交付命令)
Steps:
- Step 1:
cd backend-java && mvn -o test全绿(3451 个测试,含本功能 31 个新用例) - Step 2: 交付命令清单(人工执行):
mvn clean package -DskipTests→python scripts/deploy.py(或_deploy_jar_and_restart_both.py)→ 两台docker logs java-server观认brand-recheck首轮日志;V140 由 Flyway 启动时自动执行 - Step 3: 观察口径:补测轮日志(轮内品牌数/结论分布/熔断次数);上线一周后看「部分结果缺失」通知量与「补测完成」通知量的替代关系
未决问题(实现前与业务确认,不阻塞排期)
- rejected(补测判出侵权命中)的行不回溯改历史文件,只落无效品牌表 + 下次装配生效——用户是否接受"结果文件版本会变"?
- EXHAUSTED 后是否提供管理员手动重置入口(后台小按钮),还是完全自然过期?V1 倾向不做。
- 补测期间用户的客户端如果重新提交了同 ASIN 新任务,注入时 dedupe 复查会丢弃旧任务行——文案里要不要解释"已被新任务覆盖"?
实现落地记录(2026-10-02,未部署未提交)
- 新文件:
V140__collectdata_brand_recheck.sql、CollectDataBrandRecheckEntity/Mapper/Service/Scheduler/Injector、CollectDataBrandRecheckProperties(已在PropertiesConfig登记)、4 个新测试类(31 用例)。 - 既有文件改动:
CollectDataService(submitResult 锁外入队 +resolveCacheCountry收窄为包内可见)、CollectDataBrandBatchFilter.normalizeBrand改 public(补测链路复用同一归一化口径)、NotificationDispatchService.pushRecheckOutcome、migration-inventory.md(V140)。 - 5 个既有测试类补了构造参数/
@Mock(构造签名新增 recheck 服务)。 - 与计划的偏差:入队用 select→insert + 吞
DuplicateKeyException(语义等价 ON DUPLICATE 的"不改写"要求);maxAttempts=7(首测 + 6 轮退避 30m/1h/2h/4h/8h/16h,合计覆盖 ≈31h——计划里 6 轮的算术覆盖不了 31h);通知方法定名pushRecheckOutcome(同一方法覆盖"补测完成/未能完成"两形态)。 - 未决问题 1 按默认执行(补测只影响后续装配,不回溯改历史文件);2/3 V1 不做。