WCX/docs/project-split-analysis.md

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:

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:

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:

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:

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:

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:

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.

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:

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:

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.