Lars
6c7c24e887
All checks were successful
Deploy Development / deploy (push) Successful in 48s
Test Suite / pytest-backend (push) Successful in 45s
Test Suite / lint-backend (push) Successful in 1s
Test Suite / build-frontend (push) Successful in 15s
Test Suite / k6 /health Baseline (push) Successful in 34s
Test Suite / playwright-tests (push) Successful in 1m35s
Document cross-app architecture patterns, Mitai alignment, and family entitlement standards. Documentation only; no runtime changes. Co-authored-by: Cursor <cursoragent@cursor.com>
4.1 KiB
4.1 KiB
Migration & Deploy – Designprinzipien (Extraktion)
Status: Analyse / Arbeitspapier
Stand: 2026-07-04
Geltungsbereich: Modul „Migration & Deploy“ — Schema-Evolution, Container-Start
Serie: Designprinzipien für Produktfamilie · Shinkan Dokument 13 von 15
Mitai-Vergleich: MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md (#9)
Kernkomponenten:
| Bereich | Pfade |
|---|---|
| DB-Init | backend/db_init.py |
| Migrationen | backend/migrations/XXX_*.sql |
| Version | backend/version.py (DB_SCHEMA_VERSION, MODULE_VERSIONS) |
| Docker | docker-compose.yml, docker-compose.dev-env.yml |
| Deploy | develop → dev.shinkan · main → shinkan (Pi) |
Modul
Migration & Deploy
Nummerierte SQL-Migrationen beim Container-Start, Tracking in schema_migrations, Git-Branch → Umgebung, fail-fast ohne Auto-Rollback.
Designprinzipien
1. Nummerierte Migrationen XXX_*.sql
| Prinzip | Nur nummerierte Dateien in backend/migrations/; lexikographische Reihenfolge. |
| Begründung | Familien-Standard Mitai/Shinkan; vorhersagbare Anwendung. |
| Quelle | db_init.py; CLAUDE.md |
| Tragfähigkeit | hoch |
| Einschränkung | Manuelle Nummern-Kollisionen vermeiden — Team-Disziplin. |
2. Startup vor App — Migrationen blockieren Start bei Fehler
| Prinzip | db_init.py wartet auf Postgres, wendet fehlende Migrationen an, dann FastAPI. |
| Begründung | Keine App mit veraltetem Schema. |
| Quelle | Container-Entrypoint / startup |
| Tragfähigkeit | hoch |
| Einschränkung | Kein automatisches Rollback — manuelle Recovery. |
3. schema_migrations Tracking-Tabelle
| Prinzip | Jede angewendete Datei wird persistiert; Wiederholung überspringt Bekannte. |
| Begründung | Idempotenz über Deploys hinweg. |
| Quelle | ensure_migration_table, get_applied_migrations |
| Tragfähigkeit | hoch |
| Einschränkung | Geänderte Migration nach Apply — nicht neu ausführen (neue Nummer). |
4. DB_SCHEMA_VERSION als dokumentierter Stand
| Prinzip | version.py führt Schema-Version; MODULE_VERSIONS für Subsysteme. |
| Begründung | Support und Handover wissen erwarteten Stand. |
| Quelle | backend/version.py |
| Tragfähigkeit | hoch |
| Einschränkung | Manuell pflegen bei Migration — Drift möglich. |
5. develop/main → Dev/Prod mit festen Ports
| Prinzip | Dev 3098/8098 · Prod 3003/8003 — nie ändern ohne explizite Freigabe. |
| Begründung | Deploy-Infrastruktur auf Pi/Synology stabil. |
| Quelle | CLAUDE.md Deployment |
| Tragfähigkeit | hoch |
| Einschränkung | — |
6. Neue Spalten nur via Migration
| Prinzip | Kein ad-hoc ALTER in Routern; Coding Rules. |
| Begründung | Reproduzierbare Umgebungen. |
| Quelle | .claude/rules/CODING_RULES.md |
| Tragfähigkeit | hoch |
| Einschränkung | — |
7. IF NOT EXISTS / defensive SQL wo sinnvoll
| Prinzip | Migrationen tolerant bei Wiederanlauf in Dev — aber Tracking verhindert Doppel-Apply. |
| Begründung | Recovery in Entwicklung erleichtern. |
| Quelle | Mitai-Migrations-Muster |
| Tragfähigkeit | mittel |
| Einschränkung | Nicht alles idempotent — komplexe Migrationen brauchen Transaktion. |
Nicht übernehmen
- Manuelle psql-Schritte in Prod ohne nummerierte Migration im Repo.
- Schema-Drift nur in schema.sql ohne Migration — Init vs. Upgrade verwechseln.
- Auto-Rollback bei fehlgeschlagener Migration — fail-fast, manuell fixen.
- Port-Änderung ohne Infra-Update — bricht Fritz!Box/NAS-Routing.