docs: plan WMS shadow-only implementation

docs/superpowers/plans/2026-08-11-ft546wms-shadow-only.md

@@ -0,0 +1,155 @@
+# 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 transaction; the original Legacy procedures remain unchanged and authoritative. A reduced SQL package installs only read-model and diagnostic objects.
+
+**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.
+
+---
+
+### 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, decision log, dirty-lane queue, and three enqueue-only business-table triggers.
+- Excludes: ACTIVE mutation procedures and WMS business-table DML.
+
+- [ ] Write static SQL tests with an allow-list for tables, views, procedures, and triggers; reject 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.