Kom igång

id: kom-igang
path: /dev/kom-igang
titel: Kom igång
summering: Miljön, kommandona, repokartan och vägen genom din första ändring.
nyckelord: onboarding, miljö, yarn, node, kommandon, repo, docker

## Förutsättningar

Krav | Version | Kommentar
Node | >= 24 | Som kommunens starter. Installeras med nvm.
Yarn | 4.9.1 via corepack | corepack enable. Inte npm, inte pnpm.
WSL | WSL2 med Ubuntu | Arbeta i WSL-filsystemet, inte under /mnt/c – I/O-prestandan skiljer dramatiskt.
Docker | Desktop med WSL-integration, eller Engine i WSL | Behövs för att verifiera containern före push.

## Kommandon

Kommando | Gör
yarn dev | Båda apparna: projektportalen på 3000 och startsideportalen på 3010, som nås via http://localhost:3000/portal.
yarn lint | ESLint över hela repot från eslint.config.mjs i roten. Ett nytt paket lintas utan att något läggs till.
yarn test | Vitest över hela repot från vitest.config.mts. Tester plockas upp på filnamn: packages/**/test/**/*.test.ts.
yarn typecheck | tsc --noEmit i varje paket, topologiskt.
yarn build && yarn start | Produktionsbygge lokalt.
docker compose up --build | Samma bygge som Dokploy gör.

yarn lint och yarn test ska vara gröna före varje commit. Docker-bygget körs innan push.

## Var saker ligger

```
startsidan/
├── CLAUDE.md                  regler som gäller varje session
├── docs/
│   ├── plan.md                planen, modulkontraktet, beslutsregistret
│   ├── plan-modul-felanmalan.md
│   ├── beslut/                ADR:er
│   └── *.html                 DESIGNFACIT: prototyperna
├── apps/
│   ├── portal/                startsideportalen, basePath /portal (ADR-040)
│   │   └── src/
│   │       ├── app/           App Router: sidor, route handlers, /dev
│   │       ├── shell/         skalet: sidopanel, AI-fält, registry, session
│   │       └── ai/            flödenas AI-adapter och takgräns
│   └── projekt/               projektportalen på roten – inte startsidan
└── packages/
    ├── tokens/                designtokens (@theme) och basregler
    ├── ui/                    primitiverna (medBas för basvägen)
    ├── ai/                    den strukturerade AI-adaptern, gemensam
    ├── gemensamt/             beslutsregistret, varumärket, spärren mot gissningar
    ├── dokumentation/         katalogpost, dok, kontraktet och Blockvy
    ├── module-sdk/            kontraktet mellan skal och modul
    └── modules/<namn>/        en modul: manifest.ts, components/, data/
```

Varje modul har samma inre form: manifest.ts, components/, data/ (mock plus adapterinterface), index.ts. Det gör modulerna kopierbara som mall när nästa behov dyker upp.

## Din första ändring

1. Läs sammanhanget
   CLAUDE.md för reglerna, /dev/arkitektur för hur delarna hänger ihop, /dev/ui/llms.txt för designsystemet. Prototyperna i docs/ är designfacit – utseendet ska matcha dem.
2. Sök i katalogen först
   Finns primitiven, modulen eller endpointen redan? Katalogen finns just för att svara på det innan något nytt skapas.
3. Välj rätt form
   Kort på arbetsytan → widget i slots.main eller slots.side. Rad som kräver handling → slots.actions. Helskärmsflöde → routes med mode: "focus". Arbetsplats över hela ytan med sidopanelen kvar → mode: "full". Knapp bredvid hälsningen → slots.genvag.
   ```
   // se /dev/recept för steg per fall
   ```
4. Bygg modulen, inte skalet
   Skalet ändras bara när kontraktet faktiskt saknar något – och då som ADR i docs/beslut/.
5. Stäng med grindarna
   yarn lint && yarn test, sedan docker compose up --build, sedan commit med Conventional Commits på svenska.
   ```
   yarn lint && yarn test
   docker compose up --build
   git commit -m "feat(kalender): veckovy i högerspalten"
   ```

## Verifiera att det funkar
Grindarna säger att koden håller, inte att funktionen gör rätt. De tre stegen nedan är skillnaden.

1. Kör grindarna
   Alla tre täcker hela repot, inklusive nya paket. Typecheck är den som ser modulkoden hårdast, eftersom paketen kör noUncheckedIndexedAccess.
   ```
   yarn lint && yarn test && yarn typecheck
   ```
2. Växla roll och kontrollera båda vyerna
   Rollfiltreringen är det som oftast blir fel: en widget utan roles ärver modulens, och en modul utan rätt roles syns inte alls. Växla demoanvändare i användarmenyn och kontrollera att både medarbetare och chef ser det de ska – och inte det de inte ska.
3. Kontrollera formen mot facit
   Prototyperna i docs/ är designfacit. Gå igenom felindexet på /dev/ui mot din diff: tokens i stället för hex, headingId på varje Card, statusfärg i kant eller chip, AiChip på allt AI-genererat.
   ```
   curl -s http://localhost:3000/api/health   # svarar { ok: true }
   ```

Playwright-röktest kommer i fas 5. Tills dess är rollväxlingen den manuella kontroll som inte får hoppas över.

## När är det klart?
Klar betyder körbar, granskad och dokumenterad. Saknas något av de tre är funktionen påbörjad, inte levererad – och den ska inte lämnas över för test.

- yarn lint, yarn test och yarn typecheck är gröna.
- Båda rollerna är kontrollerade i webbläsaren: medarbetare och chef ser det de ska, och inte det de inte ska.
- Diffen är genomgången mot felindexet på /dev/ui.
- Katalogposten finns i apps/portal/src/app/dev/portal/katalog.ts – identitet, applikationen den hör till (projekt, portal eller gemensam, ADR-040), status, källa, relationer, vad den levererar.
- Doket finns i apps/portal/src/app/dev/portal/dok.ts och uppfyller dokumentationskontraktet, inklusive kvarstar och uppdaterad.
- Täckningen på /dev/docs visar inga luckor.
- Berörda dok för andra delar är uppdaterade – en ny modul som bidrar med actions ändrar också doket för agera.
- Rör ändringen ett arkitekturbeslut finns en ADR i docs/beslut/, i samma commit.

Ordningen spelar roll: dokumentationen skrivs som en del av bygget, inte efteråt. Skrivs den efteråt beskriver den vad som råkade bli, inte vad som var avsikten – och då är fältet kvarstar alltid tomt.

- /dev/docs#kontrakt — Dokumentationskontraktet (fälten och vad som krävs)
- /dev/docs#tackning — Täckningen (vilka delar som saknar dok)

Hela portalen i samma form: /dev/llms.txt · /dev/spec.json