b404fd2572
`.gitignore` 原先把 docs/plans/ 与 backend-java/docs/plans/ 记成「本地不入库」, 代价有两头:干净 worktree 出包时这些文件根本不存在(门禁要读它们的用例先假红), 跨会话的实施计划也没有留存通道。改为入库,本批把 34 个 md 落进仓库。
160 lines
15 KiB
Markdown
160 lines
15 KiB
Markdown
# 品牌检测失败自动补测(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 不做。
|