From f191095ac1d804745c6f5407e7b56004f010f58f Mon Sep 17 00:00:00 2001
From: qiuxiang <394405259@qq.com>
Date: Mon, 26 Oct 2026 17:35:37 +0800
Subject: [PATCH] fix: allow controlled table history backfills

---
 deploy/run-finance-batch.sh                   |  2 +-
 docs/开发与部署SOP.md                         | 12 +++++++++
 .../Deployment/FinanceBatchIsolationTest.php  | 27 +++++++++++++++++++
 3 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/deploy/run-finance-batch.sh b/deploy/run-finance-batch.sh
index eb3c5aa7..cc47643a 100644
--- a/deploy/run-finance-batch.sh
+++ b/deploy/run-finance-batch.sh
@@ -8,7 +8,7 @@ CAIWU_BATCH_CALLER_DIR="$PWD"
 export CAIWU_BATCH_CALLER_DIR
 case "${1:-}" in
     *:import|*:import-*|*:import:*|product:monthly-weighted-average:base) is_import=1 ;;
-    jushuitan:sync-shipping|store-receipt:order-match:sync|store-receipt:product-cost:sync|store-receipt:auto-resync|order-data:warm-shop-candidates|business-mirror:index-work-order-waybills|business-mirror:refresh-paid-sales|account-bills:exports:run|finance-ledger:recalculate|product:monthly-weighted-average:auto|product:monthly-weighted-average:compute|product:monthly-weighted-average:report|finance:monthly-weighted-product-cost:auto) ;;
+    jushuitan:sync-shipping|store-receipt:order-match:sync|store-receipt:product-cost:sync|store-receipt:auto-resync|order-data:warm-shop-candidates|business-mirror:sync-tables|business-mirror:index-work-order-waybills|business-mirror:refresh-paid-sales|account-bills:exports:run|finance-ledger:recalculate|product:monthly-weighted-average:auto|product:monthly-weighted-average:compute|product:monthly-weighted-average:report|finance:monthly-weighted-product-cost:auto) ;;
     *) echo 'Unsupported finance batch command' >&2; exit 64 ;;
 esac
 cd "$REMOTE_DIR"
diff --git a/docs/开发与部署SOP.md b/docs/开发与部署SOP.md
index 6011cf04..7c605a45 100644
--- a/docs/开发与部署SOP.md
+++ b/docs/开发与部署SOP.md
@@ -288,6 +288,18 @@ php artisan business-mirror:sync-tables
 
 首次全量、历史回补和镜像校准由任务 Codex 自主执行：先备份受影响的系统配置、镜像表及同步状态，再在生产同步节点内使用现有上游互斥锁，按稳定游标分批执行或续传 `--full`，直至完成并核对源表/镜像和实际页面。无需负责人另行授权或代跑命令；开发机驱动不支持时直接通过 SSH 使用生产容器，不以本机不能同步为由停止任务。后续无参数命令只执行或继续受控增量，不对无关数据集批量全量。
 
+生产同步节点对单个数据集执行历史回补时，也通过受限批入口分批续传，避免网页容器承担重型任务。每轮使用有限批次，返回“同步进行中”后以相同命令继续，直到显示“同步完成”：
+
+```bash
+sh /opt/caiwuxitong/run-finance-batch.sh business-mirror:sync-tables <dataset-key> --full --batch=500 --max-batches=20
+```
+
+首次全量完成后的定向增量去掉 `--full`，继续保留批次上限：
+
+```bash
+sh /opt/caiwuxitong/run-finance-batch.sh business-mirror:sync-tables <dataset-key> --batch=500 --max-batches=20
+```
+
 重型发货回填、业绩明细重算、商品成本重算和店铺候选全量核对，统一从生产节点使用受限任务入口：
 
 ```bash
diff --git a/tests/Unit/Deployment/FinanceBatchIsolationTest.php b/tests/Unit/Deployment/FinanceBatchIsolationTest.php
index 5cf0e2c3..be669cb8 100644
--- a/tests/Unit/Deployment/FinanceBatchIsolationTest.php
+++ b/tests/Unit/Deployment/FinanceBatchIsolationTest.php
@@ -93,4 +93,31 @@ class FinanceBatchIsolationTest extends TestCase
             rmdir($directory);
         }
     }
+
+    public function test_business_mirror_history_backfill_runs_in_the_isolated_batch_profile(): void
+    {
+        $directory = sys_get_temp_dir() . '/caiwu-mirror-batch-' . bin2hex(random_bytes(6));
+        mkdir($directory);
+        $arguments = [
+            'business-mirror:sync-tables',
+            'jiansun.dbo.fys_Ticketing_install_item',
+            '--full',
+            '--batch=500',
+            '--max-batches=20',
+        ];
+        try {
+            $process = $this->runBatch($directory, $arguments);
+            $this->assertTrue($process->isSuccessful(), $process->getErrorOutput());
+            $called = file($directory . '/called', FILE_IGNORE_NEW_LINES);
+            $this->assertContains('batch', $called);
+            $this->assertContains('--no-deps', $called);
+            $this->assertSame('image=123456789abc', $called[0]);
+            $this->assertSame($arguments, array_slice($called, -count($arguments)));
+        } finally {
+            foreach (glob($directory . '/*') as $path) {
+                unlink($path);
+            }
+            rmdir($directory);
+        }
+    }
 }
-- 
2.47.2