Entwickler Onboarding

Entwickler-Onboarding

Diese Anleitung führt von einem frischen Checkout bis zur ersten getesteten Änderung.

Voraussetzungen

• Git
• Docker Engine
• Docker Compose v2
• freie Ports 3000, 3001, 8000 und 8001
• optional Node.js 22 für Tests direkt auf dem Host

1. Repository vorbereiten

git clone https://github.com/FrissBrot/hocX.git
cd hocX
cp .env.example .env

Die Werte aus .env.example sind nur für lokale Entwicklung gedacht. Echte Tokens oder Produktionspasswörter dürfen nie in .env.example, Commits oder Testausgaben gelangen.

2. Entwicklungsumgebung starten

./scripts/dev.sh

Der Wrapper baut die Images, startet PostgreSQL, Redis, beide Backends und beide Frontends, führt Migrationen aus und prüft die Dienste.

Dienst	Adresse
hocX	http://localhost:3000
API/OpenAPI	http://localhost:8000/docs
Abgabebox	http://localhost:3001
Abgabebox-API	http://localhost:8001/docs

Optionale Profile:

./scripts/dev.sh up --profile scan
./scripts/dev.sh up --profile docs
./scripts/dev.sh up --profile edge

3. Lokale Konten

E-Mail	Passwort	Rolle
admin@hocx.local	ChangeMe123!	Admin
writer@hocx.local	ChangeMe123!	Bearbeitung
reader@hocx.local	ChangeMe123!	Lesen

Diese Konten dürfen ausschliesslich lokal und in E2E verwendet werden.

4. Erste Änderung

1. Betroffenen Code und vorhandene Tests lesen.
2. Änderung möglichst klein und tenant-sicher implementieren.
3. Einen Regressionstest ergänzen.
4. Den direkt betroffenen Testbereich ausführen.
5. Vor dem Pull Request die gesamte relevante Suite ausführen.

./scripts/test.sh backend
./scripts/test.sh frontend
./scripts/test.sh e2e

Details stehen im Testprozess.

5. Datenbankmigrationen

docker compose -p hocx-dev exec backend alembic current
docker compose -p hocx-dev exec backend alembic upgrade head

Schemaänderungen erfolgen ausschliesslich über Alembic. Regeln und Beispiele stehen unter Datenbank und Migrationen.

6. Logs und Status

docker compose -p hocx-dev ps
docker compose -p hocx-dev logs --tail=100 backend frontend
docker compose -p hocx-dev logs -f backend

Weitere Diagnosewege stehen unter Debugging und Observability.

7. Umgebung beenden

./scripts/dev.sh stop
./scripts/dev.sh down

stop hält Container an. down entfernt Container und Netzwerk, lässt persistente Entwicklungsdaten aber gemäss Compose-Konfiguration bestehen.

Häufige Probleme

• .env fehlt: cp .env.example .env ausführen.
• Port bereits belegt: den fremden Prozess/Stack beenden; keine E2E-Ports verwenden.
• Migration fehlt: alembic current und alembic upgrade head prüfen.
• Frontend-Test findet Container nicht: zuerst ./scripts/dev.sh starten.
• E2E ist verschmutzt: ./scripts/e2e.sh down, danach erneut all ausführen.
• Login-Schleife/Backend nicht erreichbar: Frontend- und Backend-Logs gemeinsam prüfen.

Definition of Done

• Verhalten und Sicherheitsgrenzen sind verstanden.
• Neue Logik ist getestet.
• Tenant- und Rollenprüfung wurde berücksichtigt.
• Migrationen funktionieren gegen eine frische Datenbank.
• Relevante Dokumentation wurde aktualisiert.
• Keine Secrets, Debug-Ausgaben oder generierten Artefakte wurden eingecheckt.