docs(phase-3): 3D 出处账——publish 进「真接上 publishResultFile」名单,另抓到 listScopeRows 那格本来就记错的支数

纯 javadoc(`git diff` 逐行核过:除 diff 头以外没有一行不是注释),生产逻辑零改动。
底座 551→575 行,距 800 报警线仍远;本件不在棘轮点名清单内。

跟着 `a125e8f8` 把「谁真用了哪一格」改实,共七处:
- 类头「真接上 `publishResultFile` 的目前只有 shop-payload 两支」→ 三支(+Publish)。Publish 此前一直被记成本件出处却没被接,这次逐列核过是**同形且接得上**,不是「同形接不上」。
- `newTaskHeader`/`publishResultFile` 两处 Publish 行号指针改成认方法名+「迁移前是 :xxxx」,与 3C 给 CollectData 的写法同一格式(`:1054-1070`、`:590-598` 已随迁移漂掉)。
- `ensureTaskOwnedByCurrentInstance` 的三支出处行号全部改成认方法名。这里有一句差点写成假话:我原想写「publish 那枚 public 还兜着别处进来的调用」,去核才看到 `PublishTaskHeartbeatSpi:28` 确实从类外调它(更早一次 grep 被 `head -8` 截断、把这支切掉了)⇒ 保持 public 是**必需**而不是容忍,注释里点名列出该调用方。
- `TerminalRejection#ERROR` 的 3D 补正那句「得留本地写法或先给枚举加第三档」补上结论:已按留本地写法落地,枚举未增第三档。
- 类头那组 2026-10-18 的巨石行数加一句「这组数是签名的来源、不是现状」——否则每迁一支它就更假一分。

⚠ 顺带抓到一处**与本次迁移无关、本来就错**的账:`listScopeRows` 的注释写着「真正调本件的支数现在是三(ShopMatch/PriceTrack/ShopDataCrawl),其余四支尚未迁移」。全树实点调用方是**四支**——`DeleteBrandRunService:1609/:1717` 从 3E 起就在调,那句把出处里的「DeleteBrand 同款」读成了「形状同款、还没接」,一直没跟着迁移改。同时「其余四支尚未迁移」现在整句失效(七支都在底线上了)。已改成:四支调本件;其余三支(AP/CollectData/Publish)虽在底线上却都没用它,并逐支写清它们读的是哪一形(AP 带 `.select(...)` 投影、CollectData 是跨任务历史分页、Publish 是 `selectOne(limit 1)` 查不到就 insert)——三条都是 grep 实读,不是推测。**教训**:「在底线上」不等于「用过每一格」,这两句以前混用过。
This commit is contained in:
2026-10-19 20:06:28 +08:00
parent a125e8f8a5
commit d49c6fc78b
@@ -27,7 +27,8 @@ import java.util.List;
*
* <p><b>本类只沉「七支巨石实测逐字相同的那一截」,不承诺统一四段。</b>签名逐条来自
* 2026-10-18 对七支现网代码的定点实贴(AppearancePatent 3,377/ShopDataCrawl 3,195/
* DeleteBrand 2,304/PriceTrack 2,302/Publish 2,249/CollectData 2,162/ShopMatch 2,027),
* DeleteBrand 2,304/PriceTrack 2,302/Publish 2,249/CollectData 2,162/ShopMatch 2,027)
* ——<b>这组数是「签名的来源」,不是现状</b>:被迁支逐笔只降不升,现状认蓝图 §4 各格实录,
* 每段方法的注释里都写了它的出处行号,Phase 3 迁移时被迁移支必须能逐字替换,
* 换不上就是本类缺件,不是迁移方自由发挥。
*
@@ -44,8 +45,8 @@ import java.util.List;
* 只有文案不同,是最干净的公共件。Phase 2 当时落不了——{@code config/CatchSilenceRatchetTest}
* 的自述规则是「新增捕获块要么别加,要么同批减掉一处同形状」,而 Phase 2 禁止改七支
* ⇒ 减不掉只能不加(登记见蓝图 §5 Phase 2 那条);首迁这一笔删掉被迁支的本地同名件,
* 净增 ≤ 0 才成立。现成模板 {@code PublishTaskService:2118-2124} 的私有
* {@code writeJson(Object, String)} 就是带文案参数的形状。
* 净增 ≤ 0 才成立。现成模板 {@code PublishTaskService} 的私有
* {@code writeJson(Object, String)} 就是带文案参数的形状(认方法名不认行号;那一格 3D 未并档)。
* ⚠ task 模块内部那三份逐字同名件({@code TaskProgressSnapshotService:186}/
* {@code TaskResultItemService:405}/{@code TaskResultPayloadService:113})<b>本轮仍未归并</b>:
* 归并会把 RETHROW 那一格跌破下限(它是下限不是上限;首迁后落在 386,3B 并掉 ShopDataCrawl
@@ -61,7 +62,9 @@ import java.util.List;
* shop-payload/DeleteBrand 自有存储),shop-payload 那族见
* {@link AbstractShopPayloadTaskPipeline}。</li>
* <li><b>出结果</b>:「上传对象存储 → 写列 → {@code updateById}」这一形七支都有({@link #publishResultFile}),
* 但<b>真接上本件的目前只有 shop-payload 那两支</b>——其余各支都有独立实测的接不上理由:
* <b>真接上本件的是 shop-payload 那两支+Publish,共三支</b>(3D 实测:Publish 逐列对得上,
* 它此前一直被记成「出处」却没被接,属于「同形且接得上」而不是「同形接不上」)——
* 其余各支都有独立实测的接不上理由:
* ShopDataCrawl 走批量条件更新(列数与状态位都不同)、DeleteBrand 的 {@code rowCount} 是可空
* {@code Integer}、CollectData 的上传必须排在 {@code persistStats} 之前(那条时序是自愈前提)。
* 三条理由逐条写在方法注释里,别把这句读成「六支都能换」。<b>本类不新建 report SPI</b>——
@@ -110,7 +113,8 @@ public abstract class AbstractFileTaskPipeline<T> {
* 返回 {@code commit(false, 空集)}),只有 FAILED 抛「任务已失败,拒绝继续回传」。
* 证据:回传段 golden {@code taskSuccessShortCircuitsWithoutThrowing} 逐段钉着「两次 task.load +
* tx.begin/commit、零写入、result=void」。所以 3D 接底座的这一格既不能套 IDEMPOTENT 也不能套 ERROR,
* 得留本地写法或先给枚举加第三档——这是形状差,不是行号差。
* 得留本地写法或先给枚举加第三档——这是形状差,不是行号差。<b>3D 迁移已按「留本地写法」落地</b>
* (publish 的两处终态判据原样保留,枚举未增第三档)。
*/
ERROR
}
@@ -145,6 +149,11 @@ public abstract class AbstractFileTaskPipeline<T> {
* {@code fileTaskMapper.selectById}(DB),ShopDataCrawl/ShopMatch/PriceTrack 走
* 缓存优先({@link TaskFinalizeSupport#loadTaskForExecution}),DeleteBrand 用本地缓存件。
* 派别由子类定,底座不替它选。
*
* <p><b>3D 补记:Publish 从本笔起真走这格</b>——它把原本一次三条件的 {@code requireTaskRecord}
* 拆成「加载+模块校验交 {@link #requireSubmissionTask},归属那一格留本地(因为它还认
* {@code userId} 可空)」,异常类型/文案/检查之间无副作用三条都同源,判据未动。
* 换句话说本钩子在被迁支身上不是为了满足抽象签名而写的死件。
*/
protected abstract FileTaskEntity loadTaskForSubmission(Long taskId);
@@ -157,9 +166,13 @@ public abstract class AbstractFileTaskPipeline<T> {
}
/**
* 归属实例校验钩子,默认放过。现网只有 AppearancePatent{@code :2026}/
* Publish{@code :1375}/ShopDataCrawl{@code :3114} 三支实现(多实例转发用),
* 归属实例校验钩子,默认放过。现网只有 AppearancePatent/Publish/ShopDataCrawl 三支实现
* (多实例转发用,一律认方法名不认行号——三支都已在底线上,行号每笔都在漂),
* 其余四支不校验——所以默认必须是空实现而不是抛错。
*
* <p>Publish 那支的本体必须保持 {@code public}:{@code PublishTaskHeartbeatSpi:28} 从类外调它
* (心跳入口要先验归属再动任务),覆写只许放宽不许收窄,所以 3D 迁移保持 {@code public}
* + {@code @Override},没收成 {@code protected}。
*/
protected void ensureTaskOwnedByCurrentInstance(FileTaskEntity task, String operation) {
}
@@ -175,7 +188,8 @@ public abstract class AbstractFileTaskPipeline<T> {
* 取同一时刻。后者对 AppearancePatent{@code :207-208} 与 DeleteBrand{@code :156-157}
* 是一处微差——它们各调了两次 {@code LocalDateTime.now()}(可能差几微秒),底座只取一次;
* 两列都只用于「建单时刻」,无人拿它们互相比较,故按 Majority 的单次写法沉。
* 出处:ShopDataCrawl{@code :575-587}/ShopMatch{@code :473-486}/Publish{@code :1054-1070}
* 出处:ShopDataCrawl{@code :575-587}/ShopMatch{@code :473-486}
* /Publish{@code persistTask}(3D 已改接本件,迁移前是 {@code :1054-1070})
* /CollectData{@code persistParsedTask}(3C 已改接本件,迁移前是 {@code :329-341})
* /AppearancePatent{@code :196-214}/PriceTrack{@code :501-513}
* /DeleteBrand{@code :146-157}。
@@ -183,13 +197,13 @@ public abstract class AbstractFileTaskPipeline<T> {
* <p>{@code taskMode} 六支 {@code "PYTHON_QUEUE"}、DeleteBrand 一支 {@code "IMMEDIATE"};
* {@code status} 建单时各不相同——{@code RUNNING}(ShopDataCrawl/PriceTrack/DeleteBrand)、
* {@code PENDING}(AppearancePatent/CollectData)、{@code SCHEDULED}(ShopMatch 带排期时)、
* 乃至 Publish 在全部文件解析失败时直接 {@code FAILED}({@code :1058})。
* 乃至 Publish 在全部文件解析失败时直接 {@code FAILED}(现由它的 {@code persistTask} 显式传入)。
* 两者一律由调用方显式传入,不在底座设默认值——设了就会有人不再想它。
*
* <p><b>{@code successFileCount}/{@code failedFileCount} 刻意不由底座初始化</b>:建单时五支写 0
* (AppearancePatent{@code :202-203}/ShopDataCrawl{@code :581-582}/ShopMatch{@code :479-480}/
* PriceTrack{@code :507-508}/CollectData{@code persistParsedTask} 里那两行 {@code set*(0)}),Publish{@code :1060-1061} 写的是
* 真实失败数,而 DeleteBrand{@code :146-157} 首次 insert 两列都留 NULL、到 {@code :268-278}
* PriceTrack{@code :507-508}/CollectData{@code persistParsedTask} 里那两行 {@code set*(0)}),Publish 的
* {@code persistTask} 写的是真实失败数(3D 迁移后那两行仍留在本支,本件不代它统计),而 DeleteBrand{@code :146-157} 首次 insert 两列都留 NULL、到 {@code :268-278}
* 循环后才回填。底座一旦默认写 0,就把 DeleteBrand 的「还没统计」偷换成了「零成功零失败」。
* 其余模块专有列({@code requestJson}/{@code resultJson}/{@code scheduledAt}
* /{@code errorMessage}/{@code finishedAt})同样请在返回的实体上继续 set,再交 {@link #insertTask}。
@@ -305,7 +319,8 @@ public abstract class AbstractFileTaskPipeline<T> {
* <p>七支建单与状态回写时都要把对象转成 JSON,失败形状逐字相同:
* 抛 {@code BusinessException(<文案>)} 且<b>不带 cause</b>
* (ShopMatch{@code :510-512} 的文案是「task 不存在」、{@code :1301-1303} 是「序列化任务数据失败」,
* PriceTrack{@code :571-573} 与 Publish{@code :2118-2124} 同款)。
* PriceTrack{@code :571-573} 与 Publish 的私有 {@code writeJson} 同款;Publish 那一格 3D 迁移
* <b>未</b>并档——它要动 {@code RETHROW_FLOOR},属门禁判据动作、须逐处记名授权)。
* 文案是各支自己的对外语义(其中「task 不存在」甚至是现网一句会说谎的文案——序列化失败跟任务存不存在
* 没关系,但 Python 侧按这句决定要不要重试,改它=改线协议),所以底座只收形状、文案由调用方给。
*
@@ -464,9 +479,17 @@ public abstract class AbstractFileTaskPipeline<T> {
/**
* 该任务的全部结果行,按主键升序——回传侧的作用域匹配与收尾判定都依赖这个顺序。
* 出处:ShopMatch{@code :656-659}/PriceTrack{@code :606-610}/DeleteBrand 同款 selectList。
* 3B 又并进来一支:ShopDataCrawl 本地那枚 {@code listTaskRows}(原 {@code :1194-1199})与这两家
* 逐字同形、已删 ⇒ 真正调本件的支数现在是三(ShopMatch/PriceTrack/ShopDataCrawl),
* 其余四支尚未迁移,别说成「七支都用它」。
* 3B 又并进来一支:ShopDataCrawl 本地那枚 {@code listTaskRows}(原 {@code :1194-1199})与这两家逐字同形、已删。
*
* <p><b>3D 核过的真数:调本件的是四支</b>(ShopMatch/PriceTrack/ShopDataCrawl/
* DeleteBrand{@code :1609/:1717})。本注释此前写「三支」,是把出处里那句「DeleteBrand 同款」
* 读成了「形状同款、还没接」——它 3E 就接上了,这句一直没跟着改。<b>其余三支
* (AppearancePatent/CollectData/Publish)虽都在底线上,却没有一支调本件</b>,因为它们读的不是
* 「按 taskId 取全部结果行」这一形:AP 那些 {@code selectList} 带 {@code .select(...)} 投影
* ({@code AppearancePatentTaskService:346}),CollectData 的是跨任务历史分页
* ({@code :699} 按 userId+{@code orderByDesc(createdAt)+limit}),Publish 回传侧用
* {@code ensureTaskResult} 那句 {@code selectOne(... limit 1)}、查不到就 insert。
* 别说成「七支都用它」,也别把「在底线上」读成「用过每一格」。
*/
protected final List<FileResultEntity> listScopeRows(Long taskId) {
return fileResultMapper.selectList(new LambdaQueryWrapper<FileResultEntity>()
@@ -477,7 +500,7 @@ public abstract class AbstractFileTaskPipeline<T> {
/**
* 挂一个结果文件组装 Job。{@code scopeKey} 实测是<b>四形</b>的,不是笔误:
* 归属实例域 {@code task:{id}:owner:{instance}}(Publish{@code :1046/:1216}、
* 归属实例域 {@code task:{id}:owner:{instance}}(Publish 的 {@code ownerScopeKey}、
* ShopDataCrawl{@code :1920}、AppearancePatent{@code :1753})/固定 {@code task:{id}}
* (CollectData{@code enqueueFinalWorkbook},3C 已改接本件)/店铺名(ShopMatch{@code :883}、PriceTrack{@code :905})
* /文件身份(DeleteBrand{@code :1505/:1770})。底座只转发,不解释形状。
@@ -493,7 +516,8 @@ public abstract class AbstractFileTaskPipeline<T> {
/**
* 把已组装好的结果文件上传对象存储,并写回结果行的 6 列后落库。
* 出处(列形状六支相同):ShopMatch{@code :828-840}/PriceTrack{@code :845-857}/
* Publish{@code :590-598}/CollectData{@code processResultFileJob}/AppearancePatent{@code :1876}
* Publish{@code processResultFileJob}(3D 已改接本件,迁移前是 {@code :590-598})
* /CollectData{@code processResultFileJob}/AppearancePatent{@code :1876}
* /DeleteBrand{@code :1921-1929}。
*
* <p><b>3C 实测:列形状同形不等于接得上——{@code CollectData} 接不上,卡在上传的时序。</b>