# Modeldocumenten — structuur & integratie-workflow

Evolutieve bibliotheek van kantoormodellen, ontworpen om **500+ modellen** te
integreren. De structuur spiegelt de mappen van "Modellen CD" op de
kantoorserver en de naamconventies uit `INSTRUCTIES_MODELLEN_CD`.

## Bestandsstructuur

```
data/modeldocumenten/
├── types.ts            # Modelonderdeel, Modeldocument, Hoofdthema, DocumentSoort, Nazicht, …
├── index.ts            # barrel: publieke API van de datalaag (alles via "@/data/modeldocumenten")
├── samenstellen.ts     # pure functies: stelModelSamen, genereerDocument, combineerMetSeed, bumpVersie, …
├── verrijkingsprompt.ts # VERRIJKINGS_PROMPT voor AI-ondersteund verrijken
├── rollen.ts           # rollen-conventie: {{rol_overdrager}}/{{rol_verkrijger}} → rolnamen per akteType
├── onderdelen/         # herbruikbare clausules (bouwblokken), per rubriek
│   ├── index.ts        # aggregator → seedOnderdelen
│   ├── partijen.ts     # identificatie, vertegenwoordiging, instemming partner, …
│   ├── goed.ts         # beschrijving goed, eigendomsoorsprong, hypothecaire toestand, …
│   ├── prijs.ts        # prijs & betaling, antiwitwas, kosten
│   ├── voorwaarden.ts  # eigendomsoverdracht, opschortende voorwaarden, …
│   ├── attesten.ts     # administratieve & veiligheidsattesten
│   ├── bijzonder.ts    # mede-eigendom, fiscaliteit, huwelijksstelsel/CKP
│   ├── vorm.ts         # inleidende bepalingen, slotformules, NABAN/IZIMI
│   ├── lastgeving.ts   # zorgvolmacht-clausules (art. 489 e.v. oud BW)
│   ├── volmacht.ts     # bijzondere volmachten (notarieel & onderhands)
│   ├── heldere-taal.ts + heldere-taal-attesten.ts    # Fednot Model Heldere Taal (NL)
│   ├── heldere-taal-fr.ts + heldere-taal-attesten-fr.ts # Modèle Langage Clair (FR, vertalingVanId → NL)
│   └── frans.ts        # overige Franstalige clausules (taal: "fr")
└── modellen/           # volledige modeldocumenten, één bestand per hoofdthema
    ├── index.ts        # aggregator → seedModellen
    ├── algemeen.ts     # 0. Algemeen   (volmachten, …)
    ├── familie.ts      # 1. Familie    (zorgvolmacht, erfkeuze, …)
    ├── vastgoed.ts     # 2. Vastgoed   (verkoopakte, compromis, frame, …)
    ├── vennootschappen.ts # 3. Vennootschappen
    └── fiscaal.ts      # 4. Fiscaal
```

Groeit een themabestand boven ± 1.000 regels, splits het dan in een submap per
thema (bv. `modellen/familie/zorgvolmacht.ts` + `modellen/familie/index.ts`),
naar analogie met `onderdelen/`. De aggregators blijven het enige koppelpunt;
de UI importeert uitsluitend `seedOnderdelen`/`seedModellen` via de barrel.

## Workflow: een aangeleverd kantoormodel integreren

1. **Identificeer het document via de bestandsnaam** (prefix bepaalt `soort`):
   `MOD` = volwaardig model (hypotheses + reminders aanwezig) · `VB` =
   voorbeeld, mogelijk onvolledig — kritisch bekijken, `nazicht` minstens
   `na_te_kijken` · `MODCL`/`VBCL` = losse clausule(s) → enkel
   `Modelonderdeel`(en), geen `Modeldocument` · `FORM`/`CHECKLIST`/`INFO`/
   `MODBRIEF`/`VBBRIEF` = ondersteunend document. Suffix `-NL/FR/2T/EN/DU`
   bepaalt `taal` (geen suffix = Nederlands).
2. **Vertaal de kleur-/`**`-conventies** van het Word-model:
   - `** ofwel …` (verplichte keuze) → `varianten` (één variant per hypothese);
   - `** indien …` / `** (eventueel)` → `[NAKIJKEN OF SCHRAPPEN — …]`;
   - `**`-invulvelden → `{{parameter}}` + entry in `parameters`;
   - geel gemarkeerd (nog niet nagekeken) → `nazicht.status: "na_te_kijken"`
     met de reden in `aandachtspunten`;
   - grijs (voorbeeldclausule ter inspiratie) → variant met
     `[TE VERIFIËREN]`-markering of apart onderdeel met `soort: "VBCL"`;
   - eigen aanvullingen die niet letterlijk uit het model komen →
     `[NIEUW — TE VALIDEREN DOOR DE NOTARIS]`.
3. **Hergebruik bestaande onderdelen** (identificatie, slotformules,
   NABAN/IZIMI, recht op geschriften, …) in plaats van ze te dupliceren;
   nieuwe herbruikbare clausules komen in het passende `onderdelen/`-bestand,
   model-specifieke clausules krijgen een id met het model als prefix
   (bv. `zorgvolmacht-…`).
4. **Registreer** het model in `modellen/<thema>.ts` met `thema`, `soort`,
   `bron` (oorspronkelijke bestandsnaam) en `versie`/`datum`; nieuwe
   onderdelen-bestanden ook in `onderdelen/index.ts`.
5. **Valideer**: `npx tsc --noEmit -p .` en `npx next build`; controleer in de
   UI dat geen structuur-item naar een ontbrekend onderdeel verwijst (rood
   gemarkeerd in de modelkaart).

## Rollen-conventie voor herbruikbare ("administratieve") clausules

Sommige clausules zijn inhoudelijk identiek over meerdere aktetypes heen
(instemming partner gezinswoning, identificatie, vertegenwoordiging,
slotbepalingen, …) maar noemen de partijen bij hun rol in de transactie
("verkoper", "koper"). Dat maakt ze onbruikbaar in `toepasbaarOp`-types waar
die rolnamen niet kloppen (bv. een schenkingsakte heeft een "schenker" en
"begiftigde", geen "verkoper" en "koper").

Gebruik daarom in plaats van de letterlijke rolnaam de generieke placeholders
`{{rol_overdrager}}` / `{{rol_verkrijger}}` (en, voor het begin van een zin,
`{{Rol_overdrager}}` / `{{Rol_verkrijger}}` met hoofdletter). Bij het
samenstellen van een model (`stelModelSamen`/`genereerDocument`) worden die
automatisch vervangen door de rolnamen die bij `model.akteType` horen, via
`rollen.ts`:

| akteType | overdrager | verkrijger |
| --- | --- | --- |
| verkoopakte / verkoopovereenkomst (compromis) / algemeen kader (vastgoedakte) | verkoper | koper |
| schenkingsakte | schenker | begiftigde |
| ruilovereenkomst | ruiler | ruiler |
| huurovereenkomst | verhuurder | huurder |
| erfpachtakte | erfpachtgever | erfpachter |
| opstalakte | opstalgever | opstalhouder |
| (overige, incl. kredietakte) | overdrager | verkrijger |

Vuistregel bij het verwerken van een nieuwe of bestaande clausule:
- Gaat de clausule inhoudelijk over **wie het goed/recht overdraagt of
  verkrijgt** (instemming, identificatie, wederbelegging, …) en is ze
  bruikbaar in meerdere aktetypes? → vervang "verkoper"/"koper" (of
  "schenker"/"begiftigde", …) door `{{rol_overdrager}}`/`{{rol_verkrijger}}`
  en breid `toepasbaarOp` uit.
- Is de clausule inherent gebonden aan één type transactie (bv.
  `prijs-en-betaling`, enkel zinvol bij een verkoop)? → laat de letterlijke
  rolnaam staan en beperk `toepasbaarOp` tot de relevante aktetypes.
- Komt een nieuw aktetype voor met een ander rolpaar (bv. een kredietakte
  waar de "hypothekerende partij" centraal staat)? → voeg het toe aan
  `aktetypeRollen` in `rollen.ts`.

## Snel een model of clausule toevoegen/verbeteren via chat

Voor het uitbreiden van de bibliotheek (volledig model of losse clausules)
via deze chat met het Sonnet-taalmodel:

1. **Plak de brontekst** (Word-export, Fednot-model, eigen kantoormodel of
   voorbeeldakte) samen met een korte instructie: nieuw model, nieuwe
   clausule(s), of een bestaand model/onderdeel verbeteren/aanvullen.
2. Verwerking gebeurt volgens `VERRIJKINGS_PROMPT`
   (`data/modeldocumenten/verrijkingsprompt.ts`, ook beschikbaar via de module
   AI-prompts): opsplitsen in herbruikbare `Modelonderdeel`s,
   dossiergegevens → `{{parameter}}`, hypotheses als `varianten`, en —
   nieuw — **rolnamen → `{{rol_overdrager}}`/`{{rol_verkrijger}}`** waar de
   clausule cross-aktetype herbruikbaar is (zie hierboven).
3. Bij verbetering van een **bestaand** onderdeel/model: geef het `id` mee
   zodat gericht het juiste bestand onder `onderdelen/` of `modellen/` wordt
   aangepast (versie ophogen via `bumpVersie`, `nazicht.datum` bijwerken).
4. Na verwerking: registreer nieuwe onderdelen in `onderdelen/index.ts` en
   nieuwe modellen in `modellen/<thema>.ts` + `modellen/index.ts`, en
   valideer (zie stap 5 hieronder).
5. **Bronregister bijhouden**: voeg het verwerkte bronbestand (eigen
   kantoormodel, Fednot-model of voorbeeldakte) systematisch toe aan
   `bronnen.ts` (`seedBronnen`) met bestandsnaam en verwerkingsdatum — zo
   blijft het tabblad "Verwerkte bronnen" een betrouwbaar overzicht van welke
   kantoorbestanden al dan niet reeds verwerkt zijn. (Ad-hoc registraties kan
   de notaris ook rechtstreeks via dat tabblad toevoegen.)
6. **Neveneffecten op andere bestaande onderdelen**: leidt het toevoegen van
   een model of het verwerken van een voorbeeld er ook toe dat een ander,
   reeds bestaand modelonderdeel zou moeten worden aangepast (bv. een
   ontbrekende hypothese, een verouderde formulering, een parameter die ook
   elders nodig is)? Wijzig dat onderdeel dan niet "en passant" mee in
   dezelfde verwerking, maar dien dat systematisch in als afzonderlijk
   `Wijzigingsvoorstel` (zie hieronder), zodat de notaris elke aanpassing aan
   reeds gevalideerde clausules apart kan beoordelen via het tabblad "Te
   valideren".

## Kernregels

- Bedragen, tarieven en drempels nooit hardcoden in pagina's — zie
  `ARCHITECTURE.md` (gelaagdheid `app → components → lib → data`).
- Weinig maar volledige modellen: clausules schrappen is gebruiksvriendelijker
  dan clausules uitvinden. Voorbeelden (`VB…`) zijn inspiratie, geen basis.
- Elk juridisch gevoelig of evoluerend onderdeel krijgt een `nazicht`-blok
  (status + datum + aandachtspunten), zodat de bibliotheek bij wetswijzigingen
  gericht kan worden nagekeken.
- Deze modellen zijn strikt vertrouwelijk (intellectuele rechten, GDPR,
  beroepsgeheim) — niet verspreiden buiten het kantoor.