diff --git a/docs/superpowers/plans/2026-07-24-wms-manual-tidy-capacity.md b/docs/superpowers/plans/2026-07-24-wms-manual-tidy-capacity.md index a16842d..53957ae 100644 --- a/docs/superpowers/plans/2026-07-24-wms-manual-tidy-capacity.md +++ b/docs/superpowers/plans/2026-07-24-wms-manual-tidy-capacity.md @@ -31,7 +31,7 @@ - Produces: `CapacityResult calculate(List vehicles, int activeManualWorkflows, int maxConcurrency)`. - Produces: `int AlgorithmProperties.getTidyManualMaxConcurrency()` and `void setTidyManualMaxConcurrency(int value)`. -- [ ] **Step 1: Write failing capacity and default tests** +- [x] **Step 1: Write failing capacity and default tests** Replace assigned-vehicle assertions with literal cases proving: @@ -43,7 +43,7 @@ assertThat(capacity.calculate(unavailableVehicles, 0, 3).newSlots()).isZero(); assertThat(new AlgorithmProperties().getTidyManualMaxConcurrency()).isEqualTo(3); ``` -- [ ] **Step 2: Run tests and verify RED** +- [x] **Step 2: Run tests and verify RED** Run: @@ -53,7 +53,7 @@ mvn -pl ruoyi-admin -am -Dtest=TidyVehicleCapacityTest,AlgorithmConfigurationTes Expected: test compilation fails because the new capacity signature and property getter do not exist. -- [ ] **Step 3: Implement the minimal capacity and configuration changes** +- [x] **Step 3: Implement the minimal capacity and configuration changes** Implement: @@ -69,7 +69,7 @@ Add `tidyManualMaxConcurrency = 3` plus getter/setter to `AlgorithmProperties`, tidy-manual-max-concurrency: ${FORTUCKY_TIDY_MANUAL_MAX_CONCURRENCY:3} ``` -- [ ] **Step 4: Run focused tests and verify GREEN** +- [x] **Step 4: Run focused tests and verify GREEN** Run the command from Step 2. Expected: all specified tests pass. @@ -85,11 +85,11 @@ Run the command from Step 2. Expected: all specified tests pass. - Consumes: `TidyVehicleCapacity.calculate(vehicles, activeWorkflows, properties.getTidyManualMaxConcurrency())`. - Removes: `selectActiveManualTidyVehicleIds` and `assignTidyWorkflowVehicle` runtime mapper operations. -- [ ] **Step 1: Write a failing scheduler behavior test** +- [x] **Step 1: Write a failing scheduler behavior test** Create a scheduler with mocked database/external boundaries. Return two healthy idle vehicles, one active workflow, maximum concurrency `3`, and two planner candidates. Assert that `TidyWorkflowTransaction.start` receives both candidates in planner order. The existing implementation starts only one because it subtracts the active workflow from the already-idle snapshot. -- [ ] **Step 2: Run the scheduler test and verify RED** +- [x] **Step 2: Run the scheduler test and verify RED** Run: @@ -99,7 +99,7 @@ mvn -pl ruoyi-admin -am -Dtest=ManualTidySchedulerTest -Dsurefire.failIfNoSpecif Expected: FAIL because only one workflow is started or compilation fails until the scheduler adopts the new capacity signature. -- [ ] **Step 3: Implement scheduler ownership changes** +- [x] **Step 3: Implement scheduler ownership changes** Remove assigned-vehicle collection and the vehicle iterator. Calculate slots with the configured ceiling, iterate only planner candidates, and call: @@ -111,7 +111,7 @@ Do not update a workflow vehicle. Log a candidate-oriented warning if workflow c Remove the two unused vehicle-binding methods from `WmsAlgorithmMapper` and their MyBatis XML statements. Leave the schema column and diagnostics unchanged. -- [ ] **Step 4: Run focused tidy tests and verify GREEN** +- [x] **Step 4: Run focused tidy tests and verify GREEN** Run: @@ -130,13 +130,13 @@ Expected: all specified tests pass. **Interfaces:** - Produces: deployable `ruoyi-admin/target/ruoyi-admin.jar` and an updated handoff record. -- [ ] **Step 1: Run source and diff checks** +- [x] **Step 1: Run source and diff checks** ```powershell git diff --check ``` -- [ ] **Step 2: Run the full reactor tests** +- [x] **Step 2: Run the full reactor tests** ```powershell mvn test @@ -144,7 +144,7 @@ mvn test Expected: all reactor tests pass with zero failures and errors. -- [ ] **Step 3: Build the deployment artifact** +- [x] **Step 3: Build the deployment artifact** ```powershell mvn -DskipTests package @@ -152,10 +152,10 @@ mvn -DskipTests package Expected: all reactor modules report `SUCCESS`. -- [ ] **Step 4: Update the handoff record** +- [x] **Step 4: Update the handoff record** Record the capacity-ownership change, verification totals, JAR size, and current SHA-256. Preserve the existing statement that an actual-WCS read-only snapshot smoke test remains a deployment step. -- [ ] **Step 5: Review and commit exact files** +- [x] **Step 5: Review and commit exact files** Run `git diff --cached --check`, inspect the complete staged diff, and commit only the implementation, tests, configuration, spec/plan files that belong to this change. Verify `git show --name-status HEAD` after committing. diff --git a/docs/superpowers/specs/2026-07-24-wms-manual-tidy-capacity-design.md b/docs/superpowers/specs/2026-07-24-wms-manual-tidy-capacity-design.md index b3731b8..33859be 100644 --- a/docs/superpowers/specs/2026-07-24-wms-manual-tidy-capacity-design.md +++ b/docs/superpowers/specs/2026-07-24-wms-manual-tidy-capacity-design.md @@ -30,12 +30,16 @@ On every manual tidy reconciliation cycle, WMS first performs workflow recovery WMS asks the planner for candidates only when at least one slot exists. It starts at most the calculated number of workflows in planner order. No candidate is paired with a snapshot row, and no `vehicle_id` update is issued. WCS later receives the ordinary move job and chooses the actual vehicle using its existing dispatch rules. +The manual scheduling cycle is one database transaction. `TidyModeService.reconcile` reads the warehouse's `alg.tidy_mode` row with `UPDLOCK, HOLDLOCK`; keeping that lock until the scheduling transaction commits serializes capacity calculation and workflow creation for the same warehouse across WMS instances. Different warehouses continue to use different mode rows. + ## Failure Handling If the WCS snapshot URL is absent, the request fails, the response is empty, or the response cannot be parsed, the snapshot client returns an empty list. The calculated idle count is then zero, so WMS creates no new manual tidy workflows during that cycle. Existing workflows and WCS queues continue independently and can still complete. This fail-closed behavior avoids building an unbounded WCS queue when real-time fleet availability is unknown. Operators can distinguish this condition through the existing snapshot warning log. +If any workflow creation fails, the scheduler logs the candidate type and propagates the exception. The complete scheduling batch rolls back so a partial batch cannot consume capacity outside the locked count. The next scheduled cycle can retry from a consistent database state. + ## Compatibility The existing `alg.tidy_workflow.vehicle_id` column, SQL Server index include, and diagnostic projection remain in place for schema and historical-data compatibility. Runtime code stops reading or writing the column for new manual tidy scheduling. No WCS API or database migration is required. @@ -64,5 +68,7 @@ The implementation must prove the following behavior with tests written before p 4. Offline, unhealthy, and busy vehicles do not produce slots. 5. Manual scheduling starts workflows in planner order without reading or writing vehicle bindings. 6. The default configured maximum is `3`. +7. The scheduling cycle has a rollback transaction that holds the existing warehouse mode-row lock. +8. Workflow creation failures propagate and prevent later candidates in the same batch from starting. Focused tests must pass before running the full Maven reactor test suite and package build. diff --git a/fortucky-algorithm/src/main/java/com/ruoyi/algorithm/integration/AlgorithmProperties.java b/fortucky-algorithm/src/main/java/com/ruoyi/algorithm/integration/AlgorithmProperties.java index 2b95135..30acd0e 100644 --- a/fortucky-algorithm/src/main/java/com/ruoyi/algorithm/integration/AlgorithmProperties.java +++ b/fortucky-algorithm/src/main/java/com/ruoyi/algorithm/integration/AlgorithmProperties.java @@ -12,6 +12,7 @@ public class AlgorithmProperties { private long tidyAutoScanMs = 600_000L; private long tidyReconcileMs = 5_000L; private int tidyClaimLeaseSeconds = 60; + private int tidyManualMaxConcurrency = 3; private String tidyWcsSnapshotUrl = "http://localhost:8081/wcs2Wms/api/tidyVehicleSnapshot"; private String replayRunId = ""; private String replayDatabase = ""; @@ -62,6 +63,8 @@ public class AlgorithmProperties { public void setTidyReconcileMs(long value) { this.tidyReconcileMs = value; } public int getTidyClaimLeaseSeconds() { return tidyClaimLeaseSeconds; } public void setTidyClaimLeaseSeconds(int value) { this.tidyClaimLeaseSeconds = value; } + public int getTidyManualMaxConcurrency() { return tidyManualMaxConcurrency; } + public void setTidyManualMaxConcurrency(int value) { this.tidyManualMaxConcurrency = value; } public String getTidyWcsSnapshotUrl() { return tidyWcsSnapshotUrl; } public void setTidyWcsSnapshotUrl(String value) { this.tidyWcsSnapshotUrl = value; } public String getReplayRunId() { return replayRunId; } diff --git a/fortucky-algorithm/src/test/java/com/ruoyi/algorithm/integration/AlgorithmConfigurationTest.java b/fortucky-algorithm/src/test/java/com/ruoyi/algorithm/integration/AlgorithmConfigurationTest.java index 8580cf0..7b09366 100644 --- a/fortucky-algorithm/src/test/java/com/ruoyi/algorithm/integration/AlgorithmConfigurationTest.java +++ b/fortucky-algorithm/src/test/java/com/ruoyi/algorithm/integration/AlgorithmConfigurationTest.java @@ -47,6 +47,7 @@ class AlgorithmConfigurationTest { assertThat(properties.getTidyAutoScanMs()).isEqualTo(600_000L); assertThat(properties.getTidyReconcileMs()).isEqualTo(5_000L); assertThat(properties.getTidyClaimLeaseSeconds()).isEqualTo(60); + assertThat(properties.getTidyManualMaxConcurrency()).isEqualTo(3); assertThat(properties.getTidyWcsSnapshotUrl()).contains("tidyVehicleSnapshot"); assertThat(properties.getReplayRunId()).isBlank(); assertThat(properties.getReplayDatabase()).isBlank(); diff --git a/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/WmsAlgorithmMapper.java b/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/WmsAlgorithmMapper.java index 6216b91..620f53d 100644 --- a/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/WmsAlgorithmMapper.java +++ b/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/WmsAlgorithmMapper.java @@ -74,11 +74,6 @@ public interface WmsAlgorithmMapper { int countActiveManualTidy(@Param("warehouseId") String warehouseId); - List selectActiveManualTidyVehicleIds(@Param("warehouseId") String warehouseId); - - int assignTidyWorkflowVehicle(@Param("workflowId") String workflowId, - @Param("vehicleId") String vehicleId); - List selectInboundTaskItems(@Param("jobId") String jobId); int claimInboundSpace(@Param("reservationId") String reservationId, diff --git a/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/tidy/ManualTidyScheduler.java b/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/tidy/ManualTidyScheduler.java index daaaf27..6129a63 100644 --- a/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/tidy/ManualTidyScheduler.java +++ b/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/tidy/ManualTidyScheduler.java @@ -8,12 +8,11 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.scheduling.annotation.Scheduled; import org.springframework.stereotype.Component; +import org.springframework.transaction.annotation.Transactional; import java.time.Instant; -import java.util.HashSet; import java.util.Iterator; import java.util.List; -import java.util.Set; @Component public class ManualTidyScheduler { @@ -44,6 +43,7 @@ public class ManualTidyScheduler { } @Scheduled(fixedDelayString = "${fortucky.algorithm.tidy-reconcile-ms:5000}") + @Transactional(rollbackFor = Exception.class) public void reconcileAndFill() { if (properties.getMode() != com.ruoyi.algorithm.integration.SchedulingMode.ACTIVE || !properties.isDatabaseWritesEnabled()) return; @@ -52,26 +52,21 @@ public class ManualTidyScheduler { if (mode.effectiveState() != TidyEffectiveState.TIDY_ACTIVE || !mode.requestedEnabled()) return; List vehicles = vehicleClient.fetch(); - Set assigned = new HashSet<>(mapper.selectActiveManualTidyVehicleIds(warehouseId)); TidyVehicleCapacity.CapacityResult result = capacity.calculate( - vehicles, mapper.countActiveManualTidy(warehouseId), assigned); + vehicles, mapper.countActiveManualTidy(warehouseId), + properties.getTidyManualMaxConcurrency()); if (result.newSlots() == 0) return; - Iterator vehicleIterator = vehicles.stream() - .filter(VehicleSnapshot::availableForManualTidy) - .filter(vehicle -> !assigned.contains(vehicle.vehicleId())) - .iterator(); Iterator candidateIterator = facade.planTidy(warehouseId, Instant.now()) .candidates().iterator(); int remaining = result.newSlots(); - while (remaining-- > 0 && vehicleIterator.hasNext() && candidateIterator.hasNext()) { - VehicleSnapshot vehicle = vehicleIterator.next(); + while (remaining-- > 0 && candidateIterator.hasNext()) { TidyCandidate candidate = candidateIterator.next(); try { - var workflowId = workflows.start(TidyOrigin.MANUAL_TIDY, warehouseId, candidate); - mapper.assignTidyWorkflowVehicle(workflowId.toString(), vehicle.vehicleId()); + workflows.start(TidyOrigin.MANUAL_TIDY, warehouseId, candidate); } catch (RuntimeException ex) { - log.warn("Unable to start manual tidy workflow for vehicle {}", vehicle.vehicleId(), ex); + log.warn("Unable to start manual tidy workflow for candidate {}", candidate.type(), ex); + throw ex; } } } diff --git a/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/tidy/TidyVehicleCapacity.java b/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/tidy/TidyVehicleCapacity.java index 915a0fb..28739b2 100644 --- a/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/tidy/TidyVehicleCapacity.java +++ b/ruoyi-admin/src/main/java/com/ruoyi/algorithm/wms/tidy/TidyVehicleCapacity.java @@ -1,20 +1,18 @@ package com.ruoyi.algorithm.wms.tidy; import java.util.List; -import java.util.Set; public final class TidyVehicleCapacity { public CapacityResult calculate(List vehicles, int activeManualWorkflows, - Set assignedManualVehicleIds) { + int maxConcurrency) { int effective = (int) vehicles.stream() .filter(VehicleSnapshot::availableForManualTidy) .count(); - int assigned = assignedManualVehicleIds == null ? 0 : (int) assignedManualVehicleIds.stream() - .filter(id -> vehicles.stream().anyMatch(v -> v.vehicleId().equals(id) - && v.online() && v.healthy())) - .count(); - int available = Math.max(0, effective - Math.max(activeManualWorkflows, assigned)); - return new CapacityResult(effective, available); + if (maxConcurrency <= 0) { + return new CapacityResult(effective, 0); + } + int remainingByLimit = Math.max(0, maxConcurrency - Math.max(0, activeManualWorkflows)); + return new CapacityResult(effective, Math.min(effective, remainingByLimit)); } public record CapacityResult(int effectiveCapacity, int newSlots) { } diff --git a/ruoyi-admin/src/main/resources/application.yml b/ruoyi-admin/src/main/resources/application.yml index 2fa23fb..4ae6f76 100644 --- a/ruoyi-admin/src/main/resources/application.yml +++ b/ruoyi-admin/src/main/resources/application.yml @@ -194,6 +194,7 @@ fortucky: tidy-auto-scan-ms: ${FORTUCKY_TIDY_AUTO_SCAN_MS:600000} tidy-reconcile-ms: ${FORTUCKY_TIDY_RECONCILE_MS:5000} tidy-claim-lease-seconds: ${FORTUCKY_TIDY_CLAIM_LEASE_SECONDS:60} + tidy-manual-max-concurrency: ${FORTUCKY_TIDY_MANUAL_MAX_CONCURRENCY:3} tidy-wcs-snapshot-url: ${FORTUCKY_TIDY_WCS_SNAPSHOT_URL:http://localhost:8081/wcs2Wms/api/tidyVehicleSnapshot} replay-run-id: ${FT546_REPLAY_RUN_ID:} replay-database: ${FT546_REPLAY_DATABASE:} diff --git a/ruoyi-admin/src/main/resources/mapper/algorithm/WmsAlgorithmMapper.xml b/ruoyi-admin/src/main/resources/mapper/algorithm/WmsAlgorithmMapper.xml index 9417673..1a9c924 100644 --- a/ruoyi-admin/src/main/resources/mapper/algorithm/WmsAlgorithmMapper.xml +++ b/ruoyi-admin/src/main/resources/mapper/algorithm/WmsAlgorithmMapper.xml @@ -245,21 +245,6 @@ PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" ) - - - - update alg.tidy_workflow - set vehicle_id = #{vehicleId}, updated_at = SYSUTCDATETIME() - where workflow_id = #{workflowId} and vehicle_id is null - -