Document WCX project split analysis

docs/project-split-analysis-summary.md

@@ -0,0 +1,101 @@
+# Sammanfattning: uppdelning av WCX-projektet
+
+## Databasschemarisken
+
+Den viktigaste risken före en projektuppdelning är att det versionshanterade
+databasschemat inte återskapar den databas som produktionen faktiskt använder.
+`database/wcx.db` innehåller OCR-kolumnerna `ocr_status`, `ocr_raw_text`,
+`ocr_error` och `ocr_processed_at` i tabellen `movie`, men kolumnerna saknas i
+`scripts/schema.sql`. Samtidigt förutsätter OCR-skripten och dokumentationen att
+de finns.
+
+En ny databas skapad enbart från Git blir därför inte kompatibel med hela
+facitflödet. Efter en uppdelning kan detta se ut som ett fel i den flyttade
+koden, trots att grundorsaken är ett ofullständigt schema. Facitschemat måste
+därför göras komplett och reproducerbart innan filer eller drift flyttas.
+Ändringen ska utvecklas och verifieras mot en ny, disposable databas och inte
+tillämpas blint på `database/wcx.db`.
+
+Filhanteringen har dessutom ett direkt kontrakt mot tabellerna `movie`,
+`movie_name_alias` och `movie_history`. Inkompatibla ändringar i dessa tabeller
+kan bryta det andra projektet. Detta läskontrakt behöver dokumenteras och
+versionshanteras eller åtminstone omfattas av en tydlig ändringsprocess.
+
+## Föreslagen målarkitektur
+
+Repositoryt delas i två självständiga Git-projekt:
+
+1. **Facitprojektet** äger schema, migrationsdata, webbsynkronisering, import,
+   OCR och schemalagd uppdatering. Det är ensam ägare av och enda skrivare till
+   tabellerna `movie`, `movie_history` och `movie_name_alias`.
+2. **Filhanteringsprojektet** äger filinventering, `ffprobe`-integration,
+   matchningskod, tester och matchningsdokumentation. Det läser facitdatabasen
+   genom en konfigurerbar SQLite-sökväg och ansluter strikt skrivskyddat med
+   `mode=ro`. Filsystemsrättigheter bör också neka skrivning där det är
+   praktiskt möjligt.
+
+Gränsen mellan projekten bör inledningsvis vara ett litet, dokumenterat
+SQLite-läskontrakt. Ett API eller gemensamt Python-bibliotek behövs inte för den
+nuvarande lokala användningen. Om filhanteringen senare behöver lagra lokala
+filsökvägar, manuella beslut eller bearbetningsstatus ska den få en egen
+databas. Den får referera till ett stabilt `movie.id`, men ska aldrig skriva
+lokalt tillstånd i facitdatabasen.
+
+Runtime-data ska hållas tydligt åtskild från Git-spårad kod. Den genererade
+`import/wcx_site_index.json` bör behandlas enligt ett uttryckligt beslut om
+runtime-data och normalt inte följa med som källfil till ett nytt repository.
+
+## Beslut före implementation
+
+Följande behöver avgöras innan den fysiska uppdelningen:
+
+- Ska ett korrigerat komplett grundschema vara tillräckligt, eller behövs även
+  en versionshanterad migrationsmekanism för framtida schemaändringar?
+- Var ska facitdatabasen ligga: i facitprojektets runtime-katalog eller i en
+  separat, stabil datakatalog?
+- Ska projekten köras med samma operativsystemkonto, eller ska
+  filhanteringsprocessen få ett separat konto utan skrivrättighet till facit?
+- Hur versionssätts läskontraktet, och hur samordnas inkompatibla
+  schemaändringar mellan projekten?
+- Är `movie.id` tillräckligt stabilt för framtida externa referenser från en
+  separat filhanteringsdatabas?
+- Ska `import/wcx_site_index.json` tas bort ur Git-indexet och endast genereras
+  vid körning?
+- Var finns de externa systemd-enheterna, och vilka sökvägar, miljövariabler,
+  rättigheter och låsfiler måste ändras?
+- Vilka namn och installationsplatser ska de två nya Git-projekten ha?
+- Om produktionsdatabasen ska flyttas: vilken slutlig runtime-plats,
+  backupmetod och rättighetsmodell ska användas?
+
+Direkt SQLite-läsning antas ge tillräcklig samtidighet och tillgänglighet. Om
+det antagandet inte gäller behöver arkitekturen omprövas innan implementation.
+
+## Rekommenderad migreringsordning
+
+1. **Fastställ ansvar och läskontrakt.** Dokumentera att facitprojektet är ensam
+   skrivare samt exakt vilka tabeller och kolumner filhanteringen får läsa.
+2. **Gör schemat reproducerbart.** Komplettera schemahanteringen och verifiera
+   en helt ny disposable databas, inklusive import- och OCR-operationer. Lämna
+   produktionsdatabasen orörd.
+3. **Bestäm hanteringen av genererade filer.** Rätta Git-index och
+   dokumentation om import-JSON ska vara ren runtime-data.
+4. **Gör sökvägar flyttbara i nuvarande repository.** Behåll explicita
+   kommandoradsargument, gör databassökvägar konfigurerbara och använd relativa
+   skriptsökvägar där det passar. Kontrollera även verklig systemd-konfiguration.
+5. **Tvinga fram read-only.** Byt filhanteringens anslutningar till SQLite URI
+   med `mode=ro` och verifiera både normal läsning och att skrivning nekas.
+   Använd inte `immutable=1` för en databas som uppdateras samtidigt.
+6. **Separera dokumentation och filstruktur logiskt.** Gör respektive projekt
+   självständigt begripligt och verifiera att gamla absoluta sökvägar är borta.
+7. **Skapa de två Git-projekten.** Flytta först när schema, konfiguration och
+   read-only-gräns är verifierade. Testa facitimport och filmatchning separat
+   och behåll det gamla repositoryt tills båda fungerar.
+8. **Flytta drift och systemd sist.** Kör facit manuellt från den nya platsen
+   före schemalagd produktionsdrift. Använd en säker SQLite-backupmetod om
+   databasen måste flyttas medan systemet är i bruk.
+9. **Inför en separat filhanteringsdatabas endast vid konkret behov.** Detta är
+   en senare funktionsändring, inte en förutsättning för projektuppdelningen.
+
+Schemaändring, read-only-förstärkning, filflytt och produktionsdrift bör göras
+som separata, granskningsbara förändringar så att eventuella fel går att
+isolera.