4.2 KiB
4.2 KiB
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/<setHash>/...), ids and hashes stay as they are in every step; the golden files must not change.
Prerequisites (the gate before 3b and 3c)
- Phase 2 verified on test by Bryan:
GET media-library/read-checksaysmatches: true, the library screen withReadFromLibrary=onlooks the same, crops per slide work (assumptions 47-50). - A restore point of the test sites taken right before each step (the script of Pi-Main,
test-herstelpunt.sh; path recorded inphase2-design.md), plus the row counts and a sample of ten public addresses before and after. - 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
IHeroPhotoStoreabstraction 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.