Fase 3: plan (alleen documentatie, niets gebouwd)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 23:25:50 +01:00
co-authored by Claude Sonnet 5.5
parent e1010007fa
commit 30599c60ee
@@ -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/<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.