teecup/CLAUDE.md

CLAUDE.md — arbeidsinstruks for TeeCup

Les dette først i hver økt. Det koder hva vi har bestemt og hvordan vi jobber.

Autoritative kilder (les før du gjør noe)

• ARCHITECTURE_DECISIONS.md — hva som er bestemt og hvorfor (ADR-001…). Fasit.
• FEATURE_BACKLOG.md — hva som gjenstår, hva som er utsatt, hva som mangler.
• CHANGELOG.md — kronologisk arbeidslogg (hva som er bygget, når, hvordan det ble verifisert, kjente fallgruver funnet underveis). IKKE noe å lese i sin helhet hver økt — les den ved regresjon-feilsøking, eller når du trenger å vite hvordan/hvorfor noe konkret ble bygget som det ble (grep etter filnavn/ADR-nummer/feature-navn). Se filens egen header for full bruksanvisning.
• Endres en beslutning: legg til en ny ADR, ikke slett historikk. Hold disse filene oppdatert når noe avgjøres.
• Regelverk for HCP/slagfordeling — tre PDF-er lastet opp av brukeren 2026-07-19 (ikke innsjekket i git, kun lokale filer på serveren, flyttet fra prosjektroten til Temp-uploads/ 2026-08-07 — se eget notat om denne mappen lenger ned): Temp-uploads/spilletyper-og-spilleformer-2023.pdf, Temp-uploads/Live Tourney _ A Guide to Handicap Scoring in Golf for Tournaments.pdf, Temp-uploads/SCGA Club Digest.pdf. Brukeren: disse tre gir til sammen en tydelig beskrivelse av hvordan HCP og mottatte/tildelte slag skal beregnes/ fordeles. Les disse FØR videre arbeid med handicap_engine.py, app/handicap.py, allowance-strategier (ADR-005/014) eller slagfordeling (ADR-008) for NYE turneringsformater. Rettelse 2026-08-05: de opprinnelige fire (Københavner/High-low-high/Robbins/ Try all) er ikke lenger de aktuelle — Københavner, High-low-high og Try all (Chapman/Pinehurst) er alle bygget og live (se FEATURE_BACKLOG.md), Robbins ble droppet av bruker. Gjelder nå enhver FREMTIDIG ny turneringsform (f.eks. asymmetriske lag-vs-individuell- formater) — les PDF-ene før slagfordelingen designes for slike.
• Design-dokumentasjon, to filer med bevisst motsatt retning (2026-07-27): DESIGN_SYSTEM.md (innsjekket i git) er DESKRIPTIV — hva som faktisk ER i koden i dag (farger/typografi/komponentmønstre/golfscore-språket), avledet direkte fra globals.css/components/ui/*. teecup-scorekort-og-entry- spec.md (lastet opp av brukeren til prosjektroten, IKKE innsjekket i git) er PRESKRIPTIV — hva scorekort-/score-entry-skjermene BØR bli, basert på en sammenligning mot fem etablerte golf-apper. Der de to avviker vinner kildekoden (DESIGN_SYSTEM.md beskriver den), men spec-dokumentets §3 "Compliance-pass" er en konkret sjekkliste over kjente avvik — les den FØR videre visuelt arbeid på scorekort-/score-entry-skjermene.
• Temp-uploads/-mappen (opprettet av bruker 2026-08-07, gitignored) er der brukeren laster opp støttefiler — skjermdumper, videoer, PDF-er, V0-eksport-zip-er og lignende — ment som illustrasjon/kildemateriale til Claude, ikke som permanente prosjektfiler. Sjekk denne mappen når brukeren nevner at de "har lastet opp" noe uten å oppgi full sti. Flytt nye støttefiler dit etter hvert som de dukker opp i prosjektroten, fremfor å la dem hope seg opp løst i roten.

Sikkerhetsregler (ufravikelige)

• Rør ALDRI teeoff-databasen eller den ekte teecup_db uten at brukeren eksplisitt har bekreftet det i samme økt. Test alltid migrasjoner mot en egen scratch-database først, og rydd opp etterpå.
• Vis planen (hvilke kommandoer, mot hvilken database) FØR du kjører noe som skriver, migrerer eller sletter. Vent på bekreftelse.
• Hemmeligheter (passord, secrets) bor i .env (filrettigheter 600), dekkes av .gitignore, committes aldri, og skrives aldri i klartekst i chatten eller i SQL-filer. Generer dem på serveren (openssl rand -base64 32).
• Kjør appen som databaserollen teecup_app (NOSUPERUSER, NOBYPASSRLS) — aldri som teeoff_admin/superuser i runtime.

Arkitektur-invarianter (ikke bryt uten en ny ADR)

• Tenant = organisasjon. organization_id på alle domenetabeller, håndhevet av RLS. App-koden setter app.current_org med SET LOCAL per transaksjon.
• Verifiser at brukeren er medlem av organisasjonen FØR org-konteksten settes. RLS stoler blindt på app.current_org.
• Egen innlogging (uavhengig av teeoff). Banedata hentes fra teeoff via lesende API, ikke delt database.
• v1 = nøyaktig to lag (Ryder Cup-format), håndhevet i app-laget. Match-modellen holdes generell (to sider) så knockout/flere lag kan komme senere.
• Handicap-/matchlogikk skal ligge i handicap_engine.py (rent, testet, uten db/API-avhengigheter). Allowances er konfig, ikke hardkodet.
• Media (bilder/video) skal i objektlagring (MinIO), ikke i Postgres. Postgres holder bare metadata + nøkkel.

Tilgjengelighet — frontend (ufravikelig, gjelder ALT, eksisterende og fremtidig)

• Brukeren instruerte eksplisitt 2026-07-22: ALL frontend — det som allerede finnes OG alt som designes med V0 fremover — skal være lesbart, forståelig og betjenbart for noen med noe redusert syn UTEN briller, så langt det praktisk lar seg gjøre. Dette er en STÅENDE forventning til alt fremtidig UI-arbeid, ikke en engangsting for én skjerm.
• Praktisk konsekvens: god kontrast, stor nok skrift, store nok trykkflater, ikke ikon-only uten tekst-label for viktige handlinger, ikke avhengig av finmotorikk/skarpt syn for å bruke appen.
• Gjelder begge retninger: (a) ta dette eksplisitt med som krav når en ny V0-prompt skrives eller en V0-eksport gjennomgås, og (b) rett opportunistisk opp eksisterende skjermer når de likevel røres i en annen runde — ingen egen stor retrofit-runde er igangsatt eller bedt om ennå.

Navneformat (ufravikelig, gjelder ALT, eksisterende og fremtidig)

• Brukeren instruerte eksplisitt 2026-07-26: når TeeCup kommuniserer DIREKTE TIL brukeren (adresserer dem, "snakker til" dem) — f.eks. en dashbord-hilsen ("God morgen Erol") eller en e-post/varsel rettet til mottakeren selv — skal KUN FORNAVN brukes, aldri fullt navn.
• Til vanlig (lister, roster, chat-forfatter, "fjern X"-bekreftelser, administrasjonsvisninger, alt som IKKE er direkte adressering) brukes fortsatt fullt navn, eller initial(er)+etternavn, eller annet som er nødvendig for å skille personer fra hverandre — ikke fornavn alene der.
• Samme STÅENDE forventning som tilgjengelighetsregelen over: gjelder fremtidig arbeid direkte, og rettes opportunistisk når en skjerm likevel røres — ingen egen retrofit-runde igangsatt.
• ✅ FIKSET 2026-07-26 (samme dag, i "fiks alle kjente små bugs"- runden): dashbordets hilsen brukte fullt navn — rettet til me.first_name ?? me.display_name (/auth/me eksponerte allerede first_name separat, ingen backend-endring nødvendig). Se CHANGELOG.md for full detalj.

Turneringsoppsett — stor skjerm først (ufravikelig, gjelder ALT, eksisterende og fremtidig)

• Brukeren instruerte eksplisitt 2026-08-17: turneringsOPPSETT (opprette turnering, sette opp lag/tropper, importere/administrere spillere, runder, klasser, baneoppsett, alt organisator-arbeid FØR/RUNDT selve spillingen) skal designes "stor skjerm først", IKKE "mobil først" — organisatoren sitter som regel foran en PC når dette gjøres, ikke på mobil på banen. Dette er en STÅENDE forventning til alt fremtidig UI-arbeid på denne typen skjermer, ikke en engangsting.
• Gjelder KUN oppsett-/administrasjonsskjermer. Skjermer SPILLEREN bruker UNDER selve rundens gang (scorekort/slag-registrering/rangefinder/ leaderboard-under-spilling) forblir mobil-først som før — de brukes på banen, på mobil, ikke ved en PC. Grensen følger hvem som sitter hvor, ikke en fast liste — vurder per skjerm hvem som faktisk bruker den og fra hvilken enhet.
• Praktisk konsekvens: layout/typografi/tett-vs-luftig-avstand optimaliseres for et bredt skjermbilde som førstevalg (f.eks. tabeller med flere synlige kolonner samtidig i stedet for kortstabler, sidepanel- layout i stedet for full-bredde-modaler, hover-tilstander som en reell interaksjon), men skal FORTSATT fungere og være betjenbart på smal skjerm (samme STÅENDE tilgjengelighetsregel over gjelder uansett skjermbredde) — "stor skjerm først" er en prioritering av hvilket format som designes FOR primært, ikke en unnskyldning for å la mobil forfalle.
• Gjelder begge retninger: (a) ta dette eksplisitt med som krav når en ny V0-prompt skrives for et oppsett-/administrasjonsskjermer, og (b) rett opportunistisk opp eksisterende oppsett-skjermer når de likevel røres i en annen runde — ingen egen stor retrofit-runde er igangsatt eller bedt om ennå.

Arbeidsmåte

• Inkrementelt. Ingenting tas for gitt før det er testet. Bekreft hvert steg før du går videre.
• Bruk git (remote: brukerens Forgejo). Commit i logiske steg med tydelige meldinger.
• Er du usikker på omfang eller en beslutning: spør heller enn å gjette.

Status og neste steg

Den detaljerte, kronologiske statusloggen (hva som er ferdig, verifisert og rullet ut, runde for runde) flyttet til CHANGELOG.md 2026-08-02 — denne filen ble for stor til å injiseres i sin helhet hver økt uten å fortrenge de faktiske reglene over. CHANGELOG.md sin egen "Neste steg"-seksjon nederst har den ferskeste, mest detaljerte punktlisten over åpne tråder; FEATURE_BACKLOG.md har det bredere, mindre ferske bildet av hva som gjenstår/er utsatt. Oppdater CHANGELOG.md (ikke denne filen) når noe bygges, verifiseres og rulles ut — samme format og disiplin som før: dato, hva som ble gjort, hvordan det ble verifisert, hva som ble rullet ut og hvordan.