boc/LEDGER_ARCHITECTURE.md

# LEDGER_ARCHITECTURE.md — Hållbar struktur för LandveX ekonomisystem
*Beslutad: 2026-06-17*

## Nuläge (vad som faktiskt finns och fungerar)

### ✅ Fungerar
- `aamos-ledger` kör på port 3250, 1 092 journalposter, audit trail, multi-tenant
- Reconciliation Engine (E1-004) — API finns, POST-routes registrerade
- Period Close Workflow (E1-005) — state machine open→review→approved→closed
- SIE4 Export (E1-006) — endpoint finns
- BAS 2024 kontoplan, 38 konton aktiva
- Fortnox-klonen UI på https://landvex.com/ouroboros/finance/

### ⚠️ Trasigt/ofullständigt
- trial-balance returnerar `balanced: null` (aggregering bruten)
- Reconciliation saknar GET /sessions (lista)
- Ingen period är stängd — alla 6 perioder `open`
- 1689 Observationskonto: 966k oklassificerat
- Auth mot Identity Service inte kopplad
- Diff D:5 803 792 vs C:5 928 838 = **−125 046 kr obalans**

### 🔴 Affärskritiskt
- Q1-moms 202 787 kr OBETALD
- Leon-fordran 212 922 kr
- Konto 2990 Omföringskonto: 244 899 kr residual — betyder att omföringar inte är nollade

---

## Arkitekturen — tre lager

```
┌─────────────────────────────────────────────────────────────────┐
│  LAGER 3 — AUTOMATION & API                                      │
│  Webhooks · n8n-flows · Skatteverket · Bank-API · Stripe        │
├─────────────────────────────────────────────────────────────────┤
│  LAGER 2 — INTELLIGENCE & PUSH                                   │
│  Checkpoint-motor · Nudge-engine · Task-lista · Dashboards       │
├─────────────────────────────────────────────────────────────────┤
│  LAGER 1 — KÄRNAN (aamos-ledger)                                 │
│  Journal · Kontoplan · Perioder · Reconciliation · SIE4          │
└─────────────────────────────────────────────────────────────────┘
```

**Principen:** Lager 1 måste vara komplett och stabil innan Lager 2 byggs. Lager 3 kopplas på när Lager 2 fungerar.

---

## Lager 1 — Fixa kärnan (denna sprint)

### L1-FIX-001: trial-balance aggregering
trial-balance returnerar `balanced: null`. Buggen: totalDebit/totalCredit beräknas inte server-side.
**Fix:** Summera i route-hanteraren.

### L1-FIX-002: Reconciliation GET /sessions
Saknar `GET /api/ledger/reconciliation/sessions` — listan syns aldrig.
**Fix:** Lägg till GET-route.

### L1-FIX-003: Stäng perioder 2026-01 t.o.m. 2026-05
Alla 6 perioder är `open`. En stängd period = oföränderlig historik.
**Workflow:** submit-review → approve → close
**Förutsättning:** trial-balance måste vara balanserad per period.

### L1-FIX-004: Rensa konto 2990 (Omföringskonto)
Residual 244 899 kr. Det ska alltid vara 0 — det är ett transitkonto.
**Fix:** Identifiera och bokför rättelseposter.

### L1-FIX-005: Förklara den -125 046 kr differensen
D:5 803 792 vs C:5 928 838. Kan vara FX-poster, ej bokförda kostnader, eller periodfel.
**Fix:** Spåra källan, bokför rättelse.

---

## Lager 2 — Intelligence & Push (nästa sprint)

### L2-001: Checkpoint-motor (det som pushar dig)

En `ledger_checkpoints`-tabell med regler som körs automatiskt:

```
Checkpoint                 | Trigger              | Åtgärd
---------------------------|----------------------|---------------------------
Öppen period > 30 dagar    | Nightly cron         | Push: "2026-03 ej stängd"
Konto 1689 > 0             | On journal save      | Push: "Oklassificerade poster"
Moms förfallen             | Kalenderbaserad      | Push: "Q1-moms OBETALD"
Fordran > 60 dagar         | Nightly cron         | Push: "Leon-fordran 92 dagar"
Debet ≠ Kredit i period    | On journal save      | Blockera post
2990 > 0 vid månadsslut    | Period close trigger | Push: "Omföringskonto ej nollat"
```

### L2-002: Task-lista med status

Varje checkpoint genererar en task. Tasks har:
- `id`, `type`, `title`, `due_date`, `status` (open/snoozed/done), `amount`, `period`
- API: `GET /api/ledger/tasks` → lista med prioritet
- UI: Tasks-panel i Fortnox-klonen

### L2-003: Dashboard-siffror rätt

Koppla trial-balance till P&L och balansräkning korrekt:
- Intäkter: klass 3 (credit-saldo)
- Kostnader: klass 5-7 (debet-saldo)
- Resultat: intäkter − kostnader
- Balansräkning: tillgångar vs skulder+eget kapital

---

## Lager 3 — Automationer & API (framtida)

### Prioritetsordning

1. **Momsdeklaration API** (Skatteverket eSkattedeklaration)
   - Trigger: Period close av kvartalets sista period
   - Flow: Beräkna moms → skapa XML → POST till Skatteverket

2. **AGI-fil automatisk** (Arbetsgivardeklaration)
   - Trigger: Lönekörning bokförd
   - Flow: Summera löneposter → generera AGI-fil → skicka till Skatteverket

3. **Bank-synk automatisk** (Nordea Open Banking / Revolut Webhooks)
   - Trigger: Ny banktransaktion
   - Flow: Importera → auto-kategorisera → skapa draft → notify

4. **SIE4 till revisor automatisk**
   - Trigger: Periodeclose
   - Flow: Generera SIE4 → e-posta till andreas.vretblom@kpmg.se

---

## Stängningsceremonin — hur man stänger böckerna

**Varje månad (när Lager 1+2 är klara):**

```
1. Checkpoint-lista = tom (alla poster kategoriserade)
2. Konto 1689 = 0
3. Konto 2990 = 0  
4. D = C (trial-balance balanced: true)
5. Kör: POST /api/ledger/periods/2026-05/submit-review
6. Kör: POST /api/ledger/periods/2026-05/approve
7. Kör: POST /api/ledger/periods/2026-05/close
8. → Period låst. Kan ej ändras.
```

**Kvartalsvis tillägg:**
- Beräkna momsunderlag (konto 2611, 2645)
- Deklarera och betala moms

**Årsvis (FY 2025/2026, deadline 31 okt 2026):**
- Alla 12 perioder stängda
- Årsredovisning = P&L + Balansräkning från trial-balance
- SIE4-export till Andreas Vretblom / KPMG

---

## Sprint-plan

### Sprint 1 (nu — denna session)
- [ ] L1-FIX-001: trial-balance aggregering
- [ ] L1-FIX-002: Reconciliation GET /sessions
- [ ] L1-FIX-003: Stäng 2026-01 → 2026-03 (de klara perioderna)
- [ ] L1-FIX-004: Diagnostik på 2990 och -125k differensen

### Sprint 2
- [ ] L1-FIX-005: Rensa 1689 (auto-kategorisering av Revolut-poster)
- [ ] L2-001: Checkpoint-motor (5 basregler)
- [ ] L2-002: Tasks-API + Tasks-panel i UI

### Sprint 3
- [ ] L2-003: Dashboard P&L och balansräkning korrekt
- [ ] L3-001: Momsdeklaration-flow
- [ ] L3-004: SIE4 automatisk till revisor vid period-close

---

*Bernt äger arkitekturen. Erik godkänner.*