# Analys och migreringsplan för uppdelning av WCX-projektet ## 1. Syfte och avgränsning Detta dokument beskriver hur det nuvarande WCX-repositoryt kan delas upp i två separata Git-projekt: 1. ett facitprojekt som underhåller och äger filmmetadata i SQLite, och 2. ett filhanteringsprojekt som inventerar och matchar lokala videofiler. Den grundläggande ägargränsen är att endast facitprojektet får skriva till facitdatabasen. Filhanteringsprojektet får läsa den direkt, men anslutningen ska vara strikt skrivskyddad. Filhanteringen kan senare få en egen databas för lokala filer och matchningsbeslut. Ett API eller ett gemensamt Python-bibliotek ingår inte i den föreslagna lösningen. Ett sådant lager bör införas först om konkreta framtida behov visar att direkt, skrivskyddad SQLite-läsning inte räcker. Märkningarna i dokumentet betyder: - **Verifierat faktum:** observerat i nuvarande repository eller databas. - **Antagande:** rimlig utgångspunkt som behöver bekräftas. - **Rekommendation:** föreslagen riktning, inte ett redan fattat beslut. - **Ej fattat beslut:** en fråga som måste avgöras före eller under migreringen. ## 2. Nulägesanalys ### 2.1 Repositorystruktur **Verifierat faktum:** Repositoryt innehåller följande huvudsakliga delar: ```text WCX/ ├── README.md ├── database/ │ ├── wcx.db │ ├── wcx-test.db │ ├── wcx-before-csv-migration.db │ ├── update_wcx.lock │ └── last_scheduled_update ├── import/ │ └── wcx_site_index.json ├── migration/ │ └── persons.utf8bom.csv ├── docs/ │ ├── filename-matching-requirements.md │ └── filename-matching-requirements-prompt.md └── scripts/ ├── schema.sql ├── wcx_sync.py ├── import_site.py ├── migrate_csv.py ├── update_wcx.sh ├── scheduled_update_wcx.sh ├── process_pending_ocr.py ├── check_ocr.py ├── ocr.sh ├── parse_ocr.py ├── match_filenames.py └── test_duration_matching.py ``` **Verifierat faktum:** Produktionsdatabasen och databasens test- och säkerhetskopior finns lokalt under `database/` och matchar repositoryts ignore-regler för `database/*.db`. **Verifierat faktum:** `import/wcx_site_index.json` är spårad av Git trots att README anger att `import/*.json` är genererade filer som inte ska versionshanteras. En ignore-regel slutar inte spåra en fil som redan finns i Git-indexet. **Verifierat faktum:** README beskriver huvudsakligen uppbyggnad och underhåll av facitdatabasen. Kraven för filnamnsmatchning ligger separat under `docs/`. ### 2.2 Identifierade ansvarsområden Facitunderhåll omfattar: - hämtning av webbplatsens metadata, - import och historisering av webbplatsdata, - initialt schema och framtida schemaförändringar, - återställning eller komplettering från historisk CSV, - OCR och validering av OCR-resultat, - manuellt eller automatiskt underhållen filmmetadata, - schemalagd körning och exklusiv rätt att skriva facitdatabasen. Filhantering omfattar: - inventering av lokala videofiler, - läsning av filmetadata med `ffprobe`, - normalisering och matchning av filnamn, - jämförelse med aktuella namn, alias och historiska längder, - rapportering av säkra, tvetydiga och uteblivna matchningar, - senare eventuell lagring av lokal filstatus i en separat databas. **Verifierat faktum:** Nuvarande implementation har redan en naturlig gräns: facitskripten skriver SQLite-data, medan matchningsskripten endast utför `SELECT` och inte importerar kod från facitskripten. ## 3. Klassificering av skript och data ### 3.1 Facitunderhåll **Verifierat faktum:** Följande filer hör till facitunderhåll: | Fil | Ansvar | | --- | --- | | `scripts/schema.sql` | Definierar tabeller och index. | | `scripts/wcx_sync.py` | Hämtar WCX-metadata och skriver ett JSON-index. | | `scripts/import_site.py` | Infogar och uppdaterar `movie` samt arkiverar tidigare värden i `movie_history`. | | `scripts/migrate_csv.py` | Validerar historisk CSV och kan infoga eller uppdatera `movie`. | | `scripts/process_pending_ocr.py` | Läser väntande OCR-poster och startar behandling. | | `scripts/check_ocr.py` | Läser en filmpost och skriver OCR-resultat och status till `movie`. | | `scripts/ocr.sh` | Anropar Google Vision för en bild. | | `scripts/parse_ocr.py` | Tolkar OCR-text; använder inte databasen direkt. | | `scripts/update_wcx.sh` | Orkestrerar synkronisering, import och OCR. | | `scripts/scheduled_update_wcx.sh` | Begränsar och startar schemalagda facituppdateringar. | | `migration/persons.utf8bom.csv` | Historisk, versionshanterad metadatakälla. | **Rekommendation:** Dessa filer bör tillsammans med en renodlad facit-README flyttas till facitprojektet. ### 3.2 Filhantering **Verifierat faktum:** Följande filer hör till filhantering: | Fil | Ansvar | | --- | --- | | `scripts/match_filenames.py` | Läser videofiler och facitdata, kör `ffprobe` och klassificerar matchningar. | | `scripts/test_duration_matching.py` | Diagnostiserar en fils längd mot aktuell och historisk facitlängd. | | `docs/filename-matching-requirements.md` | Kravspecifikation för matchning. | | `docs/filename-matching-requirements-prompt.md` | Historiskt arbets- och kravunderlag för matchningen. | **Rekommendation:** `match_filenames.py`, dess tester och den relevanta dokumentationen bör flyttas tillsammans till filhanteringsprojektet. **Ej fattat beslut:** Det behöver avgöras om `filename-matching-requirements-prompt.md` ska följa med som historiskt arbetsmaterial, arkiveras eller utelämnas ur det nya projektet. ## 4. Nuvarande beroenden ### 4.1 Facitflöde **Verifierat faktum:** Den schemalagda körkedjan är: ```text scheduled_update_wcx.sh → update_wcx.sh → wcx_sync.py → import_site.py → process_pending_ocr.py → check_ocr.py → ocr.sh → parse_ocr.py ``` Webbplatsens data flödar enligt följande: ```text WCX-webbplats → wcx_sync.py → import/wcx_site_index.json → import_site.py → database/wcx.db ``` `import_site.py`, `migrate_csv.py` och `check_ocr.py` har avsiktliga databasskrivningar. `process_pending_ocr.py` läser databasen direkt och låter `check_ocr.py` utföra skrivningarna. ### 4.2 Filhanteringens facitberoende **Verifierat faktum:** `match_filenames.py` läser följande minimala databaskontrakt: ```text movie: id name duration_seconds movie_name_alias: movie_id alias normalized_alias source movie_history: movie_id duration_seconds archived_at ``` `test_duration_matching.py` läser `movie.id`, `movie.duration_seconds` och historiska längder ur `movie_history`. **Verifierat faktum:** Matchningen har inga gemensamma Python-importer med facitunderhållet. Kopplingen består av SQLite-databasens placering och schema. **Verifierat faktum:** `match_filenames.py` och `test_duration_matching.py` använder vanlig `sqlite3.connect(path)`. Deras SQL är för närvarande endast läsande, men SQLite-anslutningen tvingar inte fram read-only-läge. **Rekommendation:** Filhanteringsprojektet ska öppna databasen med SQLite URI och `mode=ro`. Filsystemsrättigheter bör om möjligt också neka den process som kör filhanteringen skrivrättighet till facitdatabasen. ### 4.3 Hårdkodade sökvägar **Verifierat faktum:** Följande produktionssökvägar är hårdkodade: - `check_ocr.py`: databas, `ocr.sh` och `parse_ocr.py` under `/storage/disk1/WCX`. - `process_pending_ocr.py`: databas och `check_ocr.py` under `/storage/disk1/WCX`. - `import_site.py`: import-JSON och databas under `/storage/disk1/WCX`. - `migrate_csv.py`: migrations-CSV och databas under `/storage/disk1/WCX`. - `update_wcx.sh` och `scheduled_update_wcx.sh`: `ROOT_DIR=/storage/disk1/WCX`. - `match_filenames.py` och `test_duration_matching.py`: `/storage/disk1/WCX/database/wcx.db`. **Verifierat faktum:** `wcx_sync.py` har `/storage/disk1/X/wcx_index.json` som eget standardutdata, medan `update_wcx.sh` skickar den avsedda sökvägen `/storage/disk1/WCX/import/wcx_site_index.json` explicit. **Verifierat faktum:** README och matchningsdokumenten innehåller också flera absoluta sökvägar till nuvarande repository. ## 5. Identifierat schemaproblem **Verifierat faktum:** Den faktiska `database/wcx.db` innehåller tabellerna `movie`, `movie_history` och `movie_name_alias`. **Verifierat faktum:** Den faktiska tabellen `movie` innehåller dessutom följande OCR-kolumner: ```text ocr_status ocr_raw_text ocr_error ocr_processed_at ``` **Verifierat faktum:** Dessa fyra kolumner saknas i nuvarande `scripts/schema.sql`, trots att facitskripten och README förutsätter att de finns. Konsekvensen är att en ny databas som skapas enbart från det versionshanterade schemat inte är kompatibel med hela facitflödet. Vid en projektuppdelning kan detta orsaka svårdiagnostiserade fel: den flyttade koden kan verka felaktig trots att den verkliga orsaken är att Git inte innehåller ett komplett, reproducerbart schema. **Rekommendation:** Gör facitdatabasens schema reproducerbart innan den fysiska projektuppdelningen. Ändringen ska utvecklas och verifieras mot en ny, disposable databas och får inte tillämpas blint på `database/wcx.db`. **Ej fattat beslut:** Det behöver avgöras om nuvarande databas kan beskrivas av ett korrigerat komplett grundschema, eller om projektet även behöver en versionshanterad migrationsmekanism för framtida schemaändringar. ## 6. Risker och öppna frågor ### 6.1 Risker 1. **Oavsiktliga databasskrivningar från filhanteringen.** Nuvarande kod är läsande men anslutningen är inte tekniskt read-only. 2. **Schemaändringar bryter konsumenten.** Filhanteringen beror direkt på tre facittabeller och ett begränsat antal kolumner. 3. **Ofullständigt schema ger icke reproducerbara installationer.** OCR-flödet kan inte byggas upp korrekt från nuvarande `schema.sql`. 4. **Hårdkodade sökvägar bryts vid flytt.** Både Python-, shell- och externa systemd-konfigurationer kan peka på den gamla platsen. 5. **Felaktig kopiering av en aktiv SQLite-databas.** Om WAL används kan en kopia av endast `.db` bli inkonsekvent. `immutable=1` är inte lämpligt för en databas som facitprojektet fortsätter uppdatera. 6. **Otydligt dataägarskap.** Alias och historiska längder används av filhanteringen men måste fortsatt ägas av facitprojektet. 7. **Genererad JSON är spårad.** Den kan oavsiktligt följa med som källfil till ett nytt repository. 8. **Tester beror på lokal produktionslik data.** Det saknas ett isolerat, reproducerbart testunderlag för hela gränsen mellan projekten. 9. **Driftkonfiguration ligger utanför Git.** README hänvisar till systemd- enheter som inte finns i repositoryt och kan innehålla fler absoluta sökvägar. ### 6.2 Öppna frågor - **Ej fattat beslut:** Var ska facitdatabasen ligga efter uppdelningen: under facitprojektets runtime-katalog eller i en separat stabil datakatalog? - **Ej fattat beslut:** Ska båda projekten köras av samma operativsystemkonto, eller ska filhanteringen få ett konto som saknar skrivrättighet till facit? - **Ej fattat beslut:** Hur ska databasens läskontrakt versionssättas och hur ska inkompatibla schemaändringar kommuniceras mellan projekten? - **Ej fattat beslut:** Ska `import/wcx_site_index.json` tas bort ur Git-indexet och endast genereras vid körning? - **Ej fattat beslut:** Var finns systemd-enheterna, och vilka sökvägar måste uppdateras när facitprojektet flyttas? - **Antagande:** `movie.id` är en stabil identitet som en framtida separat filhanteringsdatabas kan referera till. - **Antagande:** Direkt SQLite-läsning ger tillräcklig samtidighet och tillgänglighet för den aktuella lokala användningen. ## 7. Rekommenderad målarkitektur ### 7.1 Facitprojekt **Rekommendation:** Facitprojektet ska innehålla schema, migrationsdata, webbsynkronisering, import, OCR och schemalagd uppdatering. Det ska vara ensam ägare av följande data: ```text movie movie_history movie_name_alias ``` Det ska vara den enda komponent som har rätt att skriva facitdatabasen. Runtime-data bör hållas tydligt åtskild från Git-spårad källkod, även om den fysiskt ligger nära projektet. ### 7.2 Filhanteringsprojekt **Rekommendation:** Filhanteringsprojektet ska innehålla matchningskod, `ffprobe`-integration, tester och matchningsdokumentation. Databasens sökväg ska vara konfigurerbar och anslutningen strikt read-only. Filhanteringen ska inte skapa alias, historik eller matchningsposter i facitdatabasen. Om beständigt tillstånd senare behövs ska en separat databas ägas av filhanteringsprojektet. Den kan referera till facitets stabila `movie.id`, men får inte använda främmande nycklar som kräver skrivning i eller tät koppling till facitfilen. ### 7.3 Gräns mellan projekten **Rekommendation:** Den initiala gränsen ska vara ett litet dokumenterat SQLite-läskontrakt, inte ett API och inte ett gemensamt Python-bibliotek. ```text facitprojekt ── skriver ──> facit.sqlite │ └── strikt read-only ──> filhanteringsprojekt filhanteringsprojekt ── kan senare skriva ──> egen filhanteringsdatabas ``` Facitprojektet ska kunna ändra intern implementation fritt så länge det dokumenterade läskontraktet förblir kompatibelt, eller ändringen samordnas med filhanteringsprojektet. ## 8. Stegvis migreringsplan Varje steg nedan anger om det enbart gäller dokumentation eller struktur, om det kan påverka körbart beteende samt hur det bör verifieras. ### Steg 1: Dokumentera ansvar och läskontrakt **Rekommendation:** Fastställ skriftligt att facitprojektet äger samtliga facittabeller och är ensam skrivare. Dokumentera de tabeller och kolumner som filhanteringen får läsa. - Typ: ren dokumentationsändring. - Körbart beteende: ingen påverkan. - Verifiering: - jämför kontraktet med alla `SELECT` i matchningsskripten, - kontrollera att inga skrivande SQL-satser finns i filhanteringsdelen, - granska och godkänn den avsedda ägargränsen. ### Steg 2: Gör facitschemat reproducerbart **Rekommendation:** Uppdatera facitets schemahantering så att en ny databas får alla kolumner som facitflödet behöver, inklusive OCR-kolumnerna. - Typ: kod-/schemaändring. - Körbart beteende: kan påverkas; nya databaser och återställningsflöden förändras. - Verifiering: - skapa en ny disposable databas från versionshanterade schemafiler, - jämför tabeller, kolumner, index, begränsningar och standardvärden med den avsedda modellen, - kör syntaxkontroll av Python-skripten, - kör import mot en liten test-JSON, - kör OCR-flödets databasoperationer utan att använda produktionsdatabasen, - kontrollera att `database/wcx.db` är oförändrad. ### Steg 3: Rätta dokumenterad hantering av genererade filer **Rekommendation:** Bestäm om `import/wcx_site_index.json` är runtime-data. Om så är fallet, sluta spåra filen utan att radera den lokala runtime-kopian och anpassa dokumentationen. - Typ: Git-struktur och dokumentation. - Körbart beteende: normalt ingen påverkan, men en ny checkout kommer inte längre innehålla en färdig importfil. - Verifiering: - kontrollera `.gitignore` och Git-index, - kör synkskriptet mot en tillfällig utdatafil, - verifiera att uppdateringsflödet skapar importfilen innan import, - verifiera att inga genererade data lagts till i Git. ### Steg 4: Gör sökvägar flyttbara i nuvarande repository **Rekommendation:** Behåll explicita kommandoradsargument för databas och indata. Beräkna interna skriptsökvägar relativt skriptens plats där det är lämpligt. Lägg till konfigurerbar databas till diagnostik som saknar det. Behåll om möjligt nuvarande standardvärden under övergången. - Typ: kod- och konfigurationsstruktur. - Körbart beteende: kan påverkas, särskilt standardkörningar och schemalagd drift. - Verifiering: - kör `python3 -m py_compile scripts/*.py`, - kör varje relevant kommando med explicita sökvägar mot disposable data, - kör `scripts/update_wcx.sh --skip-ocr` mot en säker testuppsättning eller testa dess delkommandon separat, - verifiera både nuvarande standardplats och en alternativ projektplats, - inspektera systemd-enheternas verkliga kommandon och sökvägar. ### Steg 5: Tvinga fram read-only i filhanteringen **Rekommendation:** Ändra filhanteringens SQLite-anslutningar till URI-baserat `mode=ro`. Använd inte `immutable=1` för en databas som kan uppdateras medan den läses. - Typ: kodändring och säkerhetsförstärkning. - Körbart beteende: kan påverkas; fel sökväg och otillräckliga läsrättigheter ska nu ge tydliga fel i stället för att en ny databas skapas eller öppnas skrivbart. - Verifiering: - kör matchning och längddiagnostik mot en disposable facitdatabas, - kontrollera databasfilens hash och mtime före och efter, - verifiera att läsning fungerar när filen saknar skrivrättighet för processen, - lägg in ett isolerat negativt test som visar att en `INSERT` via samma anslutningssätt nekas, - kontrollera att samtidig normal facituppdatering och läsning hanteras av SQLite utan att använda osäkra filkopior. ### Steg 6: Separera dokumentation och filstruktur logiskt **Rekommendation:** Renodla facitets README och skapa en självständig README för filhanteringen. Ordna filerna enligt den planerade projektgränsen, men behåll dem tillfälligt i samma Git-repository om det förenklar verifieringen. - Typ: i första hand dokumentation och struktur. - Körbart beteende: ingen påverkan om endast dokument flyttas; möjliga sökvägseffekter om skript flyttas. - Verifiering: - följ installations- och körinstruktionerna från en ren testkatalog, - sök efter gamla absoluta projektsökvägar, - kontrollera att shellskript hittar sina delskript efter en eventuell flytt, - kontrollera att facit- och filhanteringsdokumentation är självständigt begripliga. ### Steg 7: Skapa två Git-projekt **Rekommendation:** Flytta facit- respektive filhanteringsfiler till separata repositoryn först när schema, konfiguration och read-only-gräns är verifierade. Behåll det gamla repositoryt tills båda nya projekten har körts framgångsrikt. Föreslagen facitomfattning: ```text README.md scripts/schema.sql scripts/wcx_sync.py scripts/import_site.py scripts/migrate_csv.py scripts/process_pending_ocr.py scripts/check_ocr.py scripts/ocr.sh scripts/parse_ocr.py scripts/update_wcx.sh scripts/scheduled_update_wcx.sh migration/ ``` Föreslagen filhanteringsomfattning: ```text README.md scripts/match_filenames.py scripts/test_duration_matching.py docs/filename-matching-requirements.md ``` - Typ: Git- och projektstruktur. - Körbart beteende: kan påverkas genom nya sökvägar, installation och drift. - Verifiering: - kontrollera `git status` och ignore-regler i båda projekten, - kör syntaxkontroll och respektive projekts diagnostik, - kör facitimport mot en disposable databas, - kör filmatchning mot samma databas i read-only-läge, - verifiera att filhanteringen fungerar utan facitprojektets källkod i `PYTHONPATH` eller samma katalog, - kontrollera att inga databaser, API-nycklar eller genererade JSON-filer har följt med i Git. ### Steg 8: Flytta drift och systemd till facitprojektet **Rekommendation:** Uppdatera externa systemd-enheter och runtime-sökvägar först efter en lyckad manuell facitkörning från den nya platsen. Databasen ska inte kopieras medan den skrivs; använd en säker SQLite-backupmetod om en fysisk flytt behövs. - Typ: extern konfiguration och driftsättning. - Körbart beteende: direkt påverkan på schemalagd produktion. - Verifiering: - inspektera enhetsfiler och miljövariabler, - kör facituppdateringen manuellt med `--skip-ocr` mot avsedd databas, - kör därefter en kontrollerad OCR-körning om API-nyckel finns, - starta tjänsten manuellt och kontrollera logg, låsfil och tidsstämpel, - verifiera att endast en uppdatering kan köras samtidigt, - kör filhantering som separat läsare efter uppdateringen. ### Steg 9: Inför separat filhanteringsdatabas först vid konkret behov **Rekommendation:** Skapa inte en andra databas som del av den första uppdelningen. Inför den först när lokala filsökvägar, manuella beslut eller bearbetningsstatus behöver beständig lagring. - Typ: framtida funktions- och schemaändring i filhanteringsprojektet. - Körbart beteende: påverkar filhantering men inte facitdatabasen. - Verifiering: - testa den nya databasen isolerat, - verifiera att facitanslutningen fortfarande är `mode=ro`, - kontrollera att endast stabilt `movie.id` lagras som extern referens, - verifiera att inga skrivningar riktas till den anslutna facitdatabasen. ## 9. Rekommenderad ordning och stoppunkter **Rekommendation:** Utför steg 1–3 innan sökvägar eller körkod flyttas. Dessa steg etablerar ägarskap och gör facitdatabasen reproducerbar. Utför steg 4–5 i det befintliga repositoryt och verifiera oförändrat beteende mot disposable data. Dessa är de viktigaste tekniska förutsättningarna för en säker uppdelning. Utför steg 6–8 som separata, granskningsbara förändringar. Lägg inte schemaändring, read-only-förstärkning, filflytt och produktionsdrift i samma ändring, eftersom fel då blir svårare att isolera. **Ej fattat beslut:** Exakta namn och installationsplatser för de två nya Git-projekten är inte bestämda. **Ej fattat beslut:** Ingen fysisk flytt av produktionsdatabasen bör planeras förrän dess slutliga runtime-plats, backupmetod och filrättigheter är beslutade. ## 10. Sammanfattande rekommendation Den befintliga koden har redan en användbar ansvarslinje: facitverktygen producerar och underhåller SQLite-data, medan filhanteringen konsumerar ett litet urval av denna data. Uppdelningen behöver därför inte börja med ett API eller koddelning. Den säkra vägen är att först göra facitschemat komplett och reproducerbart, dokumentera det lilla läskontraktet, göra sökvägar konfigurerbara och tvinga filhanteringens anslutning till read-only. Därefter kan filerna delas mellan två Git-projekt med betydligt lägre risk. En separat filhanteringsdatabas bör vänta tills beständigt lokalt tillstånd faktiskt behövs.