Просмотр исходного кода

fix(aiclean): 融合清洗日志按阶段重排,逐表结果实时编号

- 匹配阶段:1级已匹配模板先落 [匹配] 日志,AI 判定结论统一 [匹配] 前缀
- 提取阶段:新增逐 sheet 完成回调,[结果] (x/N) 实时推送,
  N = 1级 + 2级 + 3级 AI 计划的全部待提取 sheet,连续编号
- 2级补开始提取日志;空表/读取失败由趟末补齐,保证每张表一条结果
- 融合模式去掉逐文件「完成 x/N」,避免文件数与 sheet 数两套计数混用
- 人员库/对象合并移到 3 级 AI 入库之后、终态之前(含停止/异常路径)
- 新增 SheetCompleteCallback,贯通 StreamingEtlListener → CleanTask → DmService
- 补 AiSmartCleanServiceTest 阶段顺序断言
cc 2 недель назад
Родитель
Сommit
dcb541cd80

+ 207 - 52
ai-server/src/main/java/com/zsjz/ai/module/aiclean/service/AiSmartCleanService.java

@@ -17,6 +17,7 @@ import com.zsjz.ai.module.aiclean.enums.AiCleanStatusEnum;
 import com.zsjz.ai.module.aiclean.mapper.AiCleanBatchMapper;
 import com.zsjz.ai.module.aiclean.mapper.AiCleanJobMapper;
 import com.zsjz.ai.module.aiclean.match.BatchMatchCache;
+import com.zsjz.ai.module.dm.clean.SheetCompleteCallback;
 import com.zsjz.ai.module.dm.mapper.FileInfoMapper;
 import com.zsjz.ai.module.dm.service.DmService;
 import com.zsjz.ai.module.govern.serivce.GovernConfService;
@@ -443,6 +444,8 @@ public class AiSmartCleanService {
             int batchSheetTotal = roots.stream()
                     .mapToInt(r -> r.getChildren() == null ? 0 : r.getChildren().size()).sum();
             pushLog("[清洗] 开始处理:" + roots.size() + " 个文件 / " + batchSheetTotal + " 个 sheet");
+            // 匹配阶段第一段:上传时已匹配模板的 1 级 sheet 先落日志,AI 判定结果随后到达
+            logSheetMatches(roots);
             // (root, sheetNode, job) 三元组:判定阶段只收集,不动数据
             List<PendingAi> pending = new ArrayList<>();
             for (FileInfo root : roots) {
@@ -560,11 +563,20 @@ public class AiSmartCleanService {
             // 按降级顺序串行清洗(需求 2026-10-11):1级(上传已匹配模板)先洗并等它
             // 全部落库,再洗 2级(AI 命中既有模板),然后才进 3级(AI 自建表入库)。
             // 4级(无法清洗)在判定阶段就只标记、不产生清洗任务。
-            int toExisting = dispatchExistingByLevel(batchId, roots, existingHits);
+            ExistingPlan existingPlan = planExistingByLevel(roots, existingHits);
+            int aiPlanCount = (int) pending.stream().filter(p -> plans.containsKey(p.job().getId())).count();
+            // 提取阶段的分母:1级 + 2级 + 3级 AI 计划;整批共用一个计数器,
+            // 序号只出现在 [结果] 行,按 sheet 完成顺序连续推进。
+            ExtractionReporter reporter = new ExtractionReporter(
+                    existingPlan.l1Count() + existingPlan.l2Count() + aiPlanCount);
+            SheetCompleteCallback sheetCallback = (root, sheet) -> reportSheetResult(root, sheet, reporter);
+            int toExisting = dispatchExistingByLevel(batchId, roots, existingPlan, sheetCallback, reporter);
 
             if (stopRequested.contains(batchId)) {
                 stage(batchId, AiCleanStageEnum.STOPPED);
                 finishInterruptedJobs(batchId, false);
+                // 停止也要把已清洗部分的人员/对象落库,不能因为中途停止丢掉人员库
+                flushPersonCacheAtEnd();
                 pushStoppedTerminal(caseId, batchId);
                 log.info("智能清洗批次已停止(既有清洗阶段): batchId={}, 交既有清洗={} 条", batchId, toExisting);
                 return;
@@ -572,7 +584,6 @@ public class AiSmartCleanService {
 
             stage(batchId, AiCleanStageEnum.LOADING_AI);
             pushProgress(caseId, batchId);
-            int aiPlanCount = (int) pending.stream().filter(p -> plans.containsKey(p.job().getId())).count();
             if (aiPlanCount > 0) {
                 pushLog("[入库] 开始写入自动新建的数据表:" + aiPlanCount + " 个 sheet");
             }
@@ -587,9 +598,12 @@ public class AiSmartCleanService {
                             System.currentTimeMillis());
                     continue;
                 }
-                loadPlan(batchId, p, plan, st);
+                loadPlan(batchId, p, plan, st, reporter);
                 pushProgress(caseId, batchId);
             }
+            // 3 级入库也属于提取:所有提取动作结束后再合并人员库/对象,
+            // 保证日志顺序是「匹配 → 提取结果 → 人员库合并 → 终态」。
+            flushPersonCacheAtEnd();
             // 终态看本地计数,不回读 DB:并发写的行刚被别人累加过,读回来的值不代表这一轮
             boolean stopped = stopRequested.contains(batchId);
             AiCleanStageEnum finalStage = stopped ? AiCleanStageEnum.STOPPED
@@ -609,6 +623,8 @@ public class AiSmartCleanService {
                     st.needReview.get(), st.failed.get(), System.currentTimeMillis() - start);
         } catch (Exception e) {
             log.error("智能清洗批次异常: batchId={}", batchId, e);
+            // 异常中断也要把已缓存的人员/对象落库,避免残留到同一案件下一批普通清洗
+            flushPersonCacheAtEnd();
             AiCleanBatch update = new AiCleanBatch();
             update.setStage(AiCleanStageEnum.FAILED);
             update.setLastError(StrUtil.maxLength(e.getMessage(), 900));
@@ -651,7 +667,7 @@ public class AiSmartCleanService {
                 p.job().setExitCode(com.zsjz.ai.module.aiclean.enums.AiCleanExitEnum.A.name());
                 aiCleanService.finish(p.job(), AiCleanStatusEnum.DISPATCHED_A, null, System.currentTimeMillis());
                 bump(batchId, "existingHit");
-                pushLog(sheetLabel(p) + " → 已匹配既有模板「" + hit.nameCn() + "」,按该模板提取数据并写入业务表");
+                pushLog("[匹配] " + sheetLabel(p) + " → 已匹配既有模板「" + hit.nameCn() + "」,按该模板提取数据并写入业务表");
             }
             case AiJudgeResult.AiPlan plan -> {
                 plans.put(p.job().getId(), plan);
@@ -659,7 +675,7 @@ public class AiSmartCleanService {
                 // 日志说明这一点,避免用户以为第二个文件又新建了一张表。
                 String headerKey = plan.ev() == null ? null : plan.ev().headerMd5();
                 boolean repeated = StrUtil.isNotBlank(headerKey) && !plannedHeaderKeys.add(headerKey);
-                pushLog(sheetLabel(p) + " → " + (repeated
+                pushLog("[匹配] " + sheetLabel(p) + " → " + (repeated
                         ? "与同批次已识别的表结构相同,跳过重复识别,写入同一数据表"
                         : aiPlanLabel(plan) + matchReason(p.job())));
             }
@@ -670,7 +686,7 @@ public class AiSmartCleanService {
                 st.needReview.incrementAndGet();
                 bump(batchId, "needReview");
                 bumpRows(batchId, 0, 0, nz(p.sheet().getDataNum()));
-                pushLog(sheetLabel(p) + " → 需人工确认:" + StrUtil.maxLength(r.reason(), 120));
+                pushLog("[匹配] " + sheetLabel(p) + " → 需人工确认:" + StrUtil.maxLength(r.reason(), 120));
             }
             case AiJudgeResult.Skip r -> {
                 aiCleanService.finish(p.job(), AiCleanStatusEnum.SKIP, r.reason(), System.currentTimeMillis());
@@ -680,7 +696,7 @@ public class AiSmartCleanService {
                 st.needReview.incrementAndGet();
                 bump(batchId, "needReview");
                 bumpRows(batchId, 0, 0, nz(p.sheet().getDataNum()));
-                pushLog(sheetLabel(p) + " → 已跳过:" + StrUtil.maxLength(r.reason(), 120));
+                pushLog("[匹配] " + sheetLabel(p) + " → 已跳过:" + StrUtil.maxLength(r.reason(), 120));
             }
             case AiJudgeResult.Failed r -> fail(batchId, p, r.reason(), st);
             case null -> fail(batchId, p, "AI 判定无结论", st);
@@ -695,26 +711,33 @@ public class AiSmartCleanService {
         st.failed.incrementAndGet();
         bump(batchId, "failed");
         bumpRows(batchId, 0, 0, nz(p.sheet().getDataNum()));
-        pushLog(sheetLabel(p) + " → 失败:" + StrUtil.maxLength(reason, 120));
+        pushLog("[匹配] " + sheetLabel(p) + " → 失败:" + StrUtil.maxLength(reason, 120));
     }
 
     /**
-     * 按降级顺序串行执行既有链路清洗:先 1级(前端已匹配模板的表),等它全部落库后再
-     * 2级(AI 命中既有模板的表)。两级各自的根树只放本级的 sheet ——
-     * NEED_REVIEW / Skip 的表不进任何一趟,doClean 不再为它们记「未配置模板」噪音日志。
+     * 既有链路两趟清洗的分组结果(只分组,不发清洗)。
      *
-     * <p>趟间用 {@link DmService#doClean(DoCleanDTO, boolean)} 返回的 Latch 严格排队。
-     * 两趟都静默:收口消息(统计/终态快照/治理宣告)由本类在 3级入库完成后统一推送
-     * (见 {@link #pushTerminal}),保证「治理启动」出现在全部清洗动作之后。
+     * @param l2TemplateNames 2级 sheet 的模板展示名(sheetId → nameCn):只用于日志,
+     *                        不改写 {@code childTemplateName},避免影响建表命名
+     */
+    private record ExistingPlan(Map<FileInfo, List<FileInfo>> l1ByRoot,
+                                Map<FileInfo, List<FileInfo>> l2ByRoot,
+                                Map<Long, String> l2TemplateNames,
+                                int l1Count, int l2Count, int applied) {
+    }
+
+    /**
+     * 按降级顺序编排既有链路清洗:1级(前端已匹配模板)先洗并等它全部落库,
+     * 再洗 2级(AI 命中既有模板);NEED_REVIEW / Skip 的表不进任何一趟。
      *
-     * @return 并入既有链路的 AI 命中表数(仅日志用)
+     * <p>分组与执行拆开:编排层要先拿到 1/2 级 sheet 数,才能定下提取阶段的分母
+     * (1级 + 2级 + 3级 AI 计划),并让整批共用一个 {@link ExtractionReporter}。
      */
-    private int dispatchExistingByLevel(Long batchId, List<FileInfo> roots, List<AiJudgeResult.ExistingHit> hits) {
+    private ExistingPlan planExistingByLevel(List<FileInfo> roots, List<AiJudgeResult.ExistingHit> hits) {
         int applied = 0;
-        // 先在原树上把 1级 / 2级 sheet 分组:templateId 非空的是前端已匹配(1级),
-        // 空的按命中结果补挂模板并归入 2级;都没命中的(3/4级)不进既有链路
         Map<FileInfo, List<FileInfo>> l1ByRoot = new IdentityHashMap<>();
         Map<FileInfo, List<FileInfo>> l2ByRoot = new IdentityHashMap<>();
+        Map<Long, String> l2TemplateNames = new java.util.HashMap<>();
         for (FileInfo root : roots) {
             if (root == null || root.getChildren() == null) {
                 continue;
@@ -741,67 +764,156 @@ public class AiSmartCleanService {
                 // 切「表头行/数据行」,缺了首行就 NPE(2026-10-11 实测零落库事故)
                 sheet.setLineNo(hit.headerRow());
                 l2ByRoot.computeIfAbsent(root, _ -> new ArrayList<>()).add(sheet);
+                if (sheet.getId() != null) {
+                    l2TemplateNames.put(sheet.getId(), hit.nameCn());
+                }
                 applied++;
             }
         }
         int l1Count = l1ByRoot.values().stream().mapToInt(List::size).sum();
         int l2Count = l2ByRoot.values().stream().mapToInt(List::size).sum();
+        return new ExistingPlan(l1ByRoot, l2ByRoot, l2TemplateNames, l1Count, l2Count, applied);
+    }
+
+    /**
+     * 按降级顺序串行执行既有链路清洗,逐表结果由 {@link SheetCompleteCallback} 实时上报。
+     *
+     * <p>两趟都静默:收口消息(统计/终态快照/治理宣告)由本类在 3级入库完成后统一推送
+     * (见 {@link #pushTerminal}),保证「治理启动」出现在全部清洗动作之后。
+     *
+     * @return 并入既有链路的 AI 命中表数(仅日志用)
+     */
+    private int dispatchExistingByLevel(Long batchId, List<FileInfo> roots, ExistingPlan plan,
+                                        SheetCompleteCallback sheetCallback, ExtractionReporter reporter) {
+        int l1Count = plan.l1Count();
+        int l2Count = plan.l2Count();
         log.info("智能清洗:按降级顺序串行清洗 1级表={} 个 → 2级表={} 个", l1Count, l2Count);
         if (l1Count + l2Count > 0) {
             pushLog("[清洗] 开始按模板清洗:" + l1Count + " 个已匹配 sheet + " + l2Count + " 个 AI 识别 sheet");
         }
-        // 1级(上传时已匹配模板)的表此前没有任何逐表日志,用户在进度页只能看到 AI 的判定日志,
-        // 会以为这些表没被提取。这里补齐「用哪个模板开始提取」与「提取了多少行」两条流水账。
-        logSheetStart(roots, l1ByRoot);
-        // 两趟都静默:收口消息由本类在 3级入库完成后统一推送(run → pushTerminal),
-        // 保证「所有文件清洗完成 / 开始数据治理」出现在全部清洗动作之后
-        runCleanPass(roots, l1ByRoot, true);
-        logSheetResults(roots, l1ByRoot);
+        logSheetStart(roots, plan.l1ByRoot(), null);
+        runCleanPass(roots, plan.l1ByRoot(), true, sheetCallback);
+        // 空表 / 文件读取失败不会触发逐 sheet 回调,趟末补齐,保证每张表都有 [结果]
+        logMissingSheetResults(roots, plan.l1ByRoot(), reporter);
         if (stopRequested.contains(batchId)) {
             // 停止:1 级趟已跑完(在途文件都已结束),2 级不再启动
             pushLog("[清洗] 已停止:2级既有清洗不再执行");
-            return applied;
+            return plan.applied();
         }
-        runCleanPass(roots, l2ByRoot, true);
-        logSheetResults(roots, l2ByRoot);
-        return applied;
+        logSheetStart(roots, plan.l2ByRoot(), plan.l2TemplateNames());
+        runCleanPass(roots, plan.l2ByRoot(), true, sheetCallback);
+        logMissingSheetResults(roots, plan.l2ByRoot(), reporter);
+        return plan.applied();
     }
 
-    /** 既有链路开始清洗前的逐表日志:说明这张表按哪个模板提取数据 */
-    private void logSheetStart(List<FileInfo> roots, Map<FileInfo, List<FileInfo>> sheetsByRoot) {
+    /** 匹配阶段第一段:上传时已匹配模板的 1 级 sheet,先于 AI 判定结果输出 */
+    private void logSheetMatches(List<FileInfo> roots) {
         for (FileInfo root : roots) {
-            for (FileInfo sheet : sheetsByRoot.getOrDefault(root, List.of())) {
-                pushLog("[清洗] " + sheetLabel(root, sheet) + " → 已匹配模板「"
-                        + templateLabel(sheet) + "」,开始提取表格数据");
+            if (root == null || root.getChildren() == null) {
+                continue;
+            }
+            for (FileInfo sheet : root.getChildren()) {
+                if (sheet == null || sheet.getTemplateId() == null) {
+                    continue;
+                }
+                pushLog("[匹配] " + sheetLabel(root, sheet) + " → 已匹配模板「" + templateLabel(sheet) + "」");
             }
         }
     }
 
     /**
-     * 既有链路一趟跑完后的逐表结果日志。
+     * 既有链路开始提取前的逐表日志:说明这张表按哪个模板提取数据。
      *
-     * <p>行数直接取内存里的 sheet 对象:{@code StreamingEtlListener} 清洗完成时会把
-     * {@code dataNum/failNum} 回写到传进去的同一批对象上,无需再查库。
+     * @param templateNames 2级 sheet 的模板展示名(1级传 null,直接用 templateLabel)
      */
-    private void logSheetResults(List<FileInfo> roots, Map<FileInfo, List<FileInfo>> sheetsByRoot) {
+    private void logSheetStart(List<FileInfo> roots, Map<FileInfo, List<FileInfo>> sheetsByRoot,
+                               Map<Long, String> templateNames) {
         for (FileInfo root : roots) {
             for (FileInfo sheet : sheetsByRoot.getOrDefault(root, List.of())) {
-                if (sheet.getFileStatus() != FileSheetStateEnum.FILE_CLEAN_COMPLETE) {
-                    pushLog("[清洗] " + sheetLabel(root, sheet) + " → 清洗未完成,详情见失败明细");
-                    continue;
-                }
-                int total = nz(sheet.getDataNum());
-                int failed = nz(sheet.getFailNum());
-                pushLog("[清洗] " + sheetLabel(root, sheet) + " → 提取完成:成功 "
-                        + Math.max(0, total - failed) + " 行,失败 " + failed + " 行");
+                String name = templateNames != null && sheet.getId() != null
+                        ? templateNames.getOrDefault(sheet.getId(), templateLabel(sheet))
+                        : templateLabel(sheet);
+                pushLog("[清洗] " + sheetLabel(root, sheet) + " → 已匹配模板「"
+                        + name + "」,开始提取表格数据");
+            }
+        }
+    }
+
+    /** 一趟结束后补齐未触发回调的 sheet(空表、读取失败等) */
+    private void logMissingSheetResults(List<FileInfo> roots, Map<FileInfo, List<FileInfo>> sheetsByRoot,
+                                        ExtractionReporter reporter) {
+        for (FileInfo root : roots) {
+            for (FileInfo sheet : sheetsByRoot.getOrDefault(root, List.of())) {
+                reportSheetResult(root, sheet, reporter);
             }
         }
     }
 
+    /**
+     * 逐表结果上报:同一张 sheet 只报一次(回调 / 趟末补齐 / AI 入库共用一套去重)。
+     *
+     * <p>多文件并发清洗时,取号与推送必须互斥:否则线程 A 取到 5、线程 B 取到 6 后
+     * 先推出去,日志里就会出现 6/93 排在 5/93 前面。
+     */
+    private void reportSheetResult(FileInfo root, FileInfo sheet, ExtractionReporter reporter) {
+        if (sheet == null) {
+            return;
+        }
+        synchronized (reporter) {
+            if (!reporter.markReported(sheet)) {
+                return;
+            }
+            int done = reporter.finished();
+            pushLog("[结果] (" + done + "/" + reporter.total() + ") " + sheetLabel(root, sheet) + " → "
+                    + sheetResultText(sheet));
+        }
+    }
+
+    /** 逐表结果文案:行数取内存终值(StreamingEtlListener 已回写 dataNum/failNum) */
+    private static String sheetResultText(FileInfo sheet) {
+        if (sheet.getFileStatus() != FileSheetStateEnum.FILE_CLEAN_COMPLETE) {
+            return "清洗未完成,详情见失败明细";
+        }
+        int total = nz(sheet.getDataNum());
+        int failed = nz(sheet.getFailNum());
+        return "提取完成:成功 " + Math.max(0, total - failed) + " 行,失败 " + failed + " 行";
+    }
+
+    /**
+     * 提取阶段的公共计数器:分母在判定结束后一次算定(1级 + 2级 + 3级 AI 计划),
+     * 分子按 sheet 完成实时累加;{@code reported} 跨回调/补齐/AI 入库去重。
+     */
+    private static final class ExtractionReporter {
+        private final int total;
+        private final AtomicInteger extracted = new AtomicInteger();
+        private final Set<Long> reported = ConcurrentHashMap.newKeySet();
+
+        private ExtractionReporter(int total) {
+            this.total = Math.max(0, total);
+        }
+
+        int total() {
+            return total;
+        }
+
+        int finished() {
+            return extracted.incrementAndGet();
+        }
+
+        /** @return true = 首次上报,需要输出日志 */
+        boolean markReported(FileInfo sheet) {
+            if (sheet == null || sheet.getId() == null) {
+                return true;
+            }
+            return reported.add(sheet.getId());
+        }
+    }
+
     /**
      * 把本级的 sheet 挂到根节点<b>浅拷贝</b>上发一趟既有清洗,并等它全部落库
      */
-    private void runCleanPass(List<FileInfo> roots, Map<FileInfo, List<FileInfo>> sheetsByRoot, boolean silent) {
+    private void runCleanPass(List<FileInfo> roots, Map<FileInfo, List<FileInfo>> sheetsByRoot, boolean silent,
+                              SheetCompleteCallback sheetCallback) {
         // 根节点用浅拷贝:不改动前端提交的原始树;两趟各持各的根,互不覆盖
         // (sheet 对象本身仍是同一批引用,瞬态字段只在分组时写一次)
         List<FileInfo> passRoots = new ArrayList<>();
@@ -824,7 +936,7 @@ public class AiSmartCleanService {
         DoCleanDTO dto = new DoCleanDTO();
         dto.setFileInfos(passRoots);
         dto.setReClean(0);
-        CountDownLatch latch = dmService.doClean(dto, silent);
+        CountDownLatch latch = dmService.doClean(dto, silent, sheetCallback);
         try {
             latch.await();
         } catch (InterruptedException e) {
@@ -833,6 +945,36 @@ public class AiSmartCleanService {
         }
     }
 
+    /**
+     * 批次级人员库/对象落库:所有提取动作(含 3 级 AI 入库)结束后统一执行一次。
+     *
+     * <p>静默趟不再各自落库,保证日志顺序是「匹配 → 提取结果 → 人员库合并 → 终态」。
+     * 缓存为空(纯 AI 批次)时直接跳过,不输出「0 条」噪音。
+     */
+    private void flushPersonCacheAtEnd() {
+        try {
+            DmService.PersonFlushResult result = dmService.flushPersonCache((libCount, personCount) -> {
+                pushLog("[清洗] 正在合并人员库(" + libCount + " 条)");
+                pushLog("[清洗] 正在创建对象(" + personCount + " 个)");
+            });
+            if (result.libCount() + result.personCount() == 0) {
+                return;
+            }
+            if (result.failed()) {
+                log.error("人员库/对象落库失败: {}", result.error());
+                pushLog("[清洗] 人员库/对象落库失败:" + result.error());
+                return;
+            }
+            pushLog("[清洗] 人员库合并完成:" + result.libCount() + " 条,耗时 "
+                    + (result.elapsedMs() / 1000) + " 秒");
+            pushLog("[清洗] 对象创建完成:" + result.personCount() + " 个,耗时 "
+                    + (result.elapsedMs() / 1000) + " 秒");
+        } catch (Exception e) {
+            log.error("人员库/对象落库异常", e);
+            pushLog("[清洗] 人员库/对象落库失败:" + StrUtil.maxLength(e.getMessage(), 120));
+        }
+    }
+
     /**
      * 出口 B 的目标说明:模型明明选中了既有模板却最终建了新表时,必须把原因写进处理日志,
      * 否则用户只看到「命中模板」、却在结果页发现数据进了一张新表。
@@ -851,11 +993,13 @@ public class AiSmartCleanService {
         return "与既有模板「" + cand.nameCn() + "」相似,但字段无法完全对应,已按当前表头新建数据表";
     }
 
-    private void loadPlan(Long batchId, PendingAi p, AiJudgeResult.AiPlan plan, Stats st) {
+    private void loadPlan(Long batchId, PendingAi p, AiJudgeResult.AiPlan plan, Stats st,
+                          ExtractionReporter reporter) {
         long start = System.currentTimeMillis();
         String source = plan.candidate() == null ? "按表头识别"
                 : plan.candidate().fromAiLib() ? "历史模板「" + plan.candidate().nameCn() + "」"
                 : "参考既有模板「" + plan.candidate().nameCn() + "」";
+        pushLog("[清洗] " + sheetLabel(p) + " → 开始提取表格数据(" + source + ")");
         try {
             long written = aiCleanService.loadViaAiTemplate(p.job(), p.root(), p.sheet(), plan);
             if (written < 0) {
@@ -863,7 +1007,7 @@ public class AiSmartCleanService {
                 st.failed.incrementAndGet();
                 bump(batchId, "failed");
                 bumpRows(batchId, 0, nz(p.job().getRowRejected()), nz(p.job().getRowUnprocessed()));
-                pushLog(sheetLabel(p) + " → 写入失败(" + source + ")");
+                reportAiResult(p, reporter, "写入失败(" + source + ")");
                 return;
             }
             aiCleanService.finish(p.job(), AiCleanStatusEnum.SUCCESS, null, start);
@@ -873,14 +1017,25 @@ public class AiSmartCleanService {
                 bump(batchId, "selfBuilt");
             }
             bumpRows(batchId, nz(p.job().getRowLoaded()), nz(p.job().getRowRejected()), 0);
-            pushLog(sheetLabel(p) + " → 提取完成:已写入 " + written + " 行(" + source + ")");
+            reportAiResult(p, reporter, "提取完成:已写入 " + written + " 行(" + source + ")");
         } catch (Exception e) {
             log.error("AI 入库异常: jobId={}", p.job().getId(), e);
             aiCleanService.finish(p.job(), AiCleanStatusEnum.FAIL, StrUtil.maxLength(e.getMessage(), 900), start);
             st.failed.incrementAndGet();
             bump(batchId, "failed");
             bumpRows(batchId, 0, nz(p.job().getRowRejected()), nz(p.job().getRowUnprocessed()));
-            pushLog(sheetLabel(p) + " → 写入异常:" + StrUtil.maxLength(e.getMessage(), 120));
+            reportAiResult(p, reporter, "写入异常:" + StrUtil.maxLength(e.getMessage(), 120));
+        }
+    }
+
+    /** AI 入库的逐表结果:与模板清洗共用同一个 [结果] x/N 计数器 */
+    private void reportAiResult(PendingAi p, ExtractionReporter reporter, String text) {
+        synchronized (reporter) {
+            if (!reporter.markReported(p.sheet())) {
+                return;
+            }
+            int done = reporter.finished();
+            pushLog("[结果] (" + done + "/" + reporter.total() + ") " + sheetLabel(p) + " → " + text);
         }
     }
 

+ 8 - 2
ai-server/src/main/java/com/zsjz/ai/module/dm/clean/CleanTask.java

@@ -41,9 +41,14 @@ import java.util.stream.Collectors;
  *
  * @param fileInfo  主文件信息对象
  * @param sheetList 工作表信息列表
+ * @param sheetCompleteCallback 单张 sheet 清洗完成回调(可为 null)
  */
 @Slf4j
-public record CleanTask(FileInfo fileInfo, List<FileInfo> sheetList) {
+public record CleanTask(FileInfo fileInfo, List<FileInfo> sheetList, SheetCompleteCallback sheetCompleteCallback) {
+
+    public CleanTask(FileInfo fileInfo, List<FileInfo> sheetList) {
+        this(fileInfo, sheetList, null);
+    }
 
     public static final List<Integer> OPEN_ACCOUNT_ID = List.of(3, 4);
 
@@ -78,7 +83,8 @@ public record CleanTask(FileInfo fileInfo, List<FileInfo> sheetList) {
         if (CollUtil.isNotEmpty(sheetMap)) {
             ExcelTypeEnum excelTypeEnum = ExcelTypeEnum.valueOf(fileInfo.getFileType());
             // 创建流式 ETL 监听器,使用日志方式处理脏数据
-            StreamingEtlListener streamingEtlListener = new StreamingEtlListener(new LogDirtyDataHandler(), excelTypeEnum, sheetList, extractSheetList);
+            StreamingEtlListener streamingEtlListener = new StreamingEtlListener(new LogDirtyDataHandler(), excelTypeEnum, sheetList, extractSheetList,
+                    sheetCompleteCallback == null ? null : sheet -> sheetCompleteCallback.onSheetComplete(fileInfo, sheet));
             // 获取文件类型和编码
             Charset charset = Charset.forName(fileInfo.getCharSet());
             //SimpleReadCacheSelector simpleReadCacheSelector = new SimpleReadCacheSelector();

+ 22 - 0
ai-server/src/main/java/com/zsjz/ai/module/dm/clean/SheetCompleteCallback.java

@@ -0,0 +1,22 @@
+package com.zsjz.ai.module.dm.clean;
+
+import com.zsjz.ai.common.model.dm.entity.FileInfo;
+
+/**
+ * 工作表清洗完成回调:每张 sheet 的 ETL 结束后触发一次。
+ *
+ * <p>触发点在 {@link StreamingEtlListener#doAfterAllAnalysed} 把
+ * {@code dataNum/failNum/fileStatus} 写回内存之后,行数已经是终值;
+ * 上层据此实时播报逐表结果,不必等整趟清洗结束再补发。
+ *
+ * <p>回调执行在清洗线程上,异常由监听器自行兜住,不得影响清洗主流程。
+ */
+@FunctionalInterface
+public interface SheetCompleteCallback {
+
+    /**
+     * @param root  工作表所属的根文件
+     * @param sheet 刚完成清洗的工作表
+     */
+    void onSheetComplete(FileInfo root, FileInfo sheet);
+}

+ 29 - 0
ai-server/src/main/java/com/zsjz/ai/module/dm/clean/StreamingEtlListener.java

@@ -20,6 +20,7 @@ import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
 import java.util.concurrent.atomic.AtomicInteger;
+import java.util.function.Consumer;
 
 /**
  * 流式 ETL 监听器
@@ -83,6 +84,11 @@ public class StreamingEtlListener extends AnalysisEventListener<Map<Integer, Str
      */
     private final List<String> headerList = new ArrayList<>();
 
+    /**
+     * 单张 sheet 清洗完成回调(可为 null):供上层实时播报逐表结果。
+     */
+    private final Consumer<FileInfo> sheetCompleteCallback;
+
     /**
      * 构造函数
      *
@@ -90,10 +96,23 @@ public class StreamingEtlListener extends AnalysisEventListener<Map<Integer, Str
      * @param sheetList    工作表信息列表
      */
     public StreamingEtlListener(DirtyDataHandler dirtyHandler, ExcelTypeEnum excelTypeEnum, List<FileInfo> sheetList, List<FileInfo> extractSheetList) {
+        this(dirtyHandler, excelTypeEnum, sheetList, extractSheetList, null);
+    }
+
+    /**
+     * 构造函数
+     *
+     * @param dirtyHandler           脏数据处理器
+     * @param sheetList              工作表信息列表
+     * @param sheetCompleteCallback  单张 sheet 清洗完成回调(可为 null)
+     */
+    public StreamingEtlListener(DirtyDataHandler dirtyHandler, ExcelTypeEnum excelTypeEnum, List<FileInfo> sheetList,
+                                List<FileInfo> extractSheetList, Consumer<FileInfo> sheetCompleteCallback) {
         this.dirtyHandler = dirtyHandler;
         this.sheetList = sheetList;
         this.extractSheetList = extractSheetList;
         this.excelTypeEnum = excelTypeEnum;
+        this.sheetCompleteCallback = sheetCompleteCallback;
     }
 
     /**
@@ -209,6 +228,16 @@ public class StreamingEtlListener extends AnalysisEventListener<Map<Integer, Str
                 currentSheet.setFailNum(sheetFailRowCount);
                 currentSheet.setFileStatus(FileSheetStateEnum.FILE_CLEAN_COMPLETE);
                 extractSheetList.add(currentSheet);
+                // 行数与状态已写回内存终值:通知上层逐表播报。回调异常只记日志,
+                // 不能影响 ETL 主流程与后续工作表。
+                if (sheetCompleteCallback != null) {
+                    try {
+                        sheetCompleteCallback.accept(currentSheet);
+                    } catch (Exception e) {
+                        log.error("逐表完成回调异常, sheetId={}, sheetName={}", currentSheet.getId(),
+                                currentSheet.getSheetName(), e);
+                    }
+                }
                 // 获取模板对应的表配置信息
                 if (currentSheet.getHasNew()) {
                     log.info("新增模板配置, sheetName={}", currentSheet.getSheetName());

+ 111 - 67
ai-server/src/main/java/com/zsjz/ai/module/dm/service/DmService.java

@@ -37,6 +37,7 @@ import com.zsjz.ai.common.utils.WorkspacePathGuard;
 import com.zsjz.ai.module.dm.ai.FileAiProfileService;
 import com.zsjz.ai.module.dm.clean.CleanCache;
 import com.zsjz.ai.module.dm.clean.CleanTask;
+import com.zsjz.ai.module.dm.clean.SheetCompleteCallback;
 import com.zsjz.ai.module.dm.clean.TaskCompleteCallback;
 import com.zsjz.ai.module.dm.mapper.FileInfoMapper;
 import com.zsjz.ai.module.dm.pre.PreTask;
@@ -72,6 +73,7 @@ import java.util.*;
 import java.util.concurrent.*;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiConsumer;
 import java.util.stream.Collectors;
 
 /**
@@ -727,7 +729,11 @@ public class DmService {
         return (totalTaskCount, completedTaskCount, message) -> {
             log.info("任务进度:已完成{} / {}({}%)",
                     completedTaskCount, totalTaskCount, Math.round((double) completedTaskCount / totalTaskCount * 100));
-            sseService.sendSee(new SseDTO(101, slowDownProgress.calculateNextProgress(), message, new SeeDataDTO(0, 0)));
+            // 融合链路里各趟都是静默的:逐文件完成消息由 [结果] (x/N) 逐表日志取代,
+            // 避免同一批日志同时出现「文件 x/19」和「sheet x/93」两套计数。
+            if (!silent) {
+                sseService.sendSee(new SseDTO(101, slowDownProgress.calculateNextProgress(), message, new SeeDataDTO(0, 0)));
+            }
             if (completedTaskCount == totalTaskCount) {
                 // 本轮是否被用户中途停止:终态文案、治理启动都要据此分流
                 boolean stopped = isStopRequested(CaseContextHolder.get());
@@ -735,65 +741,32 @@ public class DmService {
                     GlobalCache.initCache();
                     log.info("所有任务完成!");
                     log.info("执行刷新缓存数据入库!");
-                    // 按 caseId 原子取走本次清洗缓冲后再落库:
-                    // 缓冲已按案件分桶,不会把其他用户案件累积的人员冲进当前案件库
-                    CleanCache.CleanSnapshot snapshot = CleanCache.drain();
-                    // 人员库/对象落库是「最后一条提取日志 → 终态推送」之间最长的静默段,
-                    // 大批量导入时可达分钟级 —— 必须把数量与耗时实时播报出去,否则用户看到的
-                    // 就是「提取早就完成了,最终结果却迟迟不推」。两个落库互不依赖(不同表,
-                    // DuckDB 连接每次 getConnection() 都是 duplicate 出来的独立连接),并行压缩窗口。
-                    int libCount = snapshot.personLibNos().size();
-                    int personCount = snapshot.persons().size();
-                    sseService.sendSee(new SseDTO(101, slowDownProgress.calculateNextProgress(),
-                            "[清洗] 正在合并人员库(" + libCount + " 条)", new SeeDataDTO(0, 0)));
-                    sseService.sendSee(new SseDTO(101, slowDownProgress.calculateNextProgress(),
-                            "[清洗] 正在创建对象(" + personCount + " 个)", new SeeDataDTO(0, 0)));
-                    Long flushCaseId = CaseContextHolder.get();
-                    Long flushUserId = CaseContextHolder.getUserId();
-                    AtomicReference<Throwable> flushFailure = new AtomicReference<>();
-                    long flushStart = System.currentTimeMillis();
-                    Thread libThread = Thread.startVirtualThread(() ->
-                            CaseContextHolder.runWith(flushCaseId, flushUserId, () -> {
-                                try {
-                                    long t0 = System.currentTimeMillis();
-                                    personLibNoService.flushPerLib(snapshot.personLibNos());
-                                    sseService.sendSee(new SseDTO(101, slowDownProgress.current(),
-                                            "[清洗] 人员库合并完成:" + libCount + " 条,耗时 "
-                                                    + ((System.currentTimeMillis() - t0) / 1000) + " 秒",
-                                            new SeeDataDTO(0, 0)));
-                                } catch (Throwable t) {
-                                    flushFailure.compareAndSet(null, t);
-                                }
-                            }));
-                    Thread personThread = Thread.startVirtualThread(() ->
-                            CaseContextHolder.runWith(flushCaseId, flushUserId, () -> {
-                                try {
-                                    long t0 = System.currentTimeMillis();
-                                    personBasicInfoService.flushPerson(snapshot.persons());
-                                    sseService.sendSee(new SseDTO(101, slowDownProgress.current(),
-                                            "[清洗] 对象创建完成:" + personCount + " 个,耗时 "
-                                                    + ((System.currentTimeMillis() - t0) / 1000) + " 秒",
-                                            new SeeDataDTO(0, 0)));
-                                } catch (Throwable t) {
-                                    flushFailure.compareAndSet(null, t);
-                                }
-                            }));
-                    try {
-                        libThread.join();
-                        personThread.join();
-                    } catch (InterruptedException e) {
-                        Thread.currentThread().interrupt();
-                        throw ServerException.build("人员库/对象落库被中断");
-                    }
-                    if (flushFailure.get() != null) {
-                        // 落库失败不能静默吞掉:人员/对象缺失会让后续治理与画像直接少数据
-                        log.error("人员库/对象落库失败", flushFailure.get());
-                        sseService.sendSee(new SseDTO(101, slowDownProgress.current(),
-                                "[清洗] 人员库/对象落库失败:" + StrUtil.maxLength(flushFailure.get().getMessage(), 120),
-                                new SeeDataDTO(0, 0)));
+                    // 人员库/对象落库放在趟末;静默趟(融合链路)不落库、也不推消息,
+                    // 由 AiSmartCleanService 在 3 级 AI 入库结束后统一执行 ——
+                    // 这样日志顺序才是「全部提取完成 → 人员库合并 → 终态」。
+                    if (!silent) {
+                        PersonFlushResult flushResult = flushPersonCache((libCount, personCount) -> {
+                            sseService.sendSee(new SseDTO(101, slowDownProgress.calculateNextProgress(),
+                                    "[清洗] 正在合并人员库(" + libCount + " 条)", new SeeDataDTO(0, 0)));
+                            sseService.sendSee(new SseDTO(101, slowDownProgress.calculateNextProgress(),
+                                    "[清洗] 正在创建对象(" + personCount + " 个)", new SeeDataDTO(0, 0)));
+                        });
+                        if (flushResult.failed()) {
+                            // 落库失败不能静默吞掉:人员/对象缺失会让后续治理与画像直接少数据
+                            log.error("人员库/对象落库失败: {}", flushResult.error());
+                            sseService.sendSee(new SseDTO(101, slowDownProgress.current(),
+                                    "[清洗] 人员库/对象落库失败:" + flushResult.error(), new SeeDataDTO(0, 0)));
+                        } else if (flushResult.libCount() + flushResult.personCount() > 0) {
+                            sseService.sendSee(new SseDTO(101, slowDownProgress.current(),
+                                    "[清洗] 人员库合并完成:" + flushResult.libCount() + " 条,耗时 "
+                                            + (flushResult.elapsedMs() / 1000) + " 秒", new SeeDataDTO(0, 0)));
+                            sseService.sendSee(new SseDTO(101, slowDownProgress.current(),
+                                    "[清洗] 对象创建完成:" + flushResult.personCount() + " 个,耗时 "
+                                            + (flushResult.elapsedMs() / 1000) + " 秒", new SeeDataDTO(0, 0)));
+                            log.info("人员库/对象落库完成: lib={}, person={}, 耗时={}ms",
+                                    flushResult.libCount(), flushResult.personCount(), flushResult.elapsedMs());
+                        }
                     }
-                    log.info("人员库/对象落库完成: lib={}, person={}, 耗时={}ms",
-                            libCount, personCount, System.currentTimeMillis() - flushStart);
                     List<FileInfo> fileInfoList = fileInfoMapper.selectList(Wrappers.lambdaQuery(FileInfo.class)
                             .eq(FileInfo::getBatchId, batchId)
                             .isNull(FileInfo::getFileType));
@@ -858,6 +831,67 @@ public class DmService {
         };
     }
 
+    /** 人员库/对象落库结果:数量为 drain 出来的条数,error 非空表示失败 */
+    public record PersonFlushResult(int libCount, int personCount, long elapsedMs, String error) {
+        public boolean failed() {
+            return error != null;
+        }
+    }
+
+    /**
+     * 把 CleanCache 里缓存的(当前案件)人员库/对象落库。
+     *
+     * <p>drain 与并行落库封装在一起:调用方通过 {@code onDrained} 在落库开始前拿到数量、
+     * 推「正在合并…」日志。数量都为 0 时不回调、不做无意义的落库。
+     * 两个落库互不依赖(不同表,DuckDB 连接每次 getConnection() 都是 duplicate 出来的
+     * 独立连接),用两个虚拟线程并行压缩窗口。
+     *
+     * <p>落库失败不抛异常,由 {@link PersonFlushResult#failed()} 返回,调用方决定文案。
+     *
+     * @param onDrained 缓存非空时、落库开始前回调(libCount, personCount),可为 null
+     */
+    public PersonFlushResult flushPersonCache(BiConsumer<Integer, Integer> onDrained) {
+        CleanCache.CleanSnapshot snapshot = CleanCache.drain();
+        int libCount = snapshot.personLibNos().size();
+        int personCount = snapshot.persons().size();
+        if (libCount == 0 && personCount == 0) {
+            return new PersonFlushResult(0, 0, 0, null);
+        }
+        if (onDrained != null) {
+            onDrained.accept(libCount, personCount);
+        }
+        long start = System.currentTimeMillis();
+        Long caseId = CaseContextHolder.get();
+        Long userId = CaseContextHolder.getUserId();
+        AtomicReference<Throwable> failure = new AtomicReference<>();
+        Thread libThread = Thread.startVirtualThread(() ->
+                CaseContextHolder.runWith(caseId, userId, () -> {
+                    try {
+                        personLibNoService.flushPerLib(snapshot.personLibNos());
+                    } catch (Throwable t) {
+                        failure.compareAndSet(null, t);
+                    }
+                }));
+        Thread personThread = Thread.startVirtualThread(() ->
+                CaseContextHolder.runWith(caseId, userId, () -> {
+                    try {
+                        personBasicInfoService.flushPerson(snapshot.persons());
+                    } catch (Throwable t) {
+                        failure.compareAndSet(null, t);
+                    }
+                }));
+        try {
+            libThread.join();
+            personThread.join();
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            failure.compareAndSet(null, e);
+        }
+        Throwable t = failure.get();
+        return new PersonFlushResult(libCount, personCount, System.currentTimeMillis() - start,
+                t == null ? null : StrUtil.maxLength(t.toString(), 120));
+    }
+
     /**
      * 已请求「停止清洗」的案件。
      *
@@ -901,8 +935,12 @@ public class DmService {
         doClean(dto, false);
     }
 
+    public CountDownLatch doClean(DoCleanDTO dto, boolean silent) {
+        return doClean(dto, silent, null);
+    }
+
     /**
-     * 执行数据清洗任务(可静默趟)。
+     * 执行数据清洗任务(可静默趟,可逐 sheet 回调)。
      *
      * <p>智能清洗按降级顺序 1级→2级 串行多趟复用本方法,<b>各趟都静默</b>:
      * 任务级进度消息照常推送、清理副作用(缓存刷新/人员库/全文检索/临时文件)照常执行,
@@ -910,10 +948,14 @@ public class DmService {
      * 收口(统计/终态快照/治理宣告)由智能清洗批次在 3级入库完成后统一推送,
      * 否则「治理启动」会早于 AI 自建表入库。调用方用返回的 Latch 排队各趟。
      *
-     * @param silent true=静默趟(跳过用户可见的收口消息与关会话)
+     * <p>{@code sheetCallback} 非空时,每张 sheet 的 ETL 结束都会回调一次(行数与状态已是终值),
+     * 供融合链路实时播报逐表结果;普通清洗传 null 即可。
+     *
+     * @param silent        true=静默趟(跳过用户可见的收口消息与关会话)
+     * @param sheetCallback 单张 sheet 清洗完成回调(可为 null)
      * @return 全部清洗任务完成后计数归零的 Latch;无可清洗任务时返回已归零的 Latch
      */
-    public CountDownLatch doClean(DoCleanDTO dto, boolean silent) {
+    public CountDownLatch doClean(DoCleanDTO dto, boolean silent, SheetCompleteCallback sheetCallback) {
         CountDownLatch latch = new CountDownLatch(1);
         SlowDownProgress slowDownProgress = new SlowDownProgress();
         List<CleanJob> cleanJobs = buildCleanJobs(dto.getFileInfos());
@@ -948,12 +990,13 @@ public class DmService {
         Long cleanCaseId = CaseContextHolder.get();
         Long cleanUserId = CaseContextHolder.getUserId();
         Thread.startVirtualThread(() -> CaseContextHolder.runWith(cleanCaseId, cleanUserId,
-                () -> executeCleanJobs(cleanJobs, totalTaskCount, maxConcurrency, completedTaskCount, callback)));
+                () -> executeCleanJobs(cleanJobs, totalTaskCount, maxConcurrency, completedTaskCount, callback, sheetCallback)));
         return latch;
     }
 
     private void executeCleanJobs(List<CleanJob> cleanJobs, int totalTaskCount, int maxConcurrency,
-                                  AtomicInteger completedTaskCount, TaskCompleteCallback callback) {
+                                  AtomicInteger completedTaskCount, TaskCompleteCallback callback,
+                                  SheetCompleteCallback sheetCallback) {
         Semaphore semaphore = new Semaphore(maxConcurrency, true);
         // 再往下一层虚拟线程池提交时同样要重新绑定(ThreadLocal 不会跨线程继承)
         Long caseId = CaseContextHolder.get();
@@ -962,7 +1005,7 @@ public class DmService {
             List<CompletableFuture<Void>> futures = cleanJobs.stream()
                     .map(job -> CompletableFuture.runAsync(
                             () -> CaseContextHolder.runWith(caseId, userId,
-                                    () -> executeSingleCleanJob(job, semaphore, totalTaskCount, completedTaskCount, callback, caseId)),
+                                    () -> executeSingleCleanJob(job, semaphore, totalTaskCount, completedTaskCount, callback, sheetCallback, caseId)),
                             executor))
                     .toList();
             CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
@@ -972,7 +1015,8 @@ public class DmService {
     }
 
     private void executeSingleCleanJob(CleanJob job, Semaphore semaphore, int totalTaskCount,
-                                       AtomicInteger completedTaskCount, TaskCompleteCallback callback, Long caseId) {
+                                       AtomicInteger completedTaskCount, TaskCompleteCallback callback,
+                                       SheetCompleteCallback sheetCallback, Long caseId) {
         FileInfo fileInfo = job.fileInfo();
         boolean acquired = false;
         int taskStatus = 0;
@@ -993,7 +1037,7 @@ public class DmService {
                 return;
             }
             try {
-                new CleanTask(fileInfo, job.sheetList()).doTask();
+                new CleanTask(fileInfo, job.sheetList(), sheetCallback).doTask();
                 taskStatus = 1;
             } catch (Exception e) {
                 taskStatus = 2;

+ 60 - 7
ai-server/src/test/java/com/zsjz/ai/module/aiclean/service/AiSmartCleanServiceTest.java

@@ -16,6 +16,7 @@ import com.zsjz.ai.module.aiclean.mapper.AiCleanBatchMapper;
 import com.zsjz.ai.module.aiclean.mapper.AiCleanJobMapper;
 import com.zsjz.ai.module.aiclean.match.BatchMatchCache;
 import com.zsjz.ai.module.aiclean.model.TemplateCandidate;
+import com.zsjz.ai.module.dm.clean.SheetCompleteCallback;
 import com.zsjz.ai.module.dm.mapper.FileInfoMapper;
 import com.zsjz.ai.module.dm.service.DmService;
 import com.zsjz.ai.module.govern.serivce.GovernConfService;
@@ -98,7 +99,9 @@ class AiSmartCleanServiceTest {
         jobMapper = mock(AiCleanJobMapper.class);
         governConfService = mock(GovernConfService.class);
         // 按级串行清洗走 2 参 doClean(返回完成 Latch):测试里直接给已归零的 Latch
-        when(dmService.doClean(any(DoCleanDTO.class), anyBoolean())).thenReturn(new CountDownLatch(0));
+        when(dmService.doClean(any(DoCleanDTO.class), anyBoolean(), any(SheetCompleteCallback.class)))
+                .thenReturn(new CountDownLatch(0));
+        when(dmService.flushPersonCache(any())).thenReturn(new DmService.PersonFlushResult(0, 0, 0, null));
         service = newService(batchMapper, aiCleanService, dmService);
     }
 
@@ -201,7 +204,7 @@ class AiSmartCleanServiceTest {
         // 收口消息(统计/终态/治理宣告)由 AiSmartCleanService 在 3级入库后统一推
         ArgumentCaptor<DoCleanDTO> passes = ArgumentCaptor.forClass(DoCleanDTO.class);
         InOrder inOrder = inOrder(dmService);
-        inOrder.verify(dmService, times(2)).doClean(passes.capture(), eq(true));
+        inOrder.verify(dmService, times(2)).doClean(passes.capture(), eq(true), any(SheetCompleteCallback.class));
         List<DoCleanDTO> twoPasses = passes.getAllValues();
 
         List<FileInfo> l1Sheets = twoPasses.get(0).getFileInfos().stream()
@@ -231,7 +234,7 @@ class AiSmartCleanServiceTest {
         // 时序:三条判定全归零 → 1级 → 2级 → 才允许 3级入库
         InOrder order = inOrder(aiCleanService, dmService);
         order.verify(aiCleanService, times(3)).judge(any(AiCleanJob.class), any(BatchMatchCache.class), any(BatchMatchCache.ModelGate.class));
-        order.verify(dmService, times(2)).doClean(any(DoCleanDTO.class), eq(true));
+        order.verify(dmService, times(2)).doClean(any(DoCleanDTO.class), eq(true), any(SheetCompleteCallback.class));
         order.verify(aiCleanService).loadViaAiTemplate(any(), eq(rootB), eq(s6), any(AiJudgeResult.AiPlan.class));
         assertEquals(List.of(AiCleanStageEnum.JUDGING, AiCleanStageEnum.CLEANING_EXISTING,
                 AiCleanStageEnum.LOADING_AI, AiCleanStageEnum.DONE), stages());
@@ -261,7 +264,7 @@ class AiSmartCleanServiceTest {
 
         service.run(9L, 1L, List.of(file(100L, 9L, s1, s2)));
 
-        verify(dmService, never()).doClean(any(DoCleanDTO.class), anyBoolean());
+        verify(dmService, never()).doClean(any(DoCleanDTO.class), anyBoolean(), any(SheetCompleteCallback.class));
         // 出口 B 照旧入库,不受 A 组为空影响
         verify(aiCleanService, times(1)).loadViaAiTemplate(any(), any(), eq(s2), any());
     }
@@ -274,8 +277,8 @@ class AiSmartCleanServiceTest {
 
         service.run(9L, 1L, List.of(file(100L, 9L, s1, s2)));
 
-        verify(dmService, times(1)).doClean(any(DoCleanDTO.class), eq(true));
-        verify(dmService, never()).doClean(any(DoCleanDTO.class), eq(false));
+        verify(dmService, times(1)).doClean(any(DoCleanDTO.class), eq(true), any(SheetCompleteCallback.class));
+        verify(dmService, never()).doClean(any(DoCleanDTO.class), eq(false), any(SheetCompleteCallback.class));
         verify(aiCleanService, never()).prepareJob(anyLong(), any(), any());
         verify(aiCleanService, never()).judge(any(AiCleanJob.class), any(BatchMatchCache.class), any(BatchMatchCache.ModelGate.class));
     }
@@ -380,6 +383,56 @@ class AiSmartCleanServiceTest {
                 "正常匹配模板的表也要有提取结果日志:" + logs);
     }
 
+    @Test
+    @DisplayName("日志阶段顺序:1级[匹配] → AI[匹配] → [结果] x/N → 人员库合并 → 全部完成")
+    void logPhasesAreOrdered() {
+        FileInfo s1 = sheet(1, "s1", 11);
+        s1.setTableName("人员信息");
+        FileInfo s2 = sheet(2, "s2", null);
+        given(Map.of(2L, aiPlan()));
+        when(dmService.flushPersonCache(any()))
+                .thenReturn(new DmService.PersonFlushResult(140, 8, 12, null));
+
+        CaseContextHolder.runWith(1L, 2L, () -> service.run(9L, 1L, List.of(file(100L, 9L, s1, s2))));
+
+        ArgumentCaptor<com.zsjz.ai.common.model.plat.dto.SseDTO> cap =
+                ArgumentCaptor.forClass(com.zsjz.ai.common.model.plat.dto.SseDTO.class);
+        verify(sseService, atLeastOnce()).sendSee(anyLong(), cap.capture());
+        List<String> logs = cap.getAllValues().stream()
+                .map(com.zsjz.ai.common.model.plat.dto.SseDTO::message)
+                .toList();
+
+        int l1Match = indexOf(logs, m -> m.startsWith("[匹配]")
+                && m.contains("s1") && m.contains("已匹配模板「人员信息」"));
+        int aiMatch = indexOf(logs, m -> m.startsWith("[匹配]")
+                && m.contains("s2") && m.contains("新建数据表"));
+        int l1Start = indexOf(logs, m -> m.startsWith("[清洗]")
+                && m.contains("s1") && m.contains("开始提取表格数据"));
+        int l1Result = indexOf(logs, m -> m.startsWith("[结果] (1/2)") && m.contains("s1"));
+        int aiStart = indexOf(logs, m -> m.startsWith("[清洗]")
+                && m.contains("s2") && m.contains("开始提取表格数据"));
+        int aiResult = indexOf(logs, m -> m.startsWith("[结果] (2/2)") && m.contains("s2"));
+        int merge = indexOf(logs, m -> m.contains("人员库合并完成:140 条"));
+        int objects = indexOf(logs, m -> m.contains("对象创建完成:8 个"));
+        int done = indexOf(logs, m -> m.contains("[清洗] 全部完成"));
+
+        assertTrue(l1Match >= 0 && aiMatch > l1Match, "1级匹配日志必须先于 AI 判定日志:" + logs);
+        assertTrue(l1Start > aiMatch, "匹配阶段全部结束才开始提取:" + logs);
+        assertTrue(l1Result > l1Start && aiResult > l1Result, "[结果] 按 sheet 完成顺序连续编号:" + logs);
+        assertTrue(aiStart > l1Result, "AI 入库在模板趟之后:" + logs);
+        assertTrue(merge > aiResult && objects > aiResult, "人员库/对象合并必须在全部提取之后:" + logs);
+        assertTrue(done > merge && done > objects, "最终结果最后推:" + logs);
+    }
+
+    private static int indexOf(List<String> logs, java.util.function.Predicate<String> predicate) {
+        for (int i = 0; i < logs.size(); i++) {
+            if (predicate.test(logs.get(i))) {
+                return i;
+            }
+        }
+        return -1;
+    }
+
     // ==================== ④ 重复受理 ====================
 
     /** 把「起后台线程」换成「只记不跑」,受理阶段才能被断言 */
@@ -443,7 +496,7 @@ class AiSmartCleanServiceTest {
 
         s.body.run();   // 同步跑后台那一轮
         // 1级(s1) → 2级(s4) 两趟静默 doClean;待人工的 s2 两趟都不进
-        verify(dmService, times(2)).doClean(any(DoCleanDTO.class), eq(true));
+        verify(dmService, times(2)).doClean(any(DoCleanDTO.class), eq(true), any(SheetCompleteCallback.class));
         verify(aiCleanService, times(2)).judge(any(AiCleanJob.class), any(BatchMatchCache.class), any(BatchMatchCache.ModelGate.class));
     }