Commit Graph

129 Commits

Author SHA1 Message Date
huangzd1997 6a43a7e745 docs(phase-3): 3D 前置出处账——底座把 Publish 记成 TerminalRejection#ERROR 的出处这一笔不实,改记成第三种形状
纯 javadoc,一行生产逻辑未动(`git diff --stat` = 12+/4−,全在注释块内)。

3D 前置 golden(上一枚 commit)逐段读完 publish 的终态后,发现底座 `TerminalRejection#ERROR` 那段注释里两处不实:
- **Publish 从来不是本档位的使用方**。Phase 2 把它按「不带 code」这一维归了类并留了个 `:1344` 指针,但 `PublishTaskService` 全文零次出现「任务已结束」;它真实的两处是 `:1104-1108`/`:1137-1141`,形状是本枚举**没建模的第三种**:SUCCESS 静默返回(不抛),FAILED 才抛「任务已失败,拒绝继续回传」。golden 的 `taskSuccessShortCircuitsWithoutThrowing` = 两次 `task.load` + `tx.begin/commit`、零写入、`result=void` 就是这条的物证。
- **ShopDataCrawl 的 `:633` 指针也已漂**(那行现在是建单段的 `newTaskHeader`),真出处是 `submitResult` 里 `:676`。连同 `IDEMPOTENT` 段的 ShopMatch `:652`/PriceTrack `:603`(实测在 `:675`/`:642`)一起,本笔一律改成**认方法名不认行号**——这正是 3C 那笔给 CollectData 立过的规矩,当时只改了 CollectData 一支的行,剩下三支的行号照旧漂着。

对 3D 的直接结论:publish 接底座时这一格既不能套 IDEMPOTENT 也不能套 ERROR,只能留本地写法、或先给枚举加第三档;加档属公共形状变更,要单独授权。这一格与 `:1104` 那处的「锁外预检」合起来,是 publish 与 collectdata 虽同属 chunk+scope 族、却不能照抄迁移的两处硬差。

门禁:`mvn -o test-compile` rc=0;ratchet/护栏七类合跑 `Tests run: 77, Failures: 0`(含 `CatchSilenceRatchetTest` 9、`SourceScanTest` 40、`LockSkipSilentExitGuardrailTest` 4);ops readability ratchet 9 passed——本件现 551 行(ruler 口径),距 800 报警线尚有 249 行,注释变厚不构成新 offender。全量 4537 已在上枚 commit 前跑过,本笔只动注释、不重复消耗。
2026-10-19 17:56:34 +08:00
huangzd1997 e1bc19d331 docs(phase-3): 3C 出处账续笔——底座对 CollectData 的四枚行号指针改指方法名,publishResultFile 的「六支同形」改写成分层事实
迁移把被迁支的行号整体挪动,指针会腐烂(3A 已为此把 :1265 换成方法名,这次同一
失效模式又出现四处):TerminalRejection#IDEMPOTENT/newTaskHeader/successFileCount
/enqueueResultAssembly 的 CollectData 读数一律改指 persistParsedTask、
enqueueFinalWorkbook、processResultFileJob。

publishResultFile 那条「六支逐字相同」在 3C 之后不再成立,按实测改成分层表述:
列形状七支都有,真接上本件的目前只有 shop-payload 两支(grep 全树 publishResultFile
调用点核实),另有三种「接不上」的理由——ShopDataCrawl 批量条件更新、DeleteBrand
的可空 rowCount、CollectData 的上传必须排在 persistStats 之前(那条时序是自愈前提)。
判据与代码一行未动。
2026-10-19 15:45:42 +08:00
huangzd1997 394145deb5 refactor(phase-3): 3E 第五支接入底座——接得上七件九点,接不上的六格逐格立账
DeleteBrandRunService extends AbstractFileTaskPipeline<DeleteBrandParsedFileCacheDto>:
@RequiredArgsConstructor 换显式 14 枚构造子,五枚(两支 Mapper+锁+Job+OSS)交 super,
本支不再重复声明那五个字段;moduleType()/loadTaskForSubmission() 两枚钩子落地。

接上并逐点核对的七件九点:requireUserId(:176)、newTaskHeader+insertTask(:180/183)、
newScopeRow 两处(:259/271)、requireSubmissionTask(:1372)、enqueueResultAssembly(:1516)、
listScopeRows 两处(:1609/1717)。

接不上、且都写了实测理由的六格(不是「没做」,是「做了会改行为」):
- requireTaskId:本支 :1361 文案「任务 id 不合法」≠ 底座「taskId 不合法」,且它在取锁之前
- rejectTerminalSubmission:本支 :1384 只说「任务已结束」——同一 ERROR 形内部有两种文案,
  底座把文案写死了
- acquireSubmissionLockOrThrow:本支 :2249 抛不带 TASK_BUSY code 的那句,而 :1577 用
  message.contains("任务正被占用,请稍后重试") 当收尾跳过的判据 ⇒ 换件=改锁竞争语义
- writeJson:本支建单走 hutool JSONUtil,压根没有 Jackson 序列化失败那一格
- publishResultFile:形状同但本支 :1916-1924 写的是可空 Integer rowCount(缓存 DTO),
  底座件收 int ⇒ 套上去要么 NPE 要么把 NULL 洗成 0
- taskCacheService():DeleteBrandTaskCacheService 不继承 AbstractModuleTaskCacheService
  (第二例,第一例是 AP 的兄弟抽象)⇒ 心跳那格没有承接件,admitSubmission 整段用不上
另有 :1770 那处 enqueueAssembleResult 因吃掉返回值(按 job.status/retryCount 判组装已终态
失败)也没换。底座 javadoc 的四处出处账按上述实测更正,并把 :1265 那枚会腐烂的行号指针
改成方法名指针。

拆薄同笔抵账(readability 点名基线只许降):删两枚零调用私有件 countCompletedFiles/
inNewTransaction,接走建单 12 行与结果行各 5-7 行;棘轮读数 2305→2300。本支手抄的
「!MODULE_TYPE.equals(」由 8 处降到 7 处(TaskLifecycleDebt 那格方向对)。基线一格未改。

接线:TaskServiceWiringSliceTest 加第五支(3 枚新 @Bean 桩+逐枚 assertSame 本支 9 枚私有件
+「五枚底座字段不许在本支重复声明」那条 NoSuchFieldException 断言+DELETE_BRAND 那对
moduleType 验证);顺手把这篇测试自己两处会撒谎的计数(两支/三支)改成实数。

门禁:后端全量 mvn -o test 4523 例/0 红/0 错/13 skipped,BUILD SUCCESS;两条 deletebrand
golden(run-snapshot+昨日新落 submit-result-snapshot)跑完 git status 一字未动 ⇒ 建单/解析/
载荷/回传四段对外行为零变化;定向 79 例全绿;ops 面 ruff All checks passed、readability 9 passed。
⚠ 真机启动验收(mvn -o spring-boot:run)仍未做,五支都欠着,账在 Phase 8。
2026-10-19 13:33:19 +08:00
huangzd1997 695f570d59 refactor(phase-3): ShopDataCrawl 接入底座,家族层按证据不接——三支接得上、两处接不上写死
七支巨石里第三支接进 AbstractFileTaskPipeline。它接的是**底座**、不是 shop-payload 家族层:
家族模板 submitShopScopedResults 要求「按店名自建索引→逐行→changed 闸门→重算」,本支三条都不成立
(索引自建且带「回传店铺与任务不匹配」这道拒、单店合同 resultRows.size()!=1、尾部无 changed 闸门
而是无条件 persistProgressOrSnapshot+tryFinalizeTask)。照家族层套就是替它改行为。

本支复用底座的六件:newTaskHeader/newScopeRow(带显式时刻那一版——建单时刻一枚复用给头行与每一行,
默认时区逐行各取那一版会把这格改掉)、insertTask、listScopeRows(本地 listTaskRows 与孪生两支逐字同形,删)、
requireUserId(本地 validateUserId 逐字同形,删)、requireTaskId、writeJson(第四份同名件并进来,
捕获账净减:RETHROW 386→385 按该尺自述的「逐条点名改基线」处置,出处与授权逐字写进
CatchSilenceRatchetTest 注释;total 1002、不重抛/只 log/空体三格未涨)。

两处「按证据不做」写进代码而不是只留在注释里:
1)准入步序现网先归属后终态,与底座默认序相反 ⇒ 为它把 admitSubmission 拆成
   requireSubmissionTask/rejectTerminalSubmission/touchSubmissionHeartbeat 三格、按本支的序复用;
   孪生两支走的默认序一个字没动,它们的 golden 就是这条等值的证明。
2)收尾刷结果列走 LambdaUpdateWrapper 批量条件更新(只刷 success=1 的行、不写 success/errorMessage、
   objectKey 传 null)⇒ publishResultFile 仍不适用,本地写法保留。

代价要说在白处:显式构造器是继承的结构性成本,本支 23 枚参数(孪生两支 17/15),
ShopDataCrawlTaskService 3196→3215 行——这一格在 readability 棘轮上是**涨**,
与 Phase 3「只许降」那条准出标准相冲,不自行改基线判据、留给用户拍板。

对撞证据:本支两条新 golden(建单 14 例/回传 20 例)+孪生两支四条 golden 迁移前后逐字节相等,
git status -- src/test/resources 一字未动;后端全量 mvn -o test 绿。
2026-10-19 03:02:25 +08:00
huangzd1997 84f248fa6c fix(外观专利): 兜底归属校验接进 TaskFinalizeSupport 出口——手抄谓词棘轮回落 130
上一枚 commit 的 fallbackAssembleResultFile 手抄了 2 处
「!MODULE_TYPE.equals(x.getModuleType())」,把 TaskLifecycleDebtRatchetTest
钉死的 130 推到 131。按棘轮注释的指路接公共出口:
- TaskFinalizeSupport 新增 belongsToModule(expected, record) 静态出口
  (expected 为 null 判不归属,防御守卫静默失效);
- 兜底 2 处改走出口,净增 0,遍数回落 130;
- 出口语义 3 例钉在 TaskFinalizeSupportTest。
2026-10-19 00:15:08 +08:00
huangzd1997 1be4d766bb refactor(phase-3): 首迁 ShopMatch 接入管线底座,顺手补齐三件实测缺件
蓝图 §5 Phase 2 那条「两支公共件目前零生产调用方、契约可用只由单测证明」在本笔解除:
ShopMatchTaskService 现在真的继承 AbstractShopPayloadTaskPipeline,submitResult 的
「准入→取锁→按店名建索引→逐行合并→changed 闸门→重算状态」整段改为骨架调用,
本支只留 applyShopResultRow 与 onShopRowsRecomputed 两个钩子——判序(先合并再判 error)
留在被迁支里,家族层 javadoc 点名「刻意不沉」的就是它,没动。

底座缺件三件,都是「换不上就是本类缺件」那条规则的实测产物:
① newTaskHeader/newScopeRow 各加一枚带显式时刻的重载。ShopMatch 建单用的是
   now()=LocalDateTime.now(Asia/Shanghai) 且同一枚时刻复用给每一行结果行,
   底座原来只有默认时区、逐行各取一次那一版——直接套上去就把建单时间整体挪了,
   而这条快照量不出来(时钟刻意不进快照)。PriceTrack 那一派仍用五参/六参默认版。
② writeJson:Phase 2 登记「随 Phase 3 首迁同笔落」的那件,这笔落了。
   捕获账因此是净减(整树 total 1003→1002、RETHROW 387→386 正落在下限上、decoy 0),
   没有放宽任何一格;task 模块内部那三份逐字同名件仍未归并——归并会跌破 RETHROW 下限,
   那是「调整门禁判据」动作,与 Phase 0 三格守卫同批做,不在迁移笔里顺手干。
③ onPayloadIndexed(默认空实现):底座刻意不打日志,而 PriceTrack:617 有一句
   「received payloadShopCount/payloadKeys」卡在准入之后、行循环之前、每次回传恰好一次。
   没有这一格,那句要么丢、要么得挪位置——挪位置就是改现网可观测行为。

迁移登记的三处步序微差(可见结果相同,逐条对过 golden):shops 非空检查从锁内移到锁外、
锁内那次重复的 taskId 检查改由准入序列承担、旧 :670 那枚没人用的 workRoot 死局部变量摘掉
(组装在 processResultFileJob 里各建各的,本层从未写过那个目录)。

证据:shopmatch 两条 golden(建单 5 例+回传流水 5 例)迁移后逐字节未动;
CatchSilence/TaskLifecycleDebt/TaskStatusVocabulary/ArchitectureBoundary(task→业务 0)
四把尺同批复跑全绿;ShopMatchTaskService 2027→2026 行(readability 只许降这条满足)。
2026-10-18 20:47:10 +08:00
huangzd1997 d58546d314 refactor(phase-2): 后端任务管线公共层下沉——三段沉实测逐字件,跑批段如实登记无可沉
新增 modules/task/service/pipeline 两支公共件(AbstractFileTaskPipeline 394 行/
AbstractShopPayloadTaskPipeline 149 行)+ 29 例单测(19+10,覆盖正常/边界/异常)。
签名逐条来自 2026-10-18 对七支现网代码的定点实贴,注释里带出处行号:
- 解析建单沉 task 头行与结果行的落库形状(七支公共列,出处逐一点名);
- 回传落库沉准入序列(校验→加载→模块校验→终态拒绝→归属→心跳),
  终态拒绝按 BusinessCodes 拆成 IDEMPOTENT(40901)/ERROR(无 code) 两格——这不是文案,是线协议;
- 出结果沉「上传对象存储→写 6 列→updateById」,六支同形,ShopDataCrawl 走批量条件更新
  (updateResultFileColumns:1880-1892,还会传 null objectKey)不在其列,已从名单点名撤出;
- 跑批段服务端无可沉(机制早已收在 TaskFileJobService/TaskResultFileJobWorker,
  ClientTaskPullSpi 只 3/7 支实现),故不立转发钩子=不造空壳;
- report 段不新造 SPI,复用既有 ResultFileJobHandler;缓存/心跳复用 AbstractModuleTaskCacheService。
七支巨石内部一行未动(Phase 2 硬边界)。

两处「没替现网做决定」:
1) writeJson(序列化失败即 BusinessException、不带 cause,Publish:2122/AP:213/CollectData:362 同形)
   本轮不沉——CatchSilenceRatchetTest 自述「新增捕获块要么别加,要么同批减一处同形状」,
   而 Phase 2 不许改七支 ⇒ 减不掉就只能不加,该件随 Phase 3 首迁同笔落(本文件零捕获块)。
2) successFileCount/failedFileCount 不由底座初始化:建单时五支写 0、Publish 写真实失败数、
   DeleteBrand 首次 insert 两列留 NULL(:146-157 → :268-278 才回填),底座一-default 0 就是偷换语义。

门禁:mvn -o test 4460 例/3 红,三红逐条取证均不归本笔(catch 棘轮 1004=另一路在飞
CollectDataService 新增的一处捕获块;CollectDataBrandBatchFilterTest 与
ShopDataCrawlTemplateLargeWorkbookTest 单独复跑皆绿,前者是顺序污染、后者是 93s 耗时断言被抢核)。
本笔单独跑 88 例全绿(新件 29+ArchitectureBoundaryTest 6+八套 Phase 0 快照),
src/test/resources 下 golden 一字未动=未迁移模块行为逐字节相等;task→业务 依赖仍为 0。
2026-10-18 16:45:47 +08:00
huangzd1997 b9e5aa4d30 feat(任务判死): 判死时把下游一并收口——写 biz_file_result 并 fail 未完 jobs
代收在飞件落地(原作者那一路已不在跑;本笔在我到场前就在工作树里,一字未改)。
StaleTaskRepairService 新增 markDeadDownstream,挂进三条判死路径(长期未被领取/定时到点未启动/
心跳超时),新增 FileResultMapper 与 TaskFileJobService 两枚依赖;TaskFileJobService 补
failUnfinishedJobs。同名测试各 +85/+39 行。

验证依据=四面闸门 ts=2026-10-18T09:49:23 overall=pass(后端 34 格全绿,含 mvn -o test 整量),
量的是这份未提交内容;落地提交后内容逐字不变。
2026-10-18 09:52:24 +08:00
huangzd1997 3c44f686da feat(任务判死): 心跳时钟改为从首次心跳起算——排队中的 RUNNING 任务不再被心跳超时线误杀
任务一被认领(页面 activate / 客户端兜底拉取)就记 RUNNING,而客户端要等执行器真开始跑
才发心跳(同店占用、线程池 5 格全忙、浏览器首屏)。这段排队时间里服务端一行心跳都没有、
updated_at 停在认领时刻,被 30/120 分钟心跳线杀掉的是排队而不是死任务
(现网 2026-10-17 查得近 7 天 COLLECT_DATA 9 条 62 分钟判死、SIMILAR_ASIN 2 条一行未产出)。

- 新增 TaskHeartbeatLivenessService:每条心跳无条件打点(Redis,24h TTL),
  读失败一律落 0=没有证据;新增 StaleTaskHeartbeatPolicy:收到过心跳才走心跳时钟,
  从未心跳=仍在排队,超过未启动宽限(默认 240 分钟,置 0 即回退旧行为)才判死。
- 接入 product-risk/跟价/店铺匹配/巡店删除/查 ASIN/提现六条委派判死线、采集 30 分钟线、
  generic 120 分钟线(该文件另一路会话正在改,只提交本笔 HEAD+本改动的切片)。
- 沉默棘轮按逐处记名抬 3 格(total 1002→1003、不重抛 559→561、只 log 172→173),
  两处新增 catch 均为 fail-open 且误差方向是「少杀一个任务」。

验证:backend 全量 4400 例 0 失败;CatchSilenceRatchetTest 9 例绿;
ops 判死签名尺子 6 例绿;ruff check . All checks passed。
2026-10-17 19:46:04 +08:00
huangzd1997 975e053d2c 在持锁补读数:heldMs 此前只在放手那一刻打,锁还压着多久读不到
第 3/4 步(拆锁、缩合批)要立论,必须知道"此刻这把锁已经压了多久",而 [task-lock-held] 只在
LockHandle.close() 打——正在持有的那一段是盲区(货源 40902×24h RUNNING 就是这么看不见的)。

- ActiveTaskLockRegistry:登记表跟着取锁/放锁动;单独标 renewalLost——续期连续失败的锁最迟在
  TTL 后就该被另一实例拿走,本节点却还在按"仍持锁"跑,挂着多久不等于还被保护。
- 看门狗 task-lock-watch 每 60 秒扫一轮,留痕走阶梯(首个 60 秒、之后每 5 分钟),
  一次 30 分钟持锁总共 6 行而不是 30 行——与 10-06 通知放大同一口径。
- 15 例(9 节奏 + 6 接线),变异自证 M1 丢 unregister/M2 阶梯归零/M3 丢 register 三轮全 KILLED;
  后端全量 4320/0 红/跳过 7。
2026-10-14 01:06:38 +08:00
huangzd1997 1e3bcc9688 回传洪水收口(货源+外观): 「任务不是运行中」4 处出口归一进 TaskResultAdmission——真终态(SUCCESS/FAILED)带 40901,异常处理器按幂等成功回 success=true,客户端据此删本地副本停止补发;PENDING 不带码保持可重试(建单就写它,判死=丢还能送到的结果)
判据=两条链 setStatus 实测只有 PENDING/RUNNING/SUCCESS/FAILED,故取 FINISHED_ORDERED 不取 TERMINAL(取消态无证据);摘两支重复 helper 与因此空转的 1 处 BusinessCodes import;TaskDistributedLockService 补 [task-lock-held] 持锁时长留痕(>=5s info/>=60s warn),此前只有 WAIT_LLM 量得出时长
验证=后端全量 4291 passed 0 failed(skipped 7, 6.0min);正反各两支新用例钉死;变异 M1 摘码/M2 全状态带码各杀 2 红、还原字节一致;M3 换成 TERMINAL 无人判红=已知盲区(写进类注释);可读性棘轮 9 格绿(PipelineSupport 缩回 1975 行/基线 1978)
2026-10-12 01:22:43 +08:00
huangzd1997 c4d2349cda 清无用 import(卖源码): 后端 248 处跨 128 支文件全部摘掉,javac+全量实跑双重判定
判据是逐支把 import 行的简单名拿去文件其余部分(含注释与 javadoc)做词边界匹配,
名字只在注释里出现的当作「在用」保留,所以这把尺子是往保守侧偏的。
验收不靠静态回声:`mvn -o -q test-compile` rc=0,再 `mvn -o clean package`
= Tests run 4264, Failures 0, Errors 0, Skipped 7,与清之前逐项一致(4,313→4,264 那 49 例是上午清设计文档摘掉的读 docs 用例,不是这一笔)。
diff 形状只认 `+0 / -248`,行尾没被整片改写。
2026-10-11 17:04:28 +08:00
huangzd1997 a3eddd6d84 对平(进度三字段进白名单 + 去掉那处新增吞异常): Java 全量 4313 例 0 红
上一笔 light 加 progress* 后我只跑了 6 个定向类,把两把钉白名单的尺子漏了——
它们本来就是为「加字段必须显式承认」而设的,该红:
- SimilarAsinTaskLightWhitelistTest(私有 LightVo 键集合,两处断言)
- ResultFilePhaseContractTest(light 响应 JSON 键集快照)

CatchSilenceRatchetTest 报「不重抛 559→560」也是我引入的:parseIntOrNull 用了
catch (NumberFormatException)。这处边界防护要留(Redis 里是客户端上报的裸字符串,
一次抛出就整页任务失去进度显示),但不必用 catch 实现——先按字符判掉非数字、再限 9 位
防 int 溢出,Integer.valueOf 就不可能抛。这样既守住棘轮也不动别人的 catch。
补一条用例把「负号/超长/非数字」三个分支钉住(否则改了没人验)。

教训写在这儿:改公共 DTO/VO 之后不许只跑定向,全量才是验收。
2026-10-11 00:02:22 +08:00
huangzd1997 96d4e40a77 看板(心跳位置补进度): 跟价/定时匹配这类无快照的行不再恒画「—」
客户端心跳位置此前只喂 progress/light(客户端进度条),后台任务中心的进度列仍按 10-04 那条
「没分母就画 —」走,于是同一个在跑的跟价任务,客户端有条、看板是「—」。

- TaskCenterQueryService 注入位置服务:只对「无快照 + 不是行内已计数的三个模块 + 非终态」的行
  批量读位置;这个判据抽成 wantsHeartbeatPosition 一处共用——收集与填充各写一遍的话,
  改一处就会让另一处静默拿到 null,又退成「安静地没有条」
- 封顶与页大小同源(BOARD_POSITION_LOOKUPS=100):沿用 light 那个 20 的话,第 21 行之后的
  在跑任务永远读不到进度
- 心跳新增 progressGrain 一并入库;看板按它把 units 的「国家数×1000 摊平当量」折算回自然计数,
  否则管理员会读到「已完成 1222 / 总 5000」。客户端那条仍吃原始千分位(要的是平滑),
  所以折算做成 Position#displayUnits() 显式一步,不是一处改两边
- 快照优先不变:位置只是执行器自述,服务端算出来的快照更权威
- 用例:displayUnits 折算/钳位/分母不塌 0、grain 存取、老客户端不报粒度按自然计数原样通过;
  看板三例(在跑行用心跳、终态一次都不读、有快照不许被覆盖)。TaskCenterQueryServiceTest 37 例绿
2026-10-10 23:40:50 +08:00
huangzd1997 deb3d7e161 进度(light透传): 把心跳已存的 current/total 交给前端,为客户端任务进度条打通服务端一段
客户端心跳一直在发 current/total,Java 也已存进 Redis 位置 Hash,但除判死豁免外没人读它,
所以客户端界面上解决风控/跟价这些任务画不出进度条。本次只在 light 出口上透传,不新建表、不写迁移。

- TaskProgressLightVo + progressCurrent/progressTotal/progressLabel(三个同生同灭)
- 装配器只对非终态任务读位置;读不到或分母非正数一律留 null,由前端决定不画(0/0 会被读成"进度 0%",与"没有进度"是两件事)
- 位置服务加 readDrawablePositions:单次轮询封顶 20 次 Redis 往返,按尝试次数计(老客户端一个都不发时命中数为 0 但往返数仍是全量)
- 标签按「,」整段截到 60 字,定长硬切会截出半截店铺名
- 相似ASIN 那份私有 LightVo 同步(它是历史遗留的第二套实现,不同步会让该模块进度随轮询闪烁)
- 顺带修该私有实现的投影缺陷:select 少 module_type 一列,真实查询下所有任务被判 missing,
  与共享装配器 2026-09-14 那次线上事故同形态(那边有守卫测试、这份没有),现补守卫
2026-10-10 20:04:52 +08:00
huangzd1997 15094309cf 后端(四面9分批次): 锁跳过留痕、状态词表收成单点、版本硬地板进 yml 并记账
- 14 处「拿不到锁就 continue」过去零日志,现统一带可聚合锚点并有留痕判据
  (LockSkipWitnessTest 7 例 + LockSkipSilentExitGuardrailTest 4 例)。
- 任务状态词表:散落内联集合改由单一定义点判方向(TaskStatusVocabularyRatchetTest 7 例),
  CANCELED/CANCELLED 只做归一映射,没改库值也没改对外契约。
- 版本硬地板三键(min-supported / enforce / rejectUnreported)此前在任何 yml 里 0 处=出厂即惰性;
  现在入册且 enforce=false 走记账模式(ClientVersionFloorConfigTest 9 例),真挡谁留给用户拍。
- 业务码→HTTP 状态只做映射单点 + 开关(默认关,开启前逐字节等价,BusinessErrorHttpStatusTest 8 例);
  直接翻面会让三个前端把业务失败读成网络挂了。
- 验收:mvn -o test 这 5 个类 35 例 0 红(用 python subprocess 起 mvn——bash 里 cmd 包一层
  开的是交互式 cmd,rc 是 cmd 的,会给出假的 rc=0)。
2026-10-09 23:09:37 +08:00
huangzd1997 2a4d15b801 fix(文案出口): 用户可见提示语一律走 UserMessages 把关,并补结果作业租约围栏
两件事同源:2026-10-09 任务 30456 的卡片上同时出现中文进度和一句英文异常原文。

围栏:派发链在执行前重读 job 行,让 activateRunningClaim 的 CAS 恒真,撞锁方
deferRunning 把在跑的行翻回 PENDING,markSuccess 静默写 0 行——成功被判成失败。
claim 快照现在贯穿到 runClaimed 不再回读,markSuccess 返回布尔并补 stage=SUCCESS_LOST
日志,让这次丢失可观测。

文案:普查数出 61 处把 ex.getMessage() 拼进用户可见字段(异常响应、任务 error_message、
结果作业 error_msg、看板 message),逐条翻译追不上新增速度,改为出口把关——
UserMessages.with(中文主干, 异常) 只拼接中文详情、orFallback(原文, 兜底句) 只放行含中文的串,
被换掉的原文进日志;GlobalExceptionHandler 按码分档兜底(401/4011/40902 各说各的话)。
另把 chunk-read-failed[N] 摘要写成"第 N 分片读取失败"、TASK_LOCK_BUSY 换成中文(40902 码不动,
客户端按码分支)。数字人两处与结果作业 worker 故意仍存原文:孤儿判定与三条 preserves raw
用例按 error_message 读它,界面侧由前端 userNotice 兜住,已在新尺子里点名豁免并反查豁免是否还被用到。

尺子:RawExceptionMessageSinkGuardTest(出口行数下限硬钉 1500+内存造违例自证)、UserMessagesTest、
UserFacingMessageChineseGuardTest 豁免表收到只剩 JSON 键 msg 一条。mvn -o test 4205 例 0 失败。
2026-10-09 19:34:25 +08:00
huangzd1997 b4b2fe2aa5 feat(MQ降级): 补可巡检的计数出口——task.file.job.mq.degraded 指标 + 8 例纯单元
§2 那行「保留回落本地 worker 的语义,但必须产出可巡检的计数出口,不许只有日志」的后半句
从没落地:三条降级出口全是 log.warn + return false,通知表与看板都不感知。

- MeterRegistry 走 ObjectProvider,取不到就按 null 兜住(与 ClientVersionGuardFilter 同口径),
  降级判定与 return false 语义一字未动 ⇒ 现网零行为变更;不新增 catch(CatchSilenceRatchet
  钉着四数,加一个 catch 就判红)
- reason 两支:template-missing(模板取不到)、send-failed(熔断打开 / 发送失败各计一次)
- 8 例含一条反向钉"正常发送时该指标 0 次 increment",防"无脑 increment"蒙绿;
  变异自证:摘掉 template-missing 那处 increment ⇒ 2 例红(expected 1.0),还原后字节哈希相等并复跑绿
2026-10-09 13:12:51 +08:00
huangzd1997 305441b0bd feat(护栏): catch 静默形状做进代码出口 + 待处理行缓冲不再谎报"已暂存"
整棵 src/main 有 1002 个 catch 块,其中 559 个不重抛、172 个块内只有 log、55 个空体——
约三成是"记一条日志就往下走"。这没法一次清扫,先把形状钉成只许减的棘轮:扫描器自己数分母,
并与一把独立口径(原始文件里 "catch (" 出现次数)逐文件对平,两者不等就红——词法若把真代码
当字符串吃掉,total 会变小而"≤ 基线"照样绿,这一步就是防那个。

两处按三类高危出口点名改成重抛:待处理行入缓冲失败原先静默返回,等于向调用方谎报"已暂存",
装配阶段少这一行却照样把任务标成 SUCCESS;取 pending 行数失败原先返回 0,而 0 在调用方眼里
是"缓冲区空了",真实含义是"Redis 没答话"。

RETHROW 那一格刻意钉成下限(388)而非上限:把吞异常改成重抛会让这一格上涨,钉成"只许减"
就等于拦住别人做正确的事。
2026-10-08 17:36:22 +08:00
huangzd1997 419ab3be64 refactor(SQL分层): 剩余 85 条注解 SQL 全量迁进 mapper XML,等价性改由 MyBatis 自己判
96 条语句现在全在 src/main/resources/mapper/<模块>/ 下,注解侧 SQL 归零;判据从"基线清单"
改成完成态(逐接口必须为 0 + XML 语句总数 96 + 反向钉:XML 有则注解必须无)。

搬法上踩实了一个坑:注解参数是 Java 表达式("…" + CLIENT_MODULE_TYPES + "…"),
用只认字面量的抽取器搬家会把常量整段吞掉——上一轮生成的 26 份 XML 里因此出现
IN ()、AS status 前面没有表达式(MySQL 语法错),<script> 形态还被多转义一次变成 &amp;lt;。
更糟的是当时"搬迁前快照"与 XML 由同一个抽取器产出,两边一起错所以逐字比对全绿,
抓到现场的是既有的语义用例(TaskCenter 15 条 + 店铺查重那条断 <> 的)。

所以 MigratedSqlEquivalenceTest 改成:账本存注解原文,Java 侧现场用
getDefaultScriptingLanguageInstance().createSqlSource 编译原文,与 XML 解析出的
MappedStatement 各渲染一遍 BoundSql 对撞(空参数 + foreach 喂满 2 元素各一次),
转义对不对由 MyBatis 判定而不是由生成器判定;账本自己再钉 <script>/<if> 成对、不许出现 IN ()。
resultType 那一支不变:期望值由接口签名反射反推,66 条分母钉住。

取数入口跟着换:6 支原本读 @Select 注解的守卫(TaskCenter/Dedupe/店铺查重/通知保留/
鉴权形状/后台扩权)改走 MapperXmlSupport,断言内容一字未动;后台扩权那条"不许有 wrapper
投影"从全文 doesNotContain(".select(") 改成只扫可执行行——接口里现在只剩签名,
而 javadoc 正写着"别用 selectList(.select(...))",全文判会被自己的注释喂饱。

隔离树全量 4059 例 0 红(基线 4054,+5 为新增等价性与 XML 用例)。这批要生效得随下一版 jar 发版。
2026-10-08 12:00:43 +08:00
huangzd1997 3ed8a4265d refactor(SQL分层): TaskImageCacheMapper 9 条注解 SQL 迁进 mapper XML,读侧判据改逐接口钉
档 B 口径:自定义语句一律进 XML,"特别简单"只剩 BaseMapper 自带 CRUD 与单表主键/唯一键点查。

判据这次不只是改数字。读侧原来钉的是「总数 65 + 文件数 16」两个标量,那么 A 接口加一条、
B 接口减一条就能让两个标量双双不动而绕过闸门,等于档 B 下没有闸门。改成逐接口清单
SELECT_SQL_BASELINE,并加 thePerFileLedgerCatchesWhatTheScalarsCouldNot 自证:在内存里造出
那次搬家,先断言总数与文件数确实都不变(证明旧钉法失明),再断言逐接口清单必须不等。

复用片段抽在真重复处:WHERE url_hash IN <foreach> 被三条语句共用,抽成 byUrlHashIn。
没抽列清单是刻意的——这个表每条语句只取必要列,image_bytes 是 BLOB,整行回读会把省内存
的缓存变成内存负担。所以新守卫 TaskImageCacheMapperXmlTest 钉的第一条就是"只有两条直读
字节的语句能碰 image_bytes"(迁 SQL 最顺手写成 SELECT *,而它在没有库的单测里不会自然变红),
其余钉 &lt; 是否还原成 <、LIMIT ? 是否仍是绑定参数、NOW(3) 毫秒精度、byte[] 的 resultType
必须写 "[B"(别名表里没有它)。

基线同步递减:写侧 29→25、读侧 65→60,MIGRATED_TO_XML 加 TaskImageCacheMapper。
定向 47 例绿(判据 9 + 新守卫 7 + asincache 样板 6 + 两个消费方 service 25)。
既有接口是 CRLF,改动走二进制删行,没把整份文件翻成 LF。
2026-10-08 10:29:36 +08:00
huangzd1997 c1e7d57cce fix(鉴权): 请求身份全量改走会话出口;公开默认 JWT 密钥从出厂件里摘掉
三件事都属"失败很安静"那一类:

1) 请求自带 user_id 当范围条件。cp-item2 只收了会改状态/花钱的出口,其余 28 支控制器
   (进度/列表/详情,本支 18 支、另 10 支因与租户判定收口同文件而随 cp-item3 那笔)照旧把
   "这单是谁的"交给调用方自报:A 传 B 的 user_id 就读到 B 的进度,
   接口 200、日志无声。现在 190 支取请求身份的 handler 只经一个出口(写类 require/resolve、
   读类 resolve),护栏 RequestSuppliedIdentityOutletTest 钉分母 126 写 + 63 读 + 1 豁免
   (内部代理通道 InternalUserProxyController Get /user-proxy 按内部令牌放行)。DTO 形态
   (控制器把整个 @RequestBody 递给 service)靠"该 DTO 是否声明 userId 字段"的索引识别,
   少了这层判据会漏掉一半;进度类 28 支另由 ProgressQueryOwnershipOutletTest 单独钉。
   桌面执行器 4.0.44 不带凭据是既定事实,[ownership-anonymous] 按 URI 计数留证据,
   哪一支的匿名计数归零才允许把它从 resolve 换成 require。
2) 默认 JWT 密钥。application.yml 原本写的是
   `${AIIMAGE_JWT_SECRET:please-change-this-secret-…}`,那个兜底默认值就是 2026-10-07
   现网取证到的东西:两台都跑 profile server 且 env 里没有这个键,于是 JwtService 的启动闸门
   看到的是公开字面量(非空)——既不拒绝启动也不告警,签出来的 token 任何读过源码的人都能伪造
   (含超管)。现在占位符不带默认值、AuthProperties 缺省空串、isInsecure 同时认空串与该字面量,
   server profile 缺密钥直接拒绝启动(宁可起不来)。JwtSecretFallbackGuardrailTest 五例钉
   "资源文件里不许再出现那个字面量"与"两形都算不安全"。
   发版顺序是硬约束:先在 A/B 两台 .env 配好与对方一致的 AIIMAGE_JWT_SECRET,再上新 jar;
   轮换会把所有 web 会话退出登录。
3) 菜单写侧的无操作者重载(create/update/delete)删掉——三道闸门对 operator==null 的处置是
   return(放行),src/main 里没人调用它们,但这条路在,下一支控制器接上去就是静默的跨公司改删。
   读侧 list(String menuType) 是登录态自读与内部代理用的,故意保留,并被点名只许 1 处。

TaskProgressOwnershipSupport / SimilarAsinTaskLightControllerTest / ResultSuccessTimingContractTest
是 handler 加上 HttpServletRequest 之后的既有契约用例订正;SourceScan 补 withoutComments/methodBody
两支取文助手(源码守卫的匹配面必须剥注释,否则 javadoc 里提一句就能把"必须存在"那形喂绿)。

变异自证:RequestSuppliedIdentityOutletTest 4/4(M1 删参数形出口、M2 删 DTO 形出口、
M3 出口只写进注释、M4 isBound 恒真);JwtSecretFallbackGuardrailTest 4/4(J1 恢复 yml 默认值、
J2 恢复 AuthProperties 默认值、J3 闸门退回只判 isBlank、J4 isInsecure 恒真);
MenuWriteOutletOperatorTest 4/4。
2026-10-07 20:01:32 +08:00
huangzd1997 0e6e844929 fix(角色叫法): 管理员就叫管理员、normal 档统一「普通账号」
同一角色此前有两套叫法:admin 档在界面叫「管理员」、在后端 6 条 403 与 Swagger 说明里叫
「普通管理员」;normal 档在界面叫「普通用户」。清到第四轮才清净,所以把口径做进源码出口:
新增 task-048 的旧词扫描用例,两棵源码树(admin-frontend-vue/src 216 文件、
backend-java/src 1415 java 文件)里出现「普通管理员」「普通用户」即红,分母与出口文件成员
一起钉死,防"扫了个空集合"式假绿。

- 后端 6 条用户可见文案:PermissionMenuService 两判、ShopManageGroupService 一判、
  ShopManageController 三条 @Operation 说明
- company_menu_grant_gate_mutation.py 的 DENIED_THROW 锚同步改,16 条锚命中数逐条复算=1
- 注释与 javadoc 同批收口(等长替换不动排版);NotificationControllerTest 那句讲的是
  非后台账号,按本意改写而不是套「普通账号」
2026-10-05 23:15:57 +08:00
huangzd1997 95e2318c42 feat(账号到期+公司超管): 级联过期判定、过期停任务巡检与两端续费提醒弹窗
需求两条:站点超管可开设其他公司的超级管理员(站点超管看全站、公司超管只看本公司、
组内管理员仍只看本组);账号要有过期时间,管理员过期后名下普通账户一并停用、
正在跑的任务也要停掉。落库只有 users.expires_at(V146,NULL=永不过期),级联一律现算,
不写"上级过期就把下级置成过期"那种续费也救不回来的数据。

- AccountExpiryService:生效到期 = min(自身, 本公司公司超管, 成员表组长, 创建人)。
  登录拦 403(文案给续费提示)、每次请求鉴权拦 401(前端按下线踢回登录页),super_admin
  永不适用。级联口径与数据可见范围同源(成员表基本未用、实际按 created_by_id 派生)。
- ExpiredAccountTaskStopService:每分钟把过期账号(含级联成员)名下 biz_file_task
  PENDING/SCHEDULED/RUNNING → FAILED,含未领取的 PENDING(防内部通道继续派发)。原因文案
  刻意不以「客户端异常中断」开头,否则会被 TaskResumeService 自动复活。品牌采集与跟价循环
  不在那张表上,经 ExpiredAccountTaskStopSpi 由各自模块停:品牌 pending/running→cancelled
  且 UPDATE 的 WHERE 二次核对状态(抢到行后被客户端推进成完成的行不得误杀),跟价循环只置
  stop_requested=1、沿用用户点「停止循环」那条收尾路径,绝不动 status。任务心跳接口保持匿名
  不走 requireUser,所以过期账号的客户端仍能拿到 alive=false 协作停止。
- 角色 company_super_admin:由站点超管开设(唯一要显式选公司的建号场景),建号/授菜单/改用户/
  看数据四条链路都按"本公司"收口;公司超管之间、以及公司超管与站点超管互相碰不得。
- 续费提醒:剩余 <5 天在数富后台与用户端弹窗,只能收起不能关闭(无关闭按钮,收起态是右下角
  浮标),续费到 ≥5 天自动消失。后台读 /api/admin/current-user 的 expiresAt/daysToExpire;
  用户端无 Pinia,走 localStorage 的 account_expires_at(登录/check_login 落键、被顶下线清键,
  换账号不残留)。只反映账号自身到期,弹窗不做任何级联推断。
- V146 撞掉了 V145 那批的一条护栏:它按"db/ 里不许出现 V146__ 前缀"编死号位,被一条正常的
  前向迁移占用就红。改成钉动作——剥注释后的可执行 SQL 不得写 flyway_schema_history(回滚
  一律是扫描路径外的人工补丁),并把盘点文档改 V146 时丢掉的 V145 文件名补回去。

验证(本会话亲跑,不是转述):后端定向 14 类 123/0(同一轮 mvn 里连批次③的 4 类 53 例、以及既有 ShopDataCrawl/SimilarAsin 两条回归对照 21 例一起跑,合计 197 例 0 红);admin-frontend-vue 本批定向 44/0(弹窗 7 +
公司建号/列表/入口/日期默认 21 + 角色 task-48/task-251 16),全量 1726 例里那 1 支红是另一条
会话刻意留的「公司 tab 接线缺口」尺子(点名 admin_task_center 等 6 页,与本批无关);
frontend-vue 弹窗 9/0、全量 710/0。变异自证两批共 34 点:弹窗语义 16 点全杀(阈值 5、只能收起
不能关闭、挂载点含"注释掉挂载"、落键/清键链路),本批 SPI+迁移护栏 17 点全杀(含 G2 反向:
前向迁移只在注释里提 flyway_schema_history 必须照样绿),注入文件还原 dirty=0、探针残留 0。
2026-10-05 11:51:33 +08:00
huangzd1997 37592a3b62 perf(代码审查落地): 后端 A1-A8 与前端 C1-C8 加固,retention 清理补索引(V141)
A 组(backend-java):
- A1 载荷引用计数不再无条件回落全表 COUNT
- A2 结果行读取由 LIMIT 1 改整页
- A3 ziniao 索引缓存过期判断下推 SQL
- A4 循环子任务认领改 CAS,失败一律抛
- A5 建单事务里不碰外部 IO
- A6 连接池补网络层超时(connectTimeout/socketTimeout,env 可覆盖)
- A7 日志留现场 + 异步落盘
- A8 其余:货源图片预取、结果工作簿装配等
- V141:三条 retention DELETE 的可用索引,其中 biz_price_track_loop_run
  用 STORED 生成列承载 COALESCE 时间线(该表实测 881 行/17MB,COPY 秒级)

C 组(frontend-vue):URL 取值走 safe-url、行号取值走 row-id、
交付视频任务状态抽成 delivery-video-task-state.ts,各补用例。
2026-10-03 12:24:16 +08:00
huangzd1997 fa4bd57016 refactor: 第二批收敛——公共 Excel 写出器 + 任务收尾零件下沉 + 前端上传区/任务面板抽取 2026-10-01 15:00:52 +08:00
huangzd1997 4b29a150f3 refactor: 第一批低风险收敛——任务缓存服务泛型化 + 前端死代码清理与状态映射统一 2026-10-01 14:05:30 +08:00
huangzd1997 f4be12c5f9 外观专利转 Linux 后台主力执行:activate 不再推送客户端浏览器
- activateTask 改为状态校验:PENDING 保持等 Linux 内部认领,旧前端点启动给出明确提示并中止入队,任务不会重复执行
- 内部认领新增独立等待窗口 internal-min-pending-minutes(默认2分钟),任务创建后快速自动开始
- 客户端兜底拉取默认白名单移除 APPEARANCE_PATENT,防止未来误开时客户端抢抓
- 前端「启动」按钮改「提交后台执行」:不再 enqueue_json 推客户端队列,直接进入轮询
2026-09-30 13:41:26 +08:00
huangzd1997 27a7cd0f82 fix(任务兜底拉取): 认领转交 owner_instance_id 且归属校验改读列 —— 认领在 server-121 而任务 parse 落 server-110 时, 组装载荷被归属校验拒绝并误标失败; resultJson 里的 ownerInstanceId 只是 parse 快照, 转交后不同步 2026-09-30 12:14:54 +08:00
huangzd1997 279c1641ea fix(任务兜底拉取): 候选 cutoff 显式用北京时间 —— 容器默认 UTC, LocalDateTime.now() 与 DB 北京时间字面值比较错位 8 小时, 候选查询恒空(内部认领上线实测踩中) 2026-09-30 11:40:00 +08:00
huangzd1997 c0492f7c86 feat(任务兜底拉取): 新增服务端内部认领端点 /api/internal/tasks/pull-pending —— Linux 后台 worker 专用(X-Internal-Token), 不限用户认领长期 PENDING 任务, 独立开关 internal-enabled 与客户端兜底解耦; 外观专利详情页抓取迁 Linux 前置 2026-09-30 11:00:34 +08:00
huangzd1997 fa59de52fb feat(taskcenter): 13 个客户端任务创建入口记录 JWT 设备号
设备号只认 JWT 签名 claim(不接受客户端可控请求头),controller 读取、service
归一化落库;续跑任务由服务端发起,继承原任务设备号。品牌检测走独立
brand_crawl_tasks 表,同一口径。
2026-09-28 22:33:53 +08:00
huangzd1997 575b7f9f8c fix(可观测): 让"续跑/兜底拉取没开"在日志里可辨识,并纠正与 yml 相反的默认值
V129 客户端中断自动续跑从上线至今一次都没执行过:aiimage.task-resume.enabled
继承 aiimage.client-task-pull.enabled,两台生产两个键都没设 → false →
resumeInterruptedTasks() 第一行 return。7 天 12 个「客户端异常中断」任务、
48 轮巡检 resume(s=0 r=0 k=0 u=0)、pull-pending 1 小时 4443 次空返回,
在日志上与"恰好没有中断任务"完全同形。

不改开关(属产品语义:兜底拉取会把用户只解析没点启动的 PENDING 真跑,
而外观专利占 LLM 花费 95% 且扣用户自付次数),已写进决策文档 §十三 交人工决定。
本版只做三件事:
- ResumeStats.ran:真查过库才算跑过;巡检段位改 resume(ran= s= r= k= u=)
- TaskResumeService / TaskClientPullService 各加 @PostConstruct 生效配置启动行
- @Value 的 enabled 默认由 :true 改为继承 client-task-pull.enabled:false(与 yml 同语义)

测试:TaskResumeServiceTest +4、TaskClientPullServiceTest +1,全量 3271 通过 / 0 失败。
2026-09-28 16:52:33 +08:00
huangzd1997 7bb03466b0 fix(任务): 开机自回收改以本进程启动时刻为界,发版不再蚕食结果文件作业的重试次数
原判据是 now-max(60,staleSeconds),但 ApplicationReadyEvent 只在重启后几秒响一次,
那时遗留行的心跳也只停了几秒,条件结构上永不成立——线上"实例重启,作业已重新排队"累计 0 条。
遗骸改由 stuck 扫描按 +1 重试处理(今天 A 发了 7 版、重试预算只有 5),
20833 已被吃掉一次,20836/任务29475 就是被这条链判成"已达到最大重试次数"的。
2026-09-28 15:59:47 +08:00
huangzd1997 ac7412f77d fix(任务): 结果文件作业撞锁后不再自带下一次投递,消除零退避自循环
requeue() 在把行从 RUNNING 翻回 PENDING 的同一刻 publish 一条 dispatch 事件,
于是投递链立刻重新 claim 同一个 job、再撞同一把锁(持锁方是分钟级的 LLM 批次)。
线上实测 20 分钟 667 次、占该实例日志 8.7%,且每次要占满 taskQueueExecutor 的
10 秒探锁 —— 该池只有 12 个许可且与货源 LLM 重提、图像视频轮询共用,按 Little 定律
相当于长期吃掉近一半容量。

撞锁分支改用同语义但不发事件的 deferRunning(),重投节奏交回 runPendingJobs 的
10 秒周期;本地轮询关闭的 profile 没有周期兜底,继续走 requeue 以免作业搁死在 PENDING。
2026-09-28 15:20:59 +08:00
huangzd1997 3a416f3935 fix(任务): 卡死自愈扫描不再被一行的锁等待作废整轮
线上 12:58–13:13 每 110 秒一次 1205:扫描按 updated_at 升序取到的第一行正被另一台
持着行锁,一抛就把本轮已复位成功的 job 的 dispatch 事件一起带走(它们已是 PENDING
却没人派发),该判终态失败的作业也不 finalize。改成循环体逐行 try/catch、派发也逐个包,
只跳过这一行。刻意不加事务:每行本就带 status+updated_at 的幂等 CAS 条件。
2026-09-28 14:11:26 +08:00
huangzd1997 a58dc8a680 fix(断点续传): 外观/结果作业/去重三处中断语义补齐,重启不再静默丢行
- 外观专利行标改两态(in-flight 15min / processed 24h):只有 CAS 写回 payload 成功
  才转「已处理」,异常、覆盖率不足、CAS 打满等未落库出口一律撤销标记 —— 修「发 LLM
  请求前就盖章,进程被杀的那一批永不再补检」
- 结果文件作业开机自回收:按 owner_instance_id 只收本机名下 RUNNING 且心跳超 90s 的行;
  卡死阈值 30 → 5 分钟,重启接回从最长半小时压到 5 分钟
- 外观结果表缺检行显式写「未取得检测结果」并判失败,不再留空靠 0.5 覆盖率阈值蒙过
- 去重进度改 NodeSharedStore 跨节点共享,runId 用已落库的 task_no:轮询打到另一节点或
  发版重启后仍能读到真实进度、已完成文件仍可下载;共享态缺失时按 task_no 从库重建;
  逐文件心跳防 StaleTaskRepair 把长任务误判死;开机把本机残留 RUNNING 判失败并给提示
2026-09-27 22:26:09 +08:00
huangzd1997 afa45d51c3 fix(长任务判死): 封口前增加「客户端仍在推进」豁免,避免还在采集就被结案丢数据
服务端二次判死线(心跳正常但 N 分钟无结果分片上报)只看分片间隔,客户端攒批回传一慢
就把仍在采集的任务判成卡死、封口结案,后续分片全被拒(生产 28919:1300 行只出 395 行,
丢 905 行)。改为封口前用 TaskHeartbeatPositionService 的位置快照判定客户端是否仍在推进:
ADVANCING(位置在变)→ 本轮不封口;STALLED(长时间不变)→ 按原判据;UNKNOWN(老客户端
无位置信息)→ 保留原行为。接入 similar-asin / appearance-patent / brand / delete-brand /
collect-data 五条判死线。
2026-09-23 10:54:59 +08:00
huangzd1997 e2e1d99bda fix(任务恢复): 停止意图优先于自动续跑 + 未覆盖模块的中断可见
自查上一提交时发现两处遗漏:

- 用户点了「停止循环」而子任务恰好因客户端中断失败时,续派逻辑跑在停止检查之前,
  会把循环从停止意图里拉回 RUNNING 自己转起来。改为停止请求优先:直接 STOPPED。
- 模块不支持自动续跑的中断任务此前完全无痕迹(用户只看到失败)。
  这类模块(上架/改价/审批/商品管理采集/跟价非循环任务)的续跑载荷需要用户在页面上
  选的执行参数(ziniao_version 等),而这份选择只存在于派发那一刻的浏览器里、没落到
  request_json —— 自动重排队会用错参数,所以它们**不纳入**续跑(白名单的设计原则就是
  「执行参数全在服务端」)。现补一条计数查询把这类中断数量带进 stale-check summary
  的 resume(u=N),运维据此人工重跑;将来把参数回写落库后即可纳入白名单。

测试:PriceTrackLoopRunServiceTest 新增「已请求停止时中断失败不续派而是停止」,
TaskResumeServiceTest 新增「统计不支持续跑的中断任务数」。
2026-09-18 15:48:33 +08:00
huangzd1997 1b70eb0576 feat(任务恢复): 客户端中断的任务自动续跑(保留失败记录 + 重新排队)
2026-09-18 任务 28587(跟价,uid 977 店铺「张美莺」)在客户端 09:51/09:57 被更新脚本
重启后中断,任务一直挂 RUNNING 到 stale 兜底;跟价循环还有第二重问题——子任务失败
即整个循环判 FAILED,一次客户端更新就让无限循环彻底停下。

契约:中断任务**保留失败记录**(用户看得到「因客户端重启中断」),同时由服务端自动
重新排队续跑,长任务不再因为一次更新整个白跑。

- V129:biz_file_task 加 resume_of_task_id / resume_attempt,
  biz_price_track_loop_run 加 resume_attempt(代数封顶用);
- 新增 TaskResumeService:扫描最近 30 分钟内因客户端中断而失败、未续跑过、代数未超限的
  任务,复制请求参数重新排队成 PENDING,交给已有兜底拉取通道(客户端每分钟 pull-pending)
  领走执行——不新造第二套派发机制。只对注册了 ClientTaskPullSpi 的模块生效
  (相似ASIN/采集/外观专利),上架/改价等写操作模块刻意排除,避免盲目重跑;
- 幂等:按 resume_of_task_id 反查,同一原任务不会重复排队;
- 挂在 stale-check 巡检线(每 2 分钟、有分布式锁),并用隔离壳包住异常:
  续跑失败绝不拖垮判死主流程(判死优先级更高);
- PriceTrackLoopRunService:子任务因「客户端异常中断」失败时不终止循环,
  清 active_task_id 后保持 RUNNING,客户端下次 dispatchNext 拿到同一店铺/同一轮,
  即原地续跑(页内已处理 ASIN 由服务端 skip_asins 去重,不会重复改价);
  连续重派超过 3 次才真正判失败,避免会话持续不可用时无限重开浏览器
  (28587 就是这样白烧了 5 小时)。子任务成功一轮后计数归零;
- application.yml:aiimage.task-resume.enabled 默认跟随 client-task-pull 开关
  (兜底拉取关着时续跑任务无人领取,只会积压被告死)。

测试:TaskResumeServiceTest 6 例(排队/幂等/开关/无实现/插入失败/无归属用户)、
PriceTrackLoopRunServiceTest 新增 4 例(中断续跑/达上限/非中断仍终止/成功归零),
连带更新 DeleteBrandStaleTaskServiceTest 与 TaskModuleCoverageTest 的构造参数。
2026-09-18 15:42:07 +08:00
huangzd1997 c9be8f87d4 fix(临时载荷): 收口删除守卫 + chunk 读兜底,修「对象被误删→任务永久失败」
线上任务 28459(外观专利)三个分片的载荷对象被删、DB 行仍指向已删的确定性
key,组装读不到 → 整单 FAILED。数据其实还在同槽位的版本化对象里,是行指错了。

三条收口:
- 上传补偿删除加准入:只有末段带 UUID 的版本化 key(本次写入独占)才允许入队。
  确定性 key 会被重传复用,删它就删掉了行仍在引用的对象;而删除队列
  (deleteObjectFromRetry -> removeObject)本身不做引用反查,准入必须卡在入队处。
- 引用守卫阈值 >1 收紧为 >0:原来把「恰好 1 行引用」当作调用方自己那行而放行,
  但调用方无法证明归属。物理删除本就约定在 DB 行删除之后执行,正常路径引用数
  必为 0;宁可留孤儿(有保留期清理兜底),也不删可能仍被引用的对象。
- chunk 读兜底:指针对象确已缺失(NoSuchKey)时回退同槽位版本化对象 chunk-N-*。
  仅限 chunk 槽位 + 确为缺失两个条件,避免误配无关对象或掩盖真实故障。

测试:新增 31 个用例(补偿删除准入 / 引用守卫 / 兄弟对象兜底),均先确认 RED
再实现;另更新 3 个断言旧行为的既有用例。全量 mvn test 3082 个 0 失败。
2026-09-17 10:42:53 +08:00
huangzd1997 dd85c4f4f2 fix(任务收尾): 打破「数据永久缺失 → 卡死恢复无限重建 job」的死循环
线上任务 28459(appearance_patent)卡在 RUNNING:chunk 462/473/484 的 payload
对象已不存在,组装失败 → stale recovery 每 30 秒重建一次 assemble job 再失败,
而恢复过程又会刷新任务心跳、任务永远判不出「卡死」,48 分钟空转近百轮。

- appearance-patent:读 chunk 时若 payload 对象已不存在(RustFS NoSuchKey),
  跳过该分片让任务按已有分片出部分结果,不再抛异常把组装永久拖死;
  similar-asin 在原有 typeMismatch 跳过分支旁补同款处理
- TaskFileJobService.hasExhaustedAssembleJob + stale recovery:已有「重试耗尽且
  已终态收尾」的 assemble job 时放弃恢复,交给 finalizeStaleTask 按失败收尾
  —— 用户看到明确失败,而不是无限 RUNNING

实测:部署后两节点 28459 相关日志、rustfs 确定性错误、stale recovery 重建全部归零。
2026-09-17 01:19:14 +08:00
huangzd1997 5a18c5350b fix(稳定性): 修任务锁超时/实例转发/扫描降噪,补 rustfs 结论日志
线上日志扫描发现的缺陷批量修复:
- TaskFileJobService.resetStuckRunningJobsDetailed 去掉跨行长事务:两节点
  @Scheduled 各取 200 行在同一事务里逐行 UPDATE,互等行锁导致 biz_task_file_job
  每天上百次 Lock wait timeout。改逐行独立提交(本就有 CAS 条件,幂等)
- TaskOwnerForwardService 连接类失败重试 3 次:两节点滚动重启窗口内的
  Connection refused 会直接丢掉用户提交的结果(读超时不重放,避免重复提交)
- AdminApiGuardFilter 把 401/被顶下线降为 debug(线上单节点一天近 3000 条噪声)
- NoResourceFoundException 单独处理:如实返回 404,不再刷 ERROR 堆栈、不再伪装
  200(每天 580 条,绝大多数是外部扫描 /.env、/credentials、aliyun.json 等)
- RustfsObjectStorageService 补「重试后成功 / 重试耗尽」结论日志:一天上千条
  retrying 却无结论,无法判断数据是否落盘
- 连接池 keep-alive 300s→30s,减少复用已被对端关闭的空闲连接
- SimilarAsin 提交结果遇到已删除任务时带 TASK_NOT_FOUND(40401),客户端据此
  停止每 30 秒一轮的无谓重试
- 修 SimilarAsinResultRowDto 的 GBK 乱码 JsonAlias("浠锋牸" → "价格")
2026-09-17 00:32:48 +08:00
huangzd1997 eca0ea0c18 feat(保留期清理): 补齐 7 处只增不删的数据;修结果对象孤儿
审核发现一批表/元数据只增不删,且对象存储存在活跃泄漏:

- module-cleanup 漏收 task_result_item / task_result_payload 的 payload 指针,
  每晚删完行就在 json-server 桶留下孤儿对象;指针收集触顶从"截断后照样删整组"
  改为任务组二分拆分,拆到单任务仍触顶则整组不删并记 error(截断会让指针随行消失)
- 结果文件对象此前从不回收(只删 DB 行、对象留在桶里),现改为事务提交后
  按 file_result / task_file_job 的 result_file_url 逐个回收
- 新增 7 个保留期清理:device_log_file 元数据、price_track_loop_run、撞款扫描行、
  密钥用量日统计、紫鸟记忆过期行、PUBLISH 任务、BRAND 任务。后两者刻意不复用
  module-cleanup(BRAND 不写 biz_file_task;PUBLISH 单任务可达数万行),
  改为调各自既有的业务删除入口,保证结果对象与子表一起回收
- 未读通知补保留期(180 天,已读仍 90 天);ZiniaoMemoryStoreService.deleteExpired
  此前全库无调用方(实现了没接线),现已挂定时任务

全部沿用既有范式:@Scheduled + 分布式锁单实例 + 分批 + 单轮批次数上限 + 失败只记日志。
2026-09-16 01:59:28 +08:00
huangzd1997 06b3fc3502 perf(全链路): 连接池/事务边界/轮询与 IO 效率收口
Java:
- LLM 180s 读超时不再被全局 call-timeout 静默截断成 90s(长思考请求被掐断→重试→付费网关二次计费)
- 代理 HttpClient 缓存改有界 LRU(jikip 每次提取新 IP,无界缓存持续泄漏 selector 线程与连接池)
- 12 个 service 的 Redis 任务锁移出 @Transactional(自旋最坏 10s 白占 DB 连接,池仅 30),远端对象删/传改 afterCommit
- 结果文件 Job 闸门拒绝时不再回退内联执行(改重新入队,避免把背压转嫁给 MQ 消费线程)
- imagevideo 每秒扫描加列投影、过期清理加 LIMIT;权限页整表查询改列投影(不再拉回密码哈希)
- 哈希改 HexFormat;补 5 处"不能改"的技术依据注释(批量插入会丢回填主键、流式丢模板与图片等)

前端:4 个工具页轮询改轻量端点(带 fallback);PriceTrack 快照节流写盘;候选店铺表分页;页面隐藏时停表

客户端:HTTP 连接池按出口复用(Session 仍每请求新建,保持无跨请求状态);品牌检测 WIPO 逐请求握手;
代理配置按 mtime 缓存;串行任务改专属池;异常降级为标签页重连;紫鸟启动改端口轮询;模板编译缓存;
日志上报连接与落盘收口;Flask 版本 API 改按请求复用连接
2026-09-15 23:01:59 +08:00
huangzd1997 792b5f8bce feat(任务判死): 心跳正常但 180 分钟无结果上报的二次判死线(13 模块)+ 同期待发改动
判死线(治 28131 型「主线程卡死、心跳线程照发」):
- 判据改看 biz_task_scope_state.last_chunk_at(HTTP 心跳不刷新它);从未上报跳过不判
- 中央线覆盖 DELETE_BRAND/PRODUCT_RISK_RESOLVE/PRICE_TRACK/SHOP_MATCH/PATROL_DELETE/QUERY_ASIN/WITHDRAW
- 自带线接入 COLLECT_DATA/SIMILAR_ASIN/APPEARANCE_PATENT/SHOP_DATA_CRAWL/PUBLISH/BRAND
- 客户端心跳带处理位置 progressText,判死文案含最后位置;no-result-upload-timeout-minutes 默认 180(0 关闭)

同期带上另一工作流的待发改动:跟价换 IP 重试、品牌检测重试上限与 LLM 并发下调、
教程包后台管理页与 V126 迁移、admin-vue 教程记录页。
2026-09-14 17:56:20 +08:00
huangzd1997 2d5ca99068 feat(任务派发): 客户端兜底拉取页面未推送成功的任务 + 修店铺匹配定时任务误杀
问题:任务派发链路的"推送"只存在于页面里(Java 解析落库 PENDING → activate →
pywebview 桥 enqueue_json 推本机队列)。只解析没点启动、推送前关页面、在纯浏览器
打开,任务都会停在 PENDING,2 小时后被 StaleTaskRepairService 标失败
(「任务长期未被领取,已自动失败」,09-11 生产清理过 263 条同画像)。

- 服务端新增 GET /api/tasks/pull-pending(TaskClientPullController,身份从 JWT 取,
  不接受 user_id 参数):只挑创建超 5 分钟仍 PENDING 的本用户任务,逐条条件更新认领
  (PENDING→RUNNING + 接管 owner_instance_id)——与页面 activate 同一谓词,天然互斥,
  不会重复执行;认领后组装不出载荷则标 FAILED,不留 RUNNING 孤儿
- payload 由各业务模块实现 ClientTaskPullSpi 组装(task 侧不 import 业务模块,同 G5):
  首批 SIMILAR_ASIN / COLLECT_DATA / APPEARANCE_PATENT——这三个 Python 消费端会自行
  回拉明细,故载荷极简、客户端零模块知识;开关 aiimage.client-task-pull.enabled 默认 false
- 防双执行:三处 activate 由「非终态即可」收紧为只认 PENDING,未命中抛
  「任务已在执行中(可能已由客户端自动接管),无需重复启动」(顺带堵住整行 updateById
  把认领写入的 owner 覆盖回去的竞态);两个前端页 activate 失败即提示并停止入队
- 客户端:amazon/main.py 新增 pending_task_pull_worker,启动点挂在 app_client/main.py
  的 start_task_monitor(独立入口的 worker 线上并不生效);开关 pending_pull_enabled 用
  getattr 读取,避免 test/ 下的旧 config 缺键导致整包导入失败
- 同批修:StaleTaskRepairService 的 SCHEDULED 分支改按 scheduled_at + 120min 判死
  (原按 updated_at 会必杀排期 >2h 的店铺匹配定时任务,而 activate 又被 scheduledAt-90s 挡住)
- 测试:TaskClientPullServiceTest / StaleTaskRepairServiceTest / CollectDataTaskPullSpiImplTest /
  CollectDataActivateGuardTest 共 20 例;客户端 pending_task_pull_worker 7 例并更新启动顺序契约测试
2026-09-14 16:23:34 +08:00
huangzd1997 9cac49cf58 perf(F5+): 行数据按需拉取(结果行版本信号)+ 修复 progress/light 恒判 missing
行数据按需拉取(审查 F5 后续):
- V125 给 biz_file_result 补 updated_at(DEFAULT/ON UPDATE 由数据库维护,
  实体标注 insertStrategy/updateStrategy=NEVER —— 否则 selectById→updateById 的
  写回会把旧值写回去、ON UPDATE 不触发,版本信号静默冻结)
- 装配器回传 rowsVersion=「最后变更时间毫秒#行数」,5 个品牌工具页版本未变即跳过
  带行明细的重型 batch;前端变更信号为 rowsVersion + status/fileStatus/fileReady 复合
  (任务收尾常见「行早写完、之后才置成功」,只看行版本会把界面卡在旧状态)

修复线上缺陷(同一功能验证时暴露):
- TaskProgressLightAssembler 列裁剪漏选 module_type 却用它做模块过滤 →
  getModuleType() 恒为 null → light 恒把任务判成 missing;第七批把 light 接进
  跟价/定时匹配/商品风险的轮询后,消费方会把运行中任务判为 FAILED
- 补选中列 + 守卫用例 taskQueryMustSelectModuleType(已反向验证:去掉修复即红)
- 前端 lightClaimsAllTasksMissing:整体性 missing 结论用重型端点复核后再采信

契约与文档:light 白名单补 rowsVersion(Java 契约测试 / spec 06 §2 / 12 个端点描述)
测试:mvn test 2901 全绿;前端 npm test 765 全绿
2026-09-14 12:08:25 +08:00
huangzd1997 96800a2c88 refactor(boundary): 跨模块循环依赖清零(8 对 → 0),task→业务 依赖归零
共享内核下沉(跨模块共享的"身份/组织/安全"类型进 common)
- AdminUserEntity/AdminUserMapper、ShopManageGroupEntity/ShopManageGroupMapper → common
- AdminAuthSupport(33 文件 17 模块引用)、JwtService、AuthProperties、DeviceSessionPolicy
  → common/security(原先放在 admin/auth 里,任何模块用一次就多一条跨模块边)

端口化(消费方声明接口、数据方实现)
- task/spi:ResultFileJobHandler 新增 resolveResultFileUrl 钩子(BRAND 特例从 Worker 收回);
  Worker 改为调用 handler.onSuccess(该钩子历史上从未被调用,withdraw 的收尾靠 Worker 里的
  WITHDRAW 特判硬编码——现两者都归位,task 侧不再 import withdraw/brand)
- admin/spi/UserSecretCleanupPort(删除用户级联清理密钥)、notification/spi/ProxyBalancePort
  (代理余额探测)、shopdatacrawl/spi/ManagedShopNamesPort(可管店铺名)
- shopkey/spi/GroupDeletionGuardPort:分组删除守卫改由各业务模块实现(invalidasin/dedupe 两个实现),
  shopkey 不再直连它们的 Mapper

棘轮与量化(2026-09-14 实测)
- ArchitectureBoundaryTest:task→业务 119 → **0**(基线钉死为 0,新增跨模块动作必须走 task/spi)
- 跨模块 import 行数 650 → 605;双向依赖对 8 → **0**(usersecret/permission/shopkey 三向环、
  task↔withdraw、task↔brand、admin↔permission、admin↔usersecret、dedup↔shopkey、
  invalidasin↔shopkey、notification↔usersecret、shopdatacrawl↔shopduplicatecheck 全部拆解)

测试同步:接口契约 8→9、品牌 Handler 钩子契约、worker 的 10 个测试构造实参、通知/管理测试端口化。
mvn test 2881 全绿。
2026-09-14 10:05:04 +08:00
huangzd1997 f4ee7e16f0 refactor+perf+fix: G5 模块边界 SPI 化、C5 流式解析、C6/C7 查询优化、D13 队列持久化、A3/A4/A7 鉴权
模块边界(G5 / G7)
- 新增 task/spi/TaskModuleHeartbeatSpi + 13 个模块实现:TaskHeartbeatService 不再 import 任何
  业务模块(原先注入 12 个 CacheService 并用 switch 分发);启动校验重复注册
- 新增 task/spi/BrandTaskHeartbeatSpi(品牌任务心跳/中断)、BrandTaskStaleRepairSpi(陈旧修复)、
  CollectDataItemCleanupSpi(历史清理):跨模块 Mapper 操作收回业务模块
- G7:10 个被跨模块借用的 productrisk VO 迁至 common/model/vo
- 架构棘轮收紧:TASK_TO_BUSINESS_BASELINE 119 → 6(实测)
- 新增 TaskModuleHeartbeatSpiCoverageTest(moduleType 覆盖与拼写)

性能与容量(C5/C6/C7/D13)
- C5 流式解析:SkipPriceAsinService(含两行表头语义)、AppearancePatentExcelParser、
  BrandTaskService、DeleteBrandRunService、LocalFileStorageService.getExcelInfo 改 ExcelStreamReader;
  行数上限改为迭代中生效
- C6 去重总数据列表:关键字改前缀匹配(命中 uk_data_value);V124 删除永不生效的 idx_country
- C7 撞款扫描:按店逐批取数(索引前缀),不再全表 GROUP BY + JOIN + 全量拉内存
- D13 待删对象本地日志 PendingDeleteJournal(启动回放 + 收敛重写),RustfsDeleteRetryService 与
  TransientPayloadDeleteOrchestrator 接入;异步删除失败对象写回日志
- V123 删除 biz_file_result 两个被复合索引覆盖的单列索引

安全(A3/A4/A7 + 守卫名单)
- A4 数字人版本写操作要求管理员;A7 视频密钥按登录身份(超管例外)
- A3 上传接口加危险扩展名黑名单(可配置)
- AdminApiGuardFilter 用户态名单补 /api/ziniao(controller 已 requireAdmin,此处为开关打开后的第二层)

容量(明细表保留期)
- 新增 ShopDataCrawlItemRetentionService:biz_shop_data_crawl_item 按保留期(默认 30 天)分批清理
  (该表此前无任何清理策略,是增长最快的表),job 锁 + 单轮批次上限
2026-09-14 06:46:27 +08:00