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:

```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.