Files
bookmanager/README.md
T
bobbanandClaude Sonnet 5.5 dcb5d43429 Automatiska tester, och rättningar som testerna hittade
Vitest med enhetstester utan databas och databastester mot en egen
testdatabas vars namn måste sluta på _test. Rättar tomma MAP_*-värden
i .env och säkerhetskopior med å, ä och ö i filnamnet.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-01 23:19:30 +01:00

235 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Bokplanerare
Webbaserat planeringsverktyg för författare. Flera böcker, var och en med karaktärer, husdjur, bostäder, platser, företag, lokaler, scenarier, relationer, arbetsscheman och kartor med markeringar.
- **Next.js 15** (App Router, TypeScript) med utseende från **Tabler**
- **PostgreSQL** via Prisma
- Inloggning med **Authentik** (OpenID Connect via Auth.js)
- Svenska och engelska i gränssnittet (växlas i sidomenyn)
- Kartor: riktig karta (Leaflet + OpenStreetMap) eller egen uppladdad kartbild per karta
## Starta för utveckling
```bash
docker compose -f docker-compose.dev.yml up --build
```
Öppna http://localhost:3000. Utan Authentik-inställningar visas en **utvecklarinloggning** (bara i utvecklingsläge, finns aldrig i produktionsbygget). Källkoden monteras in så ändringar slår igenom direkt.
Vill du testa mot din riktiga Authentik: kopiera `.env.example` till `.env`, fyll i `AUTHENTIK_*` och sätt `AUTH_DEV_LOGIN=false`. Allt i `.env` skickas in i appen; saknas `AUTH_SECRET` och `AUTH_URL` används utvecklingsvärden (`http://localhost:3000`). Ändrar du `.env` räcker det att köra `up` igen, ingen ombyggnad behövs.
Ändrar du `prisma/schema.prisma`:
```bash
docker compose -f docker-compose.dev.yml exec app npx prisma migrate dev --name beskrivning
```
Ändrar du `package.json` eller `prisma/schema.prisma` räcker det att starta om med `docker compose -f docker-compose.dev.yml up`. Beroenden och Prisma-klienten synkas automatiskt vid varje start.
## Sätta upp Authentik
1. I Authentik: **Applications → Applications → Create with Provider**, välj **OAuth2/OpenID Connect**.
2. Client type **Confidential**. Under **Redirect URIs** lägg till (exakt match):
`https://din-adress.example.com/api/auth/callback/authentik`
(för lokal test mot Authentik: `http://localhost:3000/api/auth/callback/authentik`)
3. Scopes: `openid`, `profile`, `email`.
4. Kopiera **Client ID**, **Client Secret** och **OpenID Configuration Issuer** (slutar på `/application/o/<slug>/`) till `.env`.
## Produktion
```bash
cp .env.example .env # fyll i lösenord, AUTH_SECRET, AUTH_URL och AUTHENTIK_*
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
```
- Appen lyssnar på port `APP_PORT` (standard 3000). Lägg en omvänd proxy med HTTPS framför och sätt `AUTH_URL` till den publika adressen.
- Databasmigreringar körs automatiskt vid varje start.
- Data ligger i mappar bredvid compose-filen: `./data/db` (databas) och `./data/uploads` (bilder), eller under `DATA_DIR` om du sätter den. Ta backup på mappen, eller använd **Bokinställningar → Exportera som JSON** per bok. I utveckling används `./data/dev/`.
- Hälsokontroll: `/api/health`.
## Bygga, publicera i Gitea och köra i produktion
Gitea har ett inbyggt containerregister. Image-namnet blir `<gitea-adress>/<ägare>/<namn>:<tagg>`, till exempel `gitea.labsconnect.se/bobban/bookmanager:1.0.0`.
**1. Logga in i registret** (en gång per dator). Skapa en åtkomsttoken i Gitea under *Inställningar → Program* med behörigheten `write:package` (och `read:package` på produktionsservern).
```bash
docker login gitea.labsconnect.se -u bobban
```
**2. Bygg och publicera** från projektmappen. Bygget använder steget `prod` i Dockerfile och behöver ingen databas.
```bash
docker build --target prod -t gitea.labsconnect.se/bobban/bookmanager:1.0.0 -t gitea.labsconnect.se/bobban/bookmanager:latest .
docker push gitea.labsconnect.se/bobban/bookmanager:1.0.0
docker push gitea.labsconnect.se/bobban/bookmanager:latest
```
**3. Kör på produktionsservern.** Servern behöver bara `docker-compose.prod.yml` och en `.env`, inte källkoden. Lägg till `APP_IMAGE` i `.env`:
```
APP_IMAGE=gitea.labsconnect.se/bobban/bookmanager:1.0.0
```
```bash
docker login gitea.labsconnect.se -u bobban
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
```
Databasmigreringar körs automatiskt när appen startar, och det finns ingen data att seeda: tabellerna skapas av migreringarna och användaren skapas första gången någon loggar in via Authentik. Vid uppdatering bygger du och publicerar en ny tagg, ändrar `APP_IMAGE` och kör `pull` och `up -d` igen. Data ligger kvar i `./data`.
Om Gitea nås över http (till exempel en IP-adress) måste Docker tillåta det: lägg adressen under `"insecure-registries"` i `/etc/docker/daemon.json` på de datorer som bygger och kör, och starta om Docker.
## Mallar
Varje typ (karaktär, husdjur, bostad, plats, företag, lokal, utbildning, scenario) och relationer har en mall som styr vilka fält formuläret har. Standardmallarna är byggda efter Word-mallarna i `Mall/`:
| Word-mall | I appen |
|---|---|
| Karaktärsmall (lång och kort) | Karaktär. Den korta finns som knappen *Ladda kort mall* i mallredigeraren |
| Djurmall, Bostadsmall, Företagsmall, Lokalmall, Scenariomall | Husdjur, Bostad, Företag, Lokal, Scenario |
| Utbildningsmall | Utbildning |
| Relationsmall | Relation (öppnas från relationslistan eller från en posts sida) |
| Schema dag / natt | Scheman, vyn *Timrutnät* med Dag 06–18 och Natt 18–06 |
| Registren (Fordon, Research, Referens, Appar, Hemsidor, Kart-, Schema- och Företagsregister) | Egna poster under *Register* i menyn, och sidan *ID-register* med alla ID samlade |
| ID-översikten | ID skapas automatiskt, se nedan |
Uppgifter som i Word-mallarna är ID-listor (anställda, boende, elever, involverade karaktärer, ägare) görs i appen som **relationer** mellan poster, till exempel ”Jobbar på”, ”Bor på”, ”Elev på”, ”Involverad i”. Då kan du klicka dig mellan dem och se dem i relationsdiagrammet.
En relation kan ha fler än två deltagare, till exempel en vännergrupp: välj två i *Från* och *Till* och resten under *Fler deltagare*. Gruppen ritas som ett nav i diagrammet, och den visas på varje deltagares sida.
Under **Mallar** kan du ändra fält, ordning, rubriker och fälttyper (text, textruta, tal, datum, val, kryssruta, länk) per bok, eller klistra in en mall som JSON:
```json
[
{ "key": "nickname", "label": "Smeknamn", "type": "text", "section": "Grunduppgifter" },
{ "key": "mood", "label": "Läggning", "type": "select", "options": ["Glad", "Butter"] }
]
```
### Kopplingar till andra poster
Fälttypen **Koppling till post** pekar direkt på en annan post, till exempel *Lokal* i en företagsmall. Du väljer den i mallredigeraren och anger vilken posttyp som får väljas (eller alla). I formuläret blir fältet en rullista med posterna och deras ID, och på postens sida visas länken. På den kopplade posten visas var den används, till exempel vilka företag och skolor som använder en lokal (*Används av*). Till skillnad från en relation är det ett fält i mallen, med en tydlig roll som *Lokal*, *Skiss* eller *Ägare*.
Standardmallarna använder det för Lokal och Skiss i Företag, Lokal, Bostad och Utbildning, Företag i Utbildning, Ägare och Referens i Fordon och Kopplat till i Scenario. I JSON ser ett sådant fält ut så här: `{ "key": "premises", "label": "Lokal", "type": "reference", "refKind": "PREMISES" }` (utan `refKind` kan alla typer väljas).
Ändrar du en mall försvinner ingen data: värden för borttagna fält finns kvar i databasen.
## Export och import
Under *Bokinställningar* exporterar du hela boken:
- **Med bilder (.zip):** innehåller `book.json` och alla bilder i `files/`. Det är den fullständiga säkerhetskopian.
- **Bara data (.json):** samma innehåll utan bilder, för snabb jämförelse eller redigering.
Exporten innehåller poster (med ID, taggar och mallfält), relationer med deltagare, scheman, kartor med markeringar, mallar och bilderna.
På startsidan *Mina böcker* importerar du en exportfil (.zip eller .json). Importen **skapar alltid en ny bok** och skriver aldrig över något. Alla poster får nya interna id, och kopplingar mellan dem (relationer, kopplingsfält i mallar, markeringar och scheman) pekar om till de nya. ID som KI-0001 behålls, och räknarna fortsätter därefter. Finns redan en bok med samma titel får den nya tillägget *(import)*. Poster, bilder och kopplingar som saknas eller är ogiltiga i filen hoppas över, och antalet visas efteråt. Filen kan flyttas mellan installationer, till exempel från dev till prod.
Gränser: filer upp till 300 MB, bilder upp till 16 MB styck och 20 000 poster per sorts innehåll. Importen läser bara `book.json` och bilder under `files/` ur zip-filen, och bildtyp kontrolleras på filens innehåll. Ligger appen bakom en omvänd proxy måste den tillåta stora uppladdningar (i Nginx Proxy Manager: `client_max_body_size 0;`).
## Automatiska ID
Alla ID skapas automatiskt enligt ID-översikten, med löpande nummer per bok och typ (de börjar om i varje ny bok). ID tilldelas första gången posten sparas och ändras aldrig därefter.
| Typ | ID | Exempel |
|---|---|---|
| Karaktär | KI | KI-0001 |
| Företag | FI | FI-0001 |
| Bostad | BI | BI-0001 |
| Husdjur | DI | DI-0001 |
| Lokal | LI | LI-0001 |
| Utbildning | UI | UI-0001 |
| Fordon | FD | FD-0001 |
| Research | RI | RI-0001 |
| Referens | RD | RD-0001 |
| Skiss | SI | SI-0001 |
| Relation | REI | REI-0001 |
| Placering (markering på karta) | PI | PI-0001 |
| Schema (en persons pass hos samma arbetsplats) | SCI | SCI-0001 |
| Karta | KD-R_ (riktig karta) eller KD-E_ (egen kartbild) | KD-R_0001 |
| Plats och Scenario (saknas i översikten, förslag) | PLI och SNI | PLI-0001, SNI-0001 |
Appar och Hemsidor har inget ID. Prefixen ligger samlade i `src/lib/ids.ts`. Sidan **ID-register** listar alla ID i boken med sökning och filter. Befintliga poster får ID vid uppgraderingen i den ordning de skapades, och tidigare handskrivna koder ersätts.
## Säkerhet och drift
**Säkerhetskopior.** Varje natt (klockan `BACKUP_HOUR`, standard 03:00 i `TZ`) sparas en zip per bok med bilder i `./data/backups/<tidpunkt>/`. De `BACKUP_KEEP` senaste körningarna (standard 14) behålls. Zip-filerna är samma format som exporten och importeras via *Importera bok*. Missade körningar tas igen vid nästa start. Administratören kan köra en säkerhetskopia direkt och ladda ner filerna på *Administration*. Kopiera gärna `backups/` till en annan maskin.
**Papperskorg.** Borttagna poster och böcker flyttas till papperskorgen i `TRASH_DAYS` dagar (standard 30) och kan återställas. En post återställs med sina relationer, scheman och markeringar, och behåller sitt ID. En bok sparas som zip i `./data/trash` och återställs som en ny bok. Papperskorgen rensas automatiskt.
**Ändringshistorik.** Varje ändring av en post sparar den tidigare versionen (de `MAX_VERSIONS` senaste, standard 30). *Historik* på postens sida visar skillnaderna fält för fält och kan återställa en tidigare version. Att återställa sparar först den nuvarande, så det går att ångra. Bilder ingår inte i historiken.
**Snabbsök.** Ctrl+K (Cmd+K på Mac) öppnar en kommandopalett: sök poster (namn, ID, sammanfattning, taggar och mallfält), hoppa till en sida eller skapa något nytt.
**Bilder.** Uppladdade bilder roteras efter EXIF, skalas ned (längsta sida 2 400 px, kartbilder 6 000 px), omkomprimeras och rensas från metadata som GPS-position. Listor använder små miniatyrer. Varje användare har en lagringskvot (`USER_QUOTA_MB`, standard 2 048 MB).
**Härdning.** Säkerhetsrubriker sätts på alla sidor (Content-Security-Policy som släpper igenom kartservrarna från `MAP_TILE_URL` och `MAP_GEOCODER_URL`, HSTS över https, skydd mot inramning). Inloggning, import, export, sök och namnstatistik har hastighetsbegränsning per IP-adress. Inloggningen gäller i `SESSION_DAYS` dagar (standard 14).
**Administration.** Sidan `/admin` visar version, databas- och lagringsstorlek, antal användare och böcker, säkerhetskopior och om SCB och Skatteverket går att nå. Administratör är den som anges i `ADMIN_EMAILS`, och finns inget värde är den äldsta användaren administratör. Versionen visas också i sidomenyn. Den sätts när imagen byggs: `docker build --build-arg APP_VERSION=1.0.4 --build-arg APP_COMMIT=$(git rev-parse HEAD) ...`.
**Loggar och mätvärden.** Loggar skrivs som JSON, en rad per händelse (`LOG_LEVEL`, `LOG_FORMAT`), och serverfel loggas med sidans sökväg. Sätter du `METRICS_TOKEN` finns Prometheus-mätvärden på `/api/metrics` (anropa med `Authorization: Bearer <token>`): antal användare, böcker och poster, databas- och bildstorlek, papperskorg, senaste lyckade säkerhetskopia, minne och antal anrop som hastighetsbegränsningen stoppat.
## Namngenerator
Under *Planering → Namngenerator* slumpas svenska namn fram. Välj kvinna, man eller slumpa, **födelseår**, efternamnstyp (alla, bara -son eller utan -son), antal förslag och om ett mellannamn ska ingå. Kopiera ett namn eller klicka *Skapa karaktär* för att starta ett formulär med namnet ifyllt.
I karaktärsformuläret finns knapparna *Kvinna* och *Man* som slumpar ett namn direkt i namnfältet. De läser födelseår från fälten *Födelsedatum* eller *Ålder* om de är ifyllda, annars slumpas ett år så att åldrarna blir blandade.
Namnen viktas efter hur vanliga de var, så en man född 1960 blir oftare Anders, Mikael eller Lars och en tjej född 2005 oftare Emma eller Julia. Statistiken är öppna data som hämtas första gången den behövs och sparas i databasen (tabellen `NameStat`), så varje år hämtas bara en gång:
| Födelseår | Källa |
|---|---|
| 1922–1997 | SCB, tilltalsnamn bland folkbokförda (de 200 vanligaste namnen) |
| 1998–2020 | SCB, nyfödda efter tilltalsnamn och namngivningsår |
| 2021 och senare | Skatteverket, öppna data *Namn på nyfödda* |
| Efternamn | SCB, efternamn med minst 10 bärare (2020), de 100, 1 000 eller 5 000 vanligaste |
Året flyttas till närmaste år med statistik (tidigast 1922). Servern behöver nå `api.scb.se` och `skatteverket.entryscape.net`. Går det inte används den inbyggda namnlistan i `src/lib/names.ts` (cirka 150 förnamn per kön och 160 efternamn) och sidan visar en varning. Du kan också stänga av statistiken med reglaget *Använd namnstatistik*.
## Kartor
- **Riktig karta**: sök adress, klicka där markeringen ska sitta, koppla den till en bostad, lokal eller plats. Dra för att flytta. *Spara vy* minns utsnittet.
- **Egen kartbild**: ladda upp en bild (PNG/JPG/WebP/GIF, max 15 MB) och placera markeringar på den.
- Från en posts sida kan du gå direkt till *Placera på karta*.
- Kartplattor och adressökning hämtas som standard från OpenStreetMaps publika servrar, som är tänkta för lätt användning. För tyngre bruk, sätt `MAP_TILE_URL` och `MAP_GEOCODER_URL` till egen eller betald tjänst. Adressökningar skickas då från webbläsaren till den tjänsten.
## Tester
Testerna körs med Vitest (`npm test`). Det finns cirka 170 tester:
- **Enhetstester utan databas** (`tests/unit`): mallar och deras validering, ID-prefix, hastighetsbegränsning, säkerhetsrubriker, namngenerering, historikens jämförelser, bildbehandling (storlek, EXIF-rotation, borttagen metadata) och läsning och kontroll av importfiler (inklusive skydd mot för stora filer).
- **Databastester** (`tests/db`): löpande ID (även vid samtidiga anrop), export och import fram och tillbaka med bilder och kopplingar, papperskorg (poster och böcker), historikens gräns, fältvärden och kopplingskontroller, säkerhetskopiering (rensning, schema, att zip-filerna går att importera), lagringskvot, administratör och sök.
Databastesterna behöver en PostgreSQL-databas och använder alltid en **egen testdatabas** vars namn slutar på `_test`. De tömmer den mellan testerna och vägrar köra mot en databas med något annat namn, så din riktiga data berörs aldrig. Databasen skapas och migreras automatiskt första gången.
Med Docker (utvecklingsmiljön) räcker det att köra:
```bash
docker compose -f docker-compose.dev.yml exec app npm test
```
Testdatabasen blir då `bookmanager_test` i samma databasserver. Utan Docker, peka på en databasserver (användaren behöver få skapa databaser):
```bash
TEST_DATABASE_URL=postgresql://användare:lösenord@localhost:5432/bookmanager_test npm test
```
Saknas databas körs bara enhetstesterna och databastesterna hoppas över. Uppladdade filer och säkerhetskopior från testerna hamnar i en tillfällig mapp som städas bort. `npm run typecheck` kontrollerar även testfilerna.
## Struktur
```
prisma/ schema och migreringar
src/auth*.ts Authentik-inloggning (Auth.js)
src/actions/ server actions (skriv-operationer)
src/app/ sidor och API-routes
src/components/ gränssnittskomponenter (Tabler)
src/i18n/ sv.ts och en.ts
src/lib/templates.ts standardmallar och validering
```
Varje bok tillhör användaren som skapade den; andra inloggade användare kommer inte åt den.