Files
slp-modular-cms/aidlc-docs/features/media-library/inception/application-design/phase3-plan.md
T

83 lines
9.9 KiB
Markdown

# Phase 3: the library becomes the truth, the old Hero tables and the switches go
Status (2026-11-18): steps 3a and 3b are BUILT on `feature/media-library-phase2` (3b behind a switch that is off by default); step 3c (dropping the old table and the switches) is NOT built and NOT 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/<setHash>/...`), 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.
## As built: 3a and 3b (2026-11-18)
**3a, expand (Media migration `AddHeroPhotoColumns`, additive):** `MediaAssets` gets `SetHash`, `Variants` (the hero's own JSON), `WideFocusX/Y/Zoom`, `TallFocusX/Y/Zoom`; `MediaUses` gets `Variants`. The verified copy, the write-through and the read check fill and compare them (a difference in the set or variants shows in the library check).
**3b, the switch (Hero migration `DropSlideImageForeignKey` + switch `Media__Library__HeroPhotosInLibrary`, default off):**
- The migration drops only the foreign key `FK_HeroSlides_HeroImages_ImageId` (a slide may point at a photo that is only in `MediaAssets`). It has a `Down` that puts it back. The model snapshot is deliberately unchanged. The service layer already checks that a photo exists and is not removed while a slide uses it.
- With the switch **on**, the Hero's photo entity is mapped to the library table: rows of `MediaAssets` with module `hero` (columns `DefaultFocusX/Y/Zoom`, a `Module` column set to `hero`, a query filter on it). Everything else in the hero (services, renderer, public mapping, clean-up) is unchanged and runs on those rows. The library owns that table and its migrations; the hero's context excludes it from its own.
- `HeroImages` stays a **complete copy** while the switch is on (`HeroLegacyImageMirror` after every saved change), so switching back loses nothing.
- **Start-up guard:** with the switch on, the application refuses to start (clear message in the log) unless the library holds every photo of `HeroImages` with the same hash, set and variants. So the order is fixed: copy first, library check, then the switch.
- Public addresses, ids and hashes are unchanged; the golden files are untouched.
**Order on test (each step a deploy, SLS-Main tells Bryan):**
1. Deploy with `media_library_copy=on` (and `media_library_dual_write=on`): the migrations run and the copy fills the new columns for the existing photos. Open "Controle bibliotheek": it must say that the library matches the hero (it now also compares set and variants).
2. Deploy with `media_library_hero_photos=on`. If the guard refuses to start, the log says why; set the switch back to off.
3. Check the hero admin (upload, crop a slide, save, trash and restore) and the public site; the library check still matches.
4. Rollback at any time: `media_library_hero_photos=off` (the application reads `HeroImages` again, a complete copy). To undo the foreign-key migration too: the `Down` of `DropSlideImageForeignKey`. Last resort: the restore point of the test sites.
**Step 3c (not built):** drop `HeroImages` and the legacy mirror, remove the three media switches and the copier, make the library table the only home. Needs: Bryan's verification of 3b on test, a notice to SLS-Main with the exact migration, a fresh restore point; test only.
## Step 3c as built (2026-11-18) - on its own branch, NOT deployed
Branch `feature/media-library-phase3c` (from `feature/media-library-phase2`). It is a separate branch on purpose: dispatching `phase2` can never carry the destructive migration by accident. It is code, docs and tests only; nothing has been run on a test host.
**What it removes**
- The three migration switches and everything behind them: `Media__Library__CopyOnStartup` and the copier, `DualWrite` and the write-through (`IMediaLibrarySync`), `ReadFromLibrary` and the reader/compare mode (`IMediaLibraryReader`), `HeroPhotosInLibrary` and the legacy mirror, the start-up guard and the storage switch (`HeroStorage`, model cache key).
- The "Controle bibliotheek" panel, the `read-check` endpoint and the migration source (`IMediaMigrationSource`, `HeroMediaMigrationSource`). Bryan: keep the panel until 3b is verified on test, then remove it together with the other migration aids (so: in this step).
- The four workflow inputs (`media_library_copy`, `_dual_write`, `_read`, `_hero_photos`) and their deploy steps.
**What it makes permanent:** the hero's photos are rows of the library's `MediaAssets` (module `hero`, filter and `Module` column in the hero's model; the table and its migrations belong to the Media module). `MediaUses` is no longer written or read (it stays in the database, empty of meaning; dropping it is a later clean-up).
**The destructive migration:** Hero `DropHeroImagesTable` (`DROP TABLE HeroImages`). Protected twice:
1. `HeroImagesDropGuard` runs before the migrations at start-up: when that migration is pending and `HeroImages` holds rows, it throws (the application does not start, nothing is dropped) unless every row is in `MediaAssets` (module hero) with the same hash, set and variants, or when `MediaAssets` does not exist. A new database (nothing in `HeroImages`) passes.
2. The restore point of the test sites, taken right before the deploy.
`Down` brings back the EMPTY table (data comes from the restore point). Tested on MariaDB: refused with a missing photo, refused with a different set, dropped when the library holds everything, Down recreates the empty table.
**Order on test (needs Bryan's OK on 3b and a notice to SLS-Main with this exact migration):** (1) 3b verified: copy done, library check matches, `HeroPhotosInLibrary=on` verified by Bryan and live for a quiet period; (2) fresh restore point (Pi-Main script); (3) deploy `feature/media-library-phase3c` (the switches no longer exist; the variable `Media__Library__HeroPhotosInLibrary` in `shared/env` can stay, it is ignored); (4) check the hero admin, the public site and the library screen. Rollback: restore the restore point and deploy the previous release; `Down` only gives the empty table.
Not tested here: the deploy itself, the media directory on the Pi, the production database (never).