vinindkoeb/CLAUDE.md

Fælles Vinindkøb — Projektplan

Proces: Når en opgave (eller delopgave, fx 7a/8a) er gennemført, skal denne fil opdateres til at afspejle det faktisk byggede — datamodel, endpoints, og status i Fase 1-listen. Filen er den løbende sandhed om projektet, ikke kun den oprindelige plan.

Formål

Erstatte manuel administration (regneark til betalingstracking, direkte databaseredigering for nye runder/deltagere/vine) med en rigtig admin-backend, samt automatisk betalings-mail til deltagere. Arkitekturen designes fra start til at kunne understøtte flere organisationer (fx vinbonden Horcher-familiens egne ruter i Frankrig/Belgien), selvom kun én organisation/rute er i drift i dag.

Tech stack

• Backend: FastAPI + SQLModel + PostgreSQL + Alembic (migrations)
• Frontend: React (admin-UI) + eksisterende offentlige bestillingsside (fortsat intet login for deltagere)
• Mail: Postal (selvhostet), postal.carsteng.dk, domæne vinindkoeb.dk
• Auth: JWT (Authorization: Bearer), 2 timers levetid. Superadmin- handlinger kræver derudover en kortlivet (5 min) "eleveret" session (POST /auth/elevate, ingen ny password-indtastning) — en bevidst "ja, jeg mener det"-bekræftelse mod ved-uheld-handlinger, ikke et forsvar mod en stjålet session

Datamodel

• WineCategory — global, delt af ALLE organisationer/ruter (samme vinbonde, samme kategoristruktur). Seedet via migration med: TRADITION, SELECTION, LES IMPERTINENTS, GRANDS CRUS, VENDANGES TARDIVES, CREMANT, MAGNUM, SANS ALCOOL (i denne rækkefølge).

  • name (unik), sort_order

• Organization — administrativ gruppe (fx "Fælles Vinindkøb DK", "Horcher Frankrig")

  • name (unik)

• User — admin-login, tilhører en Organization

  • email (unik), name, is_active, is_superadmin, hashed_password (argon2id via pwdlib)
  • Passkey/WebAuthn kan tilføjes senere som en separat credentials-tabel uden ændringer på User selv

• Route — tilhører en Organization (fx "Tyskland" for jer; "Belgique" / "Paris" / "Massif Central" for Horcher-familien)

  • name, meeting_info/contact_person/contact_phone (fritekst, forudfyldes fra forrige runde i UI'et senere)
  • sender_name/sender_email — afsenderidentitet til mails, forskellig pr. rute (fx "Finn Gram - Fælles Vinindkøb finn@vinindkoeb.dk")

• Participant — tilhører en Route

  • name, email, phone, is_active
  • email er påkrævet ved oprettelse af nye deltagere; phone er påkrævet for nye deltagere via API'et, men nullable i databasen (historiske deltagere fra MongoDB-migreringen mangler det)
  • UNIQUE(route_id, email) — forhindrer dubletter pr. rute
  • Soft-delete via is_active er den normale vej (bevarer historik for deltagere der forlader og kommer tilbage); en rigtig DELETE findes også, kun til GDPR-sletningsanmodninger
  • Oprettes/opdateres også ad-hoc via den offentlige bestillings-API (opgave 8a) — matcher emailen en eksisterende deltager på ruten, overskrives name/phone/is_active fra formularen ved hver bestilling (ingen login = bestillingsformularen er selve vejen man holder sine oplysninger opdateret); ny email = ny deltager-række

• PurchaseRound — tilhører en Route

  • name (frit, fx "Forår 2026" — intet sæson/år-felt, da det ikke er universelt på tværs af fremtidige ruter)
  • status: draft / open / closed
  • opens_at, order_deadline_at, pickup_at — alle tre påkrævede så snart status ikke er draft (håndhævet af en DB-constraint)
  • eur_dkk_rate (valgfri — ikke alle organisationer skal omregne)
  • intro_text, pickup_info_text (fritekst, forudfyldes fra forrige runde via "kopiér fra forrige runde")
  • Sletning: draft kan slettes af enhver admin; open kan aldrig slettes; closed kræver en eleveret superadmin

• WineOffering — tilhører PurchaseRound + (global) WineCategory

  • name (inkl. størrelse og årgang som fri tekst, fx "SYLVANER 2021
    • 75cl" — ingen separate felter for det)
  • price (EUR, Decimal), is_organic (boolean)

• Order — deltager + runde

  • payment_status (unpaid/paid), paid_at, created_at
  • Oprettes via den offentlige bestillings-API (opgave 8a, ingen login); admin-ordreoversigt + "markér betalt" er stadig opgave 9

• OrderLine — ordre + wine_offering + antal

  • Samme som Order — skrives af opgave 8a's bestillings-endpoint

• MailTemplate — tilhører Route, én pr. (route, event_type)

  • event_type: round_announced / order_confirmed / payment_confirmed (matcher de tre mail-events nedenfor)
  • subject, body_html — simpel {{variabel}}-substitution, ingen loops/logik i skabelonen (lister som vinkataloget genereres i kode og injiceres som færdig HTML)

• MailLog — ét forsøg pr. deltager pr. afsendelse

  • participant_id, purchase_round_id, mail_template_id, event_type, rendered_subject (denormaliseret — viser hvad der faktisk blev sendt, selvom skabelonen ændres senere)
  • status: sent (Postal tog imod) → delivered/bounced/ held/delayed/failed (opdateret asynkront via webhook)
  • postal_message_id/postal_token (til korrelation med webhook), error_message, sent_at, opened_at, clicked_at

Mail-events

1. Runde åbnes → mail til alle aktive deltagere på ruten. Implementeret (opgave 7a-c): skabelon pr. rute (MailTemplate, event_type=round_announced), udløses manuelt via POST /purchase-rounds/{id}/announce, logges i MailLog, statusopdateres løbende via Postal-webhook (POST /webhooks/postal, RSA-SHA256-signatur verificeret mod DKIM-nøglen fra DNS).
2. Ordre afgivet → kvittering til deltager. Implementeret (opgave 8a): POST /public/routes/{route_id}/orders (ingen login) genbruger 7b's render/send/log-mønster for én deltager. Manglende skabelon blokerer bevidst ikke bestillingen (kun /announce's admin-flow fejler hårdt på det) — en konfigurationsfejl må aldrig stoppe en rigtig kundes ordre. Kvitteringen genskaber bevidst det gamle systems fulde vinkatalog-layout (efterligner den fysiske bestillingsseddel ved vinbonden). Notifikation til admin ved ny ordre findes ikke endnu.
3. Nyt: Admin markerer ordre "betalt" → automatisk kvitteringsmail til deltager (opgave 9 — bygger videre på samme mønster)

Event #3 er modelleret i MailEventType (payment_confirmed) og kan allerede have en skabelon oprettet via 7a's CRUD, men selve udløsningen (fra "markér betalt"-handlingen i opgave 9) er ikke bygget endnu.

Fase 1 — nuværende scope

Færdige opgaver (1-7, 8a):

1. ✅ FastAPI + SQLModel + PostgreSQL + Alembic scaffolding
2. ✅ Datamodellerne (Organization/Route-hierarki)
3. ✅ Deltager-migrering fra MongoDB (308 deltagere importeret, dedupliceret på (route, email))
4. ✅ Login til User (JWT) + efterfølgende "sudo-stil" elevation til superadmin-handlinger
5. ✅ Admin CRUD: deltagere (inkl. aktiv/inaktiv, unik email pr. rute, GDPR-hård-sletning)
6. ✅ Admin CRUD: runder + vinliste, "kopiér fra forrige runde" (inkl. vinliste og kategori)
7. ✅ "Annoncér runde" — se detaljer under Mail-events og nedenfor:
   • 7a: MailTemplate-CRUD (POST/GET/PATCH/DELETE /mail-templates)
   • 7b: Afsendelse via Postal + MailLog (POST /purchase-rounds/{id}/announce, GET /mail-logs)
   • 7c: Postal-webhook til leveringsstatus (POST /webhooks/postal)
8. "Flyt offentlig bestillingsformular til nyt API" — delt i to:
   • 8a: ✅ Backend-API (GET /public/routes/{id}/current-round, POST /public/routes/{id}/orders), ad-hoc deltageroprettelse, kvitteringsmail
   • 8b: Selve den nye offentlige frontend — brugeren har ikke adgang til den gamle frontends kode (hårdt koblet til det gamle API), så en ny bygges. Egen stack-beslutning, ikke taget endnu.

Resterende opgaver: 9. Admin-ordreoversigt pr. runde med "markér betalt" → trigger mail #3 10. Genskab afhentningsliste (HTML-udtræk til print) mod ny datamodel 11. Simpelt React admin-UI til pkt. 5, 6, 7, 9 12. Testkør en rigtig runde gennem hele flowet

Fase 2 — senere

• enablebanking.com: automatisk match af indbetalinger mod ubetalte ordrer → kalder samme "markér betalt"-logik
• Passkey-login til admin
• Rute-vælger på bestillingssiden (når flere ruter er aktive samtidig)
• sold_only_by_case-flag + validering, hvis det bliver relevant