feat(FN-3504): apply cover percentage to initial utilisation (#3695)

Author: RLavender98

dtfs-central-api/api-tests/v1/utilisation-reports/post-upload-utilisation-report.api-test.ts

@@ -18,7 +18,7 @@ import { testApi } from '../../test-api';
 import { SqlDbHelper } from '../../sql-db-helper';
 import { mongoDbClient } from '../../../src/drivers/db-client';
 import { wipe } from '../../wipeDB';
-import { aUtilisationReportRawCsvData, aPortalUser, aFacility, aBank } from '../../../test-helpers';
+import { aUtilisationReportRawCsvData, aPortalUser, aFacility, aBank, aTfmFacility } from '../../../test-helpers';
 import { PostUploadUtilisationReportRequestBody } from '../../../src/v1/controllers/utilisation-report-service/post-upload-utilisation-report.controller';
 
 console.error = jest.fn();
@@ -152,6 +152,58 @@ describe(`POST ${getUrl()}`, () => {
     expect(facilityIdExists).toEqual([true, true, true]);
   });
 
+  it('should calculate and save initial utilisation and fixed fee using facility values from facility creation', async () => {
+    // Arrange
+    const ukefFacilityId = '11111111';
+    const reportData: UtilisationReportRawCsvData[] = [
+      {
+        ...aUtilisationReportRawCsvData(),
+        'ukef facility id': ukefFacilityId,
+      },
+    ];
+
+    const tfmFacility: WithoutId<TfmFacility> = {
+      ...aTfmFacility(),
+      facilitySnapshot: {
+        ...aTfmFacility().facilitySnapshot,
+        ukefFacilityId,
+        coverPercentage: 80,
+        coverStartDate: new Date('2024-01-01'),
+        // 366 days after cover start date because 2024 is a leap year
+        coverEndDate: new Date('2025-01-01'),
+        value: 500000,
+        interestPercentage: 5,
+        dayCountBasis: 360,
+      },
+    };
+
+    const tfmFacilitiesCollection = await mongoDbClient.getCollection(MONGO_DB_COLLECTIONS.TFM_FACILITIES);
+    await tfmFacilitiesCollection.insertOne(tfmFacility);
+
+    const payload: PostUploadUtilisationReportRequestBody = { ...aValidPayload(), reportData };
+
+    // Act
+    const response = await testApi.post(payload).to(getUrl());
+
+    // Assert
+    expect(response.status).toEqual(HttpStatusCode.Created);
+
+    const facilityUtilisationData = await SqlDbHelper.manager.findOneBy(FacilityUtilisationDataEntity, { id: ukefFacilityId });
+    expect(facilityUtilisationData).not.toBeNull();
+    /**
+     * Initial utilisation is 10% of the facility value * (cover percentage / 100) thus,
+     * utilisation = 0.1 * 500000 * (80 / 100)
+     *             = 40000
+     */
+    expect(facilityUtilisationData?.utilisation).toEqual(40000);
+    /**
+     * Initial fixed fee = initial utilisation * bank margin rate * interest * days in cover period / day count basis
+     *                   = 40000 * 0.9 * (5 / 100) * 366 / 360
+     *                   = 1830
+     */
+    expect(facilityUtilisationData?.fixedFee).toEqual(1830);
+  });
+
   it('creates an entry in the AzureFileInfo table', async () => {
     // Act
     const response = await testApi.post(aValidPayload()).to(getUrl());
@@ -211,7 +263,7 @@ describe(`POST ${getUrl()}`, () => {
     });
   });
 
-  it('creates a new FacilityUtilisationData row using the report reportPeriod if the report data has a facility id which does not already exist', async () => {
+  it('creates a new FacilityUtilisationData row using the previous reportPeriod if the report data has a facility id which does not already exist', async () => {
     // Arrange
     await SqlDbHelper.deleteAll();
 

dtfs-central-api/src/services/state-machines/utilisation-report/event-handlers/helpers/calculate-initial-utilisation-and-fixed-fee.test.ts

@@ -1,9 +1,15 @@
-import { calculateInitialUtilisation } from '@ukef/dtfs2-common';
+import * as dtfsCommon from '@ukef/dtfs2-common';
 import { calculateInitialUtilisationAndFixedFee, parseDate, hasRequiredValues, RequiredParams } from './calculate-initial-utilisation-and-fixed-fee';
 import { TfmFacilitiesRepo } from '../../../../../repositories/tfm-facilities-repo';
 import { aTfmFacility } from '../../../../../../test-helpers';
-import { calculateInitialFixedFee } from './calculate-initial-fixed-fee';
-import { calculateUkefShareOfUtilisation } from '../../../../../helpers';
+import * as fixedFeeHelpers from './calculate-initial-fixed-fee';
+
+jest.mock('./calculate-initial-fixed-fee');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+jest.mock('@ukef/dtfs2-common', () => ({
+  ...jest.requireActual('@ukef/dtfs2-common'),
+  calculateDrawnAmount: jest.fn(),
+}));
 
 describe('helpers/calculate-initial-utilisation-and-fixed-fee', () => {
   describe('parseDate', () => {
@@ -145,26 +151,40 @@ describe('helpers/calculate-initial-utilisation-and-fixed-fee', () => {
         findOneByUkefFacilityIdSpy.mockResolvedValue(facility);
       });
 
-      it('should return a value for utilisation and fixed fee', async () => {
+      it('should set initial utilisation to drawn amount rounded to 2 decimal places', async () => {
+        // Arrange
+        const drawnAmount = 12345.678;
+        const drawnAmountRoundedToTwoDecimalPlaces = 12345.68;
+        const calculateDrawnAmountSpy = jest.spyOn(dtfsCommon, 'calculateDrawnAmount').mockReturnValue(drawnAmount);
+        jest.mocked(fixedFeeHelpers.calculateInitialFixedFee).mockReturnValue(999.99);
+
+        // Act
         const result = await calculateInitialUtilisationAndFixedFee(facilityId);
 
-        const { value, coverStartDate, coverEndDate, interestPercentage, dayCountBasis } = facility.facilitySnapshot;
+        // Assert
+        expect(calculateDrawnAmountSpy).toHaveBeenCalledWith(facility.facilitySnapshot.value, facility.facilitySnapshot.coverPercentage);
+        expect(result.utilisation).toEqual(drawnAmountRoundedToTwoDecimalPlaces);
+      });
 
-        const utilisation = calculateInitialUtilisation(value);
-        const ukefShareOfUtilisation = calculateUkefShareOfUtilisation(utilisation, facility.facilitySnapshot.coverPercentage);
+      it('should calculate and return the initial fixed fee', async () => {
+        // Arrange
+        const drawnAmount = 12345.678;
+        const drawnAmountRoundedToTwoDecimalPlaces = 12345.68;
+        jest.mocked(dtfsCommon.calculateDrawnAmount).mockReturnValue(drawnAmount);
+        const calculateInitialFixedFeeSpy = jest.spyOn(fixedFeeHelpers, 'calculateInitialFixedFee').mockReturnValue(999.99);
 
-        const expected = {
-          fixedFee: calculateInitialFixedFee({
-            ukefShareOfUtilisation,
-            coverStartDate: parseDate(coverStartDate),
-            coverEndDate: parseDate(coverEndDate),
-            interestPercentage,
-            dayCountBasis,
-          }),
-          utilisation,
-        };
+        // Act
+        const result = await calculateInitialUtilisationAndFixedFee(facilityId);
 
-        expect(result).toEqual(expected);
+        // Assert
+        expect(calculateInitialFixedFeeSpy).toHaveBeenCalledWith({
+          ukefShareOfUtilisation: drawnAmountRoundedToTwoDecimalPlaces,
+          coverStartDate: facility.facilitySnapshot.coverStartDate,
+          coverEndDate: facility.facilitySnapshot.coverEndDate,
+          interestPercentage: facility.facilitySnapshot.interestPercentage,
+          dayCountBasis: facility.facilitySnapshot.dayCountBasis,
+        });
+        expect(result.fixedFee).toEqual(999.99);
       });
     });
   });

dtfs-central-api/src/services/state-machines/utilisation-report/event-handlers/helpers/calculate-initial-utilisation-and-fixed-fee.ts

@@ -1,7 +1,7 @@
-import { calculateInitialUtilisation, isValidDate } from '@ukef/dtfs2-common';
+import { calculateDrawnAmount, isValidDate } from '@ukef/dtfs2-common';
+import Big from 'big.js';
 import { TfmFacilitiesRepo } from '../../../../../repositories/tfm-facilities-repo';
 import { calculateInitialFixedFee } from './calculate-initial-fixed-fee';
-import { calculateUkefShareOfUtilisation } from '../../../../../helpers';
 
 export type RequiredParams = {
   value?: number | null;
@@ -70,12 +70,10 @@ export const calculateInitialUtilisationAndFixedFee = async (facilityId: string)
     throw new Error(`TFM facility values for ${facilityId} are missing`);
   }
 
-  const utilisation = calculateInitialUtilisation(value);
-
-  const ukefShareOfUtilisation = calculateUkefShareOfUtilisation(utilisation, coverPercentage);
+  const ukefShareOfInitialUtilisation = new Big(calculateDrawnAmount(value, coverPercentage)).round(2).toNumber();
 
   const fixedFee = calculateInitialFixedFee({
-    ukefShareOfUtilisation,
+    ukefShareOfUtilisation: ukefShareOfInitialUtilisation,
     coverStartDate: parseDate(coverStartDate),
     coverEndDate: parseDate(coverEndDate),
     interestPercentage,
@@ -84,6 +82,6 @@ export const calculateInitialUtilisationAndFixedFee = async (facilityId: string)
 
   return {
     fixedFee,
-    utilisation,
+    utilisation: ukefShareOfInitialUtilisation,
   };
 };