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

160 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 品牌检测失败自动补测(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:**
- [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-<n>`,不得覆盖原 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 不做。