Files
crawler-plugin/docs/plans/17-brand-check-requeue.md
T
huangzd1997 49c3fc1491 docs(仓库): 规划文档改为入库,落盘品牌库/去重库每公司一套二期方案
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」,
代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红),
跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
2026-10-04 13:51:16 +08:00

15 KiB
Raw Blame History

品牌检测失败自动补测(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_item upsert 的 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)

  1. 入队:submitResult 锁外拿到 brandOutcome.queryFailed() 后,对每个失败品牌 INSERT ... ON DUPLICATE KEY UPDATE(唯一键 task_id+brand;重复失败不刷新首次时间、不改状态);next_attempt_at = now + firstDelayMinutes;只在条目当前为 PENDING 时写入。入队失败只记日志,绝不影响分片回传主流程。
  2. 轮询:调度器每 5 分钟一轮(与通知扫描同节拍),取 status='PENDING' AND next_attempt_at<=now 的条目,按 task 聚组、组内品牌批量检测。任务非终态或已删除 → 条目顺延(next_attempt_at += intervalBase,不计尝试次数)。
  3. 熔断:单轮内「仍查询失败」占比 > failRateThreshold(默认 0.5)且本轮已测 ≥3 个品牌时,中止本轮剩余条目并把本轮已测条目的 attempt_count+1、其余条目不动(下轮再试)。中止时记 warn 日志。
  4. 退避与终态:每次实测失败后 next_attempt_at = now + intervalBase × 2^attempt(30m→1h→2h→4h→8h→16h,封顶 16h);attempt_count ≥ maxAttempts(默认 6)→ 状态 EXHAUSTED,该 task 的 PENDING 条目全部出队后向用户推一条「补测未能完成」通知(当天聚合一次)。
  5. 注入(某品牌检测出结论时):
    • 全量扫该 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)。
  6. 通知:一轮注入产生实际变化(新增结果行 >0 或新判无效 >0)→ 推用户通知「任务 {taskNo} 品牌补测完成:新增结果 X 行、判定无效品牌 Y 行、仍失败 Z 行」;同一 task 同一自然日只推一条(dedupe_key 带自然日,复用 pushOrRefresh)。
  7. 并发:调度器全局单飞(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(prefix aiimage.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→明细对象(key recheck-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_key collect_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: 观察口径:补测轮日志(轮内品牌数/结论分布/熔断次数);上线一周后看「部分结果缺失」通知量与「补测完成」通知量的替代关系

未决问题(实现前与业务确认,不阻塞排期)

  1. rejected(补测判出侵权命中)的行不回溯改历史文件,只落无效品牌表 + 下次装配生效——用户是否接受"结果文件版本会变"?
  2. EXHAUSTED 后是否提供管理员手动重置入口(后台小按钮),还是完全自然过期?V1 倾向不做。
  3. 补测期间用户的客户端如果重新提交了同 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 不做。