chore: archive outdated architecture and roadmap documents, normalize documentation structure and metadata
This commit is contained in:
@@ -0,0 +1,100 @@
|
||||
---
|
||||
type: Reference
|
||||
status: ARCHIVED
|
||||
owner: Lead Architect
|
||||
last_update: 2026-03-15
|
||||
---
|
||||
# Repository-Architektur (MP-22)
|
||||
|
||||
**WARNUNG (Januar 2026): Dieses Dokument ist veraltet.** Die hier beschriebene "Soll"-Struktur wurde teilweise umgesetzt, aber wichtige strategische Änderungen sind in den Statusberichten vom Januar 2026 dokumentiert. Dieses Dokument dient nur noch als historischer Referenzpunkt.
|
||||
|
||||
**Aktuelle Informationen finden Sie in:**
|
||||
* `docs/90_Reports/Backend_Status_Report_01-2026.md`
|
||||
* `docs/90_Reports/Frontend_Status_Report_01-2026.md`
|
||||
* Den ADRs in `docs/01_Architecture/adr/`
|
||||
|
||||
---
|
||||
|
||||
## Zusammenfassung der wichtigsten Änderungen (Januar 2026)
|
||||
|
||||
* **Backend:** Ein Konflikt zwischen Spring Boot und Spring Cloud wurde durch einen Downgrade von Spring Cloud gelöst.
|
||||
* **Frontend:** Die Persistenz-Strategie wurde von Room auf **SQLDelight** umgestellt, um echte Cross-Platform-Fähigkeit (insbesondere für Web/Wasm) zu ermöglichen.
|
||||
* **Modul-Struktur:** Das `core:core-utils`-Modul wurde bereinigt, um eine strikte Trennung zwischen KMP-kompatiblem Code und JVM-spezifischem Code zu gewährleisten. JVM-spezifischer Code wurde in das neue Modul `:backend:infrastructure:persistence` verschoben.
|
||||
* **Build-System:** Die `libs.versions.toml` wurde stark refaktoriert und nutzt nun Bundles zur Vereinfachung der Gradle-Dateien.
|
||||
|
||||
---
|
||||
|
||||
## Ursprünglicher Inhalt (Veraltet)
|
||||
|
||||
### Zielstruktur (Top-Level)
|
||||
|
||||
backend/ Gateway, Discovery (optional), Services
|
||||
gateway Spring Cloud Gateway
|
||||
discovery
|
||||
services
|
||||
frontend/ KMP Frontend
|
||||
shells Ausführbare Apps (Assembler)
|
||||
features Vertical Slices (kein Feature→Feature)
|
||||
core Shared Foundation (Design-System, Network, Local-DB, Auth, Domain)
|
||||
design-system
|
||||
domain
|
||||
network
|
||||
local-db
|
||||
navigation
|
||||
docker/ Docker Compose, .env.example, Monitoring-/Core-Konfiguration
|
||||
docs/ Architektur, ADRs, C4-Modelle, Guides
|
||||
adr Architecture Decision Records (ADRs)
|
||||
c4 C4-Diagramme (PlantUML Quellen)
|
||||
|
||||
### Ist → Soll Mapping (erste Tranche)
|
||||
|
||||
- Frontend
|
||||
- clients/app → frontend/shells/meldestelle-portal (verschieben in Folge-Commit)
|
||||
- clients/shared/common-ui → frontend/core/design-system (verschieben in Folge-Commit)
|
||||
- clients/shared/navigation → frontend/core/navigation (verschieben in Folge-Commit)
|
||||
|
||||
- Backend
|
||||
- infrastructure/gateway → backend/gateway (verschieben in Folge-Commit)
|
||||
- services/* → backend/services/* (verschieben in Folge-Commit)
|
||||
- Discovery (falls genutzt) → backend/discovery
|
||||
|
||||
- Docker
|
||||
- compose.yaml → docker/docker-compose.yml (neu angelegt, Makefile angepasst)
|
||||
- .env Handling → docker/.env.example (neu, als Template)
|
||||
|
||||
### Build/Gradle
|
||||
|
||||
- settings.gradle.kts bleibt vorerst unverändert. Modul-Verschiebungen folgen in einem separaten Schritt mit angepassten include-Pfaden.
|
||||
- Version Catalog (gradle/libs.versions.toml) bleibt die einzige Quelle der Versionswahrheit.
|
||||
|
||||
### Richtlinien (Kurzfassung)
|
||||
|
||||
- Features kommunizieren ausschließlich über Routen (Navigation) und Shared-Modelle in frontend/core/domain.
|
||||
- Kein manueller Authorization-Header – nur der DI-verwaltete apiClient aus frontend/core/network (Koin Named Binding).
|
||||
- SQLDelight als Offline-SSoT: Schema/Migrationen zentral versionieren, UI liest stets lokal und synchronisiert im Hintergrund.
|
||||
|
||||
### DI-Policy & Architecture Guards (MP-23)
|
||||
|
||||
- DI-Policy (Frontend)
|
||||
- Http‑Requests erfolgen ausschließlich über den via Koin bereitgestellten `apiClient` (named Binding) aus `:frontend:core:network`.
|
||||
- Manuelles Setzen des `Authorization`‑Headers ist verboten. Token‑Handling wird zentral im `apiClient` konfiguriert (Auth‑Plugin/Interceptor).
|
||||
- Basis‑URL wird plattformspezifisch aufgelöst:
|
||||
- JVM/Desktop: Env `API_BASE_URL` (Fallback `http://localhost:8081`).
|
||||
- Web/JS: `globalThis.API_BASE_URL` (z. B. per `index.html` oder Proxy), sonst `window.location.origin`, Fallback `http://localhost:8081`.
|
||||
|
||||
- Architecture Guards (Frontend‑Scope)
|
||||
- Root‑Task `archGuards` bricht den Build ab, wenn verbotene Muster gefunden werden (manuelle `Authorization`‑Header). Tests sind ausgenommen; Backend ist ausgenommen.
|
||||
- Statische Analyse verfügbar über `detekt` und `ktlintCheck`; Aggregator `staticAnalysis` führt alles zusammen.
|
||||
|
||||
- Hinweise für Features
|
||||
- Features importieren keine anderen Features (Kommunikation über Navigation + Shared‑Domain‑Modelle). Eine explizite Detekt‑Regel folgt.
|
||||
- Netzwerkzugriffe in Features nutzen Koin über die App‑Shell (DI‑Bootstrap). Für schrittweise Migration kann eine Factory den `apiClient` optional beziehen.
|
||||
|
||||
### Nächste Schritte (MP-22 Folgetasks)
|
||||
|
||||
1. Physisches Verschieben der Frontend-Module gemäß Mapping und Anpassung von settings.gradle.kts.
|
||||
2. Physisches Verschieben der Backend-Komponenten in backend/* inkl. evtl. Package-Pfade, sofern notwendig.
|
||||
3. Ergänzung von docker-compose.services.yml und docker-compose.clients.yml mit echten Overlays.
|
||||
4. Erstellen der ersten ADRs unter `docs/01_Architecture/adr/` (Koin, SQLDelight, Optimistic Locking, Freshness UI, Core Domain).
|
||||
|
||||
Hinweis: ADRs liegen ab sofort zentral unter `docs/01_Architecture/adr/`. C4-Diagramme liegen unter `docs/01_Architecture/c4/`.
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
type: Roadmap
|
||||
status: ARCHIVED
|
||||
owner: Lead Architect
|
||||
last_update: 2026-03-15
|
||||
---
|
||||
|
||||
# MASTER ROADMAP Q1 2026: "Operation Tracer Bullet"
|
||||
|
||||
**Strategisches Ziel:**
|
||||
Wir validieren die gesamte Architektur-Kette (Frontend -> Gateway -> Service -> DB) anhand des **Ping-Service**. Dieser Service dient als **technischer Blueprint** (Vorlage) für alle kommenden Fach-Services. Er muss "Production Ready" gehärtet sein, bevor wir Fachlichkeit implementieren.
|
||||
|
||||
**Aktueller technischer Stand (07.02.2026):**
|
||||
* Build System: ✅ Grün (Gradle, Kotlin 2.3, Spring Boot 3.5.9, Spring Cloud 2025.0.1).
|
||||
* Code-Basis: ✅ `ping-service` existiert, Delta-Sync implementiert.
|
||||
* Infrastruktur: ✅ Docker Environment stabil (Valkey, Keycloak, Consul, Zipkin).
|
||||
* Frontend: ✅ Web-App & Desktop-App (KMP), Login funktioniert, Sync-Logik vorhanden.
|
||||
* Hardware: ✅ Minisforum MS-R1 eingetroffen.
|
||||
|
||||
---
|
||||
|
||||
## 2. Arbeitsaufträge an die AGENTS (Phasenplan)
|
||||
|
||||
### PHASE 1: Backend Hardening & Infrastructure (ABGESCHLOSSEN)
|
||||
*Ziel: Der Ping-Service läuft sicher, stabil und beobachtbar in der Docker-Umgebung.*
|
||||
|
||||
#### 👷 Agent: Senior Backend Developer
|
||||
* [x] **Security Implementation:** OAuth2 Resource Server & RBAC implementiert.
|
||||
* [x] **Resilience:** CircuitBreaker für `/ping/enhanced` aktiv.
|
||||
* [x] **Observability:** Actuator, Micrometer & Zipkin Tracing aktiv.
|
||||
* [x] **Persistence:** Flyway & Postgres Integration stabil.
|
||||
|
||||
#### 🏗️ Agent: Infrastructure & DevOps
|
||||
|
||||
* [x] **Docker Environment:** `dc-infra`, `dc-backend`, `dc-gui` stabil. Valkey als Redis-Ersatz integriert. _(
|
||||
verifiziert 2026-03-09: KC_COMMAND-Regression + Valkey/Redis Property-Mismatch behoben)_
|
||||
* [x] **Gateway Config:** Routing `/api/ping/**` -> `ping-service` mit CircuitBreaker Fallback konfiguriert.
|
||||
|
||||
---
|
||||
|
||||
### PHASE 2: Frontend Integration (ABGESCHLOSSEN)
|
||||
*Ziel: Das Frontend kann authentifiziert mit dem Backend sprechen.*
|
||||
|
||||
#### 🎨 Agent: KMP Frontend Expert
|
||||
* [x] **HTTP Client Core:** Ktor Client mit Auth & Error Handling.
|
||||
* [x] **Authentication Flow:** OIDC Login Flow (Keycloak) implementiert.
|
||||
* [x] **UI Implementation:** Debug-Screen für Pings vorhanden.
|
||||
* [x] **Sync-Fix:** `PingApiKoinClient.syncPings()` Query-Parameter `lastSyncTimestamp` → `since` korrigiert. _(
|
||||
verifiziert 2026-03-09)_
|
||||
|
||||
---
|
||||
|
||||
### PHASE 3: Offline & Sync (ABGESCHLOSSEN)
|
||||
*Ziel: Datenkonsistenz auch bei Netzwerk-Verlust.*
|
||||
|
||||
#### 🤝 Joint Task Force (Backend & Frontend)
|
||||
* [x] **Sync-Protokoll:** `PingEvent` Contract definiert.
|
||||
* [x] **Sync-Fix (CRITICAL):** Typ-Mismatch behoben! Backend und Frontend nutzen nun konsistent `since: Long`.
|
||||
* [x] **Web-App Sync:** SQLDelight Integration vorbereitet.
|
||||
|
||||
---
|
||||
|
||||
## 3. Definition of Done (für Phase 1 & 2)
|
||||
1. [x] `docker compose up` startet den kompletten Stack fehlerfrei.
|
||||
2. [x] Frontend-User kann sich einloggen (Keycloak).
|
||||
3. [x] Frontend zeigt Daten vom `ping-service` an.
|
||||
4. [x] Beim Abschalten der DB zeigt der Service einen sauberen Fallback (CircuitBreaker offen).
|
||||
5. [x] In Zipkin ist der komplette Request-Trace (Frontend -> Gateway -> Service -> DB) sichtbar.
|
||||
|
||||
## 4. Next Steps (Q1/2026)
|
||||
|
||||
1. **Entries Service:** Beginn der Implementierung des ersten echten Fach-Services ("Nennungen"). ← **NÄCHSTE PRIORITÄT
|
||||
**
|
||||
2. ~~**System Hardening:** Keycloak Production-Config (kein `start-dev`).~~ ✅ _(erledigt 2026-03-09: `.env` KC_COMMAND
|
||||
auf `start --optimized --import-realm` korrigiert)_
|
||||
3. **Reporting / Printing:** (Vorgemerkt)
|
||||
* Anforderung: PDF-Generierung für Startlisten, Ergebnislisten, Dressur-Protokolle (personalisiert).
|
||||
* Architektur-Entscheidung: Dezentraler Microservice (wegen Resource-Bursts).
|
||||
* Technologie-Evaluierung: JasperReports, Thymeleaf + Flying Saucer, etc.
|
||||
4. **Infrastructure Setup (Home-Server):**
|
||||
* Hardware: Minisforum MS-R1 (ARM64, 12 Cores, 10G LAN) ✅ **GELIEFERT (07.02.2026)**.
|
||||
* OS: Debian 12 (Vendor Variant) als Host.
|
||||
* Hypervisor: **Proxmox VE 8.4.10** (`pve.mo-code.at`).
|
||||
* Virtualization Strategy:
|
||||
* `infra-gitea` (LXC Container): Gitea + Actions Runner (Native ARM Builds).
|
||||
* `docker-host-prod` (VM): Debian VM als Docker Host für den Meldestelle-Stack (Isolation, keine Nesting-Probleme).
|
||||
* CI/CD: **Multi-Arch Support** (Native ARM64 Builds + x86_64 via `docker buildx` & QEMU).
|
||||
* Networking: Cloudflare Tunnel (Remote Access).
|
||||
* Local Discovery: DNS/mDNS Strategie für Offline-Szenarien (Main-App als lokaler Anchor).
|
||||
* Backup: Automatisierte Snapshots auf externe USB-SSD.
|
||||
Reference in New Issue
Block a user