Entwicklungs-Übersicht¶

Dieser Guide behandelt alles, was zum Einrichten einer lokalen Entwicklungsumgebung, zum Ausführen der Applikation und zum Beitragen zu TCM365 benötigt wird.

Voraussetzungen¶

Stellen Sie sicher, dass die folgenden Tools installiert sind:

Schnellstart¶

Automatisiertes Setup (empfohlen)¶

Das Projekt beinhaltet automatisierte Setup-Skripte, die Umgebungskonfiguration, Dependency-Installation, Datenbank-Initialisierung und Admin-Benutzer-Erstellung uebernehmen:

./scripts/setup.sh

.\scripts\setup.ps1

Setup-Modi:

Manuelles Setup¶

Falls Sie das manuelle Setup bevorzugen:

# 1. Repository klonen
git clone <repository-url>
cd tcm_dev1

# 2. Datenbankdienste starten (via Docker)
cd infrastructure/docker
docker compose -f docker-compose.local.yml up -d
cd ../..

# 3. Backend Dependencies installieren
cd backend-js
npm ci

# 4. Umgebung konfigurieren
cp .env.example .env
# .env mit Ihren Datenbank-Credentials bearbeiten

# 5. Datenbank-Migrationen ausführen
npm run migration:run

# 6. Admin-Benutzer erstellen
npm run db:seed

# 7. Backend Dev Server starten
npm run start:dev

# 8. In einem neuen Terminal: Frontend installieren und starten
cd frontend
npm ci
npm run dev

Standard-Credentials¶

Nach dem Setup können Sie sich anmelden mit:

Entwicklungsbefehle¶

Backend (NestJS / TypeScript)¶

Alle Backend-Befehle werden aus dem backend-js/ Verzeichnis ausgeführt:

cd backend-js

Frontend (Vue 3 / Vite)¶

Alle Frontend-Befehle werden aus dem frontend/ Verzeichnis ausgeführt:

cd frontend

Der Vite Dev Server leitet API Requests an http://localhost:8000 weiter (konfiguriert in frontend/vite.config.js).

Docker¶

cd infrastructure/docker

Häufige Entwicklungsaufgaben¶

Neuen API Endpoint hinzufügen¶

1. DTOs erstellen oder aktualisieren in backend-js/src/modules/{module}/dto/

   // create-example.dto.ts
   import { IsString, IsNotEmpty } from 'class-validator';
   import { ApiProperty } from '@nestjs/swagger';
   
   export class CreateExampleDto {
     @ApiProperty({ description: 'Name des Beispiels' })
     @IsString()
     @IsNotEmpty()
     name: string;
   }
   

2. Service-Methode hinzufügen in backend-js/src/modules/{module}/{module}.service.ts

3. Controller-Methode hinzufügen in backend-js/src/modules/{module}/{module}.controller.ts

   @Post()
   @UseGuards(JwtAuthGuard, RolesGuard)
   @Roles(UserRole.TENANT_ADMIN)
   @ApiOperation({ summary: 'Neues Beispiel erstellen' })
   @ApiResponse({ status: 201, description: 'Beispiel erstellt' })
   async create(
     @Body() dto: CreateExampleDto,
     @CurrentUser() user: User,
   ) {
     return this.exampleService.create(dto, user);
   }
   

4. Swagger Decorators hinzufügen (@ApiOperation, @ApiResponse, @ApiTags)

5. Tests schreiben in backend-js/src/modules/{module}/{module}.service.spec.ts

Neue Datenbank-Entity hinzufügen¶

1. Entity erstellen in backend-js/src/entities/{entity-name}.entity.ts

   import { Entity, Column } from 'typeorm';
   import { BaseEntity } from '../common/entities/base.entity';
   
   @Entity('examples')
   export class Example extends BaseEntity {
     @Column()
     name: string;
   
     @Column({ type: 'jsonb', nullable: true })
     metadata: Record<string, any>;
   }
   

2. Entity importieren in backend-js/src/database/data-source.ts

3. Migration generieren:

   npm run migration:generate src/database/migrations/AddExample
   

4. Migration ausführen:

   npm run migration:run
   

5. DTOs erstellen im dto/ Ordner des Moduls

Neue Frontend-Seite hinzufügen¶

1. View erstellen in frontend/src/views/{ViewName}.vue

2. Route hinzufügen in frontend/src/router/index.js

   {
     path: '/examples',
     name: 'Examples',
     component: () => import('../views/ExamplesView.vue'),
     meta: { requiresAuth: true }
   }
   

3. Komponenten erstellen in frontend/src/components/{feature}/ falls nötig

4. API Service-Methoden hinzufügen in frontend/src/services/{feature}Service.ts

   import api from './api';
   
   export const exampleService = {
     getAll: () => api.get('/examples'),
     getById: (id: string) => api.get(`/examples/${id}`),
     create: (data: any) => api.post('/examples', data),
   };
   

5. Pinia Store erstellen oder aktualisieren falls nötig in frontend/src/stores/

Path Aliases¶

Die Backend TypeScript Konfiguration definiert Path Aliases für saubere Imports:

// Statt relativer Imports:
import { User } from '../../../entities/user.entity';

// Path Aliases verwenden:
import { User } from '@entities/user.entity';

Diese sind in backend-js/tsconfig.json definiert und werden sowohl vom TypeScript Compiler als auch vom Jest Test Runner aufgeloest.

Debugging¶

Backend Debugging¶

Structured Logs:

Alle Backend Requests erzeugen strukturierte Logs mit Korrelations-IDs:

2026-03-05T14:30:00Z | INFO | SnapshotsController [req=abc123 op=create user=admin] | Snapshot created

SQL Query Logging:

Aktivieren Sie ausfuehrliches SQL Logging durch Setzen in backend-js/.env:

DATABASE_LOGGING=true

Diagnostics Endpoint:

Rufen Sie den Diagnostics Endpoint für den vollständigen Systemstatus auf:

curl http://localhost:8000/api/v1/diagnostics

Dies gibt den Status für Datenbank, Redis, Storage und Azure AD Verbindungen zurück.

Swagger UI:

Nutzen Sie die interaktive Swagger UI unter http://localhost:8000/api/docs zum direkten Testen von Endpoints mit Authentifizierungs-Unterstützung.

Frontend Debugging¶

Vue Devtools:

Installieren Sie die Vue Devtools Browser-Erweiterung für:

• Component Tree Inspektion
• Pinia Store State
• Vue Router State
• Event Tracking

Network Tab:

Überwachen Sie API Aufrufe im Browser Network Tab. Achten Sie auf X-Request-ID Header zur Korrelation mit Backend Logs.

Console Errors:

Prüfen Sie die Browser-Konsole auf JavaScript Fehler und unbehandelte Promise Rejections.

Umgebungsvariablen¶

Wichtige Umgebungsvariablen für die Entwicklung. Die vollständige Liste finden Sie in backend-js/.env.example.

Weitergehende Informationen¶

• Code-Konventionen -- Codierungsstandards und Styleguide
• Testing Guide -- Test-Framework, Patterns und Coverage
• Troubleshooting -- Häufige Probleme und Lösungen
• Contributing Guide -- Wie Sie zu TCM365 beitragen