WCX/docs/project-split-analysis-summary.md

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.