zyr/FT546MWS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2fbb20c5b1494c6789670c0d80fd40ec01a43634
FT546MWS/docs/superpowers/plans/2026-08-11-ft546wms-shadow-only.md

9.6 KiB
Raw Blame History

FT546 WMS Shadow-Only 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: Build a clean origin/main-based branch that observes inbound and outbound allocation with the Java algorithm while preserving every Legacy decision and business write.

Architecture: Reuse the existing fortucky-algorithm planner as an internal module, but expose it to WMS only through a fail-open shadow gateway. The gateway plans in a separate timed READ_UNCOMMITTED transaction; the original Legacy procedures remain unchanged and authoritative. A reduced SQL package installs only read-model and diagnostic objects, creates no Legacy-table triggers, and refreshes its read model in full before planning.

Tech Stack: Java 17, Spring Boot, Spring JDBC transactions, MyBatis, SQL Server 2016, JUnit 5, Mockito, AssertJ, Maven 3.9.11.

Global Constraints

  • Base commit is origin/main commit 916ac6bda32a5b102a3181cc8c5dbd5319c5656d.
  • No license, TLS, Security, frontend, tidy, replay, PDA, WCS callback, reservation, or ACTIVE workflow integration changes.
  • Legacy procedures execute exactly once and their current response construction remains authoritative.
  • Shadow observation is disabled by default and fails open on every runtime error.
  • Shadow database scripts never insert, update, or delete WMS business rows.
  • Shadow database scripts never create triggers on WMS business tables.

Task 1: Import the algorithm core without unrelated WMS integration

Files:

  • Create: fortucky-algorithm/pom.xml
  • Create: fortucky-algorithm/src/main/java/com/ruoyi/algorithm/**
  • Create: fortucky-algorithm/src/test/java/com/ruoyi/algorithm/**
  • Modify: pom.xml
  • Modify: ruoyi-admin/pom.xml
  • Test: ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowModuleStructureTest.java

Interfaces:

  • Produces: WarehouseApplicationService, AlgorithmProperties, and JDBC read-model repository beans.

  • Add a Maven structure test that expects fortucky-algorithm in the reactor and ruoyi-admin dependency graph.

  • Run mvn -pl ruoyi-admin -am -Dtest=ShadowModuleStructureTest test and confirm RED because the module is absent.

  • Import only the algorithm module from 8b84459072fb21a65e11f96e97df14c5b9a340ba; do not import ruoyi-license, UI, WMS workflow, or application bootstrap changes.

  • Add the module and dependency using the existing Maven compiler and test plugin versions from origin/main.

  • Run the focused test and compile reactor; confirm GREEN.

  • Commit as feat: add algorithm core for shadow observation.

Task 2: Add the fail-open shadow planning boundary

Files:

  • Create: ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowObservationProperties.java
  • Create: ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowSafetyGuard.java
  • Create: ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowPlanningEngine.java
  • Create: ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowObservationGateway.java
  • Create: ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/InboundShadowObservation.java
  • Create: ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/OutboundShadowObservation.java
  • Create: ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/ShadowStockReference.java
  • Create: ruoyi-admin/src/main/java/com/ruoyi/algorithm/shadow/mapper/ShadowInputMapper.java
  • Create: ruoyi-admin/src/main/resources/mapper/algorithm/ShadowInputMapper.xml
  • Test: ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowObservationGatewayTest.java
  • Test: ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowPlanningEngineTest.java
  • Test: ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowSafetyGuardTest.java

Interfaces:

  • Produces: fail-open planInbound, planProjectOutbound, planExactStockOutbound, and comparison methods.

  • Guarantees: runtime failures return empty observations; planning uses PROPAGATION_REQUIRES_NEW with configured timeout.

  • Write gateway tests proving disabled/missing engine and thrown planning exceptions return empty observations.

  • Run focused tests and confirm RED because gateway types do not exist.

  • Implement immutable observation records and the fail-open gateway.

  • Run gateway tests and confirm GREEN.

  • Write engine tests capturing the transaction definition and asserting REQUIRES_NEW plus timeout.

  • Run engine tests and confirm RED.

  • Implement the planning engine, minimal input mapper, and algorithm request conversion.

  • Run engine tests and confirm GREEN.

  • Write guard tests proving enabled SHADOW starts while ACTIVE, LEGACY, and disabled database writes are rejected.

  • Run guard tests RED, implement the guard, then run GREEN.

  • Commit as feat: add fail-open shadow planning boundary.

Task 3: Preserve inbound Legacy behavior

Files:

  • Modify: ruoyi-admin/src/main/java/com/ruoyi/api/service/impl/ToWmsServiceImpl.java
  • Test: ruoyi-admin/src/test/java/com/ruoyi/api/service/impl/ToWmsServiceImplShadowTest.java

Interfaces:

  • Consumes: ShadowObservationGateway.planInbound and compareInbound.

  • Preserves: MydoJobMapper.allotInJobSpace invocation count, arguments, return handling, and reloaded Legacy job.

  • Write a success test that asserts order: shadow plan, Legacy procedure once, Legacy reload, comparison; assert returned data is the Legacy job.

  • Write a failure test where the shadow gateway throws and assert the same Legacy success result and one procedure call.

  • Run both tests and confirm RED because the service has no shadow hook.

  • Add only pre-procedure observation and post-result comparison around the existing Legacy block; catch gateway failures without changing Legacy branches.

  • Run both tests and confirm GREEN.

  • Commit as feat: observe inbound allocation without changing legacy.

Task 4: Preserve outbound Legacy behavior

Files:

  • Modify: ruoyi-admin/src/main/java/com/ruoyi/out/outStockout/service/impl/OutStockoutServiceImpl.java
  • Test: ruoyi-admin/src/test/java/com/ruoyi/out/outStockout/service/impl/OutStockoutServiceImplShadowTest.java

Interfaces:

  • Consumes: project/manual shadow planning and comparison methods.

  • Preserves: autoAllot and manualAllot calls, loop behavior, warning messages, and return codes.

  • Write automatic allocation tests proving missing project data and thrown shadow failures still call autoAllot exactly once and preserve the Legacy response.

  • Write manual allocation tests proving missing shadow stock data still calls manualAllot once per selected stock and preserves the Legacy response.

  • Run focused tests and confirm RED.

  • Add observation before each original stored-procedure call and comparison afterward without branching on shadow output.

  • Run focused tests and confirm GREEN.

  • Commit as feat: observe outbound allocation without changing legacy.

Task 5: Add the shadow-only database package

Files:

  • Create: fortucky-algorithm/src/main/resources/db/sqlserver/install-shadow.sql
  • Create: fortucky-algorithm/src/main/resources/db/sqlserver/uninstall-shadow.sql
  • Create: fortucky-algorithm/src/main/resources/db/sqlserver/diagnostics-shadow.sql
  • Test: fortucky-algorithm/src/test/java/com/ruoyi/algorithm/repository/ShadowSqlServerMigrationScriptTest.java

Interfaces:

  • Produces: read-model tables/views/procedures and decision log; planning performs a full warehouse-scoped read-model refresh.

  • Excludes: ACTIVE mutation procedures and WMS business-table DML.

  • Write static SQL tests with an allow-list for tables, views, and procedures; reject all triggers, dirty queues, tidy/workflow/replay/reservation mutation names, and business-table DML.

  • Add an install/uninstall symmetry test and a test requiring initial synchronization plus diagnostic queries.

  • Run focused tests and confirm RED because scripts are absent.

  • Build the reduced scripts from the reviewed SQL Server 2016-compatible read-model portions.

  • Run focused tests and confirm GREEN.

  • Commit as feat: add shadow-only SQL Server package.

Task 6: Add field configuration and operating guide

Files:

  • Modify: ruoyi-admin/src/main/resources/application.yml
  • Create: doc/algorithm-shadow/README.md
  • Test: ruoyi-admin/src/test/java/com/ruoyi/algorithm/shadow/ShadowConfigurationTest.java

Interfaces:

  • Produces: disabled-by-default settings and exact IDEA deploy/rollback instructions.

  • Write configuration test requiring disabled default, SHADOW mode, write-enabled read model, warehouse fallback, and three-second timeout.

  • Run test RED, add configuration, then run GREEN.

  • Document backup-copy rehearsal, IDEA dual-workspace deployment, startup checks, data export, fast application rollback, and full SQL uninstall rollback.

  • Commit as docs: add IDEA shadow deployment and rollback guide.

Task 7: Review, verify, and publish

Files:

  • Review all changes relative to origin/main.

Interfaces:

  • Produces: pushed branch test/ft546wms-shadow-from-main-20260811.

  • Run focused shadow tests.

  • Run full Maven tests with Maven 3.9.11.

  • Run mvn package -DskipTests and calculate the JAR SHA-256.

  • Audit git diff --name-status origin/main...HEAD and confirm no forbidden runtime areas changed.

  • Request independent code review; fix every Critical and Important finding.

  • Re-run full tests and package after review fixes.

  • Push the branch to origin and retain the worktree for field-test feedback.

Reference in New Issue View Git Blame Copy Permalink