diff --git a/aidlc-docs/features/media-library/inception/application-design/phase3-plan.md b/aidlc-docs/features/media-library/inception/application-design/phase3-plan.md new file mode 100644 index 0000000..97faeb0 --- /dev/null +++ b/aidlc-docs/features/media-library/inception/application-design/phase3-plan.md @@ -0,0 +1,43 @@ +# Phase 3: the library becomes the truth, the old Hero tables and the switches go + +Status: plan only (2026-11-17). **Nothing in this plan is built or run.** Rules from Bryan, relayed by SLS-Main: build it only after phase 2 is verified on test; dropping the old tables only on TEST, with a back-up and rollback plan and a notice to SLS-Main first; never on production without a separate go from Bryan; no PR for the phase-2/3 branch before #22 is merged. + +## Where phase 2 leaves us + +- The Hero tables (`HeroImages`, `HeroSlides`) are the truth. The library tables (`MediaAssets`, `MediaUses`) mirror them (write-through, `DualWrite`) and the library screen can read them (`ReadFromLibrary`). +- The library tables do **not** hold what the Hero needs to publish: the variants of a set (`Variants`), the set hash of the photo, and the slide crops and sets as columns. So the Hero admin and the public hero still read the Hero tables. + +## What phase 3 does + +| Step | What | Reversible? | +|---|---|---| +| 3a Expand | Add to the library tables what the Hero needs: `MediaAssets.SetHash`, `MediaAssets.Variants` (JSON), the photo's crops as columns (not only the default focus), `MediaUses.Variants` (the use's own set) and its crop columns (today only the JSON in `Crops`). Additive migration of the Media module. The write-through fills them; a verified backfill copies existing rows. | Yes: drop the new columns; nothing reads them yet. | +| 3b Switch | The Hero reads and writes its photos and slides through a library store (`IMediaLibraryStore`, Core interface, implemented by the Media module) instead of `HeroImages`/`HeroSlides`: upload, crops, renderer, trash, restore, purge, public mapping, clean-up. Behind a setting (`Media:Library:HeroUsesLibrary`, default off) with the old code path kept for one release; compare mode first (both paths run, differences are logged). | Yes: switch off; the old tables are still complete as long as the write-through to them (the reverse mirror) is on. | +| 3c Contract | A separate migration drops `HeroImages`, the photo columns of `HeroSlides` and `HeroRetiredFiles` (or moves it), and the code removes the three switches (`CopyOnStartup`, `DualWrite`, `ReadFromLibrary`), the copier and the mirror. | **Only from a back-up.** TEST only until Bryan gives a separate go. | + +Public addresses (`/media/hero//...`), ids and hashes stay as they are in every step; the golden files must not change. + +## Prerequisites (the gate before 3b and 3c) + +1. Phase 2 verified on test by Bryan: `GET media-library/read-check` says `matches: true`, the library screen with `ReadFromLibrary=on` looks the same, crops per slide work (assumptions 47-50). +2. A restore point of the test sites taken right before each step (the script of Pi-Main, `test-herstelpunt.sh`; path recorded in `phase2-design.md`), plus the row counts and a sample of ten public addresses before and after. +3. SLS-Main is told before every deploy of 3a, 3b and 3c. + +## Tests to write before building 3b (can be written now against the current code) + +- The Hero service tests run through an `IHeroPhotoStore` abstraction twice, once on the Hero tables and once on an in-memory library store, and must give the same answers (upload, same photo twice, crop per slide, trash, restore, purge, clean-up, public mapping, golden files). +- A migration test on MariaDB for 3a (additive, backfill verified, rollback with `Down`). +- A contract test for 3c on MariaDB: after the drop, every Hero endpoint still answers the same (smoke test of the public hero and the admin). + +## Rollback per step + +| Step | Rollback | +|---|---| +| 3a | `Down` of the Media migration (drops the new columns). | +| 3b | `HeroUsesLibrary=off`; the old tables are complete because the old path was kept in sync. | +| 3c | Restore the database dump of the restore point, then deploy the previous release; the media directory is never changed destructively (retired sets stay for the retention time). | + +## Open points for Bryan (assumed until he says otherwise) + +- 3c is a separate release after a quiet period on test (assumption: at least a week), not part of the first rollout of phase 2. +- The clean-up job of the Hero (`HeroMediaCleanup`) moves to the library in 3b, so other modules can use the same retention rules.