From d49c6fc78b2663b34c8030f8958206c9c3937f15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com> Date: Mon, 19 Oct 2026 20:06:28 +0800 Subject: [PATCH] =?UTF-8?q?docs(phase-3):=203D=20=E5=87=BA=E5=A4=84?= =?UTF-8?q?=E8=B4=A6=E2=80=94=E2=80=94publish=20=E8=BF=9B=E3=80=8C?= =?UTF-8?q?=E7=9C=9F=E6=8E=A5=E4=B8=8A=20publishResultFile=E3=80=8D?= =?UTF-8?q?=E5=90=8D=E5=8D=95=EF=BC=8C=E5=8F=A6=E6=8A=93=E5=88=B0=20listSc?= =?UTF-8?q?opeRows=20=E9=82=A3=E6=A0=BC=E6=9C=AC=E6=9D=A5=E5=B0=B1?= =?UTF-8?q?=E8=AE=B0=E9=94=99=E7=9A=84=E6=94=AF=E6=95=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 纯 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 实读,不是推测。**教训**:「在底线上」不等于「用过每一格」,这两句以前混用过。 --- .../pipeline/AbstractFileTaskPipeline.java | 58 +++++++++++++------ 1 file changed, 41 insertions(+), 17 deletions(-) diff --git a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/pipeline/AbstractFileTaskPipeline.java b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/pipeline/AbstractFileTaskPipeline.java index c8ef31398..6ed05982c 100644 --- a/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/pipeline/AbstractFileTaskPipeline.java +++ b/backend-java/src/main/java/com/nanri/aiimage/modules/task/service/pipeline/AbstractFileTaskPipeline.java @@ -27,7 +27,8 @@ import java.util.List; * *

本类只沉「七支巨石实测逐字相同的那一截」,不承诺统一四段。签名逐条来自 * 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) + * ——这组数是「签名的来源」,不是现状:被迁支逐笔只降不升,现状认蓝图 §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})本轮仍未归并: * 归并会把 RETHROW 那一格跌破下限(它是下限不是上限;首迁后落在 386,3B 并掉 ShopDataCrawl @@ -61,7 +62,9 @@ import java.util.List; * shop-payload/DeleteBrand 自有存储),shop-payload 那族见 * {@link AbstractShopPayloadTaskPipeline}。 *

  • 出结果:「上传对象存储 → 写列 → {@code updateById}」这一形七支都有({@link #publishResultFile}), - * 但真接上本件的目前只有 shop-payload 那两支——其余各支都有独立实测的接不上理由: + * 真接上本件的是 shop-payload 那两支+Publish,共三支(3D 实测:Publish 逐列对得上, + * 它此前一直被记成「出处」却没被接,属于「同形且接得上」而不是「同形接不上」)—— + * 其余各支都有独立实测的接不上理由: * ShopDataCrawl 走批量条件更新(列数与状态位都不同)、DeleteBrand 的 {@code rowCount} 是可空 * {@code Integer}、CollectData 的上传必须排在 {@code persistStats} 之前(那条时序是自愈前提)。 * 三条理由逐条写在方法注释里,别把这句读成「六支都能换」。本类不新建 report SPI—— @@ -110,7 +113,8 @@ public abstract class AbstractFileTaskPipeline { * 返回 {@code commit(false, 空集)}),只有 FAILED 抛「任务已失败,拒绝继续回传」。 * 证据:回传段 golden {@code taskSuccessShortCircuitsWithoutThrowing} 逐段钉着「两次 task.load + * tx.begin/commit、零写入、result=void」。所以 3D 接底座的这一格既不能套 IDEMPOTENT 也不能套 ERROR, - * 得留本地写法或先给枚举加第三档——这是形状差,不是行号差。 + * 得留本地写法或先给枚举加第三档——这是形状差,不是行号差。3D 迁移已按「留本地写法」落地 + * (publish 的两处终态判据原样保留,枚举未增第三档)。 */ ERROR } @@ -145,6 +149,11 @@ public abstract class AbstractFileTaskPipeline { * {@code fileTaskMapper.selectById}(DB),ShopDataCrawl/ShopMatch/PriceTrack 走 * 缓存优先({@link TaskFinalizeSupport#loadTaskForExecution}),DeleteBrand 用本地缓存件。 * 派别由子类定,底座不替它选。 + * + *

    3D 补记:Publish 从本笔起真走这格——它把原本一次三条件的 {@code requireTaskRecord} + * 拆成「加载+模块校验交 {@link #requireSubmissionTask},归属那一格留本地(因为它还认 + * {@code userId} 可空)」,异常类型/文案/检查之间无副作用三条都同源,判据未动。 + * 换句话说本钩子在被迁支身上不是为了满足抽象签名而写的死件。 */ protected abstract FileTaskEntity loadTaskForSubmission(Long taskId); @@ -157,9 +166,13 @@ public abstract class AbstractFileTaskPipeline { } /** - * 归属实例校验钩子,默认放过。现网只有 AppearancePatent{@code :2026}/ - * Publish{@code :1375}/ShopDataCrawl{@code :3114} 三支实现(多实例转发用), + * 归属实例校验钩子,默认放过。现网只有 AppearancePatent/Publish/ShopDataCrawl 三支实现 + * (多实例转发用,一律认方法名不认行号——三支都已在底线上,行号每笔都在漂), * 其余四支不校验——所以默认必须是空实现而不是抛错。 + * + *

    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 { * 取同一时刻。后者对 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 { *

    {@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} 显式传入)。 * 两者一律由调用方显式传入,不在底座设默认值——设了就会有人不再想它。 * *

    {@code successFileCount}/{@code failedFileCount} 刻意不由底座初始化:建单时五支写 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 { *

    七支建单与状态回写时都要把对象转成 JSON,失败形状逐字相同: * 抛 {@code BusinessException(<文案>)} 且不带 cause * (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 迁移 + * 未并档——它要动 {@code RETHROW_FLOOR},属门禁判据动作、须逐处记名授权)。 * 文案是各支自己的对外语义(其中「task 不存在」甚至是现网一句会说谎的文案——序列化失败跟任务存不存在 * 没关系,但 Python 侧按这句决定要不要重试,改它=改线协议),所以底座只收形状、文案由调用方给。 * @@ -464,9 +479,17 @@ public abstract class AbstractFileTaskPipeline { /** * 该任务的全部结果行,按主键升序——回传侧的作用域匹配与收尾判定都依赖这个顺序。 * 出处: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})与这两家逐字同形、已删。 + * + *

    3D 核过的真数:调本件的是四支(ShopMatch/PriceTrack/ShopDataCrawl/ + * DeleteBrand{@code :1609/:1717})。本注释此前写「三支」,是把出处里那句「DeleteBrand 同款」 + * 读成了「形状同款、还没接」——它 3E 就接上了,这句一直没跟着改。其余三支 + * (AppearancePatent/CollectData/Publish)虽都在底线上,却没有一支调本件,因为它们读的不是 + * 「按 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 listScopeRows(Long taskId) { return fileResultMapper.selectList(new LambdaQueryWrapper() @@ -477,7 +500,7 @@ public abstract class AbstractFileTaskPipeline { /** * 挂一个结果文件组装 Job。{@code scopeKey} 实测是四形的,不是笔误: - * 归属实例域 {@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 { /** * 把已组装好的结果文件上传对象存储,并写回结果行的 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}。 * *

    3C 实测:列形状同形不等于接得上——{@code CollectData} 接不上,卡在上传的时序。