# Part 2: Period Management & Year-End Closing

## Overview

Part 2 implements **year-end closing (årsbokslut)** — the process that legally closes a fiscal year per Bokföringslagen. This includes period locking, closing entry generation, opening balance propagation, and the API surface to drive the workflow.

**Depends on Part 1:** immutable ledger, audit trail, tax codes, document archive, period lock enforcement, retention protection.

---

## What Was Built

### Migration 19: Period Closing Metadata

**File:** `supabase/migrations/20240101000019_period_closing.sql`

Three new columns on `fiscal_periods`:

| Column | Type | Purpose |
|--------|------|---------|
| `closing_entry_id` | `uuid FK → journal_entries` | Links to the year-end closing journal entry |
| `opening_balance_entry_id` | `uuid FK → journal_entries` | Links to the opening balance entry in this period |
| `previous_period_id` | `uuid FK → fiscal_periods` | Chain link to the prior period for validation |

One new trigger:

- **`enforce_opening_balance_immutability`** — Once `opening_balance_entry_id` or `closing_entry_id` are set, they cannot be changed. This prevents tampering with the closing chain after the fact.

---

### TypeScript Types

**File:** `types/index.ts`

Extended `FiscalPeriod` with the three new nullable fields.

New interfaces:

| Interface | Purpose |
|-----------|---------|
| `YearEndValidation` | Result of readiness check: `ready`, `errors[]`, `warnings[]`, `draftCount`, `voucherGaps[]`, `trialBalanceBalanced` |
| `YearEndPreview` | Preview of closing: `netResult`, `closingAccount` (2099/2010), `closingLines[]`, `resultAccountSummary[]` |
| `YearEndResult` | Result of execution: `closingEntry`, `nextPeriod`, `openingBalanceEntry` |
| `PeriodStatus` | Status summary: lock/close/draft/opening state |

---

### Period Service

**File:** `lib/core/bookkeeping/period-service.ts`

| Function | What it does |
|----------|-------------|
| `lockPeriod(userId, fiscalPeriodId)` | Sets `locked_at = now()`. Validates period exists, belongs to user, isn't already locked/closed. After locking, the `enforce_period_lock` trigger (from Part 1) blocks new journal entries. |
| `closePeriod(userId, fiscalPeriodId)` | Sets `is_closed = true, closed_at = now()`. Requires: already locked AND `closing_entry_id` is set. This is the final, permanent state. |
| `createNextPeriod(userId, currentPeriodId)` | Creates the next fiscal year. Computes dates from the current period's length to handle **brutet räkenskapsår** (broken fiscal years, e.g. Jul–Jun). Sets `previous_period_id` for chain validation. Auto-generates name like "FY 2025" or "FY 2025/2026". |
| `getPeriodStatus(userId, fiscalPeriodId)` | Returns a summary: `is_locked`, `is_closed`, `has_closing_entry`, `has_opening_balances`, `draft_count`, `next_period_exists`. |

---

### Year-End Service

**File:** `lib/core/bookkeeping/year-end-service.ts`

This is the core new logic.

#### `validateYearEndReadiness(userId, fiscalPeriodId)` → `YearEndValidation`

Checks preconditions before allowing year-end closing:

- **Blocking errors** (prevent closing):
  - Period already closed
  - Closing entry already exists
  - Draft journal entries exist (must be posted or deleted)
  - Trial balance is not balanced
- **Warnings** (informational):
  - Voucher number gaps detected (via `detect_voucher_gaps()` SQL function)
  - No posted entries in the period

#### `previewYearEndClosing(userId, fiscalPeriodId)` → `YearEndPreview`

Generates a preview without persisting anything:

1. Looks up `entity_type` from `company_settings` → determines closing account:
   - **Aktiebolag (AB):** account `2099` (Årets resultat)
   - **Enskild firma (EF):** account `2010` (Eget kapital)
2. Runs income statement to get `net_result`
3. Gets trial balance, filters to class 3–8 accounts
4. For each account with a non-zero balance: creates a line that zeros it
5. Adds a final balancing line to the closing account (2099/2010)
6. Returns the preview with all lines and a summary of result accounts

#### `executeYearEndClosing(userId, fiscalPeriodId)` → `YearEndResult`

Full orchestration (the main entry point):

```
1. validateYearEndReadiness()     → abort if errors
2. previewYearEndClosing()        → get closing lines
3. createJournalEntry()           → create closing entry (source_type: 'year_end')
4. UPDATE fiscal_periods          → set closing_entry_id
5. lockPeriod()                   → lock the period
6. closePeriod()                  → permanently close
7. createNextPeriod()             → create next fiscal year
8. generateOpeningBalances()      → carry forward class 1-2 balances
9. Return { closingEntry, nextPeriod, openingBalanceEntry }
```

#### `generateOpeningBalances(userId, closedPeriodId, nextPeriodId)` → `JournalEntry`

Creates opening balance entries in the new period:

1. Gets trial balance of the closed period (after closing entry)
2. Filters to balance sheet accounts (class 1–2) with non-zero closing balance
3. Creates a journal entry with `source_type: 'opening_balance'`:
   - Debit accounts get debit opening, credit accounts get credit opening
4. Verifies the entry is balanced (total debit = total credit)
5. Sets `opening_balance_entry_id` and `opening_balances_set = true` on the next period

**Key invariant:** UB (utgående balans) of year N == IB (ingående balans) of year N+1.

---

### API Routes

All follow the existing pattern: authenticate via Supabase, delegate to service, return JSON.

| Method | Path | Handler |
|--------|------|---------|
| `POST` | `/api/bookkeeping/fiscal-periods/[id]/lock` | `lockPeriod()` |
| `GET` | `/api/bookkeeping/fiscal-periods/[id]/year-end` | `validateYearEndReadiness()` + `previewYearEndClosing()` |
| `POST` | `/api/bookkeeping/fiscal-periods/[id]/year-end` | `executeYearEndClosing()` |
| `POST` | `/api/bookkeeping/fiscal-periods/[id]/close` | `closePeriod()` |

---

## Reused Components

| Component | From | Used by |
|-----------|------|---------|
| `generateTrialBalance()` | `lib/reports/trial-balance.ts` | Balance aggregation for closing + opening entries |
| `generateIncomeStatement()` | `lib/reports/income-statement.ts` | Net result calculation |
| `createJournalEntry()` | `lib/bookkeeping/engine.ts` | Creating closing + opening entries (auto-posts) |
| `validateBalance()` | `lib/bookkeeping/engine.ts` | Pre-flight balance check |
| `detect_voucher_gaps()` | Migration 16 SQL function | Gap validation during readiness check |
| `enforce_period_lock` trigger | Migration 17 | Blocks writes after locking |
| `enforce_journal_entry_immutability` trigger | Migration 17 | Protects closing/opening entries after posting |

---

## Period Lifecycle Diagram

```
                    ┌─────────┐
                    │  OPEN   │  ← Journal entries can be posted
                    └────┬────┘
                         │ lockPeriod()
                         ▼
                    ┌─────────┐
                    │ LOCKED  │  ← No new entries (enforce_period_lock trigger)
                    └────┬────┘
                         │ closePeriod() (requires closing_entry_id)
                         ▼
                    ┌─────────┐
                    │ CLOSED  │  ← Permanent, immutable
                    └─────────┘
```

The `executeYearEndClosing()` function drives the full flow from OPEN → CLOSED in one call, including creating the closing entry, locking, closing, creating the next period, and generating opening balances.

---

## Verification Checklist

- [x] `npx tsc --noEmit` — zero TypeScript errors
- [ ] Migration 19 applies cleanly (`\d fiscal_periods` shows new columns)
- [ ] `GET /api/bookkeeping/fiscal-periods/[id]/year-end` returns preview with net result
- [ ] `POST /api/bookkeeping/fiscal-periods/[id]/year-end` creates closing entry, locks, closes, creates next period, generates opening balances
- [ ] Closing entry zeros all class 3–8 accounts
- [ ] Opening balance entry in next period matches UB of closed period (class 1–2 only)
- [ ] Closed period rejects new journal entries (period lock trigger)
- [ ] Period with draft entries → validation fails with blocking error
- [ ] Period already closed → validation fails
- [ ] EF entity type → closing goes to 2010 (not 2099)

---

## Files Changed/Created

| File | Action |
|------|--------|
| `supabase/migrations/20240101000019_period_closing.sql` | **Created** — 3 ALTER columns + 1 trigger |
| `types/index.ts` | **Modified** — extended FiscalPeriod, added 4 new interfaces |
| `lib/core/bookkeeping/period-service.ts` | **Created** — lockPeriod, closePeriod, createNextPeriod, getPeriodStatus |
| `lib/core/bookkeeping/year-end-service.ts` | **Created** — validateYearEndReadiness, previewYearEndClosing, executeYearEndClosing, generateOpeningBalances |
| `app/api/bookkeeping/fiscal-periods/[id]/lock/route.ts` | **Created** — POST lock endpoint |
| `app/api/bookkeeping/fiscal-periods/[id]/year-end/route.ts` | **Created** — GET preview + POST execute |
| `app/api/bookkeeping/fiscal-periods/[id]/close/route.ts` | **Created** — POST close endpoint |