Implement alternate version of 2PT matching

app/controllers/check.controller.js

@@ -6,6 +6,7 @@
  */
 
 const CheckTwoPartService = require('../services/check/two-part.service.js')
+const TwoPartTariffMatchAndAllocateService = require('../services/bill-runs/two-part-tariff/match-and-allocate.service.js')
 
 async function twoPart (request, h) {
   const result = await CheckTwoPartService.go(request.params.naldRegionId, 'region')
@@ -19,7 +20,30 @@ async function twoPartLicence (request, h) {
   return h.response(result).code(200)
 }
 
+// Used on alternate branch
+async function twoPartReview (_request, h) {
+  const result = await TwoPartTariffMatchAndAllocateService.go(
+    { billingBatchId: '41be6d72-701b-4252-90d5-2d38614b6282', regionId: 'ffea25c2-e577-4969-8667-b0eed899230d' },
+    [{ startDate: new Date('2022-04-01'), endDate: new Date('2023-03-31') }]
+  )
+
+  return h.response(result).code(200)
+}
+
+// Used on alternate branch
+async function twoPartReviewLicence (request, h) {
+  const result = await TwoPartTariffMatchAndAllocateService.go(
+    { billingBatchId: '41be6d72-701b-4252-90d5-2d38614b6282', regionId: 'ffea25c2-e577-4969-8667-b0eed899230d' },
+    [{ startDate: new Date('2022-04-01'), endDate: new Date('2023-03-31') }],
+    request.params.licenceId
+  )
+
+  return h.response(result).code(200)
+}
+
 module.exports = {
   twoPart,
-  twoPartLicence
+  twoPartLicence,
+  twoPartReview,
+  twoPartReviewLicence
 }

app/routes/check.routes.js

@@ -28,6 +28,34 @@ const routes = [
       auth: false,
       description: 'Used by the delivery team to check the SROC 2PT billing logic for a single licence'
     }
+  },
+  {
+    // Used on the alternate branch
+    method: 'GET',
+    path: '/check/two-part-review',
+    handler: CheckController.twoPartReview,
+    options: {
+      app: {
+        excludeFromProd: true,
+        plainOutput: true
+      },
+      auth: false,
+      description: 'Used by the delivery team to check the SROC 2PT billing logic for a region'
+    }
+  },
+  {
+    // Used on the alternate branch
+    method: 'GET',
+    path: '/check/two-part-review/{licenceId}',
+    handler: CheckController.twoPartReviewLicence,
+    options: {
+      app: {
+        excludeFromProd: true,
+        plainOutput: true
+      },
+      auth: false,
+      description: 'Used by the delivery team to check the SROC 2PT billing logic for a single licence'
+    }
   }
 ]
 

app/services/bill-runs/start-bill-run-process.service.js

@@ -9,7 +9,7 @@ const DetermineBillingPeriodsService = require('./determine-billing-periods.serv
 const CreateBillRunPresenter = require('../../presenters/bill-runs/create-bill-run.presenter.js')
 const InitiateBillRunService = require('./initiate-bill-run.service.js')
 const SupplementaryProcessBillRunService = require('./supplementary/process-bill-run.service.js')
-const TwoPartTariffProcessBillRunService = require('./two-part-tariff/process-bill-run.service.js')
+const TwoPartTariffMatchAndAllocateService = require('./two-part-tariff/match-and-allocate.service.js')
 
 /**
  * Manages the creation of a new bill run
@@ -46,7 +46,7 @@ function _processBillRun (billRun, billingPeriods) {
       SupplementaryProcessBillRunService.go(billRun, billingPeriods)
       break
     case 'two_part_tariff':
-      TwoPartTariffProcessBillRunService.go(billRun, billingPeriods)
+      TwoPartTariffMatchAndAllocateService.go(billRun, billingPeriods)
       break
   }
 }

app/services/bill-runs/two-part-tariff/allocate-returns-to-licence.service.js

@@ -0,0 +1,122 @@
+'use strict'
+
+/**
+ * Matches and allocates where applicable the abstracted volumes on the return log with the appropriate charge element
+ * @module AllocateReturnsToLicenceService
+ */
+
+const { periodsOverlap } = require('../../../lib/general.lib.js')
+const MatchReturnsToChargeElementService = require('./match-returns-to-charge-element.service.js')
+
+/**
+ * For each licence the service attempts to match the return logs to the charge element(s). It does this by matching the
+ * `elementCode` of the charge element with the return logs, also checking that the abstraction periods for both the
+ * element and return log overlap.
+ *
+ * If a match is found any abstracted volume recorded on the return log will be allocated to the charge element up to a
+ * maximum of the charge elements authorised volume, or the remaining authorised volume on the charge reference,
+ * whichever is lower.
+ *
+ * @param {Object[]} licences - The licences, associated charging data, and return logs to process
+ */
+function go (licences) {
+  licences.forEach((licence) => {
+    const { chargeVersions, returnLogs } = licence
+
+    chargeVersions.forEach((chargeVersion) => {
+      const { chargeReferences } = chargeVersion
+
+      chargeReferences.forEach((chargeReference) => {
+        chargeReference.allocatedQuantity = 0
+
+        const { chargeElements } = chargeReference
+
+        chargeElements.forEach((chargeElement) => {
+          _matchAndAllocate(chargeElement, returnLogs, chargeVersion.chargePeriod, chargeReference)
+        })
+      })
+    })
+  })
+}
+
+function _chargeDatesOverlap (matchedLine, chargePeriod) {
+  const { startDate: chargePeriodStartDate, endDate: chargePeriodEndDate } = chargePeriod
+  const { startDate: lineStartDate, endDate: lineEndDate } = matchedLine
+
+  if (lineStartDate < chargePeriodEndDate && lineEndDate > chargePeriodEndDate) {
+    return true
+  }
+
+  if (lineStartDate < chargePeriodStartDate && lineEndDate > chargePeriodStartDate) {
+    return true
+  }
+
+  return false
+}
+
+function _matchAndAllocate (chargeElement, returnLogs, chargePeriod, chargeReference) {
+  const matchedReturns = MatchReturnsToChargeElementService.go(chargeElement, returnLogs)
+
+  if (matchedReturns.length === 0) {
+    return
+  }
+
+  let i = 0
+  matchedReturns.forEach((matchedReturn) => {
+    if (chargeElement.allocatedQuantity < chargeElement.authorisedAnnualQuantity && chargeReference.allocatedQuantity < chargeReference.volume) {
+      if (matchedReturn.issues === true) {
+        return
+      }
+
+      const matchedLines = _matchLines(chargeElement, matchedReturn.returnSubmissions[0].returnSubmissionLines)
+
+      if (matchedLines.length === 0) {
+        return
+      }
+
+      matchedLines.forEach((matchedLine) => {
+        const remainingAllocation = chargeElement.authorisedAnnualQuantity - chargeElement.allocatedQuantity
+        if (remainingAllocation > 0) {
+          // We default how much to allocate to what is unallocated on the line i.e. remaining >= line.unallocated
+          let qtyToAllocate = matchedLine.unallocated
+
+          // If what remains is actually less than the line we instead set qtyToAllocate to what remains. We check this
+          // on both the chargeReference and the element
+          const chargeReferenceRemainingAllocation = chargeReference.volume - chargeReference.allocatedQuantity
+
+          if (qtyToAllocate > chargeReferenceRemainingAllocation) {
+            qtyToAllocate = chargeReferenceRemainingAllocation
+          } else if (remainingAllocation < matchedLine.unallocated) {
+            qtyToAllocate = remainingAllocation
+          }
+
+          chargeElement.chargeDatesOverlap = _chargeDatesOverlap(matchedLine, chargePeriod)
+          chargeElement.allocatedQuantity += qtyToAllocate
+          console.log('Charge Element :', chargeElement)
+          console.log('Matched Return :', matchedReturn)
+          chargeElement.returnLogs[i].allocatedQuantity += qtyToAllocate
+
+          matchedLine.unallocated -= qtyToAllocate
+          matchedReturn.allocatedQuantity += qtyToAllocate
+          chargeReference.allocatedQuantity += qtyToAllocate
+        }
+      })
+    }
+    i++
+  })
+}
+
+function _matchLines (chargeElement, returnSubmissionLines) {
+  return returnSubmissionLines.filter((returnSubmissionLine) => {
+    if (returnSubmissionLine.unallocated === 0) {
+      return false
+    }
+
+    const { startDate, endDate } = returnSubmissionLine
+    return periodsOverlap(chargeElement.abstractionPeriods, [{ startDate, endDate }])
+  })
+}
+
+module.exports = {
+  go
+}

app/services/bill-runs/two-part-tariff/fetch-charge-versions.service.js

@@ -30,13 +30,22 @@ const Workflow = require('../../../models/workflow.model.js')
  *
  * @returns {Object} Contains an array of SROC charge versions with linked licences, charge references, charge elements and related purpose
  */
-async function go (regionId, billingPeriod) {
-  const regionCode = await _regionCode(regionId)
+async function go (regionId, billingPeriod, licenceId) {
+  let regionCode = null
 
-  return _fetch(regionCode, billingPeriod)
+  if (!licenceId) {
+    regionCode = await _regionCode(regionId)
+  }
+
+  return _fetch(regionCode, billingPeriod, licenceId)
 }
 
-async function _fetch (regionCode, billingPeriod) {
+async function _fetch (regionCode, billingPeriod, licenceId) {
+  const whereClause = {
+    field: licenceId ? 'licenceId' : 'regionCode',
+    value: licenceId ?? regionCode
+  }
+
   const chargeVersions = await ChargeVersionModel.query()
     .select([
       'chargeVersions.id',
@@ -48,7 +57,7 @@ async function _fetch (regionCode, billingPeriod) {
     .where('chargeVersions.scheme', 'sroc')
     .where('chargeVersions.startDate', '<=', billingPeriod.endDate)
     .where('chargeVersions.status', 'current')
-    .where('chargeVersions.regionCode', regionCode)
+    .where(`chargeVersions.${whereClause.field}`, whereClause.value)
     .where((builder) => {
       builder
         .whereNull('licence.expiredDate')

app/services/bill-runs/two-part-tariff/fetch-licences.service.js

@@ -16,8 +16,8 @@ const FetchChargeVersionsService = require('./fetch-charge-versions.service.js')
  *
  * @returns {Object[]} the licences to be matched, each containing an array of charge versions applicable for two-part tariff
  */
-async function go (regionId, billingPeriod) {
-  const chargeVersions = await FetchChargeVersionsService.go(regionId, billingPeriod)
+async function go (regionId, billingPeriod, licenceId) {
+  const chargeVersions = await FetchChargeVersionsService.go(regionId, billingPeriod, licenceId)
 
   const uniqueLicenceIds = _extractUniqueLicenceIds(chargeVersions)
 

app/services/bill-runs/two-part-tariff/match-and-allocate.service.js

@@ -0,0 +1,41 @@
+'use strict'
+
+/**
+ * Match and allocate licences to returns for a two-part tariff bill run for the given billing periods
+ * @module MatchAndAllocateService
+ */
+
+const AllocateReturnsToLicenceService = require('./allocate-returns-to-licence.service.js')
+const FetchLicencesService = require('./fetch-licences.service.js')
+const PrepareLicencesForAllocationService = require('./prepare-licences-for-allocation.service.js')
+const PersistAllocatedLicencesToResultsService = require('./persist-allocated-licences-to-results.service.js')
+/**
+ * Functionality not yet implemented
+ */
+async function go (billRun, billingPeriods, licenceId) {
+  const startTime = process.hrtime.bigint()
+
+  const licences = await FetchLicencesService.go(billRun.regionId, billingPeriods[0], licenceId)
+
+  await PrepareLicencesForAllocationService.go(licences, billingPeriods[0])
+
+  AllocateReturnsToLicenceService.go(licences, billRun.billingBatchId)
+
+  await PersistAllocatedLicencesToResultsService.go(billRun.billingBatchId, licences)
+
+  _calculateAndLogTime(startTime)
+
+  return licences
+}
+
+function _calculateAndLogTime (startTime) {
+  const endTime = process.hrtime.bigint()
+  const timeTakenNs = endTime - startTime
+  const timeTakenMs = timeTakenNs / 1000000n
+
+  global.GlobalNotifier.omg('Two part tariff matching complete', { timeTakenMs })
+}
+
+module.exports = {
+  go
+}

app/services/bill-runs/two-part-tariff/match-returns-to-charge-element.service.js

@@ -0,0 +1,65 @@
+'use strict'
+
+/**
+ * Matches the return logs to the charge element
+ * @module MatchReturnsToChargeElementService
+ */
+
+const { periodsOverlap } = require('../../../lib/general.lib.js')
+
+/**
+ * Matches return logs to a charge element and adds the matching returns to the charge element
+ *
+ * @param {module:ChargeElementModel} chargeElement - The charge element to match return logs against
+ * @param {module:ReturnLogModel[]} returnLogs - All return logs from the charge elements licence
+ *
+ * @returns {module:ReturnLogModel[]} Return logs that matched the charge element
+ */
+function go (chargeElement, returnLogs) {
+  const matchingReturns = _matchReturns(chargeElement, returnLogs)
+  _addReturnToElement(matchingReturns, chargeElement)
+
+  return matchingReturns
+}
+
+function _addReturnToElement (matchingReturns, chargeElement) {
+  if (matchingReturns.length === 0) {
+    return
+  }
+
+  matchingReturns.forEach((matchedReturn) => {
+    const matchedReturnResult = {
+      allocatedQuantity: 0,
+      returnId: matchedReturn.id
+    }
+
+    chargeElement.returnLogs.push(matchedReturnResult)
+    matchedReturn.matched = true
+  })
+}
+
+/**
+ * Filters and returns logs that match a given charge element based on legacy ID and abstraction periods
+ */
+function _matchReturns (chargeElement, returnLogs) {
+  const elementCode = chargeElement.purpose.legacyId
+  const elementPeriods = chargeElement.abstractionPeriods
+
+  return returnLogs.filter((returnLog) => {
+    const returnPeriods = returnLog.abstractionPeriods
+
+    const matchFound = returnLog.purposes.some((purpose) => {
+      return purpose.tertiary.code === elementCode
+    })
+
+    if (!matchFound) {
+      return false
+    }
+
+    return periodsOverlap(elementPeriods, returnPeriods)
+  })
+}
+
+module.exports = {
+  go
+}