Implement annual two-part tariff billing engine (#1172)

https://eaflood.atlassian.net/browse/WATER-4196

> Part of the work for two-part tariff annual billing

We're ready to generate a bill run from our two-part tariff review data and with [Add Continue bill run btn to 2PT review screen](#1122) and [Add new two-part tariff generate bill run endpoint](#1123) we have the means to trigger it. We can now also [Fetch all the billing accounts and related data](#1129) needed to generate the bills.

This implements the remaining services needed to transform that data into actual bills using the same pattern we implemented for SROC annual billing.

- a service to manage the process - `GenerateBillRunService`
- a service to transform the data into bills `ProcessBillingPeriodService`
- a mirror of `GenerateTransactionService` amended specifically for two-part tariff bill runs (because of the need to incorporate values from the review stage)

With this in place, users will finally be able to generate an annual two-part tariff SROC bill run!

app/presenters/bill-runs/two-part-tariff/review-bill-run.presenter.js

@@ -92,6 +92,7 @@ function _prepareBillRun (billRun, preparedLicences) {
     financialYear: _financialYear(billRun.toFinancialYearEnding),
     billRunType: 'two-part tariff',
     numberOfLicencesDisplayed: preparedLicences.length,
+    numberOfLicencesToReview: billRun.reviewLicences[0].numberOfLicencesToReview,
     reviewMessage: _prepareReviewMessage(billRun.reviewLicences[0].numberOfLicencesToReview),
     totalNumberOfLicences: billRun.reviewLicences[0].totalNumberOfLicences
   }

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

@@ -74,6 +74,13 @@ async function go (billRunId) {
         'revokedDate'
       ])
     })
+    .withGraphFetched('chargeVersions.licence.region')
+    .modifyGraph('chargeVersions.licence.region', (builder) => {
+      builder.select([
+        'id',
+        'chargeRegionId'
+      ])
+    })
     .withGraphFetched('chargeVersions.chargeReferences')
     .modifyGraph('chargeVersions.chargeReferences', (builder) => {
       builder.select([

app/services/bill-runs/two-part-tariff/generate-bill-run.service.js

@@ -5,17 +5,156 @@
  * @module GenerateBillRunService
  */
 
+const BillRunError = require('../../../errors/bill-run.error.js')
+const BillRunModel = require('../../../models/bill-run.model.js')
+const ChargingModuleGenerateBillRunRequest = require('../../../requests/charging-module/generate-bill-run.request.js')
+const ExpandedError = require('../../../errors/expanded.error.js')
+const {
+  calculateAndLogTimeTaken,
+  currentTimeInNanoseconds,
+  timestampForPostgres
+} = require('../../../lib/general.lib.js')
+const FetchBillingAccountsService = require('./fetch-billing-accounts.service.js')
+const HandleErroredBillRunService = require('../handle-errored-bill-run.service.js')
+const LegacyRefreshBillRunRequest = require('../../../requests/legacy/refresh-bill-run.request.js')
+const ProcessBillingPeriodService = require('./process-billing-period.service.js')
+
 /**
  * Generates a two-part tariff bill run after the users have completed reviewing its match & allocate results
  *
- * > This is currently a shell that that we intend to expand in subsequent commits
+ * In this case, "generate" means that we create the required bills and transactions for them in both this service and
+ * the Charging Module.
+ *
+ * > In the other bill run types this would be the `ProcessBillRunService` but that has already been used to handle
+ * > the match and allocate process in two-part tariff
+ *
+ * We first fetch all the billing accounts applicable to this bill run and their charge information. We pass these to
+ * `ProcessBillingPeriodService` which will generate the bill for each billing account both in WRLS and the
+ * {@link https://github.com/DEFRA/sroc-charging-module-api | Charging Module API (CHA)}.
+ *
+ * Once `ProcessBillingPeriodService` is complete we tell the CHA to generate the bill run (this calculates final
+ * values for each bill and the bill run overall).
+ *
+ * The final step is to ping the legacy
+ * {@link https://github.com/DEFRA/water-abstraction-service | water-abstraction-service} 'refresh' endpoint. That
+ * service will extract the final values from the CHA and update the records on our side, finally marking the bill run
+ * as **Ready**.
  *
- * @param {string} billRunId - The UUID of the two-part tariff bill run in review
+ * @param {module:BillRunModel} billRunId - The UUID of the two-part tariff bill run that has been reviewed and is ready
+ * for generating
  *
  * @returns {Promise} the promise returned is not intended to resolve to any particular value
  */
 async function go (billRunId) {
-  return billRunId
+  const billRun = await _fetchBillRun(billRunId)
+
+  if (billRun.status !== 'review') {
+    throw new ExpandedError('Cannot process a two-part tariff bill run that is not in review', { billRunId })
+  }
+
+  await _updateStatus(billRunId, 'processing')
+
+  _generateBillRun(billRun)
+}
+
+/**
+ * Unlike other bill runs where the bill run itself and the bills are generated in one process, two-part tariff is
+ * split. The first part which matches and allocates charge information to returns create's the bill run itself. This
+ * service handles the second part where we create the bills using the match and allocate data.
+ *
+ * This means we've already determined the billing period and recorded it against the bill run. So, we retrieve it from
+ * the bill run rather than pass it into the service.
+ */
+function _billingPeriod (billRun) {
+  const { toFinancialYearEnding } = billRun
+
+  return {
+    startDate: new Date(`${toFinancialYearEnding - 1}-04-01`),
+    endDate: new Date(`${toFinancialYearEnding}-03-31`)
+  }
+}
+
+async function _fetchBillingAccounts (billRunId) {
+  try {
+    // We don't just `return FetchBillingDataService.go()` as we need to call HandleErroredBillRunService if it
+    // fails
+    const billingAccounts = await FetchBillingAccountsService.go(billRunId)
+
+    return billingAccounts
+  } catch (error) {
+    // We know we're saying we failed to process charge versions. But we're stuck with the legacy error codes and this
+    // is the closest one related to what stage we're at in the process
+    throw new BillRunError(error, BillRunModel.errorCodes.failedToProcessChargeVersions)
+  }
+}
+
+async function _fetchBillRun (billRunId) {
+  return BillRunModel.query()
+    .findById(billRunId)
+    .select([
+      'id',
+      'batchType',
+      'createdAt',
+      'externalId',
+      'regionId',
+      'scheme',
+      'status',
+      'toFinancialYearEnding'
+    ])
+}
+
+async function _finaliseBillRun (billRun, billRunPopulated) {
+  // If there are no bill licences then the bill run is considered empty. We just need to set the status to indicate
+  // this in the UI
+  if (!billRunPopulated) {
+    await _updateStatus(billRun.id, 'empty')
+
+    return
+  }
+
+  // We now need to tell the Charging Module to run its generate process. This is where the Charging module finalises
+  // the debit and credit amounts, and adds any additional transactions needed, for example, minimum charge
+  await ChargingModuleGenerateBillRunRequest.send(billRun.externalId)
+
+  await LegacyRefreshBillRunRequest.send(billRun.id)
+}
+
+/**
+ * The go() has to deal with updating the status of the bill run and then passing a response back to the request to
+ * avoid the user seeing a timeout in their browser. So, this is where we actually generate the bills and record the
+ * time taken.
+ */
+async function _generateBillRun (billRun) {
+  const { id: billRunId } = billRun
+
+  try {
+    const startTime = currentTimeInNanoseconds()
+
+    const billingPeriod = _billingPeriod(billRun)
+
+    await _processBillingPeriod(billingPeriod, billRun)
+
+    calculateAndLogTimeTaken(startTime, 'Process bill run complete', { billRunId })
+  } catch (error) {
+    await HandleErroredBillRunService.go(billRunId, error.code)
+    global.GlobalNotifier.omfg('Bill run process errored', { billRun }, error)
+  }
+}
+
+async function _processBillingPeriod (billingPeriod, billRun) {
+  const { id: billRunId } = billRun
+
+  const billingAccounts = await _fetchBillingAccounts(billRunId)
+
+  const billRunPopulated = await ProcessBillingPeriodService.go(billRun, billingPeriod, billingAccounts)
+
+  await _finaliseBillRun(billRun, billRunPopulated)
+}
+
+async function _updateStatus (billRunId, status) {
+  return BillRunModel.query()
+    .findById(billRunId)
+    .patch({ status, updatedAt: timestampForPostgres() })
 }
 
 module.exports = {

app/services/bill-runs/two-part-tariff/generate-transaction.service.js

@@ -0,0 +1,128 @@
+'use strict'
+
+/**
+ * Generate a two-part tariff transaction data from the the charge reference and other information passed in
+ * @module GenerateTransactionService
+ */
+
+const { generateUUID } = require('../../../lib/general.lib.js')
+
+/**
+ * Generate a two-part tariff transaction data from the the charge reference and other information passed in
+ *
+ * Unlike a standard transaction, we don't have to calculate the billing days for the transaction. Instead, two-part
+ * tariff transactions focus on volume. This information comes from the review data that results after the match &
+ * allocate results have been checked and amended by users.
+ *
+ * As well as allocated volume, users can override in the review
+ *
+ * - the authorised volume
+ * - the aggregate
+ * - the charge adjustment
+ *
+ * So, we have to grab those values as well. Finally, because the standard annual bill run will have handled the
+ * compensation charge we don't have to generate an additional transaction alongside our two-part tariff one.
+ *
+ * @param {String} billLicenceId - The UUID of the bill licence the transaction will be linked to
+ * @param {module:ChargeReferenceModel} chargeReference - The charge reference the transaction generated will be
+ * generated from
+ * @param {Object} chargePeriod - A start and end date representing the charge period for the transaction
+ * @param {Boolean} newLicence - Whether the charge reference is linked to a new licence
+ * @param {Boolean} waterUndertaker - Whether the charge reference is linked to a water undertaker licence
+ *
+ * @returns {Object} the two-part tariff transaction
+ */
+function go (billLicenceId, chargeReference, chargePeriod, newLicence, waterUndertaker) {
+  const billableQuantity = _billableQuantity(chargeReference.chargeElements)
+
+  return _standardTransaction(
+    billLicenceId,
+    billableQuantity,
+    chargeReference,
+    chargePeriod,
+    newLicence,
+    waterUndertaker
+  )
+}
+
+function _billableQuantity (chargeElements) {
+  return chargeElements.reduce((total, chargeElement) => {
+    total += chargeElement.reviewChargeElements[0].amendedAllocated
+
+    return total
+  }, 0)
+}
+
+function _description (chargeReference) {
+  // If the value is false, undefined, null or simply doesn't exist we return the standard description
+  if (!chargeReference.adjustments.s127) {
+    return `Water abstraction charge: ${chargeReference.description}`
+  }
+
+  return `Two-part tariff basic water abstraction charge: ${chargeReference.description}`
+}
+
+/**
+ * Returns a json representation of all charge elements in a charge reference
+ */
+function _generateElements (chargeReference) {
+  const jsonChargeElements = chargeReference.chargeElements.map((chargeElement) => {
+    delete chargeElement.reviewChargeElements
+
+    return chargeElement.toJSON()
+  })
+
+  return JSON.stringify(jsonChargeElements)
+}
+
+/**
+ * Generates a standard transaction based on the supplied data, along with some default fields (eg. status)
+ */
+function _standardTransaction (
+  billLicenceId,
+  billableQuantity,
+  chargeReference,
+  chargePeriod,
+  newLicence,
+  waterUndertaker
+) {
+  return {
+    id: generateUUID(),
+    billLicenceId,
+    authorisedDays: 0,
+    billableDays: 0,
+    newLicence,
+    waterUndertaker,
+    chargeReferenceId: chargeReference.id,
+    startDate: chargePeriod.startDate,
+    endDate: chargePeriod.endDate,
+    source: chargeReference.source,
+    season: 'all year',
+    loss: chargeReference.loss,
+    credit: false,
+    chargeType: 'standard',
+    authorisedQuantity: chargeReference.reviewChargeReferences[0].amendedAuthorisedVolume,
+    billableQuantity,
+    status: 'candidate',
+    description: _description(chargeReference),
+    volume: chargeReference.volume,
+    section126Factor: Number(chargeReference.adjustments.s126) || 1,
+    section127Agreement: !!chargeReference.adjustments.s127,
+    section130Agreement: !!chargeReference.adjustments.s130,
+    secondPartCharge: true,
+    scheme: 'sroc',
+    aggregateFactor: chargeReference.reviewChargeReferences[0].amendedAggregate,
+    adjustmentFactor: chargeReference.reviewChargeReferences[0].amendedChargeAdjustment,
+    chargeCategoryCode: chargeReference.chargeCategory.reference,
+    chargeCategoryDescription: chargeReference.chargeCategory.shortDescription,
+    supportedSource: !!chargeReference.additionalCharges?.supportedSource?.name,
+    supportedSourceName: chargeReference.additionalCharges?.supportedSource?.name || null,
+    waterCompanyCharge: !!chargeReference.additionalCharges?.isSupplyPublicWater,
+    winterOnly: !!chargeReference.adjustments.winter,
+    purposes: _generateElements(chargeReference)
+  }
+}
+
+module.exports = {
+  go
+}