kvk-connect 0.1.6__py3-none-any.whl

kvk_connect/models/api/mutatiesignalen_api.py

@@ -0,0 +1,44 @@
+# ruff: noqa: D102
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class MutatieSignaal:
+    id: str
+    kvknummer: str
+    signaal_type: str
+    timestamp: datetime | None = None
+    vestigingsnummer: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MutatieSignaal":  # noqa: D102
+        ts = data.get("timestamp", "")
+        dt = datetime.fromisoformat(ts.replace("Z", "+00:00")) if ts else None
+        return cls(
+            id=data.get("id", ""),
+            timestamp=dt,
+            kvknummer=data.get("kvknummer", ""),
+            signaal_type=data.get("signaalType", ""),
+            vestigingsnummer=data.get("vestigingsnummer"),
+        )
+
+
+@dataclass
+class MutatiesAPI:
+    pagina: int
+    aantal: int
+    totaal: int
+    totaal_paginas: int
+    signalen: list[MutatieSignaal] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MutatiesAPI":  # noqa: D102
+        return cls(
+            pagina=data.get("pagina", 0),
+            aantal=data.get("aantal", 0),
+            totaal=data.get("totaal", 0),
+            totaal_paginas=data.get("totaalPaginas", 0),
+            signalen=[MutatieSignaal.from_dict(s) for s in data.get("signalen", [])],
+        )

kvk_connect/models/api/vestigingen_api.py

@@ -0,0 +1,73 @@
+# ruff: noqa: D102
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+# Reuse Link from basisprofiel models
+from .basisprofiel_api import Link
+
+
+@dataclass
+class Vestiging:
+    vestigingsnummer: str = ""
+    eerste_handelsnaam: str = ""
+    ind_hoofdvestiging: str = ""
+    ind_adres_afgeschermd: str = ""
+    ind_commerciele_vestiging: str = ""
+    volledig_adres: str = ""
+    links: list[Link] = field(default_factory=list)
+
+    @staticmethod
+    def from_dict(d: dict[str, Any] | None) -> Vestiging | None:  # noqa: D102
+        if not d:
+            return None
+        return Vestiging(
+            vestigingsnummer=d.get("vestigingsnummer", "") or "",
+            eerste_handelsnaam=d.get("eersteHandelsnaam", "") or "",
+            ind_hoofdvestiging=d.get("indHoofdvestiging", "") or "",
+            ind_adres_afgeschermd=d.get("indAdresAfgeschermd", "") or "",
+            ind_commerciele_vestiging=d.get("indCommercieleVestiging", "") or "",
+            volledig_adres=d.get("volledigAdres", "") or "",
+            links=[link for link in (Link.from_dict(x) for x in d.get("links", [])) if link],
+        )
+
+
+@dataclass
+class VestigingenAPI:
+    kvk_nummer: str = ""
+    aantal_commerciele_vestigingen: int | None = None
+    aantal_niet_commerciele_vestigingen: int | None = None
+    totaal_aantal_vestigingen: int | None = None
+    vestigingen: list[Vestiging] = field(default_factory=list)
+    links: list[Link] = field(default_factory=list)
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> VestigingenAPI:  # noqa: D102
+        return VestigingenAPI(
+            kvk_nummer=d.get("kvkNummer", "") or "",
+            aantal_commerciele_vestigingen=d.get("aantalCommercieleVestigingen"),
+            aantal_niet_commerciele_vestigingen=d.get("aantalNietCommercieleVestigingen"),
+            totaal_aantal_vestigingen=d.get("totaalAantalVestigingen"),
+            vestigingen=[v for v in (Vestiging.from_dict(x) for x in d.get("vestigingen", [])) if v],
+            links=[link for link in (Link.from_dict(x) for x in d.get("links", [])) if link],
+        )
+
+    @staticmethod
+    def load_from_file(path: str, encoding: str = "utf-8") -> VestigingenAPI:  # noqa: D102
+        with open(path, encoding=encoding) as f:
+            data = json.load(f)
+        return VestigingenAPI.from_dict(data)
+
+    @staticmethod
+    def load_from_json(json_str: str) -> VestigingenAPI:  # noqa: D102
+        data = json.loads(json_str)
+        return VestigingenAPI.from_dict(data)
+
+    @staticmethod
+    def load_from_dict(data: dict[str, Any]) -> VestigingenAPI:  # noqa: D102
+        return VestigingenAPI.from_dict(data)
+
+    def to_dict(self) -> dict[str, Any]:  # noqa: D102
+        return asdict(self)

kvk_connect/models/api/vestigingsprofiel_api.py

@@ -0,0 +1,71 @@
+# ruff: noqa: D102
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from .basisprofiel_api import Adres, HandelNaam, Link, MaterieleRegistratie, SBIActiviteit
+
+
+@dataclass
+class VestigingsProfielAPI:
+    vestigingsnummer: str = ""
+    kvk_nummer: str = ""
+    rsin: str = ""
+    ind_non_mailing: str = ""
+    formele_registratiedatum: str = ""
+    materiele_registratie: MaterieleRegistratie | None = None
+    statutaire_naam: str = ""
+    eerste_handelsnaam: str = ""
+    ind_hoofdvestiging: str = ""
+    ind_commerciele_vestiging: str = ""
+    voltijd_werkzame_personen: int | None = None
+    totaal_werkzame_personen: int | None = None
+    deeltijd_werkzame_personen: int | None = None
+    handelsnamen: list[HandelNaam] = field(default_factory=list)
+    adressen: list[Adres] = field(default_factory=list)
+    websites: list[str] = field(default_factory=list)
+    sbi_activiteiten: list[SBIActiviteit] = field(default_factory=list)
+    links: list[Link] = field(default_factory=list)
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> VestigingsProfielAPI:  # noqa: D102
+        return VestigingsProfielAPI(
+            vestigingsnummer=d.get("vestigingsnummer", "") or "",
+            kvk_nummer=d.get("kvkNummer", "") or "",
+            rsin=d.get("rsin", "") or "",
+            ind_non_mailing=d.get("indNonMailing", "") or "",
+            formele_registratiedatum=d.get("formeleRegistratiedatum", "") or "",
+            materiele_registratie=MaterieleRegistratie.from_dict(d.get("materieleRegistratie")),
+            statutaire_naam=d.get("statutaireNaam", "") or "",
+            eerste_handelsnaam=d.get("eersteHandelsnaam", "") or "",
+            ind_hoofdvestiging=d.get("indHoofdvestiging", "") or "",
+            ind_commerciele_vestiging=d.get("indCommercieleVestiging", "") or "",
+            voltijd_werkzame_personen=d.get("voltijdWerkzamePersonen"),
+            totaal_werkzame_personen=d.get("totaalWerkzamePersonen"),
+            deeltijd_werkzame_personen=d.get("deeltijdWerkzamePersonen"),
+            handelsnamen=[h for h in (HandelNaam.from_dict(x) for x in d.get("handelsnamen", [])) if h],
+            adressen=[a for a in (Adres.from_dict(x) for x in d.get("adressen", [])) if a],
+            websites=list(d.get("websites", []) or []),
+            sbi_activiteiten=[s for s in (SBIActiviteit.from_dict(x) for x in d.get("sbiActiviteiten", [])) if s],
+            links=[link for link in (Link.from_dict(x) for x in d.get("links", [])) if link],
+        )
+
+    @staticmethod
+    def load_from_file(path: str, encoding: str = "utf-8") -> VestigingsProfielAPI:  # noqa: D102
+        with open(path, encoding=encoding) as f:
+            data = json.load(f)
+        return VestigingsProfielAPI.from_dict(data)
+
+    @staticmethod
+    def load_from_json(json_str: str) -> VestigingsProfielAPI:  # noqa: D102
+        data = json.loads(json_str)
+        return VestigingsProfielAPI.from_dict(data)
+
+    @staticmethod
+    def load_from_dict(data: dict[str, Any]) -> VestigingsProfielAPI:  # noqa: D102
+        return VestigingsProfielAPI.from_dict(data)
+
+    def to_dict(self) -> dict[str, Any]:  # noqa: D102
+        return asdict(self)

kvk_connect/models/domain/__init__.py

@@ -0,0 +1,6 @@
+from .basisprofiel import BasisProfielDomain
+from .kvkvestigingsnummersdomain import KvKVestigingsNummersDomain
+from .vestigingsadresdomain import VestigingsAdresDomain
+from .vestigingsadressendomain import VestigingsAdressenDomain
+
+__all__ = ["BasisProfielDomain", "KvKVestigingsNummersDomain", "VestigingsAdressenDomain", "VestigingsAdresDomain"]

kvk_connect/models/domain/basisprofiel.py

@@ -0,0 +1,65 @@
+# ruff: noqa: D102
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass
+class BasisProfielDomain:
+    """Dit is ons domeinmodel van een KVK record.
+
+    Alleen de velden die hier staan schrijven we weg naar CSV/SQL
+    """
+
+    kvk_nummer: str | None = None
+    naam: str | None = None
+    hoofdactiviteit: str | None = None
+    hoofdactiviteit_omschrijving: str | None = None
+    activiteit_overig: str | None = None
+    rechtsvorm: str | None = None
+    rechtsvorm_uitgebreid: str | None = None
+    eerste_handelsnaam: str | None = None
+    vestigingsnummer: str | None = None
+    totaal_werkzame_personen: int | None = None
+    websites: str | None = None
+    registratie_datum_aanvang: str | None = None
+    registratie_datum_einde: str | None = None
+    adres_type: str | None = None
+    postbusnummer: str | None = None
+    adres_straatnaam: str | None = None
+    adres_toevoeging: str | None = None
+    adres_postcode: str | None = None
+    adres_plaats: str | None = None
+    gps_latitude: str | None = None
+    gps_longitude: str | None = None
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> BasisProfielDomain:  # noqa: D102
+        return BasisProfielDomain(
+            kvk_nummer=d.get("kvkNummer"),
+            naam=d.get("naam"),
+            hoofdactiviteit=d.get("hoofdactiviteit"),
+            hoofdactiviteit_omschrijving=d.get("hoofdactiviteitOmschrijving"),
+            activiteit_overig=d.get("activiteitOverig"),
+            rechtsvorm=d.get("rechtsvorm"),
+            rechtsvorm_uitgebreid=d.get("rechtsvormUitgebreid"),
+            eerste_handelsnaam=d.get("eersteHandelsnaam"),
+            vestigingsnummer=d.get("vestigingsnummer"),
+            totaal_werkzame_personen=d.get("totaalWerkzamePersonen"),
+            websites=d.get("websites"),
+            registratie_datum_aanvang=d.get("RegistratieDatumAanvang"),
+            registratie_datum_einde=d.get("RegistratieDatumEinde"),
+            adres_type=d.get("AdresType"),
+            postbusnummer=d.get("Postbusnummer"),
+            adres_straatnaam=d.get("AdresStraatnaam"),
+            adres_toevoeging=d.get("AdresToevoeging"),
+            adres_postcode=d.get("AdresPostcode"),
+            adres_plaats=d.get("AdresPlaats"),
+            gps_latitude=d.get("gpsLatitude"),
+            gps_longitude=d.get("gpsLongitude"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Converteer domeinmodel naar dictionary."""
+        return asdict(self)

kvk_connect/models/domain/kvkvestigingsnummersdomain.py

@@ -0,0 +1,28 @@
+# ruff: noqa: D102
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class KvKVestigingsNummersDomain:
+    """Domein model voor een lijst van alle vestigingsnummers (strings)."""
+
+    kvk_nummer: str = ""
+    vestigingsnummers: list[str] = field(default_factory=list)
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> KvKVestigingsNummersDomain:  # noqa: D102
+        return KvKVestigingsNummersDomain(
+            kvk_nummer=d.get("kvkNummer", "") or "", vestigingsnummers=d.get("vestigingen") or []
+        )
+
+    @staticmethod
+    def load_from_json(json_str: str) -> KvKVestigingsNummersDomain:  # noqa: D102
+        data = json.loads(json_str)
+        return KvKVestigingsNummersDomain.from_dict(data)
+
+    def to_dict(self) -> dict:  # noqa: D102
+        return {"kvkNummer": self.kvk_nummer, "vestigingen": list(self.vestigingsnummers)}

kvk_connect/models/domain/mutatie_abonnement.py

@@ -0,0 +1,20 @@
+# ruff: noqa: D102
+import json
+from dataclasses import dataclass
+
+
+@dataclass
+class MutatieAbonnementDomain:
+    abonnement_ids: list[str]
+
+    @staticmethod
+    def from_dict(data: list[str]) -> "MutatieAbonnementDomain":  # noqa: D102
+        return MutatieAbonnementDomain(abonnement_ids=data)
+
+    @staticmethod
+    def from_json(json_str: str) -> "MutatieAbonnementDomain":  # noqa: D102
+        data = json.loads(json_str)
+        return MutatieAbonnementDomain.from_dict(data)
+
+    def to_list(self) -> list[str]:  # noqa: D102
+        return self.abonnement_ids

kvk_connect/models/domain/vestigingsadresdomain.py

@@ -0,0 +1,62 @@
+# ruff: noqa: D102
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass
+class VestigingsAdresDomain:
+    """Domein model voor een vestigingsadres van een KVK vestiging, behorende bij een KVK record."""
+
+    kvk_nummer: str | None = None
+    vestigingsnummer: str | None = None
+    adres_type: str | None = None
+    postbusnummer: str | None = None
+    adres_straatnaam: str | None = None
+    adres_toevoeging: str | None = None
+    adres_postcode: str | None = None
+    adres_plaats: str | None = None
+    gps_latitude: str | None = None
+    gps_longitude: str | None = None
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> VestigingsAdresDomain:  # noqa: D102
+        def clean(val):
+            return val  # if val not in ("", None) else None
+
+        return VestigingsAdresDomain(
+            kvk_nummer=clean(d.get("kvkNummer")),
+            vestigingsnummer=clean(d.get("vestigingsnummer")),
+            adres_type=clean(d.get("AdresType")),
+            postbusnummer=clean(d.get("Postbusnummer")),
+            adres_straatnaam=clean(d.get("AdresStraatnaam")),
+            adres_toevoeging=clean(d.get("AdresToevoeging")),
+            adres_postcode=clean(d.get("AdresPostcode")),
+            adres_plaats=clean(d.get("AdresPlaats")),
+            gps_latitude=clean(d.get("gpsLatitude")),
+            gps_longitude=clean(d.get("gpsLongitude")),
+        )
+
+    @staticmethod
+    def from_list(data: list[dict[str, Any]]) -> list[VestigingsAdresDomain]:  # noqa: D102
+        return [VestigingsAdresDomain.from_dict(item) for item in data or []]
+
+    @staticmethod
+    def load_from_file(path: str, encoding: str = "utf-8") -> list[VestigingsAdresDomain]:  # noqa: D102
+        with open(path, encoding=encoding) as f:
+            data = json.load(f)
+        if not isinstance(data, list):
+            raise ValueError("JSON must be a list of vestigingsprofielen.")
+        return VestigingsAdresDomain.from_list(data)
+
+    @staticmethod
+    def load_from_json(json_str: str) -> list[VestigingsAdresDomain]:  # noqa: D102
+        data = json.loads(json_str)
+        if not isinstance(data, list):
+            raise ValueError("JSON must be a list of vestigingsprofielen.")
+        return VestigingsAdresDomain.from_list(data)
+
+    def to_dict(self) -> dict[str, Any]:  # noqa: D102
+        return asdict(self)

kvk_connect/models/domain/vestigingsadressendomain.py

@@ -0,0 +1,48 @@
+# ruff: noqa: D102
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from kvk_connect.models.domain.vestigingsadresdomain import VestigingsAdresDomain
+
+
+@dataclass
+class VestigingsAdressenDomain:
+    """Domein model voor alle adressen behorende bij een KVVKRecord."""
+
+    adressen: list[VestigingsAdresDomain] = field(default_factory=list)
+
+    @staticmethod
+    def from_list(data: list[Any]) -> VestigingsAdressenDomain:
+        """Maak een VestigingsAdressen object van een lijst dicts of Vestigingsprofiel instanties."""
+        profielen = [
+            VestigingsAdresDomain.from_dict(item) if not isinstance(item, VestigingsAdresDomain) else item
+            for item in (data or [])
+        ]
+        return VestigingsAdressenDomain(adressen=profielen)
+
+    @staticmethod
+    def load_from_file(path: str, encoding: str = "utf-8") -> VestigingsAdressenDomain:  # noqa: D102
+        with open(path, encoding=encoding) as f:
+            data = json.load(f)
+        if not isinstance(data, list):
+            raise ValueError("JSON must be a list of vestigingsprofielen.")
+        return VestigingsAdressenDomain.from_list(data)
+
+    @staticmethod
+    def load_from_json(json_str: str) -> VestigingsAdressenDomain:  # noqa: D102
+        data = json.loads(json_str)
+        if not isinstance(data, list):
+            raise ValueError("JSON must be a list of vestigingsprofielen.")
+        return VestigingsAdressenDomain.from_list(data)
+
+    def add_adres(self, adres: VestigingsAdresDomain) -> None:  # noqa: D102
+        self.adressen.append(adres)
+
+    def add_adressen(self, adres: VestigingsAdressenDomain) -> None:  # noqa: D102
+        self.adressen.extend(adres.adressen)
+
+    def to_dict(self) -> dict:  # noqa: D102
+        return asdict(self)

kvk_connect/models/domain/vestigingsprofiel_domain.py

@@ -0,0 +1,58 @@
+# ruff: noqa: D102
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass
+class VestigingsProfielDomain:
+    """Dataclass voor vestigingsprofiel domeinmodel (gefilterde velden)."""
+
+    vestigingsnummer: str | None = None
+
+    cor_adres_volledig: str | None = None
+    cor_adres_postcode: str | None = None
+    cor_adres_postbusnummer: int | None = None
+    cor_adres_plaats: str | None = None
+    cor_adres_land: str | None = None
+
+    bzk_adres_volledig: str | None = None
+    bzk_adres_straatnaam: str | None = None
+    bzk_adres_huisnummer: int | None = None
+    bzk_adres_postcode: str | None = None
+    bzk_adres_plaats: str | None = None
+    bzk_adres_land: str | None = None
+    bzk_adres_gps_latitude: str | None = None
+    bzk_adres_gps_longitude: str | None = None
+
+    registratie_datum_aanvang_vestiging: str | None = None
+    registratie_datum_einde_vestiging: str | None = None
+
+    @staticmethod
+    def from_dict(d: dict[str, Any]) -> VestigingsProfielDomain:
+        """Maak een VestigingsProfielDomain uit een dictionary."""
+        if not d:
+            return VestigingsProfielDomain()
+        return VestigingsProfielDomain(
+            vestigingsnummer=d.get("vestigingsnummer"),
+            cor_adres_volledig=d.get("corAdresVolledig"),
+            cor_adres_postcode=d.get("corAdresPostcode"),
+            cor_adres_postbusnummer=d.get("corAdresPostbusnummer"),
+            cor_adres_plaats=d.get("corAdresPlaats"),
+            cor_adres_land=d.get("corAdresLand"),
+            bzk_adres_volledig=d.get("bzkAdresVolledig"),
+            bzk_adres_straatnaam=d.get("bzkAdresStraatnaam"),
+            bzk_adres_huisnummer=d.get("bzkAdresHuisnummer"),
+            bzk_adres_postcode=d.get("bzkAdresPostcode"),
+            bzk_adres_plaats=d.get("bzkAdresPlaats"),
+            bzk_adres_land=d.get("bzkAdresLand"),
+            bzk_adres_gps_latitude=d.get("bzkAdresGpsLatitude"),
+            bzk_adres_gps_longitude=d.get("bzkAdresGpsLongitude"),
+            registratie_datum_aanvang_vestiging=d.get("RegistratieDatumAanvangVestiging"),
+            registratie_datum_einde_vestiging=d.get("RegistratieDatumEindeVestiging"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Converteer domeinmodel naar dictionary."""
+        return asdict(self)

kvk_connect/models/orm/base.py

@@ -0,0 +1,5 @@
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    pass

kvk_connect/models/orm/basisprofiel_orm.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy import Date, DateTime, Index, Integer, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from kvk_connect.models.orm.base import Base
+
+
+class BasisProfielORM(Base):
+    __tablename__ = "basisprofielen"
+
+    # Primary key
+    kvk_nummer: Mapped[str] = mapped_column("kvkNummer", String(8), primary_key=True)
+
+    # Text fields
+    naam: Mapped[str | None] = mapped_column("naam", Text)
+    eerste_handelsnaam: Mapped[str | None] = mapped_column("eersteHandelsnaam", Text)
+    websites: Mapped[str | None] = mapped_column("websites", Text)
+
+    # String fields
+    hoofdactiviteit: Mapped[str | None] = mapped_column("hoofdactiviteit", String(255))
+    hoofdactiviteit_omschrijving: Mapped[str | None] = mapped_column("hoofdactiviteitOmschrijving", String(255))
+    activiteit_overig: Mapped[str | None] = mapped_column("activiteitOverig", String(255))
+    rechtsvorm: Mapped[str | None] = mapped_column("rechtsvorm", String(128))
+    rechtsvorm_uitgebreid: Mapped[str | None] = mapped_column("rechtsvormUitgebreid", String(255))
+
+    # Integer field
+    totaal_werkzame_personen: Mapped[int | None] = mapped_column("totaalWerkzamePersonen", Integer)
+
+    # Date fields
+    registratie_datum_aanvang: Mapped[datetime | None] = mapped_column("RegistratieDatumAanvang", Date)
+    registratie_datum_einde: Mapped[datetime | None] = mapped_column("RegistratieDatumEinde", Date)
+
+    # Timestamp fields with defaults
+    created_at: Mapped[datetime] = mapped_column(
+        "created_at", DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
+
+    last_updated: Mapped[datetime] = mapped_column(
+        "last_updated",
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
+        index=True,  # Index voor last_updated filtering
+    )
+
+    __table_args__ = (
+        # Composite index voor outdated checks
+        Index("ix_basisprofiel_kvk_updated", kvk_nummer, last_updated),
+    )

kvk_connect/models/orm/kvkvestigingen_orm.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy import DateTime, Index, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from kvk_connect.models.orm.base import Base
+
+
+class VestigingenORM(Base):
+    """Relatie tussen KvK-nummers en hun vestigingen.
+
+    Relatie:
+    - 1 record met vestigingsnummer='000000000000' = KvK zonder vestigingen (1:0)
+    - N records met vestigingsnummer ingevuld = KvK met vestigingen (1:N)
+
+    Gebruikt een sentinel waarde ('000000000000') i.p.v. NULL voor betere
+    upsert performance met merge().
+    """
+
+    __tablename__ = "vestigingen"
+
+    # Sentinel waarde voor ontbrekende vestigingsnummers
+    SENTINEL_VESTIGINGSNUMMER = "000000000000"
+
+    # Composite primary key
+    kvk_nummer: Mapped[str] = mapped_column("kvkNummer", String(8), primary_key=True)
+    vestigingsnummer: Mapped[str] = mapped_column("vestigingsnummer", String(12), primary_key=True)
+
+    # Timestamp fields with defaults
+    created_at: Mapped[datetime] = mapped_column(
+        "created_at", DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
+
+    last_updated: Mapped[datetime] = mapped_column(
+        "last_updated",
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
+        index=True,
+    )
+
+    __table_args__ = (
+        # Index voor filteren op sentinel waarden
+        Index(
+            "ix_kvkvestigingen_vestigingsnummer_filtered",
+            vestigingsnummer,
+            postgresql_where=vestigingsnummer != SENTINEL_VESTIGINGSNUMMER,
+        ),
+        # Composite index voor joins met vestigingsprofiel
+        Index("ix_kvkvestigingen_vest_updated", vestigingsnummer, last_updated),
+    )

kvk_connect/models/orm/signaal_orm.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Index, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from kvk_connect.models.orm.base import Base
+
+"""
+ORM model for the 'signalen' table.
+"""
+
+
+class SignaalORM(Base):
+    __tablename__ = "signalen"
+
+    # Primary key (UUID)
+    id: Mapped[str] = mapped_column("id", String(36), primary_key=True)
+
+    # Required fields with indexes
+    timestamp: Mapped[datetime] = mapped_column(
+        "timestamp",
+        DateTime,
+        index=True,  # Index voor timestamp filtering
+    )
+    kvknummer: Mapped[str] = mapped_column(
+        "kvknummer",
+        String(8),
+        index=True,  # Index voor joins met basisprofiel
+    )
+    signaal_type: Mapped[str] = mapped_column("signaalType", String(100))
+
+    # Optional field
+    vestigingsnummer: Mapped[str | None] = mapped_column("vestigingsnummer", String(12))
+
+    __table_args__ = (
+        # Composite index voor outdated checks
+        Index("ix_signaal_kvk_timestamp", kvknummer, timestamp),
+    )