nexarch/docs/INT-12-PRUEFPROTOKOLL.md

Prüfprotokoll INT-12 — AI-Anbindung: Objekttyp-Registrierung (Kopplung AI GOV-01)

Datum: 2026-10-15 Host: 192.168.1.204 (Wegwerf-Arbeitsverzeichnis) Branch: feature/int-12-ai-anbindung-objekttyp-registrierung-kopplung-ai-gov-01

Ausgangslage

• DOC-01 (dms/internal/upload) liefert Upload/Chunk-Handling, aus dem die KI-relevanten Dokumentfelder stammen (Volltext aus OCR/SRC-05, Kernmetadaten aus MET-02/DOC-01).
• GOV-01 (ai/internal/moduletype) existierte bereits als reines Go-Paket mit Registry.Register, Get, ListByModule gegen die Tabelle module_objecttypes, inkl. Tenant-Verifikation gegen Core TEN-01 (GOV-07, fail-closed) über das TenantVerifier-Interface.
• Es gab keinen HTTP-Endpunkt für diese Registrierung — DMS ist ein physisch getrenntes Go-Modul (gitea.perlbach24.de/scripte/nexarch/dms) und kann ai/internal/moduletype nicht importieren. Diese Lücke musste als Teil von INT-12 geschlossen werden (minimal, im bestehenden Baustil von extractapi/residencyapi).

Umsetzung

AI-Modul (ai/)

• Neu: ai/internal/moduletypeapi — HTTP-Bindung für moduletype.Registry:
  • POST /module-objecttypes (Service-Token-Pflicht über X-Service-Token, fail closed wie extractapi/residencyapi).
  • Antwort 403 bei moduletype.ErrUnknownTenant (GOV-07), 400 bei sonstigen Validierungsfehlern, 200 bei Erfolg.
• ai/cmd/ai-app/main.go: neue Konfiguration NEXARCH_AI_APP_CORE_BASE_URL / NEXARCH_AI_APP_CORE_SERVICE_TOKEN. Der Endpunkt wird nur verdrahtet, wenn eine Core-Basis-URL konfiguriert ist — ohne Tenant-Verifikationsmöglichkeit bleibt die Registrierungsroute unverdrahtet statt eine Registrierung ohne GOV-07-Prüfung zuzulassen (fail-closed-Grundsatz von GOV-01/GOV-07 bleibt gewahrt).

DMS-Modul (dms/)

• Neu: dms/internal/moduletypeclient — schlanker HTTP-Client (Muster wie dms/internal/retentionclient für Archive RET-05/DOC-16):
  • Register(ctx, tenantSlug, objectType, fields) → POST {baseURL}/module-objecttypes mit X-Service-Token.
  • DocumentFields() liefert die KI-relevanten Felder des Objekttyps document: fulltext, title, filename, mime_type, created_at, tags.
• dms/cmd/app/main.go: neue Funktion setupAIObjectTypeRegistration(), aufgerufen beim Start aus main():
  • AK2 (optional/kein Fehler ohne AI-Modul): fehlt NEXARCH_DMS_APP_AI_BASE_URL (stellvertretend für "AI-Modul/Core-LIC-02 nicht aktiviert" — Ops setzt diese URL nur, wenn das AI-Modul lizenziert/aktiv ist, analog zum bestehenden RET-05/DOC-16-Muster in derselben Datei), wird die Registrierung übersprungen, nur eine Logzeile, kein Fehler, kein log.Fatal.
  • AK3 (fail open bei Registrierungsfehlern): jeder Fehler aus Register (Transport, Timeout, Nicht-200) wird nur geloggt (log.Printf), die Funktion kehrt zurück, main() läuft unverändert weiter — kein log.Fatal, kein Blockieren.
  • AK1: bei erfolgreicher Konfiguration wird der Objekttyp document mit den KI-relevanten Feldern automatisch beim Start registriert.

Bewusst nicht umgesetzt (Scope-Entscheidung)

• Keine Deregistrierungs-/Lösch-Schnittstelle: Die Akzeptanzkriterien von INT-12 fordern nur die Registrierung beim Start; der Ticket-Hinweis zu "Löschfehler dürfen anders behandelt werden" beschreibt nur eine Abgrenzung zur Fail-Open-Regel, verlangt aber keine Deregistrierungsfunktion. Um nicht über das Ticket hinaus zu bauen, wurde keine Delete-Route/-Client ergänzt.
• Kein eigener HTTP-Client für Core LIC-02 (Feature-Flag-Abfrage) auf DMS-Seite: Ein solcher modulübergreifender Flag-Abfrage-Client existiert im Code noch nirgends (auch nicht in anderen separaten Go-Modulen wie mail/connect/workflow). Stattdessen wird das etablierte, bereits im Code vorhandene Muster (RET-05/DOC-16 in dms/cmd/app/main.go) übernommen: Aktivierung/Deaktivierung wird über das Vorhandensein der Basis-URL-Umgebungsvariable abgebildet, die Ops nur setzt, wenn das Modul lizenziert ist. Diese Design-Entscheidung ist dokumentiert, falls ein künftiges Ticket einen generischen LIC-02-HTTP-Client für module-übergreifende Flag-Abfragen einführt.

Automatisierte Tests (real ausgeführt)

Testdatenbank (Wegwerf, eigens angelegt, nicht dms_dev/archivdms):

• Rolle/DB int12_ai_test (Postgres 17, lokal auf 204).

AK1 — Registrierung erscheint bei AI

• ai/internal/moduletypeapi/moduletypeapi_test.go::TestHandleRegister_ValidRequest_Registered — POST gegen echten httptest-Server + echte Postgres-DB, Nachweis per Registry.Get.
• dms/internal/moduletypeclient/moduletypeclient_test.go::TestRegister_SendsExpectedPayloadAndAuth — Client sendet korrektes Payload/Token.
• Realer End-to-End-Nachweis (Prüfung 1, siehe unten): echter ai-app-Prozess + echter DMS-Client-Aufruf, Ergebnis per direkter SQL-Abfrage verifiziert.

AK2 — AI-Modul nicht aktiviert → DMS startet unverändert

• dms/cmd/app/aiobjecttype_test.go::TestSetupAIObjectTypeRegistration_NoBaseURL_SkipsWithoutPanic — keine NEXARCH_DMS_APP_AI_BASE_URL, Aufruf kehrt ohne Fehler zurück.
• TestSetupAIObjectTypeRegistration_NoTenantSlug_SkipsWithoutPanic — zusätzliche Absicherung (fehlender Tenant-Kontext).

AK3 — Registrierungsfehler blockieren DMS-Start nie

• dms/cmd/app/aiobjecttype_test.go::TestSetupAIObjectTypeRegistration_UnreachableEndpoint_DoesNotBlock — Basis-URL zeigt auf geschlossenen Port (127.0.0.1:1), Aufruf kehrt kontrolliert mit Logzeile zurück statt zu blockieren/abzustürzen.
• dms/internal/moduletypeclient/moduletypeclient_test.go::TestRegister_UnreachableEndpoint_IsError / TestRegister_NonOKStatus_IsError — Client liefert Fehler statt stillschweigend zu akzeptieren (Aufrufer entscheidet über Fail-Open).
• ai/internal/moduletypeapi/moduletypeapi_test.go::TestHandleRegister_MissingServiceToken_Rejected, TestHandleRegister_UnknownTenant_Rejected — AI-seitiges fail-closed bei Auth/Tenant bleibt erhalten.

Alle genannten Tests real ausgeführt und grün:

ok  ai/internal/moduletypeapi        0.539s   (3 Tests)
ok  ai/internal/moduletype           (unverändert grün)
ok  ai/cmd/ai-app                    (unverändert grün)
ok  dms/internal/moduletypeclient    (3 Tests)
ok  dms/cmd/app                      (alle Tests inkl. 3 neue INT-12-Tests)

Vollständiger go test ./... des ai-Moduls (alle ~50 Pakete) ebenfalls grün mit TEST_TENANT_DSN gegen int12_ai_test.

Prüfungen vor Abnahme (real durchgeführt, nicht nur behauptet)

Prüfung 1 — Registrierung gegen echte, laufende AI-Testinstanz

1. Migrationen auf int12_ai_test angewendet (ai/internal/migrate, 16 Migrationen inkl. module_objecttypes).
2. Core-TEN-01-Stub gestartet (127.0.0.1:19901): GET /tenants/mandant-int12 → 200, alles andere → 404 (einfacher, legitimer Stub für die fremde, bereits eigenständig vertragsgetestete Core-Schnittstelle — kein DB-Mocking).
3. Echter ai-app-Prozess gestartet (go build → Binary, 127.0.0.1:19902), verbunden mit int12_ai_test und dem Core-Stub, NEXARCH_AI_APP_CORE_BASE_URL gesetzt → Route /module-objecttypes ist verdrahtet.
4. Echter DMS-Client (moduletypeclient.Register) rief http://127.0.0.1:19902/module-objecttypes auf → Antwort 200 ok.
5. Direkte SQL-Abfrage gegen int12_ai_test:

   select tenant_slug, module_name, object_type, fields from module_objecttypes where tenant_slug='mandant-int12';
   

   Ergebnis: ein Datensatz dms/document mit allen 6 KI-relevanten Feldern (fulltext, title, filename, mime_type, created_at, tags) — Objekttyp ist nachweislich bei AI registriert.
6. Alle Testprozesse (ai-app, Core-Stub) anschließend beendet (pkill), keine Leichen.

Prüfung 2 — AI-Modul-Flag deaktiviert

• TestSetupAIObjectTypeRegistration_NoBaseURL_SkipsWithoutPanic: NEXARCH_DMS_APP_AI_BASE_URL leer → setupAIObjectTypeRegistration() kehrt sofort zurück, nur eine Logzeile ("deaktiviert"), kein Fehler, kein Prozessabbruch. Entspricht dem Normalbetrieb ohne AI-Modul.

Prüfung 3 — AI-Endpunkt nicht erreichbar bei Registrierung

• TestSetupAIObjectTypeRegistration_UnreachableEndpoint_DoesNotBlock: NEXARCH_DMS_APP_AI_BASE_URL=http://127.0.0.1:1 (verbindungsrefused) → Register liefert Fehler, setupAIObjectTypeRegistration() loggt ihn und kehrt zurück, main() würde unverändert weiterlaufen (kein log.Fatal im Pfad). Client-seitig zusätzlich durch TestRegister_UnreachableEndpoint_IsError abgesichert (Timeout über context.WithTimeout(10s) in setupAIObjectTypeRegistration, kein endloses Warten).

Aufräumen

• Testprozesse (ai-app-Binary, Core-Stub) beendet.
• Temporäre cmd/int12-*-tmp-Verzeichnisse (Migrations-Runner, E2E-Runner) nach Gebrauch wieder gelöscht.
• Postgres-Rolle/DB int12_ai_test bleibt auf 204 als Wegwerf-Testartefakt stehen (keine Kollision mit dms_dev/archivdms), kann bei Bedarf gelöscht werden: DROP DATABASE int12_ai_test; DROP ROLE int12_ai_test;