implement rule engine module with dynamic booking evaluation, 7 entities, and Postman endpoints

apps/edr-freight-api/src/modules/rule-engine/services/cargo-types.service.ts

@@ -0,0 +1,102 @@
+import { ConflictException, Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { ILike } from 'typeorm';
+import { CreateCargoTypeDto } from '../dto/create-cargo-type.dto';
+import { UpdateCargoTypeDto } from '../dto/update-cargo-type.dto';
+import { CargoType } from '../entities/cargo-type.entity';
+import {
+  CARGO_TYPES_REPOSITORY,
+  ICargoTypesRepository,
+} from '../interfaces/cargo-types.repository.interface';
+
+@Injectable()
+export class CargoTypesService {
+  constructor(
+    @Inject(CARGO_TYPES_REPOSITORY)
+    private readonly repository: ICargoTypesRepository,
+  ) {}
+
+  /** List cargo types with pagination and optional filtering. */
+  async findAll(filter: {
+    isActive?: boolean;
+    requiresDirectorApproval?: boolean;
+    parentGroupId?: string;
+    search?: string;
+    page?: number;
+    pageSize?: number;
+    sortBy?: string;
+    sortOrder?: 'ASC' | 'DESC';
+  }): Promise<{ data: CargoType[]; meta: { total: number; page: number; pageSize: number; totalPages: number } }> {
+    const page = filter.page ?? 1;
+    const pageSize = filter.pageSize ?? 20;
+    const where: Record<string, unknown> = {};
+    if (filter.isActive !== undefined) where.isActive = filter.isActive;
+    if (filter.requiresDirectorApproval !== undefined) where.requiresDirectorApproval = filter.requiresDirectorApproval;
+    if (filter.parentGroupId !== undefined) where.parentGroupId = filter.parentGroupId;
+    if (filter.search) where.cargoTypeName = ILike(`%${filter.search}%`);
+
+    const [data, total] = await this.repository.findAndCount({
+      where,
+      order: { [filter.sortBy ?? 'displayOrder']: filter.sortOrder ?? 'ASC' },
+      skip: (page - 1) * pageSize,
+      take: pageSize,
+      relations: { parent: true },
+    });
+    return { data, meta: { total, page, pageSize, totalPages: Math.ceil(total / pageSize) } };
+  }
+
+  /** Get a single cargo type by ID. */
+  async findById(id: string): Promise<CargoType> {
+    const entity = await this.repository.findById(id);
+    if (!entity) throw new NotFoundException(`Cargo type ${id} not found`);
+    return entity;
+  }
+
+  /** Get a cargo type by code. */
+  async findByCode(code: string): Promise<CargoType | null> {
+    return this.repository.findByCode(code);
+  }
+
+  /** Create a new cargo type. */
+  async create(dto: CreateCargoTypeDto): Promise<CargoType> {
+    const existing = await this.repository.findByCode(dto.code);
+    if (existing) throw new ConflictException(`Cargo type with code "${dto.code}" already exists`);
+    if (dto.parentGroupId) {
+      const parent = await this.repository.findById(dto.parentGroupId);
+      if (!parent) throw new NotFoundException(`Parent cargo type ${dto.parentGroupId} not found`);
+    }
+    return this.repository.create({
+      code: dto.code,
+      cargoTypeName: dto.cargoTypeName,
+      parentGroupId: dto.parentGroupId ?? null,
+      showFreeTextBox: dto.showFreeTextBox ?? false,
+      requiresDirectorApproval: dto.requiresDirectorApproval ?? false,
+      isActive: dto.isActive ?? true,
+      displayOrder: dto.displayOrder ?? 1,
+    });
+  }
+
+  /** Update an existing cargo type. */
+  async update(id: string, dto: UpdateCargoTypeDto): Promise<CargoType> {
+    await this.findById(id);
+    if (dto.code) {
+      const conflict = await this.repository.findByCode(dto.code);
+      if (conflict && conflict.id !== id) {
+        throw new ConflictException(`Cargo type with code "${dto.code}" already exists`);
+      }
+    }
+    if (dto.parentGroupId) {
+      if (dto.parentGroupId === id) throw new ConflictException('A cargo type cannot be its own parent');
+      const parent = await this.repository.findById(dto.parentGroupId);
+      if (!parent) throw new NotFoundException(`Parent cargo type ${dto.parentGroupId} not found`);
+    }
+    const updated = await this.repository.update(id, dto);
+    if (!updated) throw new NotFoundException(`Cargo type ${id} not found`);
+    return updated;
+  }
+
+  /** Soft-delete a cargo type. */
+  async remove(id: string): Promise<void> {
+    await this.findById(id);
+    await this.repository.softDelete(id);
+  }
+}

apps/edr-freight-api/src/modules/rule-engine/services/container-types.service.ts

@@ -0,0 +1,75 @@
+import { ConflictException, Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { CreateContainerTypeDto } from '../dto/create-container-type.dto';
+import { UpdateContainerTypeDto } from '../dto/update-container-type.dto';
+import { ContainerType } from '../entities/container-type.entity';
+import {
+  CONTAINER_TYPES_REPOSITORY,
+  IContainerTypesRepository,
+} from '../interfaces/container-types.repository.interface';
+
+@Injectable()
+export class ContainerTypesService {
+  constructor(
+    @Inject(CONTAINER_TYPES_REPOSITORY)
+    private readonly repository: IContainerTypesRepository,
+  ) {}
+
+  /** List container types with pagination. */
+  async findAll(filter: {
+    isActive?: boolean;
+    page?: number;
+    pageSize?: number;
+  }): Promise<{ data: ContainerType[]; meta: { total: number; page: number; pageSize: number; totalPages: number } }> {
+    const page = filter.page ?? 1;
+    const pageSize = filter.pageSize ?? 20;
+    const where: Record<string, unknown> = {};
+    if (filter.isActive !== undefined) where.isActive = filter.isActive;
+
+    const [data, total] = await this.repository.findAndCount({
+      where,
+      order: { sizeCode: 'ASC' },
+      skip: (page - 1) * pageSize,
+      take: pageSize,
+    });
+    return { data, meta: { total, page, pageSize, totalPages: Math.ceil(total / pageSize) } };
+  }
+
+  /** Get a single container type by ID. */
+  async findById(id: string): Promise<ContainerType> {
+    const entity = await this.repository.findById(id);
+    if (!entity) throw new NotFoundException(`Container type ${id} not found`);
+    return entity;
+  }
+
+  /** Create a new container type. */
+  async create(dto: CreateContainerTypeDto): Promise<ContainerType> {
+    const existing = await this.repository.findBySizeCode(dto.sizeCode);
+    if (existing) throw new ConflictException(`Container type with sizeCode "${dto.sizeCode}" already exists`);
+    return this.repository.create({
+      sizeCode: dto.sizeCode,
+      description: dto.description ?? null,
+      containersPerWagon: dto.containersPerWagon,
+      isActive: dto.isActive ?? true,
+    });
+  }
+
+  /** Update an existing container type. */
+  async update(id: string, dto: UpdateContainerTypeDto): Promise<ContainerType> {
+    await this.findById(id);
+    if (dto.sizeCode) {
+      const conflict = await this.repository.findBySizeCode(dto.sizeCode);
+      if (conflict && conflict.id !== id) {
+        throw new ConflictException(`Container type with sizeCode "${dto.sizeCode}" already exists`);
+      }
+    }
+    const updated = await this.repository.update(id, dto);
+    if (!updated) throw new NotFoundException(`Container type ${id} not found`);
+    return updated;
+  }
+
+  /** Soft-delete a container type. */
+  async remove(id: string): Promise<void> {
+    await this.findById(id);
+    await this.repository.softDelete(id);
+  }
+}

apps/edr-freight-api/src/modules/rule-engine/services/priority-rules.service.ts

@@ -0,0 +1,73 @@
+import { ConflictException, Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { CreatePriorityRuleDto } from '../dto/create-priority-rule.dto';
+import { UpdatePriorityRuleDto } from '../dto/update-priority-rule.dto';
+import { PriorityRule } from '../entities/priority-rule.entity';
+import {
+  IPriorityRulesRepository,
+  PRIORITY_RULES_REPOSITORY,
+} from '../interfaces/priority-rules.repository.interface';
+
+@Injectable()
+export class PriorityRulesService {
+  constructor(
+    @Inject(PRIORITY_RULES_REPOSITORY)
+    private readonly repository: IPriorityRulesRepository,
+  ) {}
+
+  /** List priority rules with pagination. */
+  async findAll(filter: {
+    isActive?: boolean;
+    page?: number;
+    pageSize?: number;
+  }): Promise<{ data: PriorityRule[]; meta: { total: number; page: number; pageSize: number; totalPages: number } }> {
+    const page = filter.page ?? 1;
+    const pageSize = filter.pageSize ?? 20;
+    const where: Record<string, unknown> = {};
+    if (filter.isActive !== undefined) where.isActive = filter.isActive;
+
+    const [data, total] = await this.repository.findAndCount({
+      where,
+      order: { priorityType: 'ASC' },
+      skip: (page - 1) * pageSize,
+      take: pageSize,
+    });
+    return { data, meta: { total, page, pageSize, totalPages: Math.ceil(total / pageSize) } };
+  }
+
+  /** Get a single priority rule by ID. */
+  async findById(id: string): Promise<PriorityRule> {
+    const entity = await this.repository.findById(id);
+    if (!entity) throw new NotFoundException(`Priority rule ${id} not found`);
+    return entity;
+  }
+
+  /** Create a new priority rule. */
+  async create(dto: CreatePriorityRuleDto): Promise<PriorityRule> {
+    const existing = await this.repository.findAll({ where: { priorityType: dto.priorityType } });
+    if (existing.length > 0) {
+      throw new ConflictException(`Priority rule for type "${dto.priorityType}" already exists`);
+    }
+    return this.repository.create({
+      priorityType: dto.priorityType,
+      ruleName: dto.ruleName,
+      description: dto.description ?? null,
+      activationCondition: dto.activationCondition ?? null,
+      bonusPoints: dto.bonusPoints,
+      isActive: dto.isActive ?? false,
+    });
+  }
+
+  /** Update an existing priority rule. */
+  async update(id: string, dto: UpdatePriorityRuleDto): Promise<PriorityRule> {
+    await this.findById(id);
+    const updated = await this.repository.update(id, dto);
+    if (!updated) throw new NotFoundException(`Priority rule ${id} not found`);
+    return updated;
+  }
+
+  /** Soft-delete a priority rule. */
+  async remove(id: string): Promise<void> {
+    await this.findById(id);
+    await this.repository.softDelete(id);
+  }
+}

apps/edr-freight-api/src/modules/rule-engine/services/service-types.service.ts

@@ -0,0 +1,93 @@
+import { ConflictException, Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { ILike } from 'typeorm';
+import { CreateServiceTypeDto } from '../dto/create-service-type.dto';
+import { UpdateServiceTypeDto } from '../dto/update-service-type.dto';
+import { ServiceType } from '../entities/service-type.entity';
+import {
+  IServiceTypesRepository,
+  SERVICE_TYPES_REPOSITORY,
+} from '../interfaces/service-types.repository.interface';
+
+@Injectable()
+export class ServiceTypesService {
+  constructor(
+    @Inject(SERVICE_TYPES_REPOSITORY)
+    private readonly repository: IServiceTypesRepository,
+  ) {}
+
+  /** List service types with pagination and optional filtering. */
+  async findAll(filter: {
+    isActive?: boolean;
+    canBeBookedAlone?: boolean;
+    search?: string;
+    page?: number;
+    pageSize?: number;
+    sortBy?: string;
+    sortOrder?: 'ASC' | 'DESC';
+  }): Promise<{ data: ServiceType[]; meta: { total: number; page: number; pageSize: number; totalPages: number } }> {
+    const page = filter.page ?? 1;
+    const pageSize = filter.pageSize ?? 20;
+    const where: Record<string, unknown> = {};
+    if (filter.isActive !== undefined) where.isActive = filter.isActive;
+    if (filter.canBeBookedAlone !== undefined) where.canBeBookedAlone = filter.canBeBookedAlone;
+    if (filter.search) where.serviceName = ILike(`%${filter.search}%`);
+
+    const [data, total] = await this.repository.findAndCount({
+      where,
+      order: { [filter.sortBy ?? 'displayOrder']: filter.sortOrder ?? 'ASC' },
+      skip: (page - 1) * pageSize,
+      take: pageSize,
+    });
+    return { data, meta: { total, page, pageSize, totalPages: Math.ceil(total / pageSize) } };
+  }
+
+  /** Get a single service type by ID. */
+  async findById(id: string): Promise<ServiceType> {
+    const entity = await this.repository.findById(id);
+    if (!entity) throw new NotFoundException(`Service type ${id} not found`);
+    return entity;
+  }
+
+  /** Get a service type by code. */
+  async findByCode(code: string): Promise<ServiceType | null> {
+    return this.repository.findByCode(code);
+  }
+
+  /** Create a new service type. */
+  async create(dto: CreateServiceTypeDto): Promise<ServiceType> {
+    const existing = await this.repository.findByCode(dto.code);
+    if (existing) throw new ConflictException(`Service type with code "${dto.code}" already exists`);
+    return this.repository.create({
+      code: dto.code,
+      serviceName: dto.serviceName,
+      description: dto.description ?? null,
+      canBeBookedAlone: dto.canBeBookedAlone ?? true,
+      includesFirstMile: dto.includesFirstMile ?? false,
+      includesLastMile: dto.includesLastMile ?? false,
+      includesCustoms: dto.includesCustoms ?? false,
+      priorityBonusPoints: dto.priorityBonusPoints ?? 0,
+      isActive: dto.isActive ?? true,
+      displayOrder: dto.displayOrder ?? 1,
+    });
+  }
+
+  /** Update an existing service type. */
+  async update(id: string, dto: UpdateServiceTypeDto): Promise<ServiceType> {
+    await this.findById(id);
+    if (dto.code) {
+      const conflict = await this.repository.findByCode(dto.code);
+      if (conflict && conflict.id !== id) {
+        throw new ConflictException(`Service type with code "${dto.code}" already exists`);
+      }
+    }
+    const updated = await this.repository.update(id, dto);
+    if (!updated) throw new NotFoundException(`Service type ${id} not found`);
+    return updated;
+  }
+
+  /** Soft-delete a service type. */
+  async remove(id: string): Promise<void> {
+    await this.findById(id);
+    await this.repository.softDelete(id);
+  }
+}

apps/edr-freight-api/src/modules/rule-engine/services/surcharge-types.service.ts

@@ -0,0 +1,75 @@
+import { ConflictException, Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { CreateSurchargeTypeDto } from '../dto/create-surcharge-type.dto';
+import { UpdateSurchargeTypeDto } from '../dto/update-surcharge-type.dto';
+import { SurchargeType } from '../entities/surcharge-type.entity';
+import {
+  ISurchargeTypesRepository,
+  SURCHARGE_TYPES_REPOSITORY,
+} from '../interfaces/surcharge-types.repository.interface';
+
+@Injectable()
+export class SurchargeTypesService {
+  constructor(
+    @Inject(SURCHARGE_TYPES_REPOSITORY)
+    private readonly repository: ISurchargeTypesRepository,
+  ) {}
+
+  /** List surcharge types with pagination. */
+  async findAll(filter: {
+    isActive?: boolean;
+    page?: number;
+    pageSize?: number;
+  }): Promise<{ data: SurchargeType[]; meta: { total: number; page: number; pageSize: number; totalPages: number } }> {
+    const page = filter.page ?? 1;
+    const pageSize = filter.pageSize ?? 20;
+    const where: Record<string, unknown> = {};
+    if (filter.isActive !== undefined) where.isActive = filter.isActive;
+
+    const [data, total] = await this.repository.findAndCount({
+      where,
+      order: { name: 'ASC' },
+      skip: (page - 1) * pageSize,
+      take: pageSize,
+    });
+    return { data, meta: { total, page, pageSize, totalPages: Math.ceil(total / pageSize) } };
+  }
+
+  /** Get a single surcharge type by ID. */
+  async findById(id: string): Promise<SurchargeType> {
+    const entity = await this.repository.findById(id);
+    if (!entity) throw new NotFoundException(`Surcharge type ${id} not found`);
+    return entity;
+  }
+
+  /** Create a new surcharge type. */
+  async create(dto: CreateSurchargeTypeDto): Promise<SurchargeType> {
+    const existing = await this.repository.findByCode(dto.code);
+    if (existing) throw new ConflictException(`Surcharge type with code "${dto.code}" already exists`);
+    return this.repository.create({
+      code: dto.code,
+      name: dto.name,
+      description: dto.description ?? null,
+      isActive: dto.isActive ?? true,
+    });
+  }
+
+  /** Update an existing surcharge type. */
+  async update(id: string, dto: UpdateSurchargeTypeDto): Promise<SurchargeType> {
+    await this.findById(id);
+    if (dto.code) {
+      const conflict = await this.repository.findByCode(dto.code);
+      if (conflict && conflict.id !== id) {
+        throw new ConflictException(`Surcharge type with code "${dto.code}" already exists`);
+      }
+    }
+    const updated = await this.repository.update(id, dto);
+    if (!updated) throw new NotFoundException(`Surcharge type ${id} not found`);
+    return updated;
+  }
+
+  /** Soft-delete a surcharge type. */
+  async remove(id: string): Promise<void> {
+    await this.findById(id);
+    await this.repository.softDelete(id);
+  }
+}

apps/edr-freight-api/src/modules/rule-engine/services/surcharges.service.ts

@@ -0,0 +1,76 @@
+import { Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { CreateSurchargeDto } from '../dto/create-surcharge.dto';
+import { UpdateSurchargeDto } from '../dto/update-surcharge.dto';
+import { Surcharge } from '../entities/surcharge.entity';
+import {
+  ISurchargesRepository,
+  SURCHARGES_REPOSITORY,
+} from '../interfaces/surcharges.repository.interface';
+
+@Injectable()
+export class SurchargesService {
+  constructor(
+    @Inject(SURCHARGES_REPOSITORY)
+    private readonly repository: ISurchargesRepository,
+  ) {}
+
+  /** List surcharges with pagination. */
+  async findAll(filter: {
+    isActive?: boolean;
+    surchargeTypeId?: string;
+    page?: number;
+    pageSize?: number;
+  }): Promise<{ data: Surcharge[]; meta: { total: number; page: number; pageSize: number; totalPages: number } }> {
+    const page = filter.page ?? 1;
+    const pageSize = filter.pageSize ?? 20;
+    const where: Record<string, unknown> = {};
+    if (filter.isActive !== undefined) where.isActive = filter.isActive;
+    if (filter.surchargeTypeId) where.surchargeTypeId = filter.surchargeTypeId;
+
+    const [data, total] = await this.repository.findAndCount({
+      where,
+      relations: { surchargeType: true },
+      order: { feeName: 'ASC' },
+      skip: (page - 1) * pageSize,
+      take: pageSize,
+    });
+    return { data, meta: { total, page, pageSize, totalPages: Math.ceil(total / pageSize) } };
+  }
+
+  /** Get a single surcharge by ID. */
+  async findById(id: string): Promise<Surcharge> {
+    const entity = await this.repository.findById(id);
+    if (!entity) throw new NotFoundException(`Surcharge ${id} not found`);
+    return entity;
+  }
+
+  /** Create a new surcharge. */
+  async create(dto: CreateSurchargeDto): Promise<Surcharge> {
+    return this.repository.create({
+      surchargeTypeId: dto.surchargeTypeId,
+      feeName: dto.feeName,
+      triggerDescription: dto.triggerDescription ?? null,
+      calculationMethod: dto.calculationMethod,
+      rate: dto.rate,
+      currency: dto.currency,
+      applyToRail: dto.applyToRail ?? false,
+      applyToFirstMile: dto.applyToFirstMile ?? false,
+      applyToLastMile: dto.applyToLastMile ?? false,
+      isActive: dto.isActive ?? true,
+    });
+  }
+
+  /** Update an existing surcharge. */
+  async update(id: string, dto: UpdateSurchargeDto): Promise<Surcharge> {
+    await this.findById(id);
+    const updated = await this.repository.update(id, dto);
+    if (!updated) throw new NotFoundException(`Surcharge ${id} not found`);
+    return updated;
+  }
+
+  /** Soft-delete a surcharge. */
+  async remove(id: string): Promise<void> {
+    await this.findById(id);
+    await this.repository.softDelete(id);
+  }
+}

apps/edr-freight-api/src/modules/rule-engine/services/weight-limit-rules.service.ts

@@ -0,0 +1,78 @@
+import { BadRequestException, Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { CreateWeightLimitRuleDto } from '../dto/create-weight-limit-rule.dto';
+import { UpdateWeightLimitRuleDto } from '../dto/update-weight-limit-rule.dto';
+import { WeightLimitRule } from '../entities/weight-limit-rule.entity';
+import {
+  IWeightLimitRulesRepository,
+  WEIGHT_LIMIT_RULES_REPOSITORY,
+} from '../interfaces/weight-limit-rules.repository.interface';
+
+@Injectable()
+export class WeightLimitRulesService {
+  constructor(
+    @Inject(WEIGHT_LIMIT_RULES_REPOSITORY)
+    private readonly repository: IWeightLimitRulesRepository,
+  ) {}
+
+  /** List weight limit rules with pagination. */
+  async findAll(filter: {
+    isActive?: boolean;
+    containerTypeId?: string;
+    page?: number;
+    pageSize?: number;
+  }): Promise<{ data: WeightLimitRule[]; meta: { total: number; page: number; pageSize: number; totalPages: number } }> {
+    const page = filter.page ?? 1;
+    const pageSize = filter.pageSize ?? 20;
+    const where: Record<string, unknown> = {};
+    if (filter.isActive !== undefined) where.isActive = filter.isActive;
+    if (filter.containerTypeId) where.containerTypeId = filter.containerTypeId;
+
+    const [data, total] = await this.repository.findAndCount({
+      where,
+      relations: { containerType: true, surcharge: { surchargeType: true } },
+      skip: (page - 1) * pageSize,
+      take: pageSize,
+    });
+    return { data, meta: { total, page, pageSize, totalPages: Math.ceil(total / pageSize) } };
+  }
+
+  /** Get a single weight limit rule by ID. */
+  async findById(id: string): Promise<WeightLimitRule> {
+    const entity = await this.repository.findById(id);
+    if (!entity) throw new NotFoundException(`Weight limit rule ${id} not found`);
+    return entity;
+  }
+
+  /** Create a new weight limit rule. */
+  async create(dto: CreateWeightLimitRuleDto): Promise<WeightLimitRule> {
+    if (dto.warningThresholdTons > dto.maxWeightTons) {
+      throw new BadRequestException('warningThresholdTons must be ≤ maxWeightTons');
+    }
+    return this.repository.create({
+      containerTypeId: dto.containerTypeId,
+      tradeDirection: dto.tradeDirection,
+      maxWeightTons: dto.maxWeightTons,
+      warningThresholdTons: dto.warningThresholdTons,
+      exceededAction: dto.exceededAction,
+      surchargeId: dto.surchargeId ?? null,
+      isActive: dto.isActive ?? true,
+    });
+  }
+
+  /** Update an existing weight limit rule. */
+  async update(id: string, dto: UpdateWeightLimitRuleDto): Promise<WeightLimitRule> {
+    const existing = await this.findById(id);
+    const warning = dto.warningThresholdTons ?? existing.warningThresholdTons;
+    const max = dto.maxWeightTons ?? existing.maxWeightTons;
+    if (warning > max) throw new BadRequestException('warningThresholdTons must be ≤ maxWeightTons');
+    const updated = await this.repository.update(id, dto);
+    if (!updated) throw new NotFoundException(`Weight limit rule ${id} not found`);
+    return updated;
+  }
+
+  /** Soft-delete a weight limit rule. */
+  async remove(id: string): Promise<void> {
+    await this.findById(id);
+    await this.repository.softDelete(id);
+  }
+}