29 KiB
B – Implementation Blueprint: Application Foundation
Phase 3.2 · v0.3 · 16.10.2026 · vorgeschlagener Blueprint, keine ausgeführte Referenzimplementierung
Dieser Blueprint setzt A um. Er beauftragt hier keine Umsetzung. Ein späterer Coding-Auftrag darf damit die Foundation einer benannten App aufbauen; Fachfunktionen, vollständige Auth-/KI-/Subscription-Blueprints und Bestandsmigrationen gehören nicht automatisch dazu.
Geltung und Nachweis: Dieser Blueprint ist V und als kombinierte Lösung K gemäß A0. Benannte Produktdateien sind I; geforderte Mindesttests sind noch keine T-Ergebnisse. Weder die Beispielausschnitte noch die gesamte Foundation sind hier integriert, getestet oder als produktionsreif nachgewiesen. Die tatsächliche Implementierung muss die erforderlichen Nachweise erst erbringen.
Verträge und Defaults: Verbindlich bleiben insbesondere Datenraum-/Privacy-Grenzen, Fail-Closed-Zugriff, sichere Transaktionen und Release-Gates. Verzeichnisdetails, Modulnamen, Framework-/Versionslinien und numerische Einstellungen sind technische Defaults gemäß A0. Begründete Anpassungen sind im Produktauftrag bzw. in dessen Konfiguration kurz festzuhalten; keine zusätzliche Freigabeschleife. Die Aussage „gemäß A“ meint diese Unterscheidung, keinen starren Zwang zu jedem Beispielwert.
B1 – Auftrag und Zielstruktur
Auftrag an den Coding-Agenten: Erstelle im ausdrücklich benannten neuen Produkt-Repository eine Foundation nach den Verträgen dieses Blueprints. Nutze den folgenden Verzeichnisbaum und die Versionslinien aus A1 als technische Defaults; begründete Anpassungen folgen A0. Löse stabile kompatible Patchstände auf und committe Lockfiles. Übernimm die unten genannten vorhandenen Mechanismen nach Anpassung ihrer Schnittstellen. Verändere keine anderen Produkt-Repositories. Erzeuge weder Beispiel-Fachprodukt noch allgemeines Framework. Lege leere Fachmodulordner erst mit der ersten echten Funktion an.
<product>/
├── AGENTS.md # verweist auf A/B und lokale Produktgrenzen
├── backend/
│ ├── app/
│ │ ├── __init__.py
│ │ ├── main.py # create_app; ASGI-Einstieg
│ │ ├── bootstrap.py # konkrete Module und Adapter verdrahten
│ │ ├── core/
│ │ │ ├── settings.py
│ │ │ ├── context.py # Principal, ScopeRef, RequestContext
│ │ │ ├── ports.py # nur tatsächlich benötigte Adapterverträge
│ │ │ ├── errors.py
│ │ │ └── logging.py
│ │ ├── api/
│ │ │ ├── dependencies.py
│ │ │ ├── problems.py
│ │ │ └── health.py
│ │ ├── db/
│ │ │ ├── pool.py
│ │ │ ├── transaction.py
│ │ │ └── migrate.py
│ │ ├── modules/<feature>/ # später: router, schemas, service, repository
│ │ └── integrations/ # nur für tatsächlich benötigte externe Adapter
│ ├── migrations/ # einzige SQL-Migrationsfolge
│ ├── tests/
│ │ ├── unit/
│ │ ├── api/
│ │ ├── integration/
│ │ ├── migrations/
│ │ ├── fixtures/
│ │ └── conftest.py
│ ├── requirements.in / requirements.lock
│ ├── requirements-dev.in / requirements-dev.lock
│ ├── pytest.ini
│ └── Dockerfile
├── frontend/
│ ├── src/
│ │ ├── app/ # bootstrap, router, providers, module registry
│ │ ├── shared/api/ # request client, ApiError
│ │ ├── shared/session/ # kleiner Session-/Scope-Store mit epoch
│ │ ├── shared/ui/ # produktlokale Darstellung nach Design Guideline
│ │ ├── modules/<feature>/ # api, loaders/actions, routes, components
│ │ └── main.jsx
│ ├── tests/ # gemeinsame API-/Routing-/Scope-Verträge
│ ├── package.json / package-lock.json
│ ├── vite.config.js
│ └── Dockerfile
├── tests/e2e/ # Playwright gegen isolierten gebauten Stack
├── scripts/ci/ # Gate, Test-DB-Wächter, Artefaktprüfung
├── deploy/ # Compose-Varianten, Proxykonfiguration
├── .gitea/workflows/ # qualification und production; kein Live-Umbau hier
└── docs/ # OpenAPI-Baseline, kurze Start-/Betriebshinweise
Im dargestellten Strukturdefault läuft Python mit backend als Working Directory, Imports beginnen mit app.. Bei anderer begründeter Verzeichnisstruktur werden Importpfade und Befehle konsistent angepasst; keine impliziten Importnebenwirkungen. Jede Package-Ebene enthält __init__.py; keine sys.path-Reparaturen oder Importe wie from main import .... API-/DB-/Modulimporttests müssen ohne Kontakt zu DB oder Anbieter funktionieren. Der Runner legt nur sein eigenes Ledger unter Lock an. Die erste SQL-Migration erstellt den tatsächlich benötigten Infrastrukturzustand, etwa den transaktionalen Audit-Speicher mit den Feldern aus A6; keine erfundenen Tenant-, Actor-, Billing- oder Memorytabellen.
B2 – Backend bauen
Konstruktion und Adapter
create_app(settings, providers) registriert Fehlerhandler, Health und explizit ausgewählte Router. bootstrap erzeugt Pool, Transaktionsfactory und konkrete Services. Testapp und Runtime verwenden dieselbe Factory; nur Tests injizieren Fakes. Kein globales veränderliches Profil und keine Imports mit Startnebenwirkungen.
| Baustein | Mindestschnittstelle | Verhalten |
|---|---|---|
| Principal | kind, subject_id, optional actor_id |
Typisierte eigene Identität; keine mitgesendete Rolle als Autorität |
| ScopeRef | kind, scope_id |
Verifizierter persönlicher/Club-/Organisationskontext; konkrete Fachsemantik bleibt lokal |
| RequestContext | request_id, principal, scope |
Unveränderlicher Kontext; kein Credential und kein Promptinhalt |
| PrincipalResolver | resolve(request) -> Principal |
Fehlende/abgelaufene Session: 401; nicht verdrahteter Adapter: 503 |
| ScopeResolver | resolve(principal, selection) -> ScopeRef |
Mitgliedschaft prüfen; fremde/fehlende erforderliche Auswahl verweigern |
| AccessPolicy | require(context, capability, resource, tx) |
Rechte/Objektsichtbarkeit, bei Writes aktuellen Zustand in derselben Transaktion prüfen |
| EntitlementPolicy | require(context, feature, tx) |
Zusätzlich zum Zugriff; ohne aktuelle Anforderung keine vorsorgliche Quotenmaschine |
| TransactionFactory | transaction() -> ContextManager[Tx] |
Eine Verbindung je Anwendungsfall; Commit vor erfolgreicher Rückgabe |
Wiederverwendung an diesen Grenzen: Scope-/Access-Adapter werden zuerst gegen Shinkans Sichtbarkeit, Kontozustand und zugehörige Negativtests abgeglichen. Für benötigte Prompt-/Workflow-Funktionen ist Mitais Ausführungs-/Registrierungssystem die erste Referenz; für private Modellkontexte Kanshōs Gateway. Nicht durch neue generische Platzhalterlösungen ersetzen, bevor ein konkreter vorhandener Mechanismus geprüft wurde. Kairo ist kein globales Ausgangsgerüst.
Die Ports sind Typverträge, keine externen Dienste. Nur aktuell benötigte Ports werden implementiert. Ohne echten Auth-Adapter bleiben geschützte Routen geschlossen; es gibt keinen AUTH_DISABLED-/ALLOW_ALL-Runtime-Schalter. Ein geschützter Test-Router darf ausschließlich in der Testapp existieren. Die Foundation kann intern Health bereitstellen; daraus folgt keine Produktfreigabe für persönliche Fachdaten.
Transaktionsmuster
Nicht integrierte und nicht ausgeführte Illustration (K) des DB-Adapters; Pool-Konfiguration und Fehlerübersetzung kommen aus A5/A4. timeout=3 ist ein technischer Default, keine unveränderliche Architekturgrenze:
from contextlib import contextmanager
class UnitOfWork:
def __init__(self, pool):
self.pool = pool # Pool liefert autocommit=True-Verbindungen
@contextmanager
def transaction(self):
with self.pool.connection(timeout=3) as conn:
with conn.transaction():
yield conn # in Services nur als Tx-Handle weiterreichen
Die Poolöffnung erfolgt einmal im Lifespan, pool.wait() ist zeitlich begrenzt; Shutdown schließt ihn. Kein Lazy-Neuaufbau eines Pools in jedem Repository. Für die eigene Architekturgrenze gilt: Nur Repository-/DB-Adapter rufen SQL auf diesem Handle auf.
Ein Anwendungsservice folgt diesem Muster, ohne daraus ein generisches CRUD-Framework zu bauen:
def rename_resource(self, context, resource_id, command):
with self.uow.transaction() as tx:
self.access.require(context, "resource.update", resource_id, tx)
repo = self.repositories.resources(tx)
row = repo.rename_in_scope(context.scope, resource_id, command)
result = ResourceResponse.model_validate(row)
self.audit.changed(tx, context, "resource.updated", resource_id)
return result # auch der Commit muss erfolgreich gewesen sein
Alle hier verwendeten Typen/Methoden sind illustrative lokale Modulverträge. Response-DTO vor Verlassen des Blocks validieren; keine rohe DB-Zeile an FastAPI geben. Auditfehler verhindern den Commit einer auditpflichtigen Änderung. Ein späterer Scope- oder Entitlement-Adapter darf nicht unbemerkt eine zweite Connection öffnen. Bei konkurrierend bearbeiteten Ressourcen versieht das Fachmodul Updates mit erwarteter Objektversion und 409 bei Versionskonflikt.
Migration und Konfiguration
Implementiere python -m app.db.migrate --directory migrations gemäß A5. Runtime startet den Runner nicht selbst. Ein nicht erfolgreicher Migrationslauf verhindert den Prozesswechsel. Der CLI liest ausschließlich den expliziten Migrationszugang, nicht einen privilegierten Ersatz für den Runtime-Pool.
Unter dem Advisory-Lock wird gegebenenfalls das eigene Ledger angelegt; danach werden Ledger und Prüfsummen gelesen. Bei SQL-Ausführung und Ledger-Insert gibt es keinen zweiten Prozess/keine zweite Verbindung. DO $$ … $$, mehrere Statements ohne Parameter und Fehler in der Dateimitte erhalten eigene Tests. Keine einfache Semikolon-Zerlegung. Nichttransaktionale DDL wird zurückgewiesen; ihr eigener Betriebsschritt ist kein versteckter Runner-Fallback.
| Konfiguration | Vorgabe |
|---|---|
APP_ENV, PRODUCT_ID, PUBLIC_ORIGIN |
Verpflichtend; Environment-Enum und zulässige Origin validieren |
DATABASE_URL |
Secret ohne Default; Runtime-Rolle, kein DDL/Owner/Superuser |
MIGRATION_DATABASE_URL |
Nur Migrationsprozess; fehlt im Runtime-Container |
BUILD_REVISION |
Source-Commit des gebauten Images, im Image festgehalten; nicht durch Deploy überschreiben |
EXPECTED_SCHEMA_HEAD |
Aus dem qualifizierten Deploy-Manifest; Readiness vergleicht mit tatsächlichem Ledger-Head |
| Pool-/SQL-Zeitbudgets | Numerische Defaults aus A5 begründet anpassbar; typisierte Validierung und wirksame Grenzen bleiben erforderlich. |
FEATURE_FLAGS |
Validiertes Objekt registrierter boolescher Schlüssel; fehlende optionale Funktion aus |
| Provider-/Cookie-/Auth-Secrets | Erst mit dem jeweiligen echten Adapter; nie unsichere Entwicklungsdefaults |
Readiness kontrolliert zusätzlich die Prüfsummen der dem Image bekannten Migrationen. Neuere angewandte Migrationen sind nur mit qualifiziertem Kompatibilitätsnachweis für dieses Image zulässig; EXPECTED_SCHEMA_HEAD allein ist keine Freigabe für unbekanntes Schema. Das Deploy-Manifest hält den dafür erlaubten Schemahead fest. Bei unvollständiger Konfiguration Start abbrechen, keine Secrets mitloggen.
requirements.in enthält direkte Pakete innerhalb der festgelegten Versionslinien; requirements-dev.in ergänzt Testwerkzeuge. pip-tools erzeugt hashgebundene vollständige Locks. Runtime-/Dev-Lock müssen gleiche Runtime-Pins haben. CI installiert aus Locks und löst nicht neu auf; Docker verwendet Runtime-Lock und enthält weder Tests noch Test-Secrets.
B3 – Frontend bauen
Verwende für den Registry-Vertrag zuerst Mitais Schlüsselregistrierung mit Duplikatsperre und die produktlokale Komponentenregistry als Vorbilder; übertrage den kleinen Vertrag, nicht den gesamten fachlichen Placeholder-Katalog. Baue einen Data Router aus einer statischen Liste lokaler Moduldefinitionen. Definiere den Modulvertrag als JSDoc mit id, routes, navigation und benötigten Capability-/Feature-Schlüsseln. Registryaufbau prüft doppelte IDs/Pfade und unbekannte Schlüssel, statt sie zu überschreiben. UI-Gates verbessern die Bedienung; der Server prüft jeden Zugriff selbst.
Der vorgeschlagene Transportvertrag (V) wird durch folgenden nicht ausgeführten Ausschnitt (K) illustriert; timeoutMs: 15000 ist ein anpassbarer technischer Default:
request(path, {
method: 'GET',
json: undefined,
signal: undefined,
timeoutMs: 15000,
scopeSelection: undefined,
}) // Promise<DTO | undefined>; Fehler: ApiError
path ist relativ zu /api/v1; externe URLs, //host und Weiterleitungen werden nicht als Fach-API akzeptiert. Credentials und Basis-URL sind keine frei überschreibbaren Moduloptionen. Eine Scopeauswahl ist nur ein serverseitig zu prüfender Hinweis. Der Auth-Adapter ergänzt den CSRF-Nachweis bei unsicheren Methoden. Upload-/Streamingvarianten verwenden dieselben Identitäts-/Fehlergrenzen mit ausdrücklich anderem Body-/Antwortmodus.
ApiError besitzt status, code, requestId, fieldErrors; Netzfehler, Timeout, Abbruch und ungültige Antwort sind unterscheidbar. Der Client gibt niemals ungeprüften Response-Text als Fehlermeldung aus. Er erkennt 204 ohne JSON-Parsing. Bei einem Timeout nach einer Schreiboperation wird kein automatischer zweiter Write gesendet; das Ergebnis kann bereits committed sein. Wiederholung braucht den ausdrücklichen Idempotenzvertrag des Endpunkts.
Der Session-Store wird einmal im Bootstrap erzeugt und per Provider/Dependency weitergereicht. Er besitzt getSnapshot, subscribe, invalidate und eine Operation zum bestätigten Scopewechsel. React kann ihn mit useSyncExternalStore lesen. Enthalten sind nur Sessionstatus, Principal-Metadaten, ausgewählter Scope und epoch; keine Listen, Formulare oder Credentials.
Loader/Actions halten beim Start Scope und Epoche fest. Scopewechsel/Logout erhöht die Epoche, bricht aktive Requests ab und entfernt alte persönliche Ergebnisse; neue Loader beginnen leer. Sowohl erfolgreiche als auch fehlerhafte verspätete Antworten werden bei abweichender Epoche ignoriert. Ein alter 401 darf eine inzwischen neue Session nicht abmelden. Aktueller 401 leert die Session; 403 zeigt fehlende Rechte; 503 wird nicht als Logout interpretiert.
Formulare nutzen lokalen Zustand. Mutationen invalidieren die betroffenen Loader, keinen pauschalen Full-Page-Reload. Routen haben Fehlergrenzen für nicht verfügbare Module und Transportfehler. Produktlokale darstellende Komponenten importieren keinen eigenen Live-API-Client. Die Design Guideline wird verwendet, ohne in diesem Blueprint neue visuelle Tokens festzulegen.
Bevorzugter Frontend-Default sind relative Same-Origin-API-Pfade ohne Dev-/Prod-Origins im Build; damit kann R1 dasselbe Frontend-Image verwenden. R2 darf nachvollziehbar deklarierte öffentliche Build-Parameter unterscheiden und muss den konkreten Prod-Build validieren. Secrets und private VITE-Variablen bleiben in beiden Varianten ausgeschlossen. Keine PWA in der Grundstruktur; bei realem Installationsbedarf gilt A7, einschließlich Test der persönlichen API-Cachegrenze.
B4 – Mindesttests und lokale Befehle
Die folgenden Fälle sind Abnahmebedingungen für die spätere Umsetzung, keine in Phase 3.2 ausgeführten Tests.
| Suite | Verpflichtender Nachweis |
|---|---|
| Imports/Start | Router und App-Factory importierbar ohne DB-/Netzwerkzugriff; Factory mit Testprovidern; OpenAPI generierbar; unbekannte Konfiguration verhindert Start |
| Transaktion | Zwei zusammengehörige Writes plus Audit committen gemeinsam; Fehler beim zweiten Write/Audit hinterlässt keinen ersten Write; Commitfehler ergibt keinen 2xx-Erfolg |
| Datenraum | Nutzer A kann Testobjekt von B weder lesen noch ändern; gefälschte Auswahl/Elternreferenz scheitert; eingeschränkte Runtime-Rolle darf kein DDL |
| Auth/Policy | Keine Session 401, fehlende Capability 403, unsichtbares Objekt 404, unverdrahteter Pflichtadapter 503; Entitlement ersetzt keine Berechtigung |
| API | 422/409/500/503 im vereinbarten Problemformat; unbekannte Inputfelder verweigert; Response enthält keine internen Felder/Rohwerte; 204 ohne Body |
| Migration | Leere DB; Upgrade von voriger Basis; Wiederholung; geänderte/fehlende angewandte Datei; doppelte IDs; Konkurrenz; SQL-/Ledger-Fehler; Dollar-quoted SQL |
| Pool | Saubere Rückgabe nach Exception; begrenzte Erschöpfung; kein fremder Transaktions-/Scopezustand beim nächsten Entleiher |
| Client/State | JSON/204/HTML/Netzfehler/Timeout; keine automatische Write-Wiederholung; Scopewechsel mit verspäteter Antwort und verspätetem 401 |
| Modul/Route | Doppelte IDs/Pfade verweigert; unbekannter Schlüssel; Loaderfehler lokal; fehlende UI-Rechte; Dirty-Form-Blocker auf tatsächlicher Routerversion |
| Browser | Gebauter Stack: SPA-Direktaufruf, API-Fehlerzustand, Testidentitäts-/Scopewechsel; Cookie-/CSRF-Fälle erst mit echtem Auth-Adapter verpflichtend ergänzen |
| Release | In R1 und R2 sperren rote/fehlende Pflicht-Gates und nicht passende Quell-/Build-/Artefaktnachweise das Deployment. R1 prüft identische qualifizierte Artefakte; R2 prüft auch den separaten Prod-Kandidaten vor der Umschaltung. |
DB-Tests laufen gegen PostgreSQL 16 mit eigenem kurzlebigem Compose-Projekt je Run und synthetischen Daten. Keine lokale/private oder laufende Dev-/Prod-DB als Testtarget. Der Wächter verlangt APP_ENV=test, passende Run-ID im DB-Namen, erlaubtes CI-Netz und erfolgreichen Abgleich von current_database() vor jeder Schemaänderung. Runtime- und Migrationsrolle werden auch im Test getrennt. Cleanup ist garantiert, auch bei Fehlern; keine gemeinsam fest benannte Testdatenbank für parallele Runs.
Fakes werden über create_app(..., providers=...) oder FastAPI-Testoverrides eingebracht, nicht durch Umgebungsflags in den Runtime-Code. Echte DB-Vertragsfälle nutzen keine SQLite-Ersatzdatenbank. Marker integration, migration, negative dienen der Auswahl. Gitea prüft ausgewählte Mindestfallnamen und JUnit-Ergebnisse: null gesammelte Tests oder ein Skip eines erforderlichen Falls ist ein Fehler. Keine pauschale Coverage-Prozentzahl als Ersatz für die obigen Fälle.
Im später erzeugten Repository sind diese Einstiegspunkte einzurichten:
| Ort | Befehl | Zweck |
|---|---|---|
backend |
python -m pytest tests/unit tests/api -ra |
schnelle Tests mit sicheren Testprovidern |
backend, isolierter DB-Stack |
python -m pytest tests/integration tests/migrations -ra --junitxml=results.xml |
Runtime-Rolle, Transaktionen, Migrationsvertrag |
frontend |
npm ci und npm run build |
gesperrte Installation und Produktionsbuild |
frontend |
npm run test mit vitest run |
Client-/Komponenten-/Routingtests, kein Watchmodus |
| CI-Testcontainer | npx --no-install playwright test |
bereits gelockte Playwright-Installation, isolierter Image-Stack |
backend, expliziter Migrationsprozess |
python -m app.db.migrate --directory migrations |
im Deploy vor Umschaltung, niemals als Test gegen Kundendaten |
Die Browser-Testwerkzeuge liegen in der gelockten Frontend-Toolchain; die Konfiguration verweist auf tests/e2e im Repository. Ein Testimage darf Werkzeuge ergänzen, aber keine Runtime-Pins ersetzen. Browser-/HTTP-Image-Tests sprechen das unveränderte gebaute Runtime-Image an; Quellmounts dürfen dessen Anwendung nicht überlagern.
B5 – Gitea-Ablauf und Build-Nachvollziehbarkeit
Verbindlich: develop → Dev → Tests → bewusste Freigabe → main → Prod, erforderliche Release-Gates, menschliche Freigabe und eindeutige Versions-/Artefaktzuordnung. Technische Varianten: R1 „Build once, deploy many“ ist der bevorzugte Default; R2 sind nach ADR-11 weiterhin zulässige kontrollierte, reproduzierbare getrennte Dev-/Prod-Builds. Beides sind noch nicht ausgeführte Verfahrensvorgaben (V/K), keine hier validierten Pipelines.
Die bestehenden Gitea-Prozesse werden entsprechend genutzt. Zwei logische Aufgaben – Dev-Qualifikation und Produktionsfreigabe/-deployment – können in den vorhandenen Workflows abgebildet werden; Dateinamen und Jobaufteilung sind Defaults, keine neue Infrastrukturvorgabe. Nicht vertrauenswürdige PR-Checks erhalten weder Deploy-/Prod-Secrets noch Zugriff auf produktive Docker-Sockets. Deploy-Jobs laufen nur für geschützte eigene Branches auf berechtigten Runnern. Actions werden auf geprüfte Commitstände gepinnt und müssen zur eingesetzten Gitea-/Runner-Version passen. Siehe C, O2.
| Stufe | R1 – bevorzugt: identische Artefakte | R2 – zulässig: separate Builds |
|---|---|---|
| 1 · develop | Quellcommit S/Tree T, Lockfiles und Build-Eingaben festhalten; schnelle Tests und Import-/OpenAPI-Prüfung. | Derselbe Dev-Vertrag; Dev-Build-Rezept und Parameter eindeutig aufzeichnen. |
| 2 · Dev | Backend-/Frontend-Artefakte bauen und identifizieren, explizite Dev-Migration und Dev-Deployment; Read-only-Smoke. | Identifizierte Dev-Artefakte bauen und nach Dev deployen; Migration und Read-only-Smoke wie R1. |
| 3 · Tests | Die gebauten Artefakte im isolierten Stack mit Pflichtsuiten aus B4 und Browserfällen qualifizieren. | Die Dev-Artefakte mit den erforderlichen Suiten qualifizieren. Das Ergebnis gilt für diesen Dev-Build, nicht automatisch für einen späteren Prod-Build. |
| 4 · Bewusste Freigabe | Mensch nimmt den Release-PR nach erfolgreicher Dev-Qualifikation auf geschütztes main an. |
Dieselbe menschliche Freigabe; freigegebener Quellstand und deklarierte Produktions-Build-Eingaben bleiben nachvollziehbar. |
| 5 · Prod-Kandidat / Gate | Qualifizierte Artefakte aus dem passenden vertrauenswürdigen Run übernehmen, Hashes und Quellbeziehung prüfen. Default: S ist in main enthalten und tree(main) == T. |
Aus dem freigegebenen Stand mit gelockten Abhängigkeiten, festgehaltenem Build-Rezept, Toolchain/Basisimages und deklarierten Parametern reproduzierbar separat bauen. Den konkreten Prod-Kandidaten im isolierten Stack vor Deployment durch seine Pflicht-Gates führen; eigener Validierungsrun und eigene Artefaktkennungen. |
| 6 · Prod | Erst bei vollständigem Nachweis: Deployment serialisieren, Schema-/Backupbedingung prüfen, explizite Prod-Migration, qualifizierte Artefakte umschalten. | Erst nach erfolgreichen Gates für den separaten Prod-Build dieselben Betriebsbedingungen prüfen und genau diesen Prod-Kandidaten umschalten. Keine ungetestete zusätzliche Änderung oder weiterer ungeprüfter Build. |
| 7 · Smoke | Read-only-Smoke und eingesetzte Build-/Artefaktkennung protokollieren. | Identische Nachweispflicht für die tatsächlich eingesetzte Prod-Version. |
Ein rotes, fehlendes oder übersprungenes Pflicht-Gate stoppt beide Varianten. main enthält den bewusst freigegebenen Stand; eine Abweichung vom Dev-Tree darf nicht unter dessen grünem Ergebnis als mitgetestet gelten. Sie benötigt die zugehörigen Tests und Nachweise für den tatsächlich freigegebenen Produktionsquellstand. Änderungen außerhalb dieser menschlich freigegebenen Eingaben sind kein bereits genehmigter Release. Ein weiterer menschlicher Freigabezyklus nur wegen der Wahl von R2 wird nicht eingeführt.
Der Produktionstest läuft isoliert gegen den konkreten Prod-Kandidaten, niemals mit synthetischen Mutationen in einer Kundendatenbank. Weder Reproduzierbarkeit noch ein Health-Smoke nach Deployment ersetzen dieses Gate. Runtime-/Build-Eingaben werden kontrolliert aufgelöst; spontane Paketupdates oder nicht dokumentierte Build-Änderungen sind in keiner Variante erlaubt. Ein kontrollierter Prod-Build in R2 ist ausdrücklich zulässig.
Releasenachweis für beide Varianten: getesteter Quell-/Buildstand, freigegebener main-Stand und tatsächlich deployte Artefakte werden verknüpft. Das nachstehende Manifest ist das bevorzugte technische Format; gleichwertige vorhandene Gitea-Nachweise dürfen es abbilden. Verbindlich ist die vollständige Zuordnung, nicht ein bestimmter JSON-Feldname oder zusätzlicher Dienst.
product_id, build_variant (R1/R2), approved_main_commit,
dev_source_commit/tree, dev_build_id, dev_qualification_run_id,
prod_source_commit/tree, prod_build_id, prod_validation_run_id,
backend/frontend_artifact_ids und Hashes/Digests je Build,
Lockfilehashes, Build-Rezept/Toolchain/Basisimages und öffentliche Build-Parameter,
migrations_digest, expected_schema_head,
gate_results je qualifiziertem Build mit Ausführungs-/Skipnachweisen,
deployed_build_id und tatsächlich eingesetzte Artefakthashes,
qualified_rollback_images
In R1 dürfen Dev- und Prod-Build-/Validierungsreferenzen auf denselben qualifizierten Build verweisen. In R2 sind die getrennten Builds und ihre Ergebnisse explizit zugeordnet; unterschiedliche Hashes sind kein Fehler, wenn gerade das eingesetzte Prod-Artefakt qualifiziert ist. Merge-Commits werden über Commit und Source-Tree den Freigaben zugeordnet. Eine inzwischen weitergelaufene Dev-Instanz ersetzt keinen dieser Nachweise.
Production vertraut den Nachweisen der passenden geschützten Workflow-Runs, nicht einem beliebig hochgeladenen JSON oder bewegbaren latest-Tag. Artefakte bleiben mindestens über das vereinbarte Rollbackfenster nachvollziehbar verfügbar. Archive mit SHA-256 und eine bereits vorhandene OCI-Registry mit Digestbindung sind Transportvarianten; keine neue CI/CD-Infrastruktur wird verlangt.
Gitea environment: production zählt nicht als manuelle Freigabe. Workflowübergreifende Reihenfolge und Deploymentserialisierung werden ausdrücklich hergestellt. Ein produkt-/umgebungsspezifischer Hostlock ist ein technischer Default bei Jobs auf demselben Deploy-Host, keine Pflicht zu genau diesem Mechanismus. Fehler geben die gewählte Sperre und temporäre Teststacks zuverlässig frei.
Rollback verwendet ein auf dem aktuellen Schema qualifiziertes voriges Artefaktpaar. Migrationen laufen nicht automatisch rückwärts. Ohne erforderliche Kompatibilität stoppt das Release vor der Migration; nach unerwarteten Fehlern gelten kontrollierter Forward-Fix oder vorbereiteter Restore. Die Backup-/Recoverybedingungen des Produktprofils bleiben für beide Build-Varianten unverändert.
B6 – Erweiterung und Fertigstellung
Ein neues Fachmodul ergänzt Router/Schemas, Anwendungsservice und scoped Repository, registriert sich im Backend-Bootstrap und gegebenenfalls in der Frontend-Modulliste, bringt seine Migration und Negativtests mit und ändert keine fremden Router. Ein neuer externer Adapter wird nur im Composition Root eingebunden. Wiederverwendbare Komponenten erhalten einen Testvertrag; eine Library wird erst bei zwei tatsächlichen Abnehmern extrahiert.
Nicht übernehmen: Clientheader als Identität, erste Profil-/Club-ID als Fallback, Probe als neue Schutzvorgabe, dynamisch importierte Clientmodule, Commit nach Response, versteckte zweite DB-Verbindung, Migration beim Import, Erfolgsledger nach separatem SQL-Prozess, pauschales catch → null, persönliche API-Caches, ungeplant neu aufgelöste Pakete im Release, ungeprüfter Prod-Neubuild, Tests mit Kundendaten oder Anbieter-Schlüsseln.
Abnahmebedingungen für eine künftige Foundation-Implementierung sind: Struktur und Verträge umgesetzt, Pflichtfälle der tatsächlich registrierten Funktionen nachweislich bestanden, Lockfiles/OpenAPI vorhanden und wirksame Release-Sperren belegt. Diese Bedingungen sind hier Vorgaben, kein Bericht bereits bestandener Tests. Auch ihre spätere Erfüllung ersetzt keine produktbezogene Produktionsreifeprüfung. Fehlende Spezialadapter bleiben sichtbar geschlossen; sie werden nicht durch Fakes produktionsreif erklärt. Der Implementierungsbericht nennt Commit, Testbefehle/Umgebung, Ergebnisse und verbleibende Produktadapter knapp. Kein zusätzlicher ADR-Zyklus ist dafür erforderlich.
Vorhandene Vorbilder nach Mechanismus: Mitai: Registry/Resolver, Prompt-/Workflow-Laufzeit bei echtem KI-Bedarf, gemeinsamer Cursor/Savepoints. Shinkan: Sichten/Zugriff, Security-Regressionen, Navigation. Kanshō: Maskierung und Egress-Gate sowie getrennte Testdaten. Kairo: einzelne Service-/Konfigurations-/Maschinenzugriffsbausteine als ergänzende Kandidaten. Kein Produkt wird vollständig kopiert; die Zieltransaktion ist die in A/B beschriebene gezielte Referenzlösung.