From 402a859a0bfcef4cf07bf3d15c81a84ec063da17 Mon Sep 17 00:00:00 2001
From: Urban <urban@urmo.se>
Date: Fri, 17 Jul 2026 10:20:32 +0200
Subject: [PATCH] Readme

---
 README.md | 292 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 292 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b7d3c79
--- /dev/null
+++ b/README.md
@@ -0,0 +1,292 @@
+# WCX Index
+
+Lokalt index för WCX-publiceringar.
+
+Projektet bygger ett SQLite-baserat index från JSON-data som genereras av det befintliga scraper-scriptet.
+
+## Nuvarande flöde
+
+```text
+WCX-site
+   ↓
+befintligt scraper-script
+   ↓
+import/wcx_site_index.json
+   ↓
+scripts/import_site.py
+   ↓
+database/wcx.db
+```
+
+Importscriptet:
+
+* lägger till nya filmer
+* uppdaterar befintliga filmer när sitens `update`-datum är nyare
+* lämnar oförändrade filmer orörda
+* lagrar speltid som antal sekunder
+
+## Katalogstruktur
+
+```text
+/storage/disk1/WCX/
+├── database/
+│   └── wcx.db
+├── import/
+│   └── wcx_site_index.json
+└── scripts/
+    ├── schema.sql
+    └── import_site.py
+```
+
+## Förutsättningar
+
+Projektet använder:
+
+* Python 3
+* SQLite 3
+* jq, valfritt för inspektion av JSON
+
+På Ubuntu/Debian:
+
+```bash
+sudo apt update
+sudo apt install sqlite3 jq
+```
+
+Python-modulerna `json`, `sqlite3` och `pathlib` ingår i Pythons standardbibliotek. Inga externa Python-paket behövs.
+
+## Skapa databasen
+
+Databasen skapas från `schema.sql`.
+
+```bash
+mkdir -p /storage/disk1/WCX/database
+
+sqlite3 /storage/disk1/WCX/database/wcx.db \
+  < /storage/disk1/WCX/scripts/schema.sql
+```
+
+Kontrollera tabellen:
+
+```bash
+sqlite3 /storage/disk1/WCX/database/wcx.db ".schema movie"
+```
+
+## Databasmodell
+
+Tabellen `movie` innehåller:
+
+| Kolumn             | Beskrivning                                |
+| ------------------ | ------------------------------------------ |
+| `id`               | Stabilt och unikt ID från siten            |
+| `name`             | Filmens titel                              |
+| `aka`              | Alternativt namn                           |
+| `nationality`      | Nationalitet                               |
+| `age`              | Ålder                                      |
+| `shoot_location`   | Inspelningsplats                           |
+| `shoot_date`       | Inspelningsdatum                           |
+| `duration_seconds` | Speltid i sekunder                         |
+| `description`      | Manuell beskrivning                        |
+| `rating`           | Manuell rating                             |
+| `web_url`          | Länk till detaljsidan                      |
+| `thumbnail`        | Länk till thumbnail                        |
+| `published`        | Ursprungligt publiceringsdatum             |
+| `updated`          | Senaste uppdateringsdatum från siten       |
+| `created_at`       | När posten skapades i databasen            |
+| `modified_at`      | När posten senast uppdaterades i databasen |
+
+## JSON-indata
+
+Importscriptet läser:
+
+```text
+/storage/disk1/WCX/import/wcx_site_index.json
+```
+
+Filen ska innehålla en JSON-array.
+
+Exempel:
+
+```json
+{
+  "id": "sweet-cherry_41678",
+  "titel": "Sweet Cherry",
+  "details": "https://www.woodmancastingx.com/casting-x/sweet-cherry_41678.html",
+  "duration": "1:37:00",
+  "thumb": "https://example.com/thumbnail.jpg",
+  "published": "2026-07-12"
+}
+```
+
+Vid en uppdaterad publicering kan även följande fält finnas:
+
+```json
+{
+  "update": "2026-07-15"
+}
+```
+
+Importscriptet accepterar både `update` och `updated`.
+
+## Fältmappning
+
+| JSON-fält                | Databaskolumn      |
+| ------------------------ | ------------------ |
+| `id`                     | `id`               |
+| `titel`                  | `name`             |
+| `details`                | `web_url`          |
+| `duration`               | `duration_seconds` |
+| `thumb`                  | `thumbnail`        |
+| `published`              | `published`        |
+| `update` eller `updated` | `updated`          |
+
+Speltiden konverteras till sekunder.
+
+Exempel:
+
+```text
+37:35   → 2255
+1:37:00 → 5820
+```
+
+## Kör importen
+
+Gör scriptet körbart om det inte redan är gjort:
+
+```bash
+chmod +x /storage/disk1/WCX/scripts/import_site.py
+```
+
+Kör importen:
+
+```bash
+/storage/disk1/WCX/scripts/import_site.py
+```
+
+Exempel på resultat:
+
+```text
+Poster i JSON: 1250
+Tillagda:       3
+Uppdaterade:    1
+Oförändrade:    1246
+```
+
+## Importregler
+
+### Ny film
+
+Om filmens ID inte finns i databasen skapas en ny post.
+
+### Befintlig film utan `update`
+
+Om filmen redan finns och site-posten saknar `update` görs ingen ändring.
+
+### Befintlig film med `update`
+
+Posten uppdateras när:
+
+* databasen saknar ett `updated`-värde, eller
+* sitens `update`-datum är nyare än databasens `updated`-värde
+
+Vid en uppdatering skrivs följande sitefält över:
+
+* `name`
+* `duration_seconds`
+* `web_url`
+* `thumbnail`
+* `published`
+* `updated`
+
+ID och manuella metadatafält påverkas inte.
+
+Datumen lagras som `YYYY-MM-DD`, vilket gör att de kan jämföras kronologiskt som text.
+
+## Inspektera databasen
+
+Visa antal filmer:
+
+```bash
+sqlite3 /storage/disk1/WCX/database/wcx.db \
+  "SELECT COUNT(*) FROM movie;"
+```
+
+Visa några poster:
+
+```bash
+sqlite3 -header -column /storage/disk1/WCX/database/wcx.db \
+  "SELECT id, name, duration_seconds, published, updated
+   FROM movie
+   LIMIT 10;"
+```
+
+Visa en specifik film:
+
+```bash
+sqlite3 -header -column /storage/disk1/WCX/database/wcx.db \
+  "SELECT *
+   FROM movie
+   WHERE id = 'susana-melo_6707';"
+```
+
+## Testa uppdateringslogiken
+
+Ett enkelt test är att medvetet ändra en post:
+
+```bash
+sqlite3 /storage/disk1/WCX/database/wcx.db \
+  "UPDATE movie
+   SET duration_seconds = 1,
+       updated = NULL
+   WHERE id = 'susana-melo_6707';"
+```
+
+Kör sedan importen igen:
+
+```bash
+/storage/disk1/WCX/scripts/import_site.py
+```
+
+Posten ska då uppdateras från JSON-filen och `duration_seconds` ska återställas till sitens värde.
+
+## Återskapa databasen
+
+Under utveckling kan databasen enkelt återskapas eftersom all automatisk site-data kan importeras igen.
+
+```bash
+rm /storage/disk1/WCX/database/wcx.db
+
+sqlite3 /storage/disk1/WCX/database/wcx.db \
+  < /storage/disk1/WCX/scripts/schema.sql
+
+/storage/disk1/WCX/scripts/import_site.py
+```
+
+Radera inte databasen på detta sätt när den senare innehåller manuellt registrerad metadata utan att först ta en backup.
+
+## Versionshantering
+
+Källkod och dokumentation ska versionshanteras i Git.
+
+Databasen och importerade datafiler bör normalt inte checkas in.
+
+Föreslagen `.gitignore`:
+
+```gitignore
+database/*.db
+database/*.db-shm
+database/*.db-wal
+import/*.json
+__pycache__/
+*.pyc
+```
+
+## Nästa steg
+
+Planerade kommande delar:
+
+* OCR-behandling av thumbnails för nya filmer
+* manuell redigering av metadata
+* export av komplett index
+* integration med Emby
+* schemalagd körning