edr-platform/apps/edr-freight-api/src/modules/companies/dto/dashboard-summary-response.dto.ts

import { ApiProperty } from '@nestjs/swagger';

export class FreightVolumePointDto {
  @ApiProperty({ example: 'May', description: 'Short month label' })
  month!: string;

  @ApiProperty({ example: 940, description: 'Tonnage shipped in the month' })
  tonnes!: number;
}

export class FreightVolumeDto {
  @ApiProperty({ example: 4180, description: 'Total tonnage shipped year-to-date' })
  totalTonnes!: number;

  @ApiProperty({ example: 1240000, description: 'Total committed freight value year-to-date' })
  totalValue!: number;

  @ApiProperty({ example: 'ETB' })
  currency!: string;

  @ApiProperty({ example: 16, description: 'Tonnage change vs same period last year, in percent' })
  ytdChangePct!: number;

  @ApiProperty({ type: [FreightVolumePointDto], description: 'Monthly tonnage series (oldest first, last 6 months)' })
  monthly!: FreightVolumePointDto[];
}

/**
 * KPIs for the portal dashboard (MyPortalPage), aggregated from the current
 * user's company bookings. All figures are scoped to that company.
 *
 * Note: every metric here derives from the bookings table — there is no
 * separate "non-booking" data source for delivered/spend/volume. On-time
 * delivery rate is replaced by completion rate: no ETA / promised-delivery
 * column exists in the schema, so on-time cannot be computed, whereas
 * completion rate (delivered ÷ committed) can.
 */
export class DashboardSummaryResponseDto {
  @ApiProperty({ example: 12, description: 'Bookings delivered/completed year-to-date' })
  deliveredCount!: number;

  @ApiProperty({
    example: 92,
    description: 'Share of committed bookings that have been delivered/completed (YTD), in percent',
  })
  completionRate!: number;

  @ApiProperty({ example: 1240000, description: 'Total paid spend year-to-date' })
  spendYtd!: number;

  @ApiProperty({ example: 'ETB' })
  spendCurrency!: string;

  @ApiProperty({ example: 16, description: 'Spend change vs same period last year, in percent' })
  spendYtdChangePct!: number;

  @ApiProperty({ type: FreightVolumeDto })
  freightVolume!: FreightVolumeDto;
}