feat: complete maintenance tracking backend

Service/Controller/Module:
- scheduleMaintenanceAsync: schedule work
- recordMaintenanceCost: log expenses
- getUpcomingMaintenance: due items
- getVehicleMaintenanceStats: cost aggregation

Endpoints:
- POST /maintenance/schedules
- POST /maintenance/costs
- PATCH /maintenance/schedules/:id
- GET /maintenance/upcoming/:vehicleId
- GET /maintenance/history/:vehicleId
- GET /maintenance/stats/:vehicleId

Migration: idempotent maintenance tables creation

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

apps/edr-freight-api/src/app.module.ts

@@ -70,6 +70,7 @@ import { OverviewModule } from './modules/overview/overview.module';
 import { VehiclesModule } from './modules/vehicles/vehicles.module';
 import { DriversModule } from './modules/drivers/drivers.module';
 import { FuelModule } from './modules/fuel/fuel.module';
+import { MaintenanceModule } from './modules/maintenance/maintenance.module';
 import { FirstMileModule } from './modules/first-mile/first-mile.module';
 import { LastMileModule } from './modules/last-mile/last-mile.module';
 import { InterchangeDocumentsModule } from './modules/interchange-documents/interchange-documents.module';
@@ -135,6 +136,7 @@ import { ImportOperationsModule } from './modules/import-operations/import-opera
     VehiclesModule,
     DriversModule,
     FuelModule,
+    MaintenanceModule,
     FirstMileModule,
     LastMileModule,
     InterchangeDocumentsModule,

apps/edr-freight-api/src/migrations/1850000000000-CreateMaintenanceTables.ts

@@ -0,0 +1,82 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class CreateMaintenanceTables1850000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    // Create maintenance_schedules table
+    const scheduleTableExists = await queryRunner.query(`
+      SELECT EXISTS(
+        SELECT 1 FROM information_schema.tables
+        WHERE table_schema = 'freight' AND table_name = 'maintenance_schedules'
+      )
+    `);
+
+    if (!scheduleTableExists[0].exists) {
+      await queryRunner.query(`
+        CREATE TABLE "freight"."maintenance_schedules" (
+          "id" uuid NOT NULL DEFAULT gen_random_uuid(),
+          "vehicle_id" uuid NOT NULL,
+          "maintenance_type" varchar NOT NULL,
+          "description" varchar NOT NULL,
+          "scheduled_date" timestamptz NOT NULL,
+          "completed_date" timestamptz,
+          "estimated_cost" numeric(14,2),
+          "actual_cost" numeric(14,2),
+          "status" varchar NOT NULL DEFAULT 'SCHEDULED',
+          "odometer_reading" numeric,
+          "service_provider" varchar,
+          "notes" text,
+          "next_due_km" numeric,
+          "next_due_date" timestamptz,
+          "created_at" timestamptz NOT NULL DEFAULT now(),
+          "updated_at" timestamptz NOT NULL DEFAULT now(),
+          "deleted_at" timestamptz,
+          PRIMARY KEY ("id")
+        )
+      `);
+
+      await queryRunner.query(
+        `CREATE INDEX "idx_maintenance_schedules_vehicle_date" ON "freight"."maintenance_schedules" ("vehicle_id", "scheduled_date")`
+      );
+    }
+
+    // Create maintenance_costs table
+    const costsTableExists = await queryRunner.query(`
+      SELECT EXISTS(
+        SELECT 1 FROM information_schema.tables
+        WHERE table_schema = 'freight' AND table_name = 'maintenance_costs'
+      )
+    `);
+
+    if (!costsTableExists[0].exists) {
+      await queryRunner.query(`
+        CREATE TABLE "freight"."maintenance_costs" (
+          "id" uuid NOT NULL DEFAULT gen_random_uuid(),
+          "vehicle_id" uuid NOT NULL,
+          "maintenance_schedule_id" uuid,
+          "incurred_date" timestamptz NOT NULL,
+          "cost_amount" numeric(14,2) NOT NULL,
+          "cost_type" varchar NOT NULL,
+          "description" varchar NOT NULL,
+          "service_provider" varchar,
+          "invoice_number" varchar,
+          "notes" text,
+          "created_at" timestamptz NOT NULL DEFAULT now(),
+          "updated_at" timestamptz NOT NULL DEFAULT now(),
+          "deleted_at" timestamptz,
+          PRIMARY KEY ("id"),
+          CONSTRAINT "fk_maintenance_schedule" FOREIGN KEY ("maintenance_schedule_id")
+            REFERENCES "freight"."maintenance_schedules" ("id") ON DELETE SET NULL
+        )
+      `);
+
+      await queryRunner.query(
+        `CREATE INDEX "idx_maintenance_costs_vehicle_date" ON "freight"."maintenance_costs" ("vehicle_id", "incurred_date")`
+      );
+    }
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS "freight"."maintenance_costs"`);
+    await queryRunner.query(`DROP TABLE IF EXISTS "freight"."maintenance_schedules"`);
+  }
+}

apps/edr-freight-api/src/modules/maintenance/maintenance.controller.ts

@@ -0,0 +1,46 @@
+import { Controller, Post, Get, Patch, Body, Param } from '@nestjs/common';
+import { ApiTags, ApiOperation } from '@nestjs/swagger';
+import { MaintenanceService } from './maintenance.service';
+import { CreateMaintenanceScheduleDto, CreateMaintenanceCostDto, UpdateMaintenanceScheduleDto } from './dto/create-maintenance.dto';
+
+@ApiTags('Maintenance Management')
+@Controller('maintenance')
+export class MaintenanceController {
+  constructor(private readonly maintenanceService: MaintenanceService) {}
+
+  @Post('schedules')
+  @ApiOperation({ summary: 'Schedule maintenance' })
+  async scheduleMaintenanceAsync(@Body() dto: CreateMaintenanceScheduleDto) {
+    return this.maintenanceService.scheduleMaintenanceAsync(dto);
+  }
+
+  @Post('costs')
+  @ApiOperation({ summary: 'Record maintenance cost' })
+  async recordCost(@Body() dto: CreateMaintenanceCostDto) {
+    return this.maintenanceService.recordMaintenanceCost(dto);
+  }
+
+  @Patch('schedules/:id')
+  @ApiOperation({ summary: 'Update maintenance schedule' })
+  async updateSchedule(@Param('id') id: string, @Body() dto: UpdateMaintenanceScheduleDto) {
+    return this.maintenanceService.updateMaintenanceSchedule(id, dto);
+  }
+
+  @Get('upcoming/:vehicleId')
+  @ApiOperation({ summary: 'Get upcoming maintenance' })
+  async getUpcoming(@Param('vehicleId') vehicleId: string) {
+    return this.maintenanceService.getUpcomingMaintenance(vehicleId);
+  }
+
+  @Get('history/:vehicleId')
+  @ApiOperation({ summary: 'Get maintenance history' })
+  async getHistory(@Param('vehicleId') vehicleId: string) {
+    return this.maintenanceService.getMaintenanceHistory(vehicleId);
+  }
+
+  @Get('stats/:vehicleId')
+  @ApiOperation({ summary: 'Get maintenance statistics' })
+  async getStats(@Param('vehicleId') vehicleId: string) {
+    return this.maintenanceService.getVehicleMaintenanceStats(vehicleId);
+  }
+}

apps/edr-freight-api/src/modules/maintenance/maintenance.module.ts

@@ -0,0 +1,15 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { MaintenanceSchedule } from './entities/maintenance-schedule.entity';
+import { MaintenanceCost } from './entities/maintenance-cost.entity';
+import { MaintenanceService } from './maintenance.service';
+import { MaintenanceRepository } from './maintenance.repository';
+import { MaintenanceController } from './maintenance.controller';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([MaintenanceSchedule, MaintenanceCost])],
+  providers: [MaintenanceService, MaintenanceRepository],
+  controllers: [MaintenanceController],
+  exports: [MaintenanceService],
+})
+export class MaintenanceModule {}

apps/edr-freight-api/src/modules/maintenance/maintenance.service.ts

@@ -0,0 +1,82 @@
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { MaintenanceRepository } from './maintenance.repository';
+import { MaintenanceSchedule } from './entities/maintenance-schedule.entity';
+import { MaintenanceCost } from './entities/maintenance-cost.entity';
+import { CreateMaintenanceScheduleDto, CreateMaintenanceCostDto, UpdateMaintenanceScheduleDto } from './dto/create-maintenance.dto';
+
+@Injectable()
+export class MaintenanceService {
+  constructor(
+    private readonly maintenanceRepository: MaintenanceRepository,
+    @InjectRepository(MaintenanceSchedule)
+    private readonly scheduleRepository: Repository<MaintenanceSchedule>,
+    @InjectRepository(MaintenanceCost)
+    private readonly costRepository: Repository<MaintenanceCost>,
+  ) {}
+
+  async scheduleMaintenanceAsync(dto: CreateMaintenanceScheduleDto): Promise<MaintenanceSchedule> {
+    const schedule = this.scheduleRepository.create({
+      ...dto,
+      scheduledDate: new Date(dto.scheduledDate),
+      nextDueDate: dto.nextDueDate ? new Date(dto.nextDueDate) : undefined,
+    });
+    return this.scheduleRepository.save(schedule);
+  }
+
+  async recordMaintenanceCost(dto: CreateMaintenanceCostDto): Promise<MaintenanceCost> {
+    const cost = this.costRepository.create({
+      ...dto,
+      incurredDate: new Date(dto.incurredDate),
+    });
+    return this.costRepository.save(cost);
+  }
+
+  async updateMaintenanceSchedule(
+    id: string,
+    dto: UpdateMaintenanceScheduleDto,
+  ): Promise<MaintenanceSchedule> {
+    await this.scheduleRepository.update(id, {
+      ...dto,
+      completedDate: dto.completedDate ? new Date(dto.completedDate) : undefined,
+    });
+    const updated = await this.scheduleRepository.findOneBy({ id });
+    return updated!;
+  }
+
+  async getUpcomingMaintenance(vehicleId: string) {
+    return this.maintenanceRepository.getUpcomingMaintenance(vehicleId);
+  }
+
+  async getMaintenanceHistory(vehicleId: string, monthsBack: number = 12) {
+    const endDate = new Date();
+    const startDate = new Date(endDate.getFullYear(), endDate.getMonth() - monthsBack, 1);
+    return this.maintenanceRepository.getMaintenanceCosts(vehicleId, startDate, endDate);
+  }
+
+  async getVehicleMaintenanceStats(vehicleId: string, monthsBack: number = 12) {
+    const endDate = new Date();
+    const startDate = new Date(endDate.getFullYear(), endDate.getMonth() - monthsBack, 1);
+
+    const costs = await this.maintenanceRepository.getMaintenanceCosts(vehicleId, startDate, endDate);
+    const totalCost = costs.reduce((sum: number, c: MaintenanceCost) => sum + Number(c.costAmount), 0);
+
+    return {
+      vehicleId,
+      totalCost,
+      numberOfMaintenanceItems: costs.length,
+      averageCostPerMaintenance: costs.length > 0 ? totalCost / costs.length : 0,
+      costByType: this.groupCostsByType(costs),
+    };
+  }
+
+  private groupCostsByType(costs: MaintenanceCost[]) {
+    const grouped: Record<string, number> = {};
+    costs.forEach((c) => {
+      if (!grouped[c.costType]) grouped[c.costType] = 0;
+      grouped[c.costType] += Number(c.costAmount);
+    });
+    return grouped;
+  }
+}