# Kungjort Handlingar — Lager 2 (typade kommundokument)

Typade, fulltext-sökbara svenska kommundokument, parsade ner till paragraf, roster och beslut.
Källa: kommunernas offentliga protokoll m.m. (offentlighetsprincipen). Ändamål: strukturerat
underlag för journalistik och nyhetsgenerering på kungjort.se.

## Åtkomst
Alla data-API:er kräver `Authorization: Bearer <API-nyckel>` (eller admin-session). Skapa nyckel
i UI:t under /keys. Bas-URL: https://handlingar.kungjort.se

## Datamodell
- **dokument** (h_documents): id (= arkivets document-id), kommun, kommun_namn, organ, doc_type,
  meeting_date, plats, tid, paragraf_span, ordförande/sekreterare/justerare, justering, anslag,
  roster_extern (roster ligger i separat förteckning), scanned, parse_status.
  doc_type ∈ {protokoll, protokollsutdrag, kallelse, tjänsteskrivelse, kungörelse, yttrande,
  revisionsrapport, ekonomirapport, postlista, skannad, e-post, okänd}.
- **roster** (h_persons): per person namn, parti, roll, tjanstgorande_for (ersätter vem),
  distans, deltar_ej, jav, jav_paragrafer (§§ personen var jävig i). Grupper: beslutande,
  tjanstgorande_ersattare, ersattare, ovriga.
- **paragrafer/§** (h_sections): paragraf, rubrik, dnr[], diarieplan_kod, beslut_typ
  (bifall/avslag/återremiss/bordläggning/noteras), beslut_text, sammanfattning, forslag,
  beslutsunderlag[], expedieras_till[], yrkanden, beslutsgang, reservation, jav, votering,
  fastighet, sakarende (OBJEKTIV kategori: § med Dnr + substantiell rubrik, dvs. inte mötesformalia
  som justerarval/dagordning/delgivningar — INGEN nyhetsvärdering; vad som är en nyhet avgör
  konsumenten), block_text (rå §-text = facit). DB-kolumnen heter newsworthy av historiska skäl.

## Endpoints
- `GET /api/search?q=&kommun=&organ=&doc_type=&since=&until=&dnr=&person=&sakarende=1&limit=&offset=`
  Faceterad fulltext över §-avsnitt (svensk textsökning). Returnerar träffar (dokument-id, kommun,
  organ, datum, paragraf, rubrik, dnr, beslut_typ, snippet med «…»-markering) + facetter: doc_type
  samt kommun som {slug, namn, n} — använd slug som ?kommun=-filter, namn är bara visning.
  Utan q listas senaste besluten (filterbara).
- `GET /api/documents/{id}[?full=1]` — ett helt typat dokument: möteshuvud + roster (grupperad) + alla
  paragrafer med typade fält + fil_url (same-origin-proxy till originalet) + arkiv_url (arkivets
  direkta fil-URL — citatens original-referens). full=1 → även parserns rå-header (JSON) + hela
  råtexten. Dokumentvyn i UI:t har §-ankare: /documents/{id}#p45 djuplänkar till paragrafen.
- `GET /api/documents/{id}/original` — originalfilen (PDF), proxad under denna apps auth.
- `GET /api/documents/{id}/pages[?info=1|&n=X]` — originalets sidor renderade som PNG (info=1 →
  {pages: N}, annars sida n som bild).
- `GET /api/beslut?since=&kommun=&organ=&votering=1&reservation=1&jav=1&beslut_typ=&formalia=1&limit=&offset=`
  — BESLUTSFLÖDET (neutralt): alla beslut nyast först med OBJEKTIVA filter — plattformen värderar
  inte nyhetsvärde, konsumenten (journalist eller AI) filtrerar efter sina kriterier. Varje post bär
  typade fält + block_text (facit — belägg varje påstående ordagrant där), original_url, dokument_api
  och arende_api (Dnr-tråden). Detta är kungjort.se:s primära råvarukälla; formalia utelämnas som
  default (objektiv kategori, ?formalia=1 inkluderar).
- `GET /api/arenden?dnr=&kommun=` — ärendetråden: alla §-avsnitt som bär diarienumret, kronologiskt
  över möten/organ (deterministisk koppling, exakt Dnr).
- `GET /api/personer?namn=&kommun=` — en persons framträdanden i rosterdata (roll, tjänstgöringar,
  jäv med §§), grupperat per NAMN med partier[] aggregerade över beläggen (parti = första belagda,
  bakåtkompatibilitet).
- `GET /api/browse[?kommun=slug]` — bläddringsdata: kommunöversikt (täckning) resp. en kommuns
  organ + mötestidslinje. Organ-listan är skiftläges-normaliserad ("KOMMUNSTYRELSEN" och
  "Kommunstyrelsen" = ett organ); organ-filtren i /api/search och /api/beslut matchar
  skiftläges-okänsligt.
- `GET /api/stats` — antal dokument/§/personer/kommuner, datumspann, doc_type- och status-fördelning.
- `POST /api/ingest` — (parse-worker) upsertar parsade dokument. `GET` ger ingest-status.
- `GET/POST /api/admin` — (admin-session) granska/sätt parse_status; 3-panels-granskning i UI:t på
  /admin/review/{id} (original | återmonterat | rådata).

## Kvalitetsmodell (autonom)
parse_status: parsed (ev. flaggor: skannad, roster-saknas, "verifierad: datum=arkiv", "datum: från
arkiv", "datum: parser vald, arkiv avvek (…)", "datum: arkiv vald, parser avvek (…)") ·
needs_review (ENDAST datum-motsägelse som datumdomaren inte kunnat avgöra) · error (parse_error,
maskin-känt trasig) · approved/flagged (manuellt; skyddas mot om-parsning). Parsad möteshuvud-datum
verifieras mot arkivets källdatum per dokument; vid motsägelse dömer datumdomaren deterministiskt
(rimlighet, intern konsistens i dokumenttexten, dokumenttypssemantik — t.ex. är ett protokolls-
utdrags eget mötesdatum facit medan arkivdatumet är det mottagande mötet) och vinnaren blir
meeting_date med informationsflagga.

## Att skriva nyheter av detta
En nyhet börjar oftast i ett sakärende-§ med ett Dnr — men BEDÖMNINGEN är din: plattformen taggar
bara (votering/reservation/jäv/beslut_typ/sakarende). Relaterade handlingar hittas via
samma Dnr (ärende-tråd över möten) och samma möte. block_text är facit — alla påståenden ska kunna
beläggas ordagrant där. Roster ger vem som beslutade, vem som var jävig och vem som ersatte vem.