truck_track Development Guidelines

Auto-generated from all feature plans. Last updated: 2025-12-23

Active Technologies

• Java 17 (backend), TypeScript 5.9 with Angular 21 (frontend) (006-fleet-analytics)
• PostgreSQL 15+ with PostGIS (existing), Redis 7+ (cache KPIs) (006-fleet-analytics)
• Java 17 (backend), TypeScript 5.x avec Angular 17 (frontend) + Spring Boot 3.2.1, Spring Security, Angular Material 17, NgRx (008-rbac-permissions)
• PostgreSQL 15+ (tables users, user_truck_groups existantes) (008-rbac-permissions)
• TypeScript 5.x avec React Native 0.73+ + React Native, React Navigation 6, React Native Maps, Firebase Cloud Messaging, AsyncStorage, Axios (009-driver-mobile-app)
• AsyncStorage (local), SQLite via WatermelonDB (offline sync), Backend PostgreSQL (via API) (009-driver-mobile-app)
• Java 17 (backend), TypeScript 5.x with Angular 17 (frontend), TypeScript with React Native/Expo (mobile) + Spring Boot 3.2.x, Spring Data JPA, Spring Security, Angular Material, Expo SDK (010-trip-management)
• PostgreSQL 15+ with existing schema, Redis for real-time status caching (010-trip-management)
• YAML (GitHub Actions), Java 17, Node.js 18+, Python 3.x + GitHub Actions, Maven, npm, Docker, Expo CLI (011-cicd-pipelines)
• GitHub Container Registry (ghcr.io) pour les images Docker (011-cicd-pipelines)
• Java 17 (backend), TypeScript 5.9 with Angular 21 (frontend) + Spring Boot 3.2.x, Spring Data Redis, NgRx 21.x with createSelector (012-multi-level-cache)
• Redis 7+ (cache layer), PostgreSQL 15+ (existing primary storage) (012-multi-level-cache)
• TypeScript 5.4 avec Angular 17 + Jasmine, Karma, Angular Testing Utilities (014-frontend-tests)
• N/A (tests uniquement) (014-frontend-tests)
• Java 17 (backend), TypeScript 5.x (mobile Expo, frontend Angular) (015-proof-of-delivery)
• PostgreSQL 15+ (DeliveryProof, ProofPhoto tables), Images en Base64 dans PostgreSQL (015-proof-of-delivery)
• Java 17 (Spring Boot 3.2.x) + Spring Boot Starter, Spring Kafka, SendGrid SDK, Firebase Admin SDK, Thymeleaf, Resilience4j (016-016-email-notifications)
• PostgreSQL 15+ (tables notification_logs, user_notification_preferences, push_tokens, notification_templates, email_recipients) (016-016-email-notifications)
• TypeScript 5.9 with Angular 21.0.6 + Angular Material 21.0.5, NgRx 21.x, RxJS 7.8.2, Leaflet 1.9.4, ngx-charts 23.1.0 (017-modern-ui-redesign)
• N/A (visual styling only, no data model changes) (017-modern-ui-redesign)
• TypeScript 5.9.3 with Angular 21.0.6 + Angular Material 21.0.5, NgRx 21.x, RxJS 7.8.2, SCSS (017-modern-ui-redesign)
• N/A (frontend styling only) (017-modern-ui-redesign)
• TypeScript 5.9.3 with Angular 21.0.6 + Angular 21, NgRx 21.x, RxJS 7.8.2, Angular Material 21.0.5, Leaflet 1.9.4 (019-angular-frontend-cleanup)
• N/A (frontend refactoring, backend inchangé) (019-angular-frontend-cleanup)
• TypeScript 5.9 with Angular 21.0.6 + Tailwind CSS 3.4+, @tailwindcss/forms, Flatpickr, @angular/cdk (overlay, a11y) (020-tailwind-migration)
• N/A (frontend only - no backend changes) (020-tailwind-migration)
• TypeScript 5.9.3 with Angular 21.0.6 + @ngx-translate/core, @ngx-translate/http-loader, Angular Material 21.0.5 (021-frontend-i18n)
• localStorage (language preference persistence) (021-frontend-i18n)

Backend

• Java 17 + Spring Boot 3.2.1, Spring Security, Spring Data JPA
• PostgreSQL 15+ with PostGIS, Redis 7+ (cache/sessions)
• Kafka for async messaging

Frontend

• Angular 21.0.6 with TypeScript 5.9.3
• Angular Material 21.0.5
• NgRx 21.x (state management)
• RxJS 7.8.2
• Leaflet 1.9.4 (maps)

Project Structure

src/
tests/

Commands

npm test && npm run lint

Code Style

• Backend: Java 17 with Spring Boot conventions
• Frontend: TypeScript 5.9 with Angular 21 conventions (signals, block control flow)

Recent Changes

• 021-frontend-i18n: Added TypeScript 5.9.3 with Angular 21.0.6 + @ngx-translate/core, @ngx-translate/http-loader, Angular Material 21.0.5
• 020-tailwind-migration: Added TypeScript 5.9 with Angular 21.0.6 + Tailwind CSS 3.4+, @tailwindcss/forms, Flatpickr, @angular/cdk (overlay, a11y)
• 019-angular-frontend-cleanup: Added TypeScript 5.9.3 with Angular 21.0.6 + Angular 21, NgRx 21.x, RxJS 7.8.2, Angular Material 21.0.5, Leaflet 1.9.4
  • Block control flow (@if/@for) now default
  • Signals for reactive state
  • Esbuild for faster builds
  • Build time improved by 27%

<!-- MANUAL ADDITIONS START -->

Git Workflow (CRITIQUE - OBLIGATOIRE)

INTERDIT:

• Ne JAMAIS commiter directement sur master ou main
• Ne JAMAIS merger une PR soi-même (gh pr merge est INTERDIT)

OBLIGATOIRE: Toujours suivre ce workflow:

1. Créer une feature branch: git checkout -b feature/nom-descriptif
2. Faire les commits sur la feature branch
3. Push la branch: git push -u origin feature/nom-descriptif
4. Créer une Pull Request via gh pr create
5. STOP - Attendre que l'utilisateur merge la PR lui-même
6. Après merge par l'utilisateur: git checkout master && git pull

# ❌ INTERDIT
git commit -m "feat: something"
git push origin master
gh pr merge 123  # JAMAIS merger soi-même!

# ✅ CORRECT
git checkout -b feature/dark-mode
git add -A
git commit -m "feat: implement dark mode"
git push -u origin feature/dark-mode
gh pr create --title "feat: dark mode" --body "..."
# STOP ICI - L'utilisateur mergera la PR

RAPPEL: Cette règle s'applique à TOUTES les modifications, même les plus petites.

---

Backend Java/Spring Conventions (OBLIGATOIRE)

Authentification dans les Controllers

INTERDIT: Ne JAMAIS utiliser @RequestHeader pour récupérer le contexte utilisateur:

// ❌ INTERDIT - Ancienne méthode
@GetMapping("/example")
public ResponseEntity<?> example(
    @RequestHeader("X-User-Id") String userId,
    @RequestHeader("X-Username") String username,
    @RequestHeader("X-User-Role") String role) { ... }

OBLIGATOIRE: Toujours utiliser @AuthenticationPrincipal GatewayUserPrincipal:

// ✅ CORRECT - Nouvelle méthode
import com.trucktrack.common.security.GatewayUserPrincipal;
import org.springframework.security.core.annotation.AuthenticationPrincipal;

@GetMapping("/example")
public ResponseEntity<?> example(
    @AuthenticationPrincipal GatewayUserPrincipal principal) {

    String userId = principal.userId();
    String username = principal.username();
    String role = principal.role();
    String groups = principal.groups(); // comma-separated UUIDs
    // ...
}

Méthodes helper recommandées pour les controllers:

private String getUserId(GatewayUserPrincipal principal) {
    return principal != null ? principal.userId() : "anonymous";
}

private String getUsername(GatewayUserPrincipal principal) {
    return principal != null ? principal.username() : "anonymous";
}

private String getUserRole(GatewayUserPrincipal principal) {
    return principal != null ? principal.role() : "GUEST";
}

Communication inter-services

INTERDIT: Appels directs entre services (bypass du gateway)

OBLIGATOIRE: Passer par l'API Gateway avec SERVICE_ACCOUNT_JWT:

• Configurer gateway.service-token dans application.yml
• Utiliser WebClient avec le token Bearer
• Générer le token via POST /admin/users/service-token

Angular Frontend Conventions (OBLIGATOIRE)

IMPORTANT: Pour tout développement frontend Angular, TOUJOURS consulter et respecter:

• frontend/ANGULAR_CONVENTIONS.md

Résumé des règles clés:

1. Signal Inputs: Utiliser input() au lieu de @Input()

   readonly items = input<Item[]>([]);
   readonly id = input.required<string>();
   

2. Signal Outputs: Utiliser output() au lieu de @Output() + EventEmitter

   readonly clicked = output<void>();
   

3. Modern Control Flow: Utiliser @if, @for, @switch au lieu de *ngIf, *ngFor, *ngSwitch

   @if (condition()) { ... }
   @for (item of items(); track item.id) { ... }
   

4. Injection: Utiliser inject() au lieu de constructor injection

   private readonly http = inject(HttpClient);
   

5. Standalone Components: Tous les composants doivent être standalone: true

6. OnPush: Utiliser ChangeDetectionStrategy.OnPush avec les signals

7. Structure des fichiers de composant - JAMAIS inline:

   • INTERDIT: Mettre le template et les styles inline dans le fichier .ts
   • OBLIGATOIRE: Toujours créer des fichiers séparés pour chaque composant:
     • component-name.component.ts (logique)
     • component-name.component.html (template)
     • component-name.component.scss (styles)

   // ❌ INTERDIT - Template/styles inline
   @Component({
     selector: 'app-example',
     template: `<div>...</div>`,
     styles: [`...`]
   })
   
   // ✅ CORRECT - Fichiers séparés
   @Component({
     selector: 'app-example',
     templateUrl: './example.component.html',
     styleUrls: ['./example.component.scss']
   })
   

8. NgRx Store - TOUJOURS privilégier le store:

   • INTERDIT: Faire des appels API pour récupérer des données déjà présentes dans le store
   • OBLIGATOIRE: Utiliser StoreFacade pour accéder aux données déjà chargées

   // ❌ INTERDIT - Appel API inutile
   ngOnInit() {
     this.authService.getUserProfile().subscribe(user => ...);
   }
   
   // ✅ CORRECT - Données du store
   readonly user = this.facade.currentUser;
   

   • Les données utilisateur sont chargées après login → utiliser facade.currentUser
   • Les trucks sont chargés au démarrage → utiliser facade.trucks
   • Vérifier le store AVANT de créer un nouvel appel API

Trip Management System (Feature 010)

Overview

Complete trip lifecycle management for dispatchers, fleet managers, and drivers.

Trip Status Flow

PENDING → ASSIGNED → IN_PROGRESS → COMPLETED
           ↓              ↓
      CANCELLED ←─────────┘

Backend API Endpoints (location-service)

Admin Endpoints (/admin/trips):

• GET /admin/trips - List trips with filters (status, driver, truck, date range)
• GET /admin/trips/{id} - Get trip details
• POST /admin/trips - Create new trip
• PUT /admin/trips/{id} - Update trip
• POST /admin/trips/{id}/assign - Assign to truck/driver
• POST /admin/trips/{id}/reassign - Reassign to different truck/driver
• POST /admin/trips/{id}/cancel - Cancel trip
• GET /admin/trips/{id}/history - Get status change history
• GET /admin/trips/stats - Get trip counts by status
• GET /admin/trips/analytics - Get detailed KPIs

Driver Endpoints (/location/v1/trips):

• GET /my - Get driver's assigned trips
• GET /{id} - Get trip details
• POST /{id}/start - Start trip (ASSIGNED → IN_PROGRESS)
• POST /{id}/complete - Complete trip (IN_PROGRESS → COMPLETED)

Key Backend Files

• TripService.java - Core business logic
• AdminTripController.java - Admin REST endpoints
• TripController.java - Driver REST endpoints
• Trip.java - Entity with status transitions
• TripAnalyticsDTO.java - KPI calculations

Frontend Components (Angular)

• TripListComponent - List with filters, date range picker, status cards
• TripDetailComponent - View/edit/assign/reassign/cancel
• TripStatsComponent - KPI dashboard widget

Push Notifications

• Trip assignment notification to driver
• Trip cancellation notification to driver
• Trip reassignment notification (to both old and new driver)

Mobile (React Native/Expo)

• TripsScreen - List of assigned trips
• TripDetailScreen - Start/Complete trip actions
• Push notification handling for trip updates

<!-- MANUAL ADDITIONS END -->