32 KiB
A – Jinkendo Technical Reference Architecture
Phase 3.2 · v0.3 · 16.10.2026 · vorgeschlagener Referenzstandard für neue Anwendungen
Empfohlen wird eine modulare FastAPI-Anwendung mit React/Vite, PostgreSQL, expliziten Transaktionen und einem Gitea-Ablauf mit verpflichtenden Release-Gates und nachvollziehbarer Zuordnung von Quellstand, Build und getesteter Produktionsversion. Die Module bleiben zunächst produktlokal. Authentifizierung, Datenraum, Berechtigungen, KI und Subscriptions werden über klar definierte Grenzen angebunden.
Die Referenz wird pro Mechanismus ausgewählt: Mitai für Prompt-/Workflow-Ausführung und Registry-Verträge, Shinkan für Nutzer-/Vereinssichten und Zugriffsschutz, Kanshō für private KI-Daten und Maskierung. Kairo ergänzt einzelne Struktur-, Konfigurations- und Maschinenzugriffsmuster. Keine Anwendung ist als Ganzes die führende oder am besten betriebsbewährte Referenz. Die folgende Foundation ist eine gezielte Synthese mit expliziten Anpassungen.
Diese Empfehlung ist keine Freigabe für Produktionsänderungen. ADR-01 bis ADR-14 und Reuse First gelten als beschlossen; ADR-15 und ADR-16 bleiben offen. Bestehende Apps werden durch dieses Dokument nicht zur Migration verpflichtet. Die visuelle Gestaltung gehört weiterhin in die Frontend Design Guideline.
Lesereihenfolge: A definiert die technischen Verträge, B macht daraus einen Implementierungsauftrag, C begründet die Auswahl und nennt drei offene Produkt-/Betriebspunkte.
A0 – Verbindliche Verträge, technische Defaults und Nachweis
Die Zielarchitektur in A und ihre Ausgestaltung in B sind ein vorgeschlagener technischer Standard. Die bereits beschlossenen Architekturverträge gelten unabhängig davon; technische Detailvorschläge werden durch dieses Dokument nicht automatisch zu weiteren beschlossenen Familienverträgen.
| Einordnung | Geltung in dieser Referenz |
|---|---|
| Verbindliche Architekturverträge | Verifizierte Identität und Datenraumgrenzen; Fail-Closed-Autorisierung neuer geschützter Funktionen; wirksame Objekt-/Scopeprüfung; sichere atomare Transaktionsgrenzen; verlässlicher Migrations-/Erfolgsnachweis; Secret-/Privacy-Grenzen; verpflichtende Release-Gates und eindeutige Zuordnung zur produktiven Version. Maßgeblich bleiben die beschlossenen ADRs und produktbezogenen Schutzgrenzen. |
| Technische Defaults | Bevorzugte Framework-/Versionslinien in A1, Verzeichnis- und Dateidetails in A2/B1, konkrete Modul-/Hilfsnamen, numerische Listenlimits in A4, Poolgrößen und Zeitbudgets in A5, Clienttimeout in A7/B3 sowie Artefakttransport und bevorzugtes Build-Verfahren in A9/B5. Sie sind begründet anpassbare Ausgangspunkte. |
Bei begründetem Produktbedarf dürfen Defaults angepasst werden. Grund, gewählter Wert bzw. Ersatz und geeigneter Funktions-/Kompatibilitätsnachweis werden kurz im Produktauftrag oder in der Produktkonfiguration festgehalten; dafür wird kein neuer ADR oder zusätzlicher Freigabezyklus verlangt. Begründete Varianten dürfen keinen verbindlichen Schutz-, Transaktions- oder Releasevertrag abschwächen. Anpassbare Verzeichnisnamen ändern beispielsweise nicht die Verantwortungsgrenzen; anpassbare Timeouts beseitigen keine wirksamen Ressourcenlimits. Die gewählten Versionen müssen weiterhin unterstützt und untereinander kompatibel sein. Nach außen veröffentlichte API-Verträge bleiben gegenüber ihren Clients kompatibel, auch wenn interne Details angepasst werden.
Für die folgenden Abschnitte gilt diese Nachweiskennzeichnung:
| Nachweisgrad | Bedeutung / aktueller Stand |
|---|---|
| V – Vorgeschlagener technischer Standard | Zielentscheidungen und Implementierungsvorgaben in A/B; technisch konkret, noch keine ausgeführte Referenzimplementierung. |
| I – Bereits vorhandene Implementierungsreferenz | Benannte Produktdateien und Mechanismen aus v0.2; statisch untersuchte Vorbilder. Vorhandener Code oder eine Testdatei allein ist kein erfolgreicher Testnachweis. |
| T – Tatsächlich durch Tests validierte Lösung | Nur mit konkretem Testumfang, bestandenem Ergebnis, Quell-/Buildstand und Ausführungsumgebung. Für die hier vorgeschlagene Foundation wird kein solcher Gesamtnachweis behauptet; v0.3 führt keine Tests aus. |
| K – Noch nicht integrierte oder getestete Kombination | Die produktübergreifende Foundation-Synthese, Adapterkombinationen und kleinen Codebeispiele. Zusammenwirken und Versionskompatibilität müssen bei der Umsetzung erst validiert werden. |
Eine Passage kann V und K zugleich sein; ein I-Verweis hebt sie nicht automatisch auf T. B beschreibt einen künftigen Aufbau und dessen Abnahmebedingungen, keine bereits produktionsreife Referenzimplementierung. Die Versions-/Supportangaben aus A1 werden als bisheriger Dokumentstand übernommen, in v0.3 nicht erneut recherchiert.
A1 – Technologiestack und zulässige Varianten
| Bestandteil | Technischer Default für eine neue App | Verwendung |
|---|---|---|
| Backend | Python 3.12, FastAPI, Uvicorn, Pydantic 2 | HTTP, Validierung, Dependency Injection; überwiegend synchrone DB-Anwendungsfälle |
| Datenbank | PostgreSQL 16, Psycopg 3 und dessen psycopg_pool |
Parametrisiertes SQL; begrenzter Pool; kein ORM als Foundation-Abhängigkeit |
| Frontend | React/React DOM 19.3, JavaScript/JSX mit JSDoc, Vite 8.3, React Router 8.4 im Data Mode | SPA; explizite Routen, Loader, Actions und Modulregistrierung |
| Build | Node.js 24 LTS, npm, Docker Compose | Statischer Frontend-Build, Backend-Image, bestehender Reverse-Proxy mit TLS |
| Tests | pytest, HTTPX/TestClient; Vitest 5, jsdom, React Testing Library; Playwright | Unit-, HTTP-/DB-Vertrags-, Komponenten- und wenige Browsertests |
| Abhängigkeiten | npm-Lockfile; Python-Lockfiles mit pip-tools als Build-Werkzeug |
Exakte, überprüfbare Auflösung einschließlich transitiver Pakete und Python-Pakethashes |
| Betrieb | Gitea Actions, Docker Compose, strukturierte Standard-Logs | Bestehende Betriebsform; kein neuer Plattformdienst |
Versionen sind Versionslinien, keine erzeugten Paket-Lockfiles. Beim Anlegen der App werden stabile Patchstände und kompatible Plugins aufgelöst, exakt gelockt und gemeinsam getestet. FastAPI bleibt in der stabilen 0.x-Linie, Psycopg in 3.x; Pydantic in 2.x. Keine Vorabversion aus einer „latest“-Dokumentation installieren. Runtime-/Build-Basisbilder werden mit Version und Digest festgehalten. Starlette und andere transitive Pakete nicht unabhängig gegen FastAPIs Anforderungen pinnen. FastAPI-Versionierung
Die Python-Locks werden mit pip-compile --generate-hashes für die Zielumgebung erstellt und mit Hashprüfung installiert; ihre Erzeugung ist kein Runtime-Schritt. pip-tools
Die neuere Frontend-Basis ist eine gezielte Aktualisierung desselben Stacks: Vite 5 wird offiziell nicht mehr unterstützt, Node 20 ist EOL. React 19.3 und Router 8.4 sind die beim Nachschlagen aktuellen stabilen Linien; Vitest nennt passende Mindestanforderungen für Vite/Node. PostgreSQL 16 bleibt unterstützt. Vite, Node, React, Router, Vitest, PostgreSQL
Bestandsvarianten: React 18/Router 6, Psycopg 2 und heutige Projektpfade bleiben bei Erweiterungen nutzbar; der Änderungsschnitt muss die Verträge dieses Dokuments erfüllen. Eine Versionsmigration ist ein separater Auftrag. Kanshōs SQLite-Adapter bleibt eine lokale Produktvariante, kein zweites Standard-Backend für neue Apps. Asynchrone DB-Zugriffe, ORM, globaler State-Store, PWA oder Worker kommen erst bei einem konkreten Anwendungsfall hinzu. Kein SSR, SSO oder Billing-Service auf Vorrat.
A2 – Projektstruktur und Abhängigkeiten
Technischer Strukturdefault: Eine Anwendung bleibt ein Repository mit Backend, Frontend, Migrationen, Tests und Deploymentdefinitionen. Verzeichnisdetails und Zuschnitt dürfen gemäß A0 angepasst werden; die Verantwortungs- und Schutzgrenzen bleiben erhalten. Backend und Frontend werden getrennt gebaut. Innerhalb des Backends hat jedes Fachmodul Router, Schemas, Service und Repository. Kleine reine Berechnungen können im selben Modul bleiben; zusätzliche Schichten entstehen nur für eine tatsächliche Zuständigkeit.
flowchart LR
UI[Route / Komponente] --> API[Frontend API-Modul]
API --> Router[FastAPI Router]
Router --> Service[Anwendungsservice]
Service --> TX[Transaktion / Repository]
TX --> PG[(PostgreSQL)]
Service --> Ports[Access / Entitlement / KI-Ports]
Root[Composition Root] -. verdrahtet .-> Router
Root -. verdrahtet .-> Service
Root -. verdrahtet .-> Ports
Die Abhängigkeitsrichtung lautet Router → Service → Repository/Port. Repositories kennen SQL, Services kennen den Anwendungsfall, Router kennen HTTP. Nur der Composition Root kennt alle konkreten Implementierungen. core importiert keine Fachmodule; Fachmodule importieren keine fremden Router. Benötigte fremde Funktionalität läuft über eine explizite Service-Schnittstelle. Keine generische Basisklasse oder Repository-Abstraktion ohne zweiten realen Bedarf.
Die Zielaufteilung ist ein Referenzentwurf aus vorhandenen Teilmechanismen, keine unveränderte Kairo-Architektur. Mitai zeigt explizit übergebene Cursor und registrierte Resolver; Kairo zeigt gesonderte Router/Services. Sein Router greift jedoch sowohl auf Services als auch auf Read Models zu, der Data Layer importiert private Service-Helfer und führt selbst SQL aus. Das ist kein durchgängig eingehaltenes Router → Service → Repository. Zusätzliche Connections in Serviceprüfungen werden ebenfalls nicht übernommen. Für neue Anwendungsfälle gilt A3; die genaue Zielstruktur steht einmalig in B1.
A3 – Backend, Dependency Injection und Transaktionen
create_app(settings, providers) baut eine App ohne DB-Migration, Seed oder Provideraufruf beim Modulimport. bootstrap registriert konkrete Module und bindet ihre Abhängigkeiten. FastAPI Depends liefert Services und den verifizierten Requestkontext; es ist kein Service-Locator innerhalb der Fachlogik. Poolöffnung und Poolschluss gehören in den App-Lifespan.
Mit synchronem Psycopg verwenden DB-Router normale def-Handler. Blockierende Treiber werden nicht direkt aus einem async def-Handler aufgerufen. Echte asynchrone I/O-Pfade erhalten einen durchgehend passenden Adapter; reine Hilfsfunktionen wechseln ihren Ausführungsmodus nicht automatisch. FastAPI-Ausführungsmodell
Transaktionsvertrag: Ein Anwendungsservice öffnet genau einen Transaktionskontext für eine atomare Operation. Alle beteiligten Repositories, veränderungsrelevanten Scope-Prüfungen, Quotenbuchungen und erforderlichen Audit-Einträge nutzen diese Verbindung. Normaler Blockabschluss committed, jede Exception rollt zurück; Rückgabe an den Router erfolgt erst danach. Repositories committen nicht. Kein nachgelagerter Commit in einer Request-Dependency nach Rückgabe der HTTP-Antwort.
Lesepfade schließen ihren kurzen Transaktionskontext ebenfalls zuverlässig. Externe HTTP-/KI-Aufrufe liegen außerhalb offener DB-Transaktionen. Falls eine spätere Operation Reservierung/Bestätigung benötigt, erhält sie einen expliziten Zustands-/Idempotenzvertrag; ein DB-Commit wird nicht als Atomarität mit einem externen Anbieter dargestellt.
Die gemeinsame Cursor-Nutzung und SAVEPOINT-Lektion aus Mitais Import-Leitfaden wird übernommen. Standard ist vollständiges Rollback. Nur ein ausdrücklich als teilweise erfolgreich definierter Batch darf einzelne Zeilen über Savepoints isolieren.
Fachfehler sind kleine explizite Exception-Typen, etwa NotFound, PermissionDenied und Conflict. Nur der HTTP-Adapter übersetzt sie in Antworten. Bekannte Constraint-Verletzungen werden gezielt übersetzt; unbekannte DB-Fehler bleiben Serverfehler. Kein pauschales except Exception: return [] und kein stilles Weiterarbeiten nach einem DB-Fehler.
A4 – API Contract
Neue Fach-APIs beginnen unter /api/v1. JSON-Felder verwenden snake_case, IDs sind opake Zeichenketten, Zeitpunkte ISO 8601 in UTC mit Z; reine Datumswerte bleiben YYYY-MM-DD. Geldwerte sind Dezimalzeichenketten plus Währung. Request-Modelle verbieten unbekannte Felder. Output-Modelle erlauben nur explizit freigegebene Felder; DB-Zeilen werden nicht direkt serialisiert.
| Vertrag | Festlegung |
|---|---|
| Erfolg | Einzelobjekt direkt; Listen {items, next_cursor}; keine zusätzliche globale data-Hülle |
| Listen | Numerische Defaults: limit 50, Maximum 200; begründet anpassbar. Begrenzte Abfragen, validierter Cursor und stabile Sortierung mit ID als Tiebreaker bleiben der Vertrag. |
| Status | 201 plus Location für Anlage; 200 für Lesen/Ändern; 204 ohne Body für Löschen |
| Fehler | RFC-9457-Problem-Details mit type, title, status, sicherem detail, instance; Erweiterungen code, request_id, optional errors |
| Feldfehler | errors: [{path, code, message}]; keine Rohwerte, Passwörter oder Pydantic-input-Felder zurückgeben |
| Codes | 401 ohne gültige Identität; 403 fehlende Befugnis; 404 nicht sichtbares Objekt; 409 Konflikt; 422 ungültige Eingabe; 503 nicht verfügbare Abhängigkeit |
| Nachvollziehbarkeit | Server erzeugt Request-ID; Antwortheader X-Request-ID; nur validierte eigene Proxy-ID übernehmen |
| Änderung | Additiv innerhalb v1, inkompatible öffentliche Änderungen unter v2; OpenAPI-Vertragsdiff in CI |
type ist eine stabile URI-Referenz, zum Beispiel urn:jinkendo:problem:validation; code ist ein stabiler Maschinenwert, kein übersetzter Text. Bei 500/503 werden interne SQL-/Provider-/Proxyinhalte nicht ausgegeben. Problem Details
/health/live prüft den Prozess, /health/ready Pool, kompatiblen Migrationsstand und erforderliche Adapter. Beide sind read-only, geben bei Fehlern nur einen sicheren Status aus und besitzen kurze Timeouts. Die Build-ID erscheint als X-Build-Revision; volle Releaseinformationen bleiben im Betriebsartefakt. Kein automatischer DB-Reparaturversuch über Health.
A5 – PostgreSQL, Connection-Handling und Migrationen
Psycopg 3 ist bereits in Kanshō vorhanden. Übernommen wird der Treiber, nicht die SQLite-förmige SQL-Übersetzung. SQL verwendet native PostgreSQL-Platzhalter und parametrisierte Werte. Dynamische Bezeichner werden nur aus einer erlaubten Menge über psycopg.sql zusammengesetzt. Keine SQL-Fragmente aus Requestdaten.
Ein threadgeeigneter psycopg_pool.ConnectionPool pro Backend-Prozess begrenzt Verbindungen. Anpassbare technische Defaults: ein Prozess, Pool 1–5, Wartezeit 3 Sekunden, höchstens 20 Wartende. Verbindungsaufbau 5 Sekunden; Standard-Statement 5 Sekunden, Lock-Wartezeit 2 Sekunden. Größere Aufgaben dürfen begründete eigene Zeitbudgets erhalten. Mehr Prozesse benötigen eine neue Connection-Budgetrechnung; keine automatische Poolvervielfachung ohne Grenze.
Der Pool liefert autocommit=True-Verbindungen ausschließlich an den DB-Adapter. Dieser führt jeden fachlichen Zugriff in connection.transaction() aus und gibt die Verbindung sauber zurück. Poolerschöpfung wird 503; sie wird nicht durch unbegrenzte zusätzliche Verbindungen umgangen. Psycopg-Pool, Transaktionskontexte
Migrationsverfahren: vorhandenes SQL-Dateimuster gezielt härten, kein neuer Alembic-/ORM-Wechsel. Ein expliziter CLI-Lauf vor Prozesswechsel verwendet eine getrennte Migrationsrolle und eine ungepoolte Verbindung. Runtime darf kein DDL ausführen und ist weder Superuser noch BYPASSRLS-Rolle.
Neue IDs folgen 20261016T120000Z_short_name.sql; vollständige IDs und Zeitpräfixe sind eindeutig, Reihenfolge ist lexikalisch. Ein Ledger schema_migrations(id, sha256, applied_at, build_revision) ist maßgeblich. Der Runner:
- Validiert Dateinamen und Duplikate im Paket.
- Serialisiert Ledgerprüfung und Ausführung mit einem PostgreSQL-Session-Advisory-Lock auf derselben Verbindung und einem festen dokumentierten Schlüssel; nach einem begrenzten Wartebudget bricht er ab (technischer Default: 60 Sekunden). Auf leerer DB legt der Runner unter diesem Lock ausschließlich sein Ledger an. Danach liest er den Stand und prüft sämtliche angewandten Prüfsummen; angewandte, aber fehlende Dateien sind ein Fehler.
- Führt jede noch offene SQL-Datei und ihren Ledger-Eintrag in derselben Transaktion und Verbindung aus. Scheitert eine Datei, endet der Lauf ungleich null; frühere erfolgreich committete Dateien bleiben angewandt.
- Gibt den Lock im
finallyfrei und schließt die Verbindung. Ein Wiederanlauf überspringt nur nachweislich erfolgreiche Dateien.
SQL-Dateien enthalten weder eigene Transaktionssteuerung noch psql-Metabefehle. Parameterlose SQL-Dateien werden als Ganzes ausgeführt, nicht per Semikolon zerlegt. Dollar-quoted Funktionen müssen funktionieren. Nichttransaktionale DDL benötigt einen separaten geplanten Betriebsschritt. Entwicklungsdaten-Seeds laufen gesondert und niemals automatisch in Produktion. Psycopg: mehrere Statements
SQL-Dateien und Runner sind in Shinkan, Mitai und Kairo vorhanden. Keiner dieser Runner wird hier als vollständig passende Standardimplementierung ausgezeichnet. Der Vertrag kombiniert das bestehende SQL-Verfahren mit kleinen gezielten Korrekturen; insbesondere wird Kairos separater SQL-Prozess mit späterem Ledger-Commit nicht übernommen. Historische IDs bestehender Apps werden nicht umbenannt. Neue Apps starten mit einer Initialmigration; Bestandsübernahmen benötigen eine gezielte Baseline. Expand/Contract hält das vorige Image bei einem notwendigen Rollback möglichst lauffähig; kein automatisches produktives „Down“.
A6 – Konfiguration, Secrets und technische Funktionen
Eine zentrale Pydantic-Settings-Struktur validiert beim Start eine explizit zusammengestellte Prozessumgebung. APP_ENV ist verpflichtend und genau development, test oder production; unbekannt bedeutet Startfehler. Benötigt werden Produktkennung, öffentliche Origin, Runtime-DB-Verbindung und Buildrevision. Produktionsmodus verlangt HTTPS-Origin und eine vollständige Schutzkonfiguration.
Secrets kommen aus der bestehenden Betriebsbereitstellung als Prozessumgebung oder gemountete Secret-Datei, nie aus dem Frontend, einem Seed oder einem Default-Passwort. Nur der Secret-Adapter kennt Rohwerte. Keine eigene produktive .env-Schreibfunktion. Lokale Entwicklungsdateien dürfen durch die Startumgebung injiziert werden; die App lädt sie nicht still beim Import nach. Migrationszugangsdaten werden nicht dem laufenden Backend überlassen.
Technische Feature-Schlüssel sind registriert und typisiert. Unbekannte Schlüssel sind Fehler; fehlende optionale Funktionen bleiben aus. Auth-, Scope- und Pflichtprüfungen sind nicht deaktivierbare „Features“. Anbieter-/Netzwerkfunktionen sind ohne vollständige Konfiguration aus. Kairos Secretreferenz-Prüfung ist das Vorbild für DB-Konfiguration ohne Klartext-Secrets. Kanshōs Fallback auf development wird nicht übernommen.
Logs verwenden logging mit kleinem produktlokalem JSON-Formatter: Zeit, Level, Ereigniscode, Request-ID, Modul und Dauer. Keine Bodies, Prompts, Cookies, Zugangsdaten oder vollständigen Querystrings. Erforderliche Fachaudits nennen Subject-/Actor-ID, Scope, Aktion, Ressourcen-ID und Ergebnis; bei DB-Änderungen teilen sie deren Transaktion. Fehlgeschlagene Autorisierungsversuche bekommen einen getrennten sicheren Security-Logpfad. Kairos Audit-Helfer liefert das Ereignismuster, nicht die unabhängige Audit-Connection.
A7 – Technische Frontend-Architektur
Eine explizite Modulregistrierung liefert Routen und Navigation; doppelte IDs oder Pfade brechen den Aufbau ab. Data Router wird einmal außerhalb des React-Renderns erzeugt. Routen besitzen Loader/Actions und lokale Fehlergrenzen. Kein Router-Neuaufbau beim Wechsel des gewählten Datenraums. Router Data Mode
Ein gemeinsamer request-Client kapselt ausschließlich Transport und Fehler. Fachliche API-Funktionen liegen im jeweiligen Modul. Transportdefault: relative Same-Origin-URLs und 15 Sekunden Timeout; begründete Anpassungen folgen A0. Cookie-Credentials, AbortSignal, Prüfung von Content-Type/Status und Unterstützung von 204 gehören zum beschriebenen Transportvertrag. Keine Session in Local Storage oder URLs. Keine ungeprüfte HTML-Fehlerausgabe und keine automatischen Wiederholungen von Schreiboperationen. Cookie/CSRF- und Loginlogik bleibt im Auth-Adapter.
Serverdaten gehören in Route-Loader bzw. modulbezogene Hooks. Formulare und flüchtiger UI-Zustand bleiben lokal in useState/useReducer. Ein kleiner Session-/Scope-Store enthält nur bestätigten Kontext und einen monotonen epoch-Wert. Bei Logout oder Scopewechsel werden Requests abgebrochen, personenbezogene Ergebnisse verworfen und Loader neu ausgeführt. Antworten einer alten Epoche dürfen nicht in die neue Ansicht gelangen. Ein weiterer Cache ist kein Foundation-Bestandteil.
Mitai ist das primäre Vorbild für explizite Registrierung: Die Placeholder-Registry verweigert doppelte Schlüssel und bindet Metadaten/Resolver; die UI-Registry verbindet Komponenten mit einer Fehlergrenze. Die Duplikatsperre der ersten ist bei Übernahme auch für die zweite erforderlich. Kairos Slice-Lader sind eine ergänzende Referenz für tatsächlich benötigtes selektives Nachladen; ihr stilles catch → null wird nicht kopiert. Aus Shinkan stammen Rücknavigation/Dirty-Form-Schutz. Deren Routerannahmen werden auf der neuen Version getestet.
SPA-Dateien können lange mit Hash gecacht werden; index.html wird revalidiert. Persönliche API-Antworten erhalten Cache-Control: no-store. PWA ist optional; wenn vorhanden, werden persönliche APIs nicht im Service Worker gecacht. Kanshōs NetworkOnly-Konfiguration dient als Richtung, deren tatsächliches URL-Matching muss getestet werden. Gestaltung und visuelle Komponentenverträge werden hier nicht familienweit festgelegt.
A8 – Schnittstellen zu Security, Datenraum, KI und Subscriptions
| Grenze | Foundation-Vertrag | Bewusst nicht vorweggenommen |
|---|---|---|
| Identität | PrincipalResolver liefert verifizierte eigene User-/Maschinenidentität; kein Profil aus Clientheadern |
Login-, MFA-, Recovery- und Session-Spezialimplementierung |
| Datenraum | ScopeResolver validiert eine Auswahl gegen Identität/Mitgliedschaft; Service/Repository verlangen expliziten Scope |
Universelle Tenanttabelle oder RLS für alle Produkte |
| Zugriff | AccessPolicy prüft aktuelle Befugnis und Objektsichtbarkeit, standardmäßig verweigernd |
Dauerhafter Probe-Modus oder UI als Sicherheitsgrenze |
| Subscriptions | EntitlementPolicy prüft produktlokale Features/Quoten zusätzlich zur Befugnis |
Zentrales Billing oder Vermischung von Kaufstatus und Objektberechtigung |
| KI/Agenten | ModelGateway/Tool-Adapter erhält autorisierten minimalen Kontext; Tool ruft denselben Service auf |
Externe Freigabe einzelner Anbieter, Memory-Kern, autonome DB-Zugriffe |
Konkrete Herkunft dieser Grenzen: Shinkans Sichtbarkeitsfunktion trennt offiziell, privat und Verein einschließlich aktiver Mitgliedschaft; Kontozustände, Capabilities und Security-Regressionen ergänzen den Zugriffsschutz. Dieser fachlich konkrete Bestand ist die primäre Referenz für Scope-/Policy-Adapter, keine bloße Navigationshilfe.
Für KI-Funktionen wird zuerst Mitais vorhandene Workflow-Ausführung, Promptauflösung und Placeholder-Registry auf passende Wiederverwendung geprüft. Kanshō liefert die Maskierung und Prüfung vor dem Anbieteraufruf. Der Zielfluss lautet bei entsprechendem Bedarf: autorisierter Kontext → Prompt-/Workflow-Laufzeit → produktbezogene Privacy-Prüfung/Maskierung → Anbieter. Diese Kombination ist ein vorgeschlagener Schnittstellenfluss, keine bereits gemeinsam getestete Integration. Die Foundation importiert nicht vorsorglich einen Workflow-Editor oder jede Privacy-Implementierung in jede App.
RequestContext trägt request_id, verifizierten Principal und ausgewählten Scope. Ein Client darf den Scope auswählen, aber nie seine Berechtigung oder Identität bestimmen. Keine Auswahl des ersten Profils/Clubs als stiller Sicherheitsfallback. Personen-, Club- und Organisationsräume sind Varianten dieses Vertrags, keine einheitliche Fachdomäne.
Neue Same-Origin-Browser-Apps planen serverseitige Sessions mit HttpOnly, Secure, geeignetem SameSite sowie CSRF-/Originprüfung für unsichere Methoden. Fehlende Adapter sperren geschützte Funktionen; Testidentitäten existieren ausschließlich in Testverdrahtung. Separate begrenzte Agentenidentitäten werden erst bei echtem Maschinenbedarf ergänzt. Kanshōs lokale Privacy-Grenzen bleiben verbindlich, einschließlich Detect-/Generate-Trennung und Prüfung des vollständigen Egress.
Risikobasierte Isolation folgt ADR-06: App-Policies plus Constraints und eingeschränkte Runtime-Rolle sind die kleine Basis; vertrauliche Mehrraumprodukte müssen zusätzlichen RLS-Schutz ausdrücklich prüfen. Bei RLS gehört DB-Kontext transaktionslokal gesetzt und darf nicht zwischen Poolnutzern überleben. Fremde Eltern-/Kindreferenzen müssen auch durch passende DB-Constraints verhindert werden.
A9 – Testing, Deployment und Reuse
Die erforderlichen Mindestnachweise und ihre technischen Umsetzungsvorschläge (Befehle und Abläufe) stehen in B4/B5; konkrete Pfade und Befehle dürfen im Rahmen von A0 konsistent angepasst werden. Grundsatz der technischen Umsetzung: isolierte PostgreSQL-Testdaten, echte Negativtests, Import-/OpenAPI-Prüfung, Frontend-Fehler-/Scopewechseltests und ein kleiner Browserdurchlauf gegen das tatsächlich gebaute Image. Verpflichtende DB-Suiten dürfen weder vollständig skippen noch durch fehlende Konfiguration still als erfolgreich gelten.
Verbindlicher Releasevertrag gemäß ADR-11: Der Weg bleibt develop → Dev → Tests → bewusste Freigabe → main → Prod. Pflicht-Gates müssen vor der Produktionsumschaltung bestanden sein. Quellstand, Build-Eingaben, Testläufe und tatsächlich eingesetzte Artefakte müssen eindeutig zusammengehören. Ein nachgelagerter Health-Smoke ersetzt das Release-Gate nicht. Die bewusste menschliche Produktionsfreigabe bleibt erhalten.
| Technische Variante | Umsetzung / Nachweis |
|---|---|
| R1 – Bevorzugter Default: Build once, deploy many | Die in Dev qualifizierten Backend-/Frontend-Artefakte werden unverändert nach Prod übernommen. Hashes/Digests und Buildrevision binden Test und Deployment; kein weiterer Build ist für diese Variante nötig. |
| R2 – Zulässige ADR-11-Variante: kontrollierte separate Builds | Dev- und Prod-Artefakte dürfen getrennt aus nachvollziehbaren Quellständen und reproduzierbar festgehaltenen Build-Eingaben entstehen. Lockfiles, Build-Rezept, Toolchain/Basisimages und erlaubte öffentliche Build-Parameter werden dokumentiert. Der konkrete Prod-Build erhält vor der Umschaltung seine erforderlichen Tests/Gates und eine eigene Artefakt-/Buildkennung. Ein grüner Dev-Build allein qualifiziert kein neu gebautes Prod-Artefakt. Unterschiedliche Artefakthashes zwischen Dev und Prod sind dabei zulässig. |
In beiden Varianten verknüpft der Releasenachweis getesteten Quell-/Buildstand, menschlich freigegebenen main-Stand und tatsächlich deployte Artefakte. Bei Merge-Commits wird die Beziehung über Commit und Source-Tree nachgewiesen. Der Default ist ein mit dem qualifizierten Stand identischer Tree; abweichender Produktionsquellstand oder abweichende Build-Eingaben benötigen die passenden dokumentierten Gate-Ergebnisse für den konkreten Kandidaten, keine ungeprüfte Gleichsetzung mit dem Dev-Lauf. Reproduzierbarkeit ersetzt diese Tests nicht.
Default für den Artefakttransport sind Docker-Image-Archive mit SHA-256 und Release-Manifest über die vorhandene Ablage; eine vorhandene Gitea-OCI-Registry mit Digestbindung ist ebenfalls zulässig. Keine Variante verlangt neue CI/CD-Infrastruktur. Die Freigabe erfolgt über geschützten main und bewusst angenommenen Release-PR, nicht über ein vermeintliches GitHub-Environment-Gate: Gitea ignoriert jobs.<job_id>.environment. Gitea-Kompatibilität
Reuse First konkret: zunächst lokale Implementierung nach denselben Verträgen und Contracttests. Kandidaten für eine spätere Library sind API-Fehlernormalisierung, Registry-Validierung, Settings-/Problem-Modelle und Migrationsrunner. Extraktion erst bei zwei tatsächlichen Nutzern, stabilem Vertrag und Maintainer. Auth, KI-Policy und Subscriptions bleiben produktlokale Adapter; zentrale Dienste sind keine automatische Folge ähnlichen Codes. Keine gemeinsame Fachdatenbank, keine Imports zwischen laufenden Produkt-Repositories.
Eine extrahierte Library erhält eine kleine öffentliche API, versionierte Releases, exakte Consumer-Pins und Contracttests in beiden Produkten. Ihr Maintainer verantwortet Sicherheitsfixes und eine erkennbare Update-/Kompatibilitätspolitik. Bis dahin werden übernommene lokale Bausteine mit Herkunft und relevanten Abweichungen dokumentiert; die Ähnlichkeit zweier Dateien allein löst keine Paketgründung aus.
Nachweisgrenze
Basis sind A01 des Inventars, dessen Dependency-/Guardrailregister und konkrete ausgewählte Quellen. Die genannten Mechanismen sind statisch nachvollzogen. In v0.2 wurde die pauschale Vorrangstellung Kairos entfernt und die Herkunft von Registry-, Zugriffs- und Privacy-Verträgen konkretisiert. Produktreife, Umfang eines Mechanismus, Testquellen und tatsächliche erfolgreiche Nutzung bleiben getrennte Nachweise; es gibt keine belegte Gesamtrangfolge der Produkte. Nach A0 sind die Zielangaben V, die benannten Produktmechanismen I und die Foundation-Synthese samt Beispielen K. Ein T-Gesamtnachweis liegt nicht vor: Referenzkombination, Versionskompatibilität und Beispiele wurden nicht als Anwendung ausgeführt. Auch die neuen Release-Varianten sind dokumentierte Vorgaben, keine in diesem Auftrag getesteten Pipelines. Keine Produktdateien, Migrationen, Deployments oder Gitea-Einstellungen wurden verändert.