// ── Module "Conventie-nazicht" — types van de kennisbank ────────────────────
// Een ontwerp van conventie (compromis, volmacht, bankgift-bevestiging, …)
// dat het kantoor van een derde ontvangt (confrater, makelaar, partij) volgt
// een ONBEKEND model. Het kantoor kan het dus niet tegen één eigen sjabloon
// leggen; het toetst de tekst aan een kennisbank van controlepunten per
// rechtshandeling. Elke afwijking wordt een voorstel van aanpassing dat als
// echte Word-revisie (track changes) in het document terechtkomt, zodat de
// notaris elk punt afzonderlijk kan aanvaarden of verwerpen.
//
// De kennisbank zelf is domeindata (deze map, pure constanten); de analyse en
// de Word-render leven in lib/conventie-nazicht en lib/word.

import type { AkteTypeNaam } from "@/data/modeldocumenten/akte-types";

/**
 * Gewicht van een controlepunt:
 * - "essentieel": zonder dit punt is de conventie juridisch gebrekkig of
 *   nietig — moet er altijd in;
 * - "belangrijk": hoort er in de regel in; ontbreken vraagt een bewuste,
 *   gemotiveerde keuze van de notaris;
 * - "beter": de kantoorpraktijk kent een sterkere formulering of aanpak;
 * - "te-vermijden": formulering of mechanisme dat het kantoor weert
 *   (nietigheidsrisico, onevenwicht, gekende valkuil).
 */
export type NazichtCategorie = "essentieel" | "belangrijk" | "beter" | "te-vermijden";

export const nazichtCategorieLabels: Record<NazichtCategorie, string> = {
  essentieel: "Essentieel",
  belangrijk: "Belangrijk",
  beter: "Kan beter",
  "te-vermijden": "Te vermijden",
};

/** Vaste weergavevolgorde: zwaarste categorie eerst. */
export const NAZICHT_CATEGORIE_VOLGORDE: readonly NazichtCategorie[] = [
  "te-vermijden",
  "essentieel",
  "belangrijk",
  "beter",
];

/**
 * Richting van de toets:
 * - "vereist": het punt hoort AANWEZIG te zijn — geen signaal gevonden →
 *   bevinding "ontbreekt" en de `voorstel`-clausule wordt als invoeging
 *   voorgesteld;
 * - "verdacht": het punt hoort AFWEZIG te zijn — signaal gevonden → de
 *   getroffen passage wordt als schrapping (met eventuele `vervanging`)
 *   voorgesteld.
 */
export type NazichtDoel = "vereist" | "verdacht";

/**
 * Validatiestand van een controlepunt. Seed-punten zijn door de AI opgesteld
 * en dragen géén validatie ("te-valideren"); zodra de notaris een punt in de
 * UI valideert of bewerkt, wordt de stand als kantooraanpassing bewaard.
 */
export interface ControlepuntValidatie {
  status: "te-valideren" | "gevalideerd";
  /** ISO-datum (jjjj-mm-dd) van de laatste validatie of bewerking. */
  datum?: string;
}

/**
 * Eén controlepunt uit de kennisbank.
 *
 * Detectie werkt met signaalgroepen (`signalen`): het punt geldt als
 * "aangetroffen" zodra voor MINSTENS ÉÉN groep AL haar trefwoorden in de
 * tekst voorkomen (hoofdletter- en accentongevoelig). Bij `doel: "verdacht"`
 * moeten de trefwoorden van een groep in DEZELFDE alinea staan, zodat de
 * schrapping een concrete alinea kan aanwijzen.
 */
export interface Controlepunt {
  id: string;
  categorie: NazichtCategorie;
  doel: NazichtDoel;
  /** Rechtshandelingen waarop dit punt slaat; "alle" = elk document. */
  akteTypes: readonly AkteTypeNaam[] | "alle";
  titel: string;
  /** Waarom dit punt telt — de motivering die de notaris (en de wederpartij) leest. */
  uitleg: string;
  /** Signaalgroepen: buitenste niveau = OF, binnenste niveau = EN. Genormaliseerd gezocht. */
  signalen: readonly (readonly string[])[];
  /**
   * Bij `doel: "vereist"`: de clausuletekst die als track-changes-invoeging
   * wordt voorgesteld wanneer het punt ontbreekt. Open plekken als
   * `[AAN TE VULLEN: …]`, conform de huisstijl van de modeldocumenten.
   */
  voorstel?: string;
  /**
   * Bij `doel: "verdacht"`: vervangtekst voor de geschrapte passage.
   * Weggelaten = zuivere schrapping.
   */
  vervanging?: string;
  wetsbasis?: readonly string[];
  /** Wenk voor de (AI-)agent: wanneer is dit punt wél/niet van toepassing, gekende valkuilen. */
  agentwenken?: string;
  /** Validatiestand; ontbreekt = "te-valideren" (AI-opgesteld, nog niet nagekeken). */
  validatie?: ControlepuntValidatie;
}