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>
118 lines
4.1 KiB
Markdown
118 lines
4.1 KiB
Markdown
# 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](file:///c:/Dev/mitai-jinkendo/.claude/docs/technical/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
|
||
|
||
1. **Manuelle psql-Schritte in Prod** ohne nummerierte Migration im Repo.
|
||
2. **Schema-Drift nur in schema.sql** ohne Migration — Init vs. Upgrade verwechseln.
|
||
3. **Auto-Rollback bei fehlgeschlagener Migration** — fail-fast, manuell fixen.
|
||
4. **Port-Änderung ohne Infra-Update** — bricht Fritz!Box/NAS-Routing.
|
||
|
||
---
|
||
|
||
## Verwandte Dokumentation
|
||
|
||
- [DATABASE_SCHEMA.md](../../../.claude/docs/technical/DATABASE_SCHEMA.md)
|
||
- Mitai: [MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md](file:///c:/Dev/mitai-jinkendo/.claude/docs/technical/MIGRATION_DEPLOY_DESIGN_PRINCIPLES.md)
|
||
- [DESIGN_PRINCIPLES_INDEX.md](./DESIGN_PRINCIPLES_INDEX.md)
|