zyr/FT546MWS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add IDEA shadow deployment and rollback guide

Browse Source
This commit is contained in:
zgw
2026-08-11 19:38:26 +08:00
parent 8b050ac9d6
commit 2fbb20c5b1
5 changed files with 365 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/superpowers/specs/2026-08-11-ft546wms-shadow-only-design.md
View File

@@ -8,7 +8,7 @@ Create a clean field-test branch directly from `origin/main` that runs the Java
1. The branch is based on `origin/main` and contains no license, UI, TLS, tidy, replay, PDA, WCS callback, or ACTIVE workflow integration changes.
2. Legacy stored procedures are called exactly once with the same inputs and their return values remain authoritative.
3. Shadow planning runs before the Legacy allocation so it observes the pre-decision state, but it runs in a separate `REQUIRES_NEW` transaction with a configurable timeout.
3. Shadow planning runs before the Legacy allocation so it observes the pre-decision state, but it runs in a separate `REQUIRES_NEW`, `READ_UNCOMMITTED` transaction with a configurable timeout.
4. A shadow exception, timeout, missing optional input, missing algorithm object, or comparison logging failure is caught and logged; it cannot skip, replace, roll back, or rewrite the Legacy result.
5. No ACTIVE entry point is exposed by `ruoyi-admin`. Startup rejects any algorithm mode other than `SHADOW` when shadow observation is enabled.
6. Shadow mode writes only `alg.*` read-model and diagnostic objects. It never calls reservation, tidy, deep-workflow, replay, move-completion, or other procedures that write WMS business tables.
@@ -45,7 +45,7 @@ There are no algorithm controllers, ACTIVE schedulers, workflow callbacks, reser
## Transaction and failure isolation
Shadow planning uses `TransactionTemplate` with `PROPAGATION_REQUIRES_NEW`, read-model writes enabled, and a short timeout. The transaction completes or rolls back before Legacy allocation starts, so algorithm locks and rollback state cannot leak into the Legacy transaction. The adapter catches runtime failures at its public boundary and returns an empty observation.
Shadow planning uses `TransactionTemplate` with `PROPAGATION_REQUIRES_NEW`, `ISOLATION_READ_UNCOMMITTED`, read-model writes enabled, and a short timeout. The transaction completes or rolls back before Legacy allocation starts, so algorithm locks and rollback state cannot leak into the Legacy transaction. The adapter catches runtime failures at its public boundary and returns an empty observation.
The integration never queries `alg.tidy_mode` and never uses an update lock for admission control.
@@ -55,13 +55,13 @@ The integration never queries `alg.tidy_mode` and never uses an update lock for
- policy/read-model/diagnostic tables required by inbound and outbound planning;
- read-only views over WMS business data;
- topology, snapshot, lane-state, dirty-lane refresh, and decision-log support;
- three narrowly scoped `dbo` triggers that only enqueue affected lanes into `alg.dirty_lane_queue`;
- topology, snapshot, lane-state, full-refresh, and decision-log support;
- no triggers on any Legacy WMS table and no dirty-lane queue;
- initial read-model synchronization.
It excludes tidy, replay, reservation mutation procedures, deep workflow, outbound workflow, WCS completion, PDA callback, and any stored procedure that inserts, updates, or deletes WMS business rows.
`uninstall-shadow.sql` first removes the three `dbo` triggers, then removes only shadow-owned `alg` objects and the `alg` schema. It never modifies WMS business rows. Operators must export `alg.decision_log` before uninstalling.
`uninstall-shadow.sql` removes only shadow-owned `alg` objects and the `alg` schema. It never modifies WMS business rows. Operators must export `alg.decision_log` before uninstalling.
## Configuration
@@ -85,7 +85,7 @@ Automated tests prove:
- missing project/stock input still invokes Legacy exactly once;
- Legacy result and response structure remain authoritative;
- SHADOW configuration rejects ACTIVE mode;
- shadow SQL contains only allow-listed objects and no WMS business-table DML;
- shadow SQL contains only allow-listed `alg` objects, no triggers, and no WMS business-table DML;
- install/uninstall object lists are symmetrical;
- existing project tests and packaging still succeed.