# 品牌检测失败自动补测(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-` 防覆盖原 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:** - [x] **Step 1:** 写迁移(幂等写法对齐 V138:information_schema 判存 + PREPARE/EXECUTE;文件尾注释回滚语句) - [x] **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:** - [x] **Step 1:** entity/mapper(MyBatis-Plus 注解,对齐同包既有写法) - [x] **Step 2:** `enqueue`:品牌归一化复用 `BrandCheckClient` 同款 trim 规则;`INSERT ... ON DUPLICATE KEY UPDATE`(命中已有行且状态非 PENDING 时不改写);空列表零写入 - [x] **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:** - [x] **Step 1:** Properties 类 + 默认值 + relaxed binding 验证用单测 ### Task 4: 调度器(轮询 + 熔断 + 退避) **Files:** - Create: `modules/collectdata/service/CollectDataBrandRecheckScheduler.java`(`@Scheduled` + Redis 锁,写法对齐 `NotificationScanScheduler`) - Test: `CollectDataBrandRecheckSchedulerTest` **Steps:** - [x] **Step 1:** 轮询入口:取到期 PENDING(limit roundBatchSize),按 task_id 聚组;task 非终态/不存在 → 顺延不计次 - [x] **Step 2:** 组内调 `brandCheckClient.checkAll(brands, defaultStrategy)`;把结论分派给注入服务(Task 5) - [x] **Step 3:** 熔断与退避(按行为规格 3/4);`EXHAUSTED` 收口 + 聚合通知挂到 Task 6 一起做 - [x] **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:** - [x] **Step 1:** 按 task 持任务锁(拿不到整组顺延);读 chunk payload 收集目标品牌行(复用 streamRawRows 语义) - [x] **Step 2:** dedupe 复查(`CollectDataBatchQuery.filter`)→ 分流:accepted→明细对象(key `recheck-chunk-`,不得覆盖原 chunk 明细)+ `upsertAccepted`;rejected→`invalidAsinBatchWriter.writeBatch` - [x] **Step 3:** 结论写 ASIN 缓存;组内全部条目处理完 → `enqueueAssembleResult`(仅当本轮有实际写入) - [x] **Step 4:** 幂等验证测试:同 (task,brand) 二次注入 `newlyInserted=0`;rejected 品牌行不进结果;任务锁竞争时零写入 - [x] **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:** - [x] **Step 1:** 实现通知 + 文案(X 行新增 / Y 判无效 / Z 仍失败);EXHAUSTED 收口通知同函数复用 - [x] **Step 2:** 同 task 同日只推一条测试(`pushOrRefresh` 语义) ### Task 7: 全量回归 + 交付部署(只交付命令) **Steps:** - [x] **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 不做。