Bilko Modul B-1 — GL Foundation Build (2026-06-13)

TL;DR

Bilko Modul B-1 GL Foundation je KOMPLETAN. Backend (commit 6efb16f9) + frontend (commiti 69c87cf3 + b1f6401a) izgradeni. GL subsystem je iza BILKO_ACCOUNTING_GL + GL_AUTO_POST flagova — obje default OFF globalno. Modul A (fakturisanje) potpuno netaknut. Proveo UAT PASS 20/20 (MC #103549), Vlado domain acceptance PRIHVACENO 19/19, Petter (lead) sign-off: merge GO. PR #369 ceka CEO merge odluku — dormantan, flag-gated, nema regresije.

B-1 ZAVRSEN (stanje 2026-06-13)

Bilko Modul B-1 — GL Foundation je KOMPLETAN. Backend + frontend izgradjeni, Proveo UAT PASS (20/20), Vlado domain acceptance PRIHVACENO (19/19), Petter (lead) sign-off: merge GO. PR #369 je spreman za CEO merge odluku — flag-gated (BILKO_ACCOUNTING_GL default OFF), Module A potpuno netaknut, nema regresije.

Sta modul radi (iza BILKO_ACCOUNTING_GL flag, default OFF)

Backend (commit 6efb16f9)

• GL engine: tabele journal_entries, journal_postings, posting_rules, account_mapping, bilko_flags
• PG trigeri: balance-invariant (P0001), immutability (P0002), idempotency (P0004) — okidaju uzivo na PG16
• 9 REST endpointa na /api/v1/accounting/*
• Flyway V85 — permissions seed (accounting:view, accounting:post, accounting:manage)
• PAYMENT/CREDIT_NOTE bridge (unit-tested; GL_AUTO_POST zasebni flag, default OFF)
• 68 GL unit + 10 HTTP integration testova — sve zeleno

Frontend (commiti 69c87cf3 + b1f6401a)

• 5 stranica pod app/(dashboard)/accounting/:
  • kontni-plan — tabela Konto | Naziv | Uloga, HR account names (RRiF konvencija)
  • temeljnice — glavna knjiga, paginirani pregled DRAFT/POSTED/REVERSED sa filterima
  • temeljnica/[id] — detalj: postings Duguje/Potrazuje, akcije Potvrdi (DRAFT→POSTED) i Storno
  • nova-temeljnica — rucni unos s live balance-check (ΣD=ΣC prikazano uzivo)
  • bruto-bilanca — per-account totalDebit/totalCredit/saldo, grand totals, asOf filter; ΣD=ΣC indikator
• Sidebar "Knjigovodstvo" nav sekcija (gating: accountant/admin/owner rola)
• 404-graceful gating — kada je flag OFF, stranice prikazuju "Ovaj modul nije dostupan" (ne crashaju)
• 5 lokalizacijskih lokala
• Playwright spec: apps/e2e/tests/accounting-b1.spec.ts (commitan, spreman za browser run kada je demo SSL dostupan)

Tok racunovodje

1. Otvori Kontni plan — pregled konta (logicalRole / accountCode / jurisdikcija, HR RRiF)
2. Faktura/placanje kreira DRAFT temeljnicu automatski (kada je GL_AUTO_POST ON) ili rucni unos
3. Potvrdi DRAFT → POSTED (trajna, nepromjenjiva knjizba)
4. POSTED entry se pojavljuje u Glavnoj knjizi (temeljnice pregled)
5. Bruto bilanca pokazuje ΣD=ΣC — system-level invariant verificiran trigerom i API-jem
6. Storno = nova reversing POSTED entry (append-only, original nikad ne brises; cl. 11.3 ZoR)

Validacija

Iskrene ogranicenja / odgodeno na B-2

• Live invoice → auto-DRAFT: bridge unit-tested; e2e nije provjereno (GL_AUTO_POST je OFF zasebni flag; aktivira se u B-2 kada aktiviramo pilot org)
• Browser-layer E2E: odgodjeno (demo SSL nedostupan za Playwright live run); spec commitan u apps/e2e/tests/accounting-b1.spec.ts
• Sekvencijalno numerisanje temeljnica: B-2
• Predujam (avans) bridge kompletno: B-2 (6c knjizenje — netiranje avansa, djelomicni avans)

Production-activation gates (prije pravog racunovodje)

1. Operator ukljuci BILKO_ACCOUNTING_GL = true za imenovanog pilot org (GL_AUTO_POST ostaje OFF do gate 2)
2. [VERIFY-NN] OBAVEZNO: pravna provjera na narodne-novine.nn.hr / porezna-uprava.gov.hr za 10 VERIFY-NN stavki (PDV stope/clanci) — nije opcionalno
3. Imenovan racunovoda design-partner (board U2) live walkthrough sign-off

Status PR #369

Merge preporuka: GO — dormantan, flag-gated, Module A netaknut, nema regresije. Ceka CEO merge odluku.

Veze

• Spec/board page: page 3115 (B-1 board presuda)
• PR #369 — feature/b1-gl-foundation
• MC #103531 (parent) | #103547 (backend Proveo) | #103548 (frontend Vizu) | #103549 (UAT) | #103550 (docs)

Architecture

Database — 5 tables, Flyway migration V84

Postgres Triggers — 3 enforcement points

PostingRuleEngine (Kotlin)

Located at apps/api/src/main/kotlin/no/alai/bilko/gl/PostingRuleEngine.kt. The engine is config-driven: it reads JSONB posting templates from the posting_rules table and resolves amounts from the incoming GlDocumentData struct. It never computes tax; all net/vat/gross values must originate from the Module A invoice document.

Key behaviours:

• Gross check — net + vat must equal gross; mismatch returns REJECTED status (no crash).
• Rule lookup — matched by (event_type, jurisdiction, vat_exemption_code). Most-specific match wins (rule with explicit vat_exemption_code scores higher than wildcard null match).
• split_by vat_rate — for multi-rate invoices (Event 2), one CREDIT posting is emitted per distinct VAT rate line, each carrying vat_rate for the B-2 VAT return.
• No rule found — returns ZA_KONTIRANJE status (no crash, Module A unaffected, accountant must manually post).
• All drafts — status=DRAFT, requiresAccountantConfirmation=true always set on output.

GlBridge — A to B integration point

Located at apps/api/src/main/kotlin/no/alai/bilko/gl/GlBridge.kt. Called from InvoiceService.sendInvoice() inside the existing orgTransaction after the invoice transitions to SENT status.

• If BILKO_ACCOUNTING_GL=false: early return, engine is never called (MockK verify exactly=0 confirmed by Proveo).
• If GL_AUTO_POST=false: early return.
• Both ON: engine called, result persisted as DRAFT via GlRepository.persistDraft().
• Idempotent: if a journal entry already exists for the same (org, source_type, source_document_id), persistDraft returns null (no duplicate, no exception).
• Non-throwing: all GL errors are caught and logged; Module A (invoice flow) is never interrupted.

Posting Rules — Vlado's 6 Events

Domain contract authored by Vlado Brkanić (certified accountant, design-partner). Scope: outgoing/sales documents only, Croatian jurisdiction (HR). All amounts in EUR. Rates: 25% / 13% / 5% [VERIFY-NN čl.38].

JSONB Rule Format — R-1 and R-3a examples

R-1: Taxable domestic invoice (vat_exemption_code is null):

{
  "event_type": "SALES_INVOICE_ISSUED",
  "jurisdiction": "HR",
  "match": { "vat_exemption_code": null },
  "postings": [
    { "account": "1200", "side": "DEBIT",  "amount_source": "invoice.gross", "analytic": "partner:{invoice.partner_oib}" },
    { "account": "7600", "side": "CREDIT", "amount_source": "invoice.net" },
    { "account": "2400", "side": "CREDIT", "amount_source": "invoice.vat_by_rate", "split_by": "vat_rate", "carry": ["vat_rate"] }
  ],
  "balance_assert": "sum(DEBIT) == sum(CREDIT)",
  "status_on_create": "DRAFT",
  "requires_accountant_confirmation": true
}

R-3a: EU-exempt supply (vat_exemption_code = "EU_41"):

{
  "event_type": "SALES_INVOICE_ISSUED",
  "jurisdiction": "HR",
  "match": { "vat_exemption_code": "EU_41" },
  "report_target": "ZP",
  "postings": [
    { "account": "1201", "side": "DEBIT",  "amount_source": "invoice.gross", "analytic": "partner:{invoice.partner_vat_id}" },
    { "account": "7610", "side": "CREDIT", "amount_source": "invoice.net" }
  ],
  "balance_assert": "sum(DEBIT) == sum(CREDIT)",
  "status_on_create": "DRAFT",
  "requires_accountant_confirmation": true,
  "preconditions": ["partner_vat_id_valid_vies"]
}

How to Enable the Module (Operator Runbook)

The two flags

What happens when both flags are ON

1. Invoice transitions to SENT in Module A (InvoiceService).
2. GlBridge.onInvoiceIssued() is called inside the existing orgTransaction.
3. PostingRuleEngine evaluates the invoice against JSONB rules in posting_rules.
4. A DRAFT journal entry + postings are persisted. Status = DRAFT, requiresAccountantConfirmation = true.
5. Accountant reviews the DRAFT in the (future) accounting module UI and transitions to POSTED manually.
6. If an entry already exists for this invoice (idempotency key), step 4 is a no-op.

[VERIFY-NN] legal-review gate

This gate must pass before auto-post can go live in production. Vlado's domain contract contains 10 [VERIFY-NN] annotations referencing Croatian tax law articles (ZoPDV, ZoR). The exact Narodne Novine references must be verified against porezna-uprava.gov.hr / narodne-novine.nn.hr before any POSTED auto-entries are generated for real clients. This is a platform-admin review gate — do not skip.

Validation Evidence

Proveo verdict: PASS — Angie Jones, 2026-06-13. Mesh thread: mesh-thr-proveo-103535-20260613T044650Z. Validation report: /tmp/evidence-103535/VALIDATION-REPORT-v2.md.

Two validation rounds were required:

• v1 (PARTIAL) — Commit 464c3d14: V84 migration blocked with SQLState 42601. Postgres 16 does not allow COALESCE expressions inside inline PRIMARY KEY / UNIQUE table constraint syntax. Affected 4 locations across bilko_flags and account_mapping.
• v2 (PASS) — Commit 687f1d0b (fix): Replaced inline COALESCE constraints with surrogate UUID PKs + separate expression unique indexes. All 4 locations corrected.

DB-invariant proofs (12 sub-tests on live Postgres 16)

Test counts

• 16 unit tests: PostingRuleEngineTest (10/10) + GlBridgeTest (6/6) — MockK, no DB.
• 12 DB-invariant tests: GlInvariantDbTest — full Flyway V1-V84 on postgres:16-alpine Testcontainer.
• SelfPostingConstraintTest (2/2) — migration regression guard.
• Pre-existing 4 failures in CountryPlugin XML tests — same on main, unrelated to B-1.

Flag safety (GlBridgeTest 6/6)

• BILKO_ACCOUNTING_GL=false: engine never called (MockK verify exactly=0).
• GL_AUTO_POST=false: engine never called.
• Both ON + DRAFT: engine called x1, persistDraft called x1.
• Both ON + ZA_KONTIRANJE result: no persist, no crash.
• Engine exception: swallowed, Module A unaffected.

What Is NOT Done Yet (Deferred to next B-1 slice)

• Frontend kontni-plan UI — accountant-facing account plan management screen.
• Glavna knjiga / bruto bilanca API endpoints — general ledger summary and trial balance REST endpoints.
• Accountant DRAFT → POSTED screen — UI for accountant to review and confirm draft journal entries.
• Remaining posting rule seeds — Events 3b (EXPORT_45), 3c (EXEMPT_39/40), 4 (PAYMENT_RECEIVED), 5 (CREDIT_NOTE), 6a/6b/6c (advance/advance-settlement) are domain-specified but not yet seeded as active rules in posting_rules table.
• Live end-to-end test — full invoice send with both flags ON, confirming a real DRAFT entry lands in the DB. Recommended for B-2 gate (Proveo open item).
• [VERIFY-NN] legal review — porezna-uprava.gov.hr article verification gate before production auto-posting is enabled.

Cross-links

• Spec and board decision: BookStack page 3115 — Bilko Modul B (Knjigovodstvo) — Spec + Board presuda
• PR #369: feature/b1-gl-foundation (not yet merged)
• MC #103531 (parent build task)
• MC #103535 (Proveo validation task)
• Domain contract: /tmp/evidence-knjigovodstvo/vlado-posting-rule-templates-B1.md
• Validation report v2: /tmp/evidence-103535/VALIDATION-REPORT-v2.md