fix: hold blocked outbound before WCS dispatch

fix: separate shadow refresh transaction timeout
fix: classify equivalent outbound no-stock results
2026-09-15 11:04:07 +08:00 · 2026-09-15 10:58:59 +08:00 · 2026-09-15 10:56:11 +08:00 · 2026-09-14 10:31:17 +08:00
23 changed files with 735 additions and 13 deletions
--- a/docs/superpowers/plans/2026-09-15-ft546wms-takeover-readiness.md
+++ b/docs/superpowers/plans/2026-09-15-ft546wms-takeover-readiness.md
@@ -0,0 +1,105 @@
+# FT546WMS Takeover Readiness Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Produce a testable candidate that reports equivalent outbound failures correctly, refreshes reliably, and never dispatches a blocked rear outbound before its relocation completes.
+
+**Architecture:** Keep Legacy as the production executor while hardening observation and dispatch safety. Separate refresh timeout from request comparison timeout; classify outbound comparisons by business meaning; enforce the relocation dependency both before WMS HTTP dispatch and, where the WCS contract permits, before WCS execution. ACTIVE takeover remains disabled until a dedicated mutation adapter and field evidence exist.
+
+**Tech Stack:** Java 17, Spring Boot, MyBatis, SQL Server 2016, JUnit 5, Mockito, PowerShell integration fixtures.
+
+**Spec:** User instruction in this thread: relocation precedes associated outbound; completion and inventory update release outbound; WCS must guard bypasses; unrelated channels continue normally.
+
+## Global Constraints
+
+- No production switch, restart, synthetic production task, or business-data mutation during implementation.
+- Existing mixed-pilot lane scope and Legacy allocation behavior remain unchanged.
+- Every behavior change follows red-green testing and is independently revertible.
+- SQL Server 2016 syntax only; no online dependency downloads are assumed.
+
+---
+
+### Task 1: Outbound comparison semantics
+
+**Files:**
+- Modify: `ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowPlanningEngineTest.java`
+- Modify: `ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowPlanningEngine.java`
+
+**Interfaces:**
+- Consumes: `OutboundShadowObservation.resultCode()` and Legacy numeric result code.
+- Produces: stable `MATCH`, `DIFFERENT`, `NOT_COMPARABLE` comparison codes while retaining raw evidence in `reason`.
+
+- [ ] Add a failing test proving shadow `ERROR_STOCK_NOT_FOUND` plus Legacy `3` is an equivalent no-inventory outcome, and successful/technical/skipped cases are not falsely matched.
+- [ ] Run only `ShadowPlanningEngineTest` and observe the exact `LEGACY_3` failure.
+- [ ] Add a private outbound comparison classifier; do not alter planning or Legacy execution.
+- [ ] Re-run focused and shadow-module tests.
+- [ ] Commit independently.
+
+### Task 2: Dedicated refresh timeout
+
+**Files:**
+- Modify: `ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowConfigurationTest.java`
+- Modify: `ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowPlanningEngineTest.java`
+- Modify: `ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowObservationProperties.java`
+- Modify: `ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowPlanningEngine.java`
+- Modify: `ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowSafetyGuard.java`
+- Modify: `ruoyi-admin/src/main/resources/application.yml`
+
+**Interfaces:**
+- Consumes: `FORTUCKY_SHADOW_REFRESH_TIMEOUT_SECONDS`, default 10 seconds.
+- Produces: a refresh-only transaction timeout; the 3-second Legacy comparison deadline stays unchanged.
+
+- [ ] Add failing property/guard tests and a transaction-manager test that distinguishes planning timeout from refresh timeout.
+- [ ] Run focused tests and observe missing property/incorrect timeout failure.
+- [ ] Use separate transaction templates or per-refresh timeout without sharing mutable template state.
+- [ ] Re-run focused and shadow-module tests.
+- [ ] Commit independently.
+
+### Task 3: WMS dispatch dependency gate
+
+**Files:**
+- Create or modify focused mapper/service files under `ruoyi-admin/src/main/java/com/ruoyi/api` and `ruoyi-admin/src/main/resources/mapper` after locating the existing job mapper contract.
+- Create: focused JUnit test for `ToWcsServiceImpl.pushOutMydoJob()`.
+- Modify: `scripts/mixed-pilot/tests/behavior.sql` only if an SQL regression is required by the confirmed race.
+
+**Interfaces:**
+- Consumes: candidate outbound job plus current lane obstruction / unresolved relocation state.
+- Produces: dispatch decision `READY` or `WAITING_FOR_RELOCATION`; only READY calls WCS and advances status.
+
+- [ ] Add a failing service test: blocked rear outbound makes zero HTTP calls, unrelated/front outbounds still dispatch, and completing relocation makes the rear job dispatch exactly once.
+- [ ] Reproduce the task-creation race in the SQL scratch fixture if it bypasses the existing status-8 trigger.
+- [ ] Add the smallest read-only pre-dispatch guard and atomic claim/update boundary supported by current service patterns.
+- [ ] Re-run Java and SQL mixed-pilot regression suites.
+- [ ] Commit independently.
+
+### Task 4: WCS defense and release candidate
+
+**Files:**
+- Modify only the actual FT546-WCS receiving/execution module identified by repository audit.
+- Add focused WCS tests at its receive or execution seam.
+- Add deployment and rollback notes under `scripts/` in each affected repository.
+
+**Interfaces:**
+- Consumes: WMS job payload and WCS current/declared dependency evidence.
+- Produces: explicit accepted/waiting/rejected behavior without treating HTTP receipt as physical completion.
+
+- [ ] Add a failing WCS test proving a blocked rear task cannot enter executable state, including manual/replayed payloads.
+- [ ] Implement the minimal defense compatible with the existing WMS/WCS contract; if WCS lacks authoritative obstruction data, reject ambiguous rear tasks rather than inventing state.
+- [ ] Run both repository test suites and inspect package contents offline.
+- [ ] Prepare versioned artifacts and rollback scripts; do not deploy or switch without a maintenance decision.
+- [ ] Request independent code review and address findings.
+
+### Task 5: ACTIVE takeover gate
+
+**Files:**
+- No production code change until Tasks 1-4 and field evidence pass.
+- Update readiness documentation with exact remaining mutation adapter and rollback requirements.
+
+**Interfaces:**
+- Consumes: verified planner result and explicit operator mode.
+- Produces: a future single-writer execution path, never simultaneous Legacy and algorithm allocation.
+
+- [ ] Preserve `ShadowSafetyGuard` rejection of ACTIVE in this candidate.
+- [ ] Define endpoint-by-endpoint single-writer tests before adding any ACTIVE mutation adapter.
+- [ ] Require fresh inbound, successful outbound, no-inventory outbound, refresh and relocation field evidence before implementation approval.
+- [ ] Do not claim formal takeover readiness merely because the candidate builds.
--- a/fortucky-algorithm/src/main/resources/db/sqlserver/install-shadow.sql
+++ b/fortucky-algorithm/src/main/resources/db/sqlserver/install-shadow.sql
@@ -756,7 +756,7 @@ BEGIN
            COUNT(*) AS space_count,
           SUM(CASE WHEN cargo.space_status = '2' OR ISNULL(stock.stock_detail_count, 0) > 0 THEN 1 ELSE 0 END) AS occupied_count,
           SUM(CASE WHEN cargo.space_status = '1'
-                     AND NULLIF(LTRIM(RTRIM(cargo.locked)), '') IS NULL
+                     AND (NULLIF(LTRIM(RTRIM(cargo.locked)), '') IS NULL OR LTRIM(RTRIM(cargo.locked)) IN ('0', 'N'))
                     AND NULLIF(LTRIM(RTRIM(cargo.tray_code)), '') IS NULL
                     AND ISNULL(stock.stock_detail_count, 0) = 0
                     AND ISNULL(role.role, 'STORAGE') = 'STORAGE'
--- a/fortucky-algorithm/src/main/resources/db/sqlserver/upgrade-shadow-v2-to-v3.sql
+++ b/fortucky-algorithm/src/main/resources/db/sqlserver/upgrade-shadow-v2-to-v3.sql
@@ -775,7 +775,7 @@ BEGIN
    SELECT cargo.warehouse_id, cargo.lane_code, COUNT(*) AS space_count,
           SUM(CASE WHEN cargo.space_status = '2' OR ISNULL(stock.stock_detail_count, 0) > 0 THEN 1 ELSE 0 END) AS occupied_count,
           SUM(CASE WHEN cargo.space_status = '1'
-                     AND NULLIF(LTRIM(RTRIM(cargo.locked)), '') IS NULL
+                     AND (NULLIF(LTRIM(RTRIM(cargo.locked)), '') IS NULL OR LTRIM(RTRIM(cargo.locked)) IN ('0', 'N'))
                     AND NULLIF(LTRIM(RTRIM(cargo.tray_code)), '') IS NULL
                     AND ISNULL(stock.stock_detail_count, 0) = 0
                     AND ISNULL(role.role, 'STORAGE') = 'STORAGE'
--- a/ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowObservationProperties.java
+++ b/ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowObservationProperties.java
@@ -9,6 +9,7 @@ public class ShadowObservationProperties {
    private boolean enabled;
    private String warehouseId = "";
    private int timeoutSeconds = 3;
+    private int refreshTimeoutSeconds = 10;
    private int snapshotMaxAgeSeconds = 60;
    private int quietIntervalMillis = 1000;

@@ -36,6 +37,14 @@ public class ShadowObservationProperties {
        this.timeoutSeconds = timeoutSeconds;
    }

+    public int getRefreshTimeoutSeconds() {
+        return refreshTimeoutSeconds;
+    }
+
+    public void setRefreshTimeoutSeconds(int refreshTimeoutSeconds) {
+        this.refreshTimeoutSeconds = refreshTimeoutSeconds;
+    }
+
    public int getSnapshotMaxAgeSeconds() {
        return snapshotMaxAgeSeconds;
    }
--- a/ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowPlanningEngine.java
+++ b/ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowPlanningEngine.java
@@ -35,17 +35,19 @@ public class ShadowPlanningEngine {
    private final SchedulingFacade schedulingFacade;
    private final ShadowInputMapper inputMapper;
    private final ShadowObservationProperties properties;
-    private final TransactionTemplate transactions;
+    private final TransactionTemplate planningTransactions;
+    private final TransactionTemplate refreshTransactions;

    public ShadowPlanningEngine(SchedulingFacade schedulingFacade, ShadowInputMapper inputMapper,
            ShadowObservationProperties properties, PlatformTransactionManager transactionManager) {
        this.schedulingFacade = Objects.requireNonNull(schedulingFacade, "schedulingFacade");
        this.inputMapper = Objects.requireNonNull(inputMapper, "inputMapper");
        this.properties = Objects.requireNonNull(properties, "properties");
-        this.transactions = new TransactionTemplate(Objects.requireNonNull(transactionManager, "transactionManager"));
-        this.transactions.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRES_NEW);
-        this.transactions.setIsolationLevel(TransactionDefinition.ISOLATION_READ_UNCOMMITTED);
-        this.transactions.setTimeout(properties.getTimeoutSeconds());
+        PlatformTransactionManager requiredTransactionManager =
+                Objects.requireNonNull(transactionManager, "transactionManager");
+        this.planningTransactions = transactionTemplate(requiredTransactionManager, properties.getTimeoutSeconds());
+        this.refreshTransactions = transactionTemplate(
+                requiredTransactionManager, properties.getRefreshTimeoutSeconds());
    }

    public InboundShadowObservation planInbound(String taskNo, String trayNo) {
@@ -68,7 +70,7 @@ public class ShadowPlanningEngine {
            throw new IllegalArgumentException("shadow snapshot instanceId is required");
        }
        String warehouseId = configuredWarehouseId();
-        return transactions.execute(status -> {
+        return refreshTransactions.execute(status -> {
            if (!inputMapper.claimInstance(warehouseId, instanceId, INSTANCE_STALE_SECONDS)) {
                throw new IllegalStateException("could not claim shadow snapshot refresh for warehouse " + warehouseId);
            }
@@ -215,7 +217,7 @@ public class ShadowPlanningEngine {
    public void compareInbound(InboundShadowObservation observation, String legacyResultCode,
            String legacySpaceId) {
        Objects.requireNonNull(observation, "observation");
-        transactions.executeWithoutResult(status -> {
+        planningTransactions.executeWithoutResult(status -> {
            validateComparisonSnapshot(observation.snapshotGeneration(), observation.warehouseId(),
                    observation.snapshotSynchronizedAt(), observation.sourceSignature());
            int inserted = inputMapper.insertComparison(
@@ -230,13 +232,13 @@ public class ShadowPlanningEngine {

    public void compareOutbound(OutboundShadowObservation observation, String legacyResultCode) {
        Objects.requireNonNull(observation, "observation");
-        transactions.executeWithoutResult(status -> {
+        planningTransactions.executeWithoutResult(status -> {
            validateComparisonSnapshot(observation.snapshotGeneration(), observation.warehouseId(),
                    observation.snapshotSynchronizedAt(), observation.sourceSignature());
            int inserted = inputMapper.insertComparison(
                    UUID.randomUUID().toString(), observation.warehouseId(), "OUTBOUND_COMPARE",
                    observation.snapshotGeneration(), observation.snapshotSynchronizedAt(),
-                    observation.sourceSignature(), "LEGACY_" + nullSafe(legacyResultCode),
+                    observation.sourceSignature(), outboundComparisonCode(observation, legacyResultCode),
                    outboundComparisonReason(observation, legacyResultCode));
            requireComparisonInserted(inserted);
        });
@@ -349,7 +351,7 @@ public class ShadowPlanningEngine {

    private <T> T planWithStableSnapshot(PublishedShadowSnapshot snapshot, Supplier<T> planner) {
        validateLeasedSnapshot(snapshot);
-        return transactions.execute(status -> {
+        return planningTransactions.execute(status -> {
            requirePublishedSnapshot(snapshot, "published snapshot changed during planning");
            T result = planner.get();
            requirePublishedSnapshot(snapshot, "published snapshot changed during planning");
@@ -357,6 +359,15 @@ public class ShadowPlanningEngine {
        });
    }

+    private TransactionTemplate transactionTemplate(
+            PlatformTransactionManager transactionManager, int timeoutSeconds) {
+        TransactionTemplate template = new TransactionTemplate(transactionManager);
+        template.setPropagationBehavior(TransactionDefinition.PROPAGATION_REQUIRES_NEW);
+        template.setIsolationLevel(TransactionDefinition.ISOLATION_READ_UNCOMMITTED);
+        template.setTimeout(timeoutSeconds);
+        return template;
+    }
+
    private void validateLeasedSnapshot(PublishedShadowSnapshot snapshot) {
        Objects.requireNonNull(snapshot, "snapshot");
        if (snapshot.generation() <= 0) {
@@ -600,6 +611,15 @@ public class ShadowPlanningEngine {
                ? result + "_CONSERVATIVE" : result;
    }

+    private String outboundComparisonCode(OutboundShadowObservation observation, String legacyCode) {
+        if (observation.observed()
+                && "ERROR_STOCK_NOT_FOUND".equals(observation.resultCode())
+                && "3".equals(legacyCode)) {
+            return "MATCH_NO_INVENTORY";
+        }
+        return "LEGACY_" + nullSafe(legacyCode);
+    }
+
    private boolean isBlank(String value) {
        return value == null || value.isBlank();
    }
--- a/ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowSafetyGuard.java
+++ b/ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowSafetyGuard.java
@@ -36,6 +36,10 @@ public class ShadowSafetyGuard implements InitializingBean {
        if (shadowProperties.getTimeoutSeconds() < 1 || shadowProperties.getTimeoutSeconds() > 30) {
            throw new IllegalStateException("Shadow observation timeout must be between 1 and 30 seconds");
        }
+        if (shadowProperties.getRefreshTimeoutSeconds() < 5
+                || shadowProperties.getRefreshTimeoutSeconds() > 60) {
+            throw new IllegalStateException("Shadow refresh timeout must be between 5 and 60 seconds");
+        }
        if (shadowProperties.getSnapshotMaxAgeSeconds() < 5
                || shadowProperties.getSnapshotMaxAgeSeconds() > 300) {
            throw new IllegalStateException("Shadow snapshot maximum age must be between 5 and 300 seconds");
--- a/ruoyi-admin/src/main/java/com/ruoyi/api/service/impl/ToWcsServiceImpl.java
+++ b/ruoyi-admin/src/main/java/com/ruoyi/api/service/impl/ToWcsServiceImpl.java
@@ -51,6 +51,11 @@ public class ToWcsServiceImpl implements IToWcsService {
        mydoJobParam.setInOut("2");
        List<MydoJob> outMydoJobs = mydoJobService.selectMydoJobListApi(mydoJobParam);
        for (MydoJob outMydoJob : outMydoJobs) {
+            // HTTP success only confirms receipt. A rear outbound stays in status 1 until
+            // every deeper position in its own lane is physically clear.
+            if (mydoJobService.isOutboundDispatchBlocked(outMydoJob.getJobId())) {
+                continue;
+            }
            RequestLog requestLog = requestLogService.getRequestLog(PUSH_OUT_MYDO_JOB, JSONUtil.toJsonStr(outMydoJob), "推送出库任务","wms","wcs");
            if ("1".equals(requestLog.getIsSuccessful())){
                outMydoJob.setStatus("3");
--- a/ruoyi-admin/src/main/java/com/ruoyi/job/mydojob/mapper/MydoJobMapper.java
+++ b/ruoyi-admin/src/main/java/com/ruoyi/job/mydojob/mapper/MydoJobMapper.java
@@ -95,4 +95,6 @@ public interface MydoJobMapper
    void updateLedError(HashMap<String, Object> map);

    Integer selectBySpare4OrCargo(InStockinDetail inStockinDetail);
+
+    int countOutboundDispatchBlockers(@Param("jobId") String jobId);
 }
--- a/ruoyi-admin/src/main/java/com/ruoyi/job/mydojob/service/IMydoJobService.java
+++ b/ruoyi-admin/src/main/java/com/ruoyi/job/mydojob/service/IMydoJobService.java
@@ -111,4 +111,7 @@ public interface IMydoJobService
    List<MydoJob> getInJobBySerial(String serial);

    void ykCompleted(MydoJob outJob);
+
+    /** True while a deeper position in the same lane blocks this outbound. */
+    boolean isOutboundDispatchBlocked(String jobId);
 }
--- a/ruoyi-admin/src/main/java/com/ruoyi/job/mydojob/service/impl/MydoJobServiceImpl.java
+++ b/ruoyi-admin/src/main/java/com/ruoyi/job/mydojob/service/impl/MydoJobServiceImpl.java
@@ -540,4 +540,9 @@ public class MydoJobServiceImpl implements IMydoJobService {
            log.info("移库任务处理成功 jobId:[{}] trayCode:[{}]", outJob.getJobId(), outJob.getTrayCode());
        }
    }
+
+    @Override
+    public boolean isOutboundDispatchBlocked(String jobId) {
+        return mydoJobMapper.countOutboundDispatchBlockers(jobId) > 0;
+    }
 }
--- a/ruoyi-admin/src/main/resources/application.yml
+++ b/ruoyi-admin/src/main/resources/application.yml
@@ -189,6 +189,7 @@ fortucky:
    enabled: ${FORTUCKY_SHADOW_ENABLED:false}
    warehouse-id: ${FORTUCKY_SHADOW_WAREHOUSE_ID:}
    timeout-seconds: ${FORTUCKY_SHADOW_TIMEOUT_SECONDS:3}
+    refresh-timeout-seconds: ${FORTUCKY_SHADOW_REFRESH_TIMEOUT_SECONDS:10}
    snapshot-max-age-seconds: ${FORTUCKY_SHADOW_SNAPSHOT_MAX_AGE_SECONDS:60}
    quiet-interval-millis: ${FORTUCKY_SHADOW_QUIET_INTERVAL_MILLIS:1000}
  algorithm:
--- a/ruoyi-admin/src/main/resources/mapper/job/MydoJobMapper.xml
+++ b/ruoyi-admin/src/main/resources/mapper/job/MydoJobMapper.xml
@@ -271,6 +271,33 @@ PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
        select * from mydo_job where task_no = #{taskNo}
    </select>

+    <select id="countOutboundDispatchBlockers" parameterType="String" resultType="int">
+        select count(1)
+        from mydo_job job
+        join bas_cargo_space source_space on source_space.cargo_space_id = job.cargo_space_id
+        where job.job_id = #{jobId}
+          and try_convert(int, job.in_or_out) &gt;= 20
+          and exists (
+              select 1
+              from bas_cargo_space outer_space
+              where outer_space.warehouse_id = source_space.warehouse_id
+                and outer_space.group_coding_no = source_space.group_coding_no
+                and try_convert(int, outer_space.group_coding) &gt; try_convert(int, source_space.group_coding)
+                and (
+                    isnull(outer_space.status, '') &lt;&gt; '1'
+                    or isnull(outer_space.locked, '') &lt;&gt; 'N'
+                    or nullif(ltrim(rtrim(outer_space.tray_code)), '') is not null
+                    or exists (select 1 from bas_stock stock where stock.cargo_space_id = outer_space.cargo_space_id)
+                    or exists (
+                        select 1 from mydo_job outer_job
+                        where outer_job.job_id &lt;&gt; job.job_id
+                          and (outer_job.cargo_space_id = outer_space.cargo_space_id
+                               or outer_job.target_cargo_space_id = outer_space.cargo_space_id)
+                    )
+                )
+          )
+    </select>
+

    <select id="allotInJobSpace" parameterType="java.util.Map"  statementType="CALLABLE">
        {call proc_allot_space(
--- a/ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowConfigurationTest.java
+++ b/ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowConfigurationTest.java
@@ -33,6 +33,7 @@ class ShadowConfigurationTest {
        assertThat(shadow.isEnabled()).isFalse();
        assertThat(shadow.getWarehouseId()).isEmpty();
        assertThat(shadow.getTimeoutSeconds()).isEqualTo(3);
+        assertThat(shadow.getRefreshTimeoutSeconds()).isEqualTo(10);
        assertThat(shadow.getSnapshotMaxAgeSeconds()).isEqualTo(60);
        assertThat(shadow.getQuietIntervalMillis()).isEqualTo(1000);
        assertThat(algorithm.getMode()).isEqualTo(SchedulingMode.SHADOW);
--- a/ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowPlanningEngineTest.java
+++ b/ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowPlanningEngineTest.java
@@ -211,6 +211,43 @@ class ShadowPlanningEngineTest {
                eq(SNAPSHOT.synchronizedAt()), eq("ABC123"), eq("LEGACY_10"), any());
    }

+    @Test
+    void outboundComparisonMatchesWhenBothPlannersReportNoInventory() {
+        ShadowInputMapper mapper = mock(ShadowInputMapper.class);
+        when(mapper.insertComparison(any(), any(), any(), any(Long.class),
+                any(Instant.class), any(), any(), any())).thenReturn(1);
+        ShadowPlanningEngine engine = engine(mock(SchedulingFacade.class), mapper);
+        OutboundShadowObservation observation = OutboundShadowObservation.unavailable(
+                SNAPSHOT, "DETAIL-1", "ERROR_STOCK_NOT_FOUND", "no matching inventory");
+
+        engine.compareOutbound(observation, "3");
+
+        verify(mapper).insertComparison(any(), eq("01"), eq("OUTBOUND_COMPARE"), eq(42L),
+                eq(SNAPSHOT.synchronizedAt()), eq("ABC123"), eq("MATCH_NO_INVENTORY"),
+                argThat(reason -> reason.contains("shadow=ERROR_STOCK_NOT_FOUND")
+                        && reason.contains("legacy=3")));
+    }
+
+    @Test
+    void outboundComparisonDoesNotMatchNoInventoryAgainstTechnicalOrDifferentOutcomes() {
+        ShadowInputMapper mapper = mock(ShadowInputMapper.class);
+        when(mapper.insertComparison(any(), any(), any(), any(Long.class),
+                any(Instant.class), any(), any(), any())).thenReturn(1);
+        ShadowPlanningEngine engine = engine(mock(SchedulingFacade.class), mapper);
+        OutboundShadowObservation technical = OutboundShadowObservation.unavailable(
+                SNAPSHOT, "DETAIL-1", "ERROR_TECHNICAL", "database failure");
+        OutboundShadowObservation noInventory = OutboundShadowObservation.unavailable(
+                SNAPSHOT, "DETAIL-2", "ERROR_STOCK_NOT_FOUND", "no matching inventory");
+
+        engine.compareOutbound(technical, "3");
+        engine.compareOutbound(noInventory, "10");
+
+        verify(mapper).insertComparison(any(), eq("01"), eq("OUTBOUND_COMPARE"), eq(42L),
+                eq(SNAPSHOT.synchronizedAt()), eq("ABC123"), eq("LEGACY_3"), any());
+        verify(mapper).insertComparison(any(), eq("01"), eq("OUTBOUND_COMPARE"), eq(42L),
+                eq(SNAPSHOT.synchronizedAt()), eq("ABC123"), eq("LEGACY_10"), any());
+    }
+
    @Test
    void inboundComparisonRetainsRequiredEvidenceWhenUnicodeReasonIsOversized() {
        ShadowInputMapper mapper = mock(ShadowInputMapper.class);
@@ -278,17 +315,23 @@ class ShadowPlanningEngineTest {

    @Test
    void refreshClaimsInstanceAndReturnsValidatedPublishedSnapshot() {
+        ShadowObservationProperties properties = properties();
+        properties.setTimeoutSeconds(3);
+        properties.setRefreshTimeoutSeconds(11);
+        CapturingTransactionManager transactions = new CapturingTransactionManager();
        ShadowInputMapper mapper = mock(ShadowInputMapper.class);
        when(mapper.claimInstance("01", "INSTANCE-1", 120)).thenReturn(true);
        PublishedShadowSnapshot refreshedSnapshot = snapshot(43L, "01");
        when(mapper.selectPublishedSnapshot("01")).thenReturn(descriptor(refreshedSnapshot));
-        ShadowPlanningEngine engine = engine(mock(SchedulingFacade.class), mapper);
+        ShadowPlanningEngine engine = new ShadowPlanningEngine(
+                mock(SchedulingFacade.class), mapper, properties, transactions);

        PublishedShadowSnapshot refreshed = engine.refreshSnapshot(43L, "INSTANCE-1");

        verify(mapper).claimInstance("01", "INSTANCE-1", 120);
        verify(mapper).refreshSnapshot("01", 43L, "INSTANCE-1");
        assertThat(refreshed).isEqualTo(refreshedSnapshot);
+        assertThat(transactions.definition.getTimeout()).isEqualTo(11);
    }

    @Test
--- a/ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowSafetyGuardTest.java
+++ b/ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowSafetyGuardTest.java
@@ -76,6 +76,22 @@ class ShadowSafetyGuardTest {
                .hasMessageContaining("between 100 and 10000");
    }

+    @Test
+    void rejectsRefreshTimeoutOutsideValidatedRange() {
+        ShadowObservationProperties shadow = enabledShadow();
+        AlgorithmProperties algorithm = new AlgorithmProperties();
+        algorithm.setMode(SchedulingMode.SHADOW);
+        algorithm.setDatabaseWritesEnabled(true);
+
+        shadow.setRefreshTimeoutSeconds(3);
+        assertThatThrownBy(() -> new ShadowSafetyGuard(shadow, algorithm).validate())
+                .hasMessageContaining("refresh timeout");
+
+        shadow.setRefreshTimeoutSeconds(61);
+        assertThatThrownBy(() -> new ShadowSafetyGuard(shadow, algorithm).validate())
+                .hasMessageContaining("refresh timeout");
+    }
+
    private ShadowObservationProperties enabledShadow() {
        ShadowObservationProperties properties = new ShadowObservationProperties();
        properties.setEnabled(true);
--- a/ruoyi-admin/src/test/java/com/ruoyi/api/service/impl/ToWcsServiceImplTest.java
+++ b/ruoyi-admin/src/test/java/com/ruoyi/api/service/impl/ToWcsServiceImplTest.java
@@ -0,0 +1,72 @@
+package com.ruoyi.api.service.impl;
+
+import com.ruoyi.job.mydojob.domain.MydoJob;
+import com.ruoyi.job.mydojob.service.IMydoJobService;
+import com.ruoyi.log.domain.RequestLog;
+import com.ruoyi.log.service.IRequestLogService;
+import org.junit.jupiter.api.Test;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import java.util.List;
+
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+class ToWcsServiceImplTest {
+
+    @Test
+    void blockedRearOutboundWaitsWithoutCallingWcsOrAdvancingStatus() {
+        IRequestLogService requests = mock(IRequestLogService.class);
+        IMydoJobService jobs = mock(IMydoJobService.class);
+        MydoJob rear = outbound("OUT-REAR", "120803");
+        when(jobs.selectMydoJobListApi(org.mockito.ArgumentMatchers.any())).thenReturn(List.of(rear));
+        when(jobs.isOutboundDispatchBlocked("OUT-REAR")).thenReturn(true);
+        ToWcsServiceImpl service = service(requests, jobs);
+
+        service.pushOutMydoJob();
+
+        verify(requests, never()).getRequestLog(anyString(), anyString(), anyString(), anyString(), anyString());
+        verify(jobs, never()).updateMydoJob(rear);
+    }
+
+    @Test
+    void unblockedOutboundDispatchesAndAdvancesExactlyOnce() {
+        IRequestLogService requests = mock(IRequestLogService.class);
+        IMydoJobService jobs = mock(IMydoJobService.class);
+        MydoJob front = outbound("OUT-FRONT", "120703");
+        when(jobs.selectMydoJobListApi(org.mockito.ArgumentMatchers.any())).thenReturn(List.of(front));
+        when(jobs.isOutboundDispatchBlocked("OUT-FRONT")).thenReturn(false);
+        RequestLog accepted = new RequestLog();
+        accepted.setIsSuccessful("1");
+        when(requests.getRequestLog(eq(ToWcsServiceImpl.PUSH_OUT_MYDO_JOB), anyString(),
+                eq("推送出库任务"), eq("wms"), eq("wcs"))).thenReturn(accepted);
+        ToWcsServiceImpl service = service(requests, jobs);
+
+        service.pushOutMydoJob();
+
+        verify(requests).getRequestLog(eq(ToWcsServiceImpl.PUSH_OUT_MYDO_JOB), anyString(),
+                eq("推送出库任务"), eq("wms"), eq("wcs"));
+        verify(jobs).updateMydoJob(front);
+        org.assertj.core.api.Assertions.assertThat(front.getStatus()).isEqualTo("3");
+    }
+
+    private ToWcsServiceImpl service(IRequestLogService requests, IMydoJobService jobs) {
+        ToWcsServiceImpl service = new ToWcsServiceImpl();
+        ReflectionTestUtils.setField(service, "requestLogService", requests);
+        ReflectionTestUtils.setField(service, "mydoJobService", jobs);
+        return service;
+    }
+
+    private MydoJob outbound(String jobId, String spaceId) {
+        MydoJob job = new MydoJob();
+        job.setJobId(jobId);
+        job.setCargoSpaceId(spaceId);
+        job.setInOrOut("21");
+        job.setStatus("1");
+        return job;
+    }
+}
--- a/scripts/dispatch-guard/test-dispatch-guard.ps1
+++ b/scripts/dispatch-guard/test-dispatch-guard.ps1
@@ -0,0 +1,44 @@
+param(
+    [string]$Server = 'lpc:.',
+    [string]$MapperFile = "$PSScriptRoot/../../ruoyi-admin/src/main/resources/mapper/job/MydoJobMapper.xml"
+)
+$ErrorActionPreference='Stop'
+[Console]::OutputEncoding=[Text.UTF8Encoding]::new($false)
+$testDb='FT546WMS_DispatchGuard_Test_'+[Guid]::NewGuid().ToString('N')
+$cn=[Data.SqlClient.SqlConnection]::new("Server=$Server;Database=master;Integrated Security=True;Connect Timeout=8;Application Name=FT546DispatchGuardTests")
+function Exec([string]$sql){$c=$cn.CreateCommand();$c.CommandTimeout=15;$c.CommandText=$sql;try{[void]$c.ExecuteNonQuery()}finally{$c.Dispose()}}
+function Scalar([string]$sql,[string]$jobId=$null){$c=$cn.CreateCommand();$c.CommandTimeout=15;$c.CommandText=$sql;if($null-ne$jobId){[void]$c.Parameters.Add('@jobId',[Data.SqlDbType]::VarChar,255);$c.Parameters['@jobId'].Value=$jobId};try{$c.ExecuteScalar()}finally{$c.Dispose()}}
+function Assert([bool]$ok,[string]$name){if(-not$ok){throw "FAIL: $name"};Write-Output "PASS: $name"}
+$created=$false
+$cn.Open()
+try{
+ $data=[string](Scalar "SELECT CONVERT(nvarchar(4000),SERVERPROPERTY('InstanceDefaultDataPath'))")
+ $log=[string](Scalar "SELECT CONVERT(nvarchar(4000),SERVERPROPERTY('InstanceDefaultLogPath'))")
+ Exec "CREATE DATABASE [$testDb] ON PRIMARY(NAME=N'$testDb',FILENAME=N'$data$testDb.mdf',SIZE=8MB,MAXSIZE=64MB) LOG ON(NAME=N'${testDb}_log',FILENAME=N'$log${testDb}_log.ldf',SIZE=8MB,MAXSIZE=64MB)"
+ $created=$true;$cn.ChangeDatabase($testDb);Exec 'SET LOCK_TIMEOUT 1500;SET DEADLOCK_PRIORITY LOW;'
+ Exec @'
+CREATE TABLE bas_cargo_space(cargo_space_id varchar(80),warehouse_id varchar(80),group_coding_no varchar(80),group_coding varchar(20),status varchar(10),locked varchar(10),tray_code varchar(80));
+CREATE TABLE bas_stock(stock_id varchar(80),cargo_space_id varchar(80));
+CREATE TABLE mydo_job(job_id varchar(255),cargo_space_id varchar(80),target_cargo_space_id varchar(80),in_or_out varchar(10));
+INSERT bas_cargo_space VALUES
+ ('REAR','01','LANE-A','1','4','N','REAR-TRAY'),('FRONT','01','LANE-A','2','2','N','FRONT-TRAY'),
+ ('OTHER-REAR','01','LANE-B','1','4','N','OTHER'),('OTHER-FRONT','01','LANE-B','2','1','N',NULL);
+INSERT bas_stock VALUES('FRONT-STOCK','FRONT');
+INSERT mydo_job VALUES('OUT-REAR','REAR',NULL,'21'),('OUT-FRONT','FRONT',NULL,'21'),('OUT-OTHER','OTHER-REAR',NULL,'21');
+'@
+ $settings=[Xml.XmlReaderSettings]::new();$settings.DtdProcessing=[Xml.DtdProcessing]::Ignore
+ $reader=[Xml.XmlReader]::Create($MapperFile,$settings);try{$xml=[Xml.XmlDocument]::new();$xml.Load($reader)}finally{$reader.Dispose()}
+ $node=$xml.SelectSingleNode("//*[local-name()='select' and @id='countOutboundDispatchBlockers']")
+ if($null-eq$node){throw 'Mapper query missing'}
+ $sql=$node.InnerText.Replace('#{jobId}','@jobId')
+ Assert ((Scalar $sql 'OUT-REAR')-gt 0) 'occupied outer position blocks rear outbound'
+ Assert ((Scalar $sql 'OUT-FRONT')-eq 0) 'front outbound is not blocked by its own lane'
+ Assert ((Scalar $sql 'OUT-OTHER')-eq 0) 'unrelated lane remains dispatchable'
+ Exec "DELETE bas_stock;DELETE mydo_job WHERE job_id='OUT-FRONT';UPDATE bas_cargo_space SET status='1',tray_code=NULL WHERE cargo_space_id='FRONT';INSERT mydo_job VALUES('MOVE-FRONT','FRONT','OTHER-FRONT','30')"
+ Assert ((Scalar $sql 'OUT-REAR')-gt 0) 'unfinished relocation keeps rear outbound waiting'
+ Exec "DELETE mydo_job WHERE job_id='MOVE-FRONT'"
+ Assert ((Scalar $sql 'OUT-REAR')-eq 0) 'confirmed relocation completion releases rear outbound'
+}finally{
+ if($created){$cn.ChangeDatabase('master');[Data.SqlClient.SqlConnection]::ClearAllPools();if($testDb-notmatch'^FT546WMS_DispatchGuard_Test_[a-f0-9]{32}$'){throw'Invalid scratch database'};Exec "DROP DATABASE [$testDb]";Write-Output "Scratch database removed: $testDb"}
+ $cn.Dispose()
+}
--- a/scripts/shadow-lane-lock/README.md
+++ b/scripts/shadow-lane-lock/README.md
@@ -0,0 +1,57 @@
+# 影子通道汇总锁定值修复（2026-09-14）
+
+现场 `locked=N` 表示未锁定；旧 `alg.usp_rebuild_lane_state` 仅接受 NULL/空白，导致通道可用数量归零。补丁让它与现有货位视图一致，接受 NULL、空白、`0`、`N`。其他占用、库存、角色、预留、出库与空洞限制全部保留。两个完整安装 SQL 也同步修正，避免以后安装重新引入问题。
+
+## 对正在运行的业务有何影响
+
+影子读取生产 `dbo` 数据，生成 `alg.*` 快照，再规划和记录比较结果。此次只 ALTER `alg.usp_rebuild_lane_state`，其运行结果写入 `alg.lane_state`。不修改生产货位的锁定值、货位状态、库存、订单或 Legacy 分配过程，不切换 ACTIVE，不需要替换 JAR 或重启 WMS/WCS。
+
+现有三通道混放试点是另外一套已批准的业务规则，本补丁不更改其范围或开关。共用 SQL Server 仍会共享 CPU、I/O、内存及锁资源，不能承诺性能影响为零；补丁使用 1.5 秒锁等待上限，等待失败退出，不结束其他会话。
+
+## 从 CMD 操作
+
+在本目录执行，使用 Windows 集成认证；账号需要读取过程定义及 ALTER 此过程的权限。默认数据库仅支持 `FT546-wms`。
+
+```bat
+repair-shadow-lane-lock.cmd -Mode Check
+```
+
+记录返回的 `sha256`。确认状态为 `NEEDS_FIX` 后，将下面的占位文字换成该值；备份文件使用全新路径（不能覆盖已有文件）：
+
+```bat
+repair-shadow-lane-lock.cmd -Mode Apply -ExpectedSha256 检查返回的sha256 -BackupFile "C:\project\FT546WMS-shadow-lane-lock-20260914\original-procedure.json"
+```
+
+返回 `status=OK` 后，等待现有影子流程在业务退出后的安静窗口正常刷新；它不是固定每隔几分钟必刷。不要手动重建正在使用的快照，也不要为此运行完整 `shadow-v3-install.cmd`。补丁不改整包版本标识，用过程哈希确认状态。`ALREADY_FIXED` 表示无需重复更新；hash mismatch 表示现场定义有变化，应先核对。锁超时或失败时事务自动回滚，已有备份保留；重试采用新的备份文件名。
+
+只读检查（SQL 查询窗口）：
+
+```sql
+SELECT snapshot_generation,snapshot_status,synchronized_at,last_error
+FROM alg.shadow_snapshot_state WHERE warehouse_id='01';
+SELECT COUNT(*) candidate_lanes,SUM(l.available_count) aggregated_available_spaces
+FROM alg.lane_state l JOIN alg.shadow_snapshot_state p
+ ON p.warehouse_id=l.warehouse_id AND p.snapshot_generation=l.snapshot_generation
+WHERE l.warehouse_id='01' AND p.snapshot_status='PUBLISHED'
+ AND l.available_count>0 AND l.pending_outbound=0 AND l.has_gap=0;
+```
+
+候选通道恢复不代表任意托盘一定能分配，也不代表完整算法可以接管。仍需新发生的真实入库/出库比较和混放移库闭环证据。
+
+## 回退
+
+重新 `Check`，将返回的当前 `sha256` 填入命令，使用 Apply 保存的原始备份。只恢复此过程原文及 ANSI/quoted 设置；有后续改动时会拒绝覆盖：
+
+```bat
+repair-shadow-lane-lock.cmd -Mode Rollback -ExpectedSha256 当前sha256 -BackupFile "C:\project\FT546WMS-shadow-lane-lock-20260914\original-procedure.json"
+```
+
+回退后下一次正常刷新会恢复旧汇总行为，包括旧的 `N` 误排除问题。既有影子记录不删除，业务数据不回退。
+
+## 隔离回归
+
+```bat
+powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File scripts\shadow-lane-lock\test-shadow-lane-lock.ps1 -TestRepair
+```
+
+从项目根目录执行。自动创建随机名称 `FT546WMS_LaneLock_Test_<GUID>` 的小型测试库，只放人工数据；不会接收生产库作为测试目标。执行两个源 SQL 中真实的 rebuild 过程，指纹计算使用明确标注的测试桩。覆盖锁值、各排除规则、跨代次、跨仓库/通道、重复刷新、修复的精确范围、哈希拒绝、重复更新、DDL 失败回滚及恢复原文。退出时删除本次测试库；此测试不验证现场托盘的实际规划效果。
--- a/scripts/shadow-lane-lock/assertions.sql
+++ b/scripts/shadow-lane-lock/assertions.sql
@@ -0,0 +1,22 @@
+IF NOT EXISTS(SELECT 1 FROM alg.lane_state WHERE warehouse_id='01' AND lane_code='UNLOCK_N' AND available_count=1)
+    THROW 51950,'locked=N must be available in the actual lane aggregate',1;
+IF (SELECT COUNT(*) FROM alg.lane_state WHERE warehouse_id='01' AND lane_code LIKE 'UNLOCK_%' AND available_count=1 AND pending_outbound=0 AND has_gap=0 AND snapshot_generation=101)<>7
+    THROW 51950,'NULL, blank, 0, N, trimmed N, released reservation and old generation must remain eligible',1;
+IF EXISTS(SELECT 1 FROM alg.lane_state WHERE warehouse_id='01' AND lane_code NOT LIKE 'UNLOCK_%' AND available_count<>0)
+    THROW 51950,'locked/unknown/occupied/tray/stock/role/reservation/outbound/gap exclusions must remain',1;
+IF NOT EXISTS(SELECT 1 FROM alg.lane_state WHERE warehouse_id='01' AND lane_code='OUTBOUND' AND pending_outbound=1 AND available_count=0)
+    THROW 51950,'outbound must exclude the entire lane',1;
+IF NOT EXISTS(SELECT 1 FROM alg.lane_state WHERE warehouse_id='01' AND lane_code='GAP' AND has_gap=1 AND available_count=0)
+    THROW 51950,'gap must exclude the entire lane',1;
+IF NOT EXISTS(SELECT 1 FROM alg.lane_state WHERE warehouse_id='01' AND lane_code='UNLOCK_N' AND space_count=1 AND occupied_count=0)
+    THROW 51950,'old generation must not pollute current counts',1;
+DECLARE @stamp datetime2=(SELECT rebuilt_at FROM alg.lane_state WHERE warehouse_id='01' AND lane_code='UNLOCK_N');
+EXEC alg.usp_rebuild_lane_state @warehouse_id='01';
+IF (SELECT rebuilt_at FROM alg.lane_state WHERE warehouse_id='01' AND lane_code='UNLOCK_N')<>@stamp
+    THROW 51950,'unchanged repeat rebuild should not rewrite lane state',1;
+EXEC alg.usp_rebuild_lane_state @warehouse_id='02';
+EXEC alg.usp_rebuild_lane_state @warehouse_id='01',@lane_code='UNLOCK_N';
+IF NOT EXISTS(SELECT 1 FROM alg.lane_state WHERE warehouse_id='02' AND lane_code='OTHER_WAREHOUSE' AND available_count=1 AND snapshot_generation=201)
+    THROW 51950,'scoped rebuild must preserve other warehouse',1;
+IF (SELECT COUNT(*) FROM alg.lane_state WHERE warehouse_id='01')<>16
+    THROW 51950,'scoped rebuild must preserve other lanes',1;
--- a/scripts/shadow-lane-lock/fixture.sql
+++ b/scripts/shadow-lane-lock/fixture.sql
@@ -0,0 +1,43 @@
+-- Only synthetic fixtures; this script is run exclusively in a randomly named scratch DB.
+CREATE TABLE alg.cargo_space_snapshot(warehouse_id varchar(80),space_id varchar(80),lane_code varchar(80),depth_raw varchar(10),space_status varchar(10),locked varchar(10),tray_code varchar(80),snapshot_generation bigint);
+CREATE TABLE alg.space_inventory_summary(warehouse_id varchar(80),space_id varchar(80),stock_detail_count int,snapshot_generation bigint);
+CREATE TABLE alg.space_role(space_id varchar(80),role varchar(40));
+CREATE TABLE alg.active_job_snapshot(warehouse_id varchar(80),source_space_id varchar(80),in_or_out varchar(10),snapshot_generation bigint);
+CREATE TABLE alg.reservation(reservation_id varchar(80),space_id varchar(80),status varchar(20));
+CREATE TABLE alg.shadow_snapshot_state(warehouse_id varchar(80),snapshot_generation bigint,snapshot_status varchar(20));
+CREATE TABLE alg.lane_state(warehouse_id varchar(80),lane_code varchar(80),space_count int,occupied_count int,available_count int,pending_outbound bit,has_gap bit,semantic_fingerprint varbinary(32),snapshot_generation bigint,rebuilt_at datetime2 DEFAULT SYSUTCDATETIME(),PRIMARY KEY(warehouse_id,lane_code));
+GO
+-- Explicit test stub: fingerprint internals are outside this aggregation regression.
+-- The actual rebuild procedure, cursor, guards and MERGE are always executed unmodified.
+CREATE PROCEDURE alg.usp_compute_lane_semantic_fingerprint
+    @warehouse_id varchar(80),@lane_code varchar(80),@semantic_fingerprint varbinary(32) OUTPUT,
+    @inventory_source varchar(20),@snapshot_generation bigint
+AS
+SET @semantic_fingerprint=HASHBYTES('SHA2_256',@warehouse_id+':'+@lane_code+':'+CONVERT(varchar(30),@snapshot_generation));
+GO
+INSERT alg.shadow_snapshot_state VALUES('01',101,'PUBLISHED'),('02',201,'PUBLISHED');
+INSERT alg.cargo_space_snapshot VALUES
+('01','N','UNLOCK_N','1','1','N',NULL,101),
+('01','ZERO','UNLOCK_ZERO','1','1','0',NULL,101),
+('01','NULL','UNLOCK_NULL','1','1',NULL,NULL,101),
+('01','BLANK','UNLOCK_BLANK','1','1','  ',NULL,101),
+('01','TRIM','UNLOCK_TRIM','1','1',' N ',NULL,101),
+('01','Y','LOCK_Y','1','1','Y',NULL,101),
+('01','UNKNOWN','LOCK_UNKNOWN','1','1','?',NULL,101),
+('01','STATUS','OCCUPIED','1','2','N',NULL,101),
+('01','TRAY','HAS_TRAY','1','1','N','T1',101),
+('01','STOCK','HAS_STOCK','1','1','N',NULL,101),
+('01','ROLE','PROTECTED','1','1','N',NULL,101),
+('01','RESERVED','RESERVED','1','1','N',NULL,101),
+('01','RELEASED','UNLOCK_RELEASED','1','1','N',NULL,101),
+('01','OUT1','OUTBOUND','1','1','N',NULL,101),
+('01','OUT2','OUTBOUND','2','1','N',NULL,101),
+('01','GAP1','GAP','1','1','N',NULL,101),
+('01','GAP2','GAP','2','2','N','T2',101),
+('01','HISTORY','UNLOCK_HISTORY','1','1','N',NULL,101),
+('01','N','UNLOCK_N','1','2','Y','OLD',100),
+('02','W2','OTHER_WAREHOUSE','1','1','N',NULL,201);
+INSERT alg.space_inventory_summary VALUES('01','STOCK',1,101),('01','HISTORY',1,100);
+INSERT alg.space_role VALUES('ROLE','BUFFER');
+INSERT alg.reservation VALUES('R1','RESERVED','ACTIVE'),('R2','RELEASED','RELEASED');
+INSERT alg.active_job_snapshot VALUES('01','OUT1','20',101),('01','HISTORY','20',100);
--- a/scripts/shadow-lane-lock/repair-shadow-lane-lock.cmd
+++ b/scripts/shadow-lane-lock/repair-shadow-lane-lock.cmd
@@ -0,0 +1,3 @@
+@echo off
+powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "%~dp0repair-shadow-lane-lock.ps1" %*
+exit /b %errorlevel%
--- a/scripts/shadow-lane-lock/repair-shadow-lane-lock.ps1
+++ b/scripts/shadow-lane-lock/repair-shadow-lane-lock.ps1
@@ -0,0 +1,136 @@
+param(
+    [string]$Server = 'lpc:.',
+    [string]$Database = 'FT546-wms',
+    [ValidateSet('Check','Apply','Rollback')][string]$Mode = 'Check',
+    [string]$ExpectedSha256,
+    [string]$BackupFile
+)
+$ErrorActionPreference='Stop'
+[Console]::OutputEncoding=[Text.UTF8Encoding]::new($false)
+if($Database -ne 'FT546-wms' -and $Database -notmatch '^FT546WMS_LaneLock_Test_[a-f0-9]{32}$') {
+    throw 'Only FT546-wms or the dedicated scratch database is supported'
+}
+if($Mode -ne 'Check' -and ($ExpectedSha256 -notmatch '^[a-fA-F0-9]{64}$' -or -not $BackupFile)) {
+    throw 'Apply/Rollback requires ExpectedSha256 and BackupFile'
+}
+$old="NULLIF(LTRIM(RTRIM(cargo.locked)), '') IS NULL"
+$new="(NULLIF(LTRIM(RTRIM(cargo.locked)), '') IS NULL OR LTRIM(RTRIM(cargo.locked)) IN ('0', 'N'))"
+function Hash([string]$value) {
+    $sha=[Security.Cryptography.SHA256]::Create()
+    try { ([BitConverter]::ToString($sha.ComputeHash([Text.Encoding]::UTF8.GetBytes($value)))).Replace('-','').ToLowerInvariant() }
+    finally { $sha.Dispose() }
+}
+function Canonical([string]$value) {
+    if($value -notmatch '(?i)\A\s*(CREATE|ALTER)\s+PROCEDURE\s+alg\.usp_rebuild_lane_state\b') {
+        throw 'Unexpected procedure header'
+    }
+    [regex]::Replace($value,'(?i)\A\s*(CREATE|ALTER)\s+PROCEDURE','ALTER PROCEDURE')
+}
+$cs=[Data.SqlClient.SqlConnectionStringBuilder]::new()
+$cs['Data Source']=$Server; $cs['Initial Catalog']=$Database; $cs['Integrated Security']=$true
+$cs['Connect Timeout']=8; $cs['Application Name']='FT546ShadowLaneLockRepair'
+$cn=[Data.SqlClient.SqlConnection]::new($cs.ConnectionString)
+$transaction=$null
+function Command([string]$sql) {
+    $cmd=$cn.CreateCommand(); $cmd.CommandTimeout=10; $cmd.CommandText=$sql
+    if($script:transaction){$cmd.Transaction=$script:transaction}
+    return $cmd
+}
+function Exec([string]$sql) {
+    $cmd=Command $sql
+    try { [void]$cmd.ExecuteNonQuery() } finally { $cmd.Dispose() }
+}
+function Scalar([string]$sql) {
+    $cmd=Command $sql
+    try { $cmd.ExecuteScalar() } finally { $cmd.Dispose() }
+}
+function ReadDefinition {
+    $cmd=Command @'
+SELECT m.definition,m.uses_ansi_nulls,m.uses_quoted_identifier
+FROM sys.sql_modules m JOIN sys.procedures p ON p.object_id=m.object_id
+WHERE p.object_id=OBJECT_ID(N'alg.usp_rebuild_lane_state',N'P');
+'@
+    try {
+        $reader=$cmd.ExecuteReader()
+        try {
+            if(-not $reader.Read() -or $reader.IsDBNull(0)){throw 'Procedure missing or encrypted'}
+            [pscustomobject]@{definition=$reader.GetString(0);ansi=$reader.GetBoolean(1);quoted=$reader.GetBoolean(2)}
+        } finally {$reader.Dispose()}
+    } finally {$cmd.Dispose()}
+}
+$cn.Open()
+try {
+    Exec 'SET NOCOUNT ON; SET XACT_ABORT ON; SET LOCK_TIMEOUT 1500; SET DEADLOCK_PRIORITY LOW;'
+    $instance=[string](Scalar 'SELECT CONVERT(nvarchar(128),SERVERPROPERTY(''ServerName''))')
+    $before=ReadDefinition
+    $beforeHash=Hash $before.definition
+    if($ExpectedSha256 -and $beforeHash -ne $ExpectedSha256){throw 'Procedure hash mismatch; recapture and review before retrying'}
+    $null=Canonical $before.definition
+    $fixedCount=([regex]::Matches($before.definition,[regex]::Escape($new))).Count
+    $oldCount=([regex]::Matches($before.definition,[regex]::Escape($old))).Count
+    if($oldCount -ne 1 -or $fixedCount -gt 1){throw 'Unexpected lock predicate; no changes made'}
+    if($Mode -eq 'Check') {
+        [ordered]@{mode=$Mode;server=$instance;database=$Database;sha256=$beforeHash;state=$(if($fixedCount -eq 1){'ALREADY_FIXED'}else{'NEEDS_FIX'});ansi=$before.ansi;quoted=$before.quoted}|ConvertTo-Json -Compress
+        return
+    }
+    if($Mode -eq 'Apply' -and $fixedCount -eq 1) {
+        [ordered]@{mode=$Mode;status='ALREADY_FIXED';sha256=$beforeHash;database_written=$false}|ConvertTo-Json -Compress
+        return
+    }
+    if($Mode -eq 'Apply') {
+        $target=(Canonical $before.definition).Replace($old,$new)
+        $backup=[ordered]@{
+            format='FT546WMS_SHADOW_LANE_LOCK_20260914';server=$instance;database=$Database
+            utc=[DateTime]::UtcNow.ToString('o');definition=$before.definition;original_sha256=$beforeHash
+            fixed_canonical_sha256=(Hash $target);ansi=$before.ansi;quoted=$before.quoted
+        }
+        # Backup is durable before beginning DDL; no existing file can be overwritten.
+        $stream=[IO.File]::Open($BackupFile,[IO.FileMode]::CreateNew,[IO.FileAccess]::Write,[IO.FileShare]::None)
+        try {
+            $bytes=[Text.Encoding]::UTF8.GetBytes(($backup|ConvertTo-Json -Depth 4))
+            $stream.Write($bytes,0,$bytes.Length);$stream.Flush($true)
+        } finally {$stream.Dispose()}
+    } else {
+        $backup=[IO.File]::ReadAllText($BackupFile)|ConvertFrom-Json
+        if($backup.format -ne 'FT546WMS_SHADOW_LANE_LOCK_20260914' -or $backup.server -cne $instance -or $backup.database -cne $Database) {
+            throw 'Backup identity mismatch'
+        }
+        if((Hash $backup.definition) -ne $backup.original_sha256){throw 'Backup integrity mismatch'}
+        if($fixedCount -ne 1 -or (Hash (Canonical $before.definition)) -ne $backup.fixed_canonical_sha256) {
+            throw 'Rollback refuses drift from the backed-up repair'
+        }
+        $target=Canonical $backup.definition
+    }
+    # Only the alg procedure is changed. No rebuild of the currently published generation,
+    # no dbo DML, no application restart, no full migration and no active session is killed.
+    $transaction=$cn.BeginTransaction()
+    $lockResult=Scalar "DECLARE @r int; EXEC @r=sys.sp_getapplock @Resource=N'FT546WMS_ShadowLaneLockRepair',@LockMode='Exclusive',@LockOwner='Transaction',@LockTimeout=0; SELECT @r;"
+    if($lockResult -lt 0){throw 'Another lane-lock repair is running'}
+    $recheck=ReadDefinition
+    if((Hash $recheck.definition) -ne $beforeHash -or $recheck.ansi -ne $before.ansi -or $recheck.quoted -ne $before.quoted) {
+        throw 'Procedure changed during preparation; no changes made'
+    }
+    # Refuse unreviewed database DDL hooks that could make ALTER write business data.
+    if((Scalar 'SELECT COUNT(*) FROM sys.triggers WHERE parent_class=0 AND is_disabled=0') -gt 0) {
+        throw 'Enabled database DDL triggers require review before this repair'
+    }
+    $ansi=if($backup.ansi){'ON'}else{'OFF'}
+    $quoted=if($backup.quoted){'ON'}else{'OFF'}
+    Exec "SET ANSI_NULLS $ansi; SET QUOTED_IDENTIFIER $quoted;"
+    $watch=[Diagnostics.Stopwatch]::StartNew()
+    Exec $target
+    $after=ReadDefinition
+    if((Canonical $after.definition) -cne $target -or $after.ansi -ne $backup.ansi -or $after.quoted -ne $backup.quoted) {
+        throw 'Definition verification failed; rolling back'
+    }
+    $transaction.Commit();$transaction.Dispose();$transaction=$null
+    $watch.Stop()
+    [ordered]@{
+        mode=$Mode;status='OK';server=$instance;database=$Database;object='alg.usp_rebuild_lane_state'
+        before_sha256=$beforeHash;after_sha256=(Hash $after.definition);ddl_ms=$watch.ElapsedMilliseconds
+        backup=$BackupFile;refresh_invoked=$false;utc=[DateTime]::UtcNow.ToString('o')
+    }|ConvertTo-Json -Compress
+} finally {
+    if($transaction){try{$transaction.Rollback()}finally{$transaction.Dispose()}}
+    $cn.Dispose()
+}
--- a/scripts/shadow-lane-lock/test-shadow-lane-lock.ps1
+++ b/scripts/shadow-lane-lock/test-shadow-lane-lock.ps1
@@ -0,0 +1,104 @@
+param(
+    [string]$Server = 'lpc:.',
+    [string]$SqlDirectory = "$PSScriptRoot/../../fortucky-algorithm/src/main/resources/db/sqlserver",
+    [switch]$TestRepair
+)
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+# This runner accepts no database name: fixtures can only enter its own tiny scratch DB.
+$testDb = 'FT546WMS_LaneLock_Test_' + [Guid]::NewGuid().ToString('N')
+$cs = [Data.SqlClient.SqlConnectionStringBuilder]::new()
+$cs['Data Source']=$Server; $cs['Initial Catalog']='master'; $cs['Integrated Security']=$true
+$cs['Connect Timeout']=8; $cs['Application Name']='FT546ShadowLaneLockTests'
+$cn = [Data.SqlClient.SqlConnection]::new($cs.ConnectionString)
+function Exec([string]$sql) {
+    $cmd=$cn.CreateCommand(); $cmd.CommandTimeout=15; $cmd.CommandText=$sql
+    try { [void]$cmd.ExecuteNonQuery() } finally { $cmd.Dispose() }
+}
+function Scalar([string]$sql) {
+    $cmd=$cn.CreateCommand(); $cmd.CommandTimeout=15; $cmd.CommandText=$sql
+    try { $cmd.ExecuteScalar() } finally { $cmd.Dispose() }
+}
+function Assert([bool]$condition,[string]$message) {
+    if(-not $condition){throw "FAIL: $message"}
+    Write-Output "PASS: $message"
+}
+function Hash([string]$value) {
+    $sha=[Security.Cryptography.SHA256]::Create()
+    try { ([BitConverter]::ToString($sha.ComputeHash([Text.Encoding]::UTF8.GetBytes($value)))).Replace('-','').ToLowerInvariant() }
+    finally { $sha.Dispose() }
+}
+function Definition { [string](Scalar "SELECT OBJECT_DEFINITION(OBJECT_ID('alg.usp_rebuild_lane_state'))") }
+function Canonical([string]$value) { [regex]::Replace($value,'(?i)\A\s*(CREATE|ALTER)\s+PROCEDURE','ALTER PROCEDURE') }
+$created=$false
+$cn.Open()
+try {
+    $dataPath=([string](Scalar "SELECT CONVERT(nvarchar(4000),SERVERPROPERTY('InstanceDefaultDataPath'))")).Replace("'","''")
+    $logPath=([string](Scalar "SELECT CONVERT(nvarchar(4000),SERVERPROPERTY('InstanceDefaultLogPath'))")).Replace("'","''")
+    Exec "CREATE DATABASE [$testDb] ON PRIMARY (NAME=N'$testDb',FILENAME=N'${dataPath}$testDb.mdf',SIZE=8MB,MAXSIZE=64MB,FILEGROWTH=8MB) LOG ON (NAME=N'${testDb}_log',FILENAME=N'${logPath}${testDb}_log.ldf',SIZE=8MB,MAXSIZE=64MB,FILEGROWTH=8MB)"
+    $created=$true; $cn.ChangeDatabase($testDb)
+    Exec 'SET NOCOUNT ON; SET LOCK_TIMEOUT 1500; SET DEADLOCK_PRIORITY LOW;'
+    Exec 'CREATE SCHEMA alg'
+    foreach($batch in ([IO.File]::ReadAllText("$PSScriptRoot/fixture.sql") -split '(?im)^\s*GO\s*\r?$')) {
+        if($batch.Trim()){ Exec $batch }
+    }
+    foreach($source in @('install-shadow.sql','upgrade-shadow-v2-to-v3.sql')) {
+        $text=[IO.File]::ReadAllText((Join-Path $SqlDirectory $source))
+        $bodies=@($text -split '(?im)^\s*GO\s*\r?$' | Where-Object {$_ -match '(?im)^\s*(CREATE|ALTER) PROCEDURE alg\.usp_rebuild_lane_state\b'})
+        Assert ($bodies.Count -eq 1) "$source has exactly one real rebuild body"
+        $body=$bodies[0]
+        $start=[regex]::Match($body,'(?im)^\s*(CREATE|ALTER) PROCEDURE alg\.usp_rebuild_lane_state\b').Index
+        $body=$body.Substring($start).Trim()
+        Exec "IF OBJECT_ID('alg.usp_rebuild_lane_state') IS NOT NULL DROP PROCEDURE alg.usp_rebuild_lane_state"
+        Exec ([regex]::Replace($body,'(?i)\A(CREATE|ALTER) PROCEDURE','CREATE PROCEDURE'))
+        Exec 'DELETE alg.lane_state'
+        Exec "EXEC alg.usp_rebuild_lane_state @warehouse_id='01'"
+        Exec ([IO.File]::ReadAllText("$PSScriptRoot/assertions.sql"))
+        Write-Output "PASS: $source actual T-SQL aggregation, exclusions, repeat and scoping"
+        if($TestRepair) {
+            $old="NULLIF(LTRIM(RTRIM(cargo.locked)), '') IS NULL"
+            $new="(NULLIF(LTRIM(RTRIM(cargo.locked)), '') IS NULL OR LTRIM(RTRIM(cargo.locked)) IN ('0', 'N'))"
+            $original=(Canonical (Definition)).Replace($new,$old)
+            Exec $original
+            $before=Definition
+            $backup=Join-Path $PSScriptRoot "$testDb-$source.backup.json"
+            $repair=Join-Path $PSScriptRoot 'repair-shadow-lane-lock.ps1'
+            try {
+                $null=& $repair -Server $Server -Database $testDb -Mode Check -ExpectedSha256 (Hash $before)
+                Assert ((Definition) -ceq $before) 'check mode leaves procedure unchanged'
+                $null=& $repair -Server $Server -Database $testDb -Mode Apply -ExpectedSha256 (Hash $before) -BackupFile $backup
+                $fixed=Definition
+                Assert ((Canonical $fixed) -ceq (Canonical $before).Replace($old,$new)) 'repair changes only the lock predicate'
+                Exec "EXEC alg.usp_rebuild_lane_state @warehouse_id='01'"
+                Exec ([IO.File]::ReadAllText("$PSScriptRoot/assertions.sql"))
+                $null=& $repair -Server $Server -Database $testDb -Mode Apply -ExpectedSha256 (Hash $fixed) -BackupFile $backup
+                Assert ((Definition) -ceq $fixed) 'repeat apply is a no-op'
+                $refused=$false
+                try { $null=& $repair -Server $Server -Database $testDb -Mode Apply -ExpectedSha256 ('0'*64) -BackupFile $backup }
+                catch { $refused=$_.Exception.Message -like '*hash mismatch*' }
+                Assert $refused 'unexpected definition is refused'
+                # Invalid ALTER must roll back atomically, including connection transaction cleanup.
+                $tx=$cn.BeginTransaction()
+                $cmd=$cn.CreateCommand(); $cmd.Transaction=$tx; $cmd.CommandText='ALTER PROCEDURE alg.usp_rebuild_lane_state AS INVALID SQL HERE'
+                $failed=$false
+                try { [void]$cmd.ExecuteNonQuery() } catch { $failed=$true } finally { $tx.Rollback();$cmd.Dispose();$tx.Dispose() }
+                Assert ($failed -and (Definition) -ceq $fixed) 'failed ALTER preserves the published procedure'
+                $null=& $repair -Server $Server -Database $testDb -Mode Rollback -ExpectedSha256 (Hash $fixed) -BackupFile $backup
+                Assert ((Canonical (Definition)) -ceq (Canonical $before)) 'rollback restores the exact original body'
+                Exec "EXEC alg.usp_rebuild_lane_state @warehouse_id='01'"
+                Assert ((Scalar "SELECT available_count FROM alg.lane_state WHERE warehouse_id='01' AND lane_code='UNLOCK_N'") -eq 0) 'rollback reproduces the original N exclusion'
+            } finally {
+                if(Test-Path -LiteralPath $backup){ Remove-Item -LiteralPath $backup }
+            }
+        }
+    }
+} finally {
+    if($created) {
+        $cn.ChangeDatabase('master')
+        [Data.SqlClient.SqlConnection]::ClearAllPools()
+        if($testDb -notmatch '^FT546WMS_LaneLock_Test_[a-f0-9]{32}$'){throw 'Invalid scratch database name'}
+        Exec "DROP DATABASE [$testDb]"
+        Write-Output "Scratch database removed: $testDb"
+    }
+    $cn.Dispose()
+}
Author	SHA1	Message	Date
zgw	58e9832b61	fix: hold blocked outbound before WCS dispatch	2026-09-15 11:04:07 +08:00
zgw	a0af05bfa2	fix: separate shadow refresh transaction timeout	2026-09-15 10:58:59 +08:00
zgw	acc6994385	fix: classify equivalent outbound no-stock results	2026-09-15 10:56:11 +08:00
zgw	8dbdd411bf	fix: recognize unlocked N lanes in shadow aggregation	2026-09-14 10:31:17 +08:00