Set authorised volume for 2pt (#1037)

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

As part of the ongoing work for the two-part tariff review screens, this PR introduces the ability for the users to change the authorised volume on the charge reference.

app/controllers/bill-runs.controller.js

@@ -8,6 +8,7 @@
 const Boom = require('@hapi/boom')
 
 const AmendAdjustmentFactorService = require('../services/bill-runs/two-part-tariff/amend-adjustment-factor.service.js')
+const AmendAuthorisedVolumeService = require('../services/bill-runs/two-part-tariff/amend-authorised-volume.service.js')
 const AmendBillableReturnsService = require('../services/bill-runs/two-part-tariff/amend-billable-returns.service.js')
 const CancelBillRunService = require('../services/bill-runs/cancel-bill-run.service.js')
 const ChargeReferenceDetailsService = require('../services/bill-runs/two-part-tariff/charge-reference-details.service.js')
@@ -20,6 +21,7 @@ const ReviewLicenceService = require('../services/bill-runs/two-part-tariff/revi
 const SendBillRunService = require('../services/bill-runs/send-bill-run.service.js')
 const StartBillRunProcessService = require('../services/bill-runs/start-bill-run-process.service.js')
 const SubmitAmendedAdjustmentFactorService = require('../services/bill-runs/two-part-tariff/submit-amended-adjustment-factor.service.js')
+const SubmitAmendedAuthorisedVolumeService = require('../services/bill-runs/two-part-tariff/submit-amended-authorised-volume.service.js')
 const SubmitAmendedBillableReturnsService = require('..//services/bill-runs/two-part-tariff/submit-amended-billable-returns.service.js')
 const SubmitCancelBillRunService = require('../services/bill-runs/submit-cancel-bill-run.service.js')
 const SubmitRemoveBillRunLicenceService = require('../services/bill-runs/two-part-tariff/submit-remove-bill-run-licence.service.js')
@@ -40,6 +42,18 @@ async function amendAdjustmentFactor (request, h) {
   })
 }
 
+async function amendAuthorisedVolume (request, h) {
+  const { id: billRunId, licenceId, reviewChargeReferenceId } = request.params
+
+  const pageData = await AmendAuthorisedVolumeService.go(billRunId, licenceId, reviewChargeReferenceId)
+
+  return h.view('bill-runs/amend-authorised-volume.njk', {
+    pageTitle: 'Set the authorised volume',
+    activeNavBar: 'bill-runs',
+    ...pageData
+  })
+}
+
 async function amendBillableReturns (request, h) {
   const { id: billRunId, licenceId, reviewChargeElementId } = request.params
 
@@ -180,6 +194,23 @@ async function submitAmendedAdjustmentFactor (request, h) {
   return h.redirect(`/system/bill-runs/${billRunId}/review/${licenceId}/charge-reference-details/${reviewChargeReferenceId}`)
 }
 
+async function submitAmendedAuthorisedVolume (request, h) {
+  const { id: billRunId, licenceId, reviewChargeReferenceId } = request.params
+  const pageData = await SubmitAmendedAuthorisedVolumeService.go(
+    billRunId,
+    licenceId,
+    reviewChargeReferenceId,
+    request.payload,
+    request.yar
+  )
+
+  if (pageData.error) {
+    return h.view('bill-runs/amend-authorised-volume.njk', pageData)
+  }
+
+  return h.redirect(`/system/bill-runs/${billRunId}/review/${licenceId}/charge-reference-details/${reviewChargeReferenceId}`)
+}
+
 async function submitAmendedBillableReturns (request, h) {
   const { id: billRunId, licenceId, reviewChargeElementId } = request.params
 
@@ -268,6 +299,7 @@ async function view (request, h) {
 
 module.exports = {
   amendAdjustmentFactor,
+  amendAuthorisedVolume,
   amendBillableReturns,
   cancel,
   chargeReferenceDetails,
@@ -279,6 +311,7 @@ module.exports = {
   reviewLicence,
   send,
   submitAmendedAdjustmentFactor,
+  submitAmendedAuthorisedVolume,
   submitAmendedBillableReturns,
   submitCancel,
   submitReview,

app/presenters/bill-runs/two-part-tariff/amend-authorised-volume.presenter.js

@@ -0,0 +1,58 @@
+'use strict'
+
+/**
+ * Formats the two part tariff review data ready for presenting in the amend authorised volume page
+ * @module AmendAuthorisedVolumePresenter
+ */
+
+const { formatLongDate, formatFinancialYear } = require('../../base.presenter.js')
+
+/**
+ * Prepares and processes bill run and review charge reference data for presenting
+ *
+ * @param {module:BillRunModel} billRun - the data from the bill run
+ * @param {module:ReviewChargeReference} reviewChargeReference - the data from the review charge reference
+ * @param {String} licenceId - the UUID of the licence being reviewed
+ *
+ * @returns {Object} the prepared bill run and charge reference data to be passed to the amend authorised volume page
+ */
+function go (billRun, reviewChargeReference, licenceId) {
+  return {
+    billRunId: billRun.id,
+    licenceId,
+    financialYear: formatFinancialYear(billRun.toFinancialYearEnding),
+    chargePeriod: _prepareDate(
+      reviewChargeReference.reviewChargeVersion.chargePeriodStartDate,
+      reviewChargeReference.reviewChargeVersion.chargePeriodEndDate
+    ),
+    chargeReference: {
+      id: reviewChargeReference.id,
+      description: reviewChargeReference.chargeReference.chargeCategory.shortDescription,
+      authorisedVolume: reviewChargeReference.amendedAuthorisedVolume,
+      totalBillableReturns: _totalBillableReturns(reviewChargeReference.reviewChargeElements)
+    },
+    chargeCategory: {
+      minVolume: reviewChargeReference.chargeReference.chargeCategory.minVolume,
+      maxVolume: reviewChargeReference.chargeReference.chargeCategory.maxVolume
+    }
+  }
+}
+
+function _prepareDate (startDate, endDate) {
+  const preparedStartDate = formatLongDate(startDate)
+  const preparedEndDate = formatLongDate(endDate)
+
+  return `${preparedStartDate} to ${preparedEndDate}`
+}
+
+function _totalBillableReturns (reviewChargeElements) {
+  return reviewChargeElements.reduce((total, reviewChargeElement) => {
+    total += reviewChargeElement.amendedAllocated
+
+    return total
+  }, 0)
+}
+
+module.exports = {
+  go
+}

app/presenters/bill-runs/two-part-tariff/charge-reference-details.presenter.js

@@ -31,7 +31,7 @@ function go (billRun, reviewChargeReference, licenceId) {
       reference: reviewChargeReference.chargeReference.chargeCategory.reference,
       description: reviewChargeReference.chargeReference.chargeCategory.shortDescription,
       totalBillableReturns: _totalBillableReturns(reviewChargeReference.reviewChargeElements),
-      authorisedVolume: reviewChargeReference.chargeReference.volume,
+      authorisedVolume: reviewChargeReference.amendedAuthorisedVolume,
       adjustments,
       additionalCharges: _additionalCharges(reviewChargeReference.chargeReference)
     },

app/routes/bill-runs.routes.js

@@ -162,6 +162,32 @@ const routes = [
       description: 'Review a charge reference from a two-part tariff licence'
     }
   },
+  {
+    method: 'GET',
+    path: '/bill-runs/{id}/review/{licenceId}/charge-reference-details/{reviewChargeReferenceId}/amend-authorised-volume',
+    handler: BillRunsController.amendAuthorisedVolume,
+    options: {
+      auth: {
+        access: {
+          scope: ['billing']
+        }
+      },
+      description: 'Amend a charge references authorised volume from a two-part tariff licence'
+    }
+  },
+  {
+    method: 'POST',
+    path: '/bill-runs/{id}/review/{licenceId}/charge-reference-details/{reviewChargeReferenceId}/amend-authorised-volume',
+    handler: BillRunsController.submitAmendedAuthorisedVolume,
+    options: {
+      auth: {
+        access: {
+          scope: ['billing']
+        }
+      },
+      description: 'Submit the amended charge references authorised volume from a two-part tariff licence'
+    }
+  },
   {
     method: 'GET',
     path: '/bill-runs/{id}/review/{licenceId}/charge-reference-details/{reviewChargeReferenceId}/amend-adjustment-factor',

app/services/bill-runs/two-part-tariff/amend-authorised-volume.service.js

@@ -0,0 +1,30 @@
+'use strict'
+
+/**
+ * Orchestrates fetching and presenting the data needed for the amend authorised volume page
+ * @module AmendAuthorisedVolumeService
+ */
+
+const AmendAuthorisedVolumePresenter = require('../../../presenters/bill-runs/two-part-tariff/amend-authorised-volume.presenter.js')
+const FetchAuthorisedVolumeService = require('./fetch-authorised-volume.service.js')
+
+/**
+ * Orchestrates fetching and presenting the data needed for the amend authorised volume page
+ *
+ * @param {String} billRunId - The UUID for the bill run
+ * @param {String} licenceId - The UUID of the licence that is being reviewed
+ * @param {String} reviewChargeReferenceId - The UUID of the review charge reference being viewed
+ *
+ * @returns {Promise<Object>} the 'pageData' needed to view the amend authorised volume page
+ */
+async function go (billRunId, licenceId, reviewChargeReferenceId) {
+  const { billRun, reviewChargeReference } = await FetchAuthorisedVolumeService.go(billRunId, reviewChargeReferenceId)
+
+  const pageData = AmendAuthorisedVolumePresenter.go(billRun, reviewChargeReference, licenceId)
+
+  return pageData
+}
+
+module.exports = {
+  go
+}

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

@@ -0,0 +1,70 @@
+'use strict'
+
+/**
+ * Fetches the individual charge reference details when the authorised volume is being amended for a two-part tariff
+ * bill run
+ * @module FetchAuthorisedVolumeService
+ */
+
+const BillRunModel = require('../../../models/bill-run.model.js')
+const ReviewChargeReferenceModel = require('../../../models/review-charge-reference.model.js')
+
+/**
+ * Fetches the charge reference details for an individual licence
+ *
+ * @param {String} billRunId - UUID of the bill run
+ * @param {String} reviewChargeReferenceId - The UUID of the review charge reference being viewed
+ *
+ * @returns {Promise<Object>} An object containing the bill run and review charge reference instances
+ */
+async function go (billRunId, reviewChargeReferenceId) {
+  const billRun = await _fetchBillRun(billRunId)
+  const reviewChargeReference = await _fetchReviewChargeReference(reviewChargeReferenceId)
+
+  return { billRun, reviewChargeReference }
+}
+
+async function _fetchBillRun (billRunId) {
+  return BillRunModel.query()
+    .findById(billRunId)
+    .select(
+      'id',
+      'toFinancialYearEnding')
+}
+
+async function _fetchReviewChargeReference (reviewChargeReferenceId) {
+  return ReviewChargeReferenceModel.query()
+    .findById(reviewChargeReferenceId)
+    .select('id', 'amendedAuthorisedVolume')
+    .withGraphFetched('chargeReference')
+    .modifyGraph('chargeReference', (builder) => {
+      builder.select([
+        'chargeCategoryId'
+      ])
+    })
+    .withGraphFetched('chargeReference.chargeCategory')
+    .modifyGraph('chargeReference.chargeCategory', (builder) => {
+      builder.select([
+        'shortDescription',
+        'minVolume',
+        'maxVolume'
+      ])
+    })
+    .withGraphFetched('reviewChargeVersion')
+    .modifyGraph('reviewChargeVersion', (builder) => {
+      builder.select([
+        'chargePeriodStartDate',
+        'chargePeriodEndDate'
+      ])
+    })
+    .withGraphFetched('reviewChargeElements')
+    .modifyGraph('reviewChargeElements', (builder) => {
+      builder.select([
+        'amendedAllocated'
+      ])
+    })
+}
+
+module.exports = {
+  go
+}

app/services/bill-runs/two-part-tariff/submit-amended-authorised-volume.service.js

@@ -0,0 +1,68 @@
+'use strict'
+
+/**
+ * Orchestrates validating and patching the data for the amend authorised volume page
+ * @module SubmitAmendedAuthorisedVolumeService
+*/
+
+const AmendAuthorisedVolumePresenter = require('../../../presenters/bill-runs/two-part-tariff/amend-authorised-volume.presenter.js')
+const AuthorisedVolumeValidator = require('../../../validators/bill-runs/two-part-tariff/authorised-volume.validator.js')
+const FetchAuthorisedVolumeService = require('./fetch-authorised-volume.service.js')
+const ReviewChargeReferenceModel = require('../../../models/review-charge-reference.model.js')
+
+/**
+ * Orchestrates validating the data for the amend authorised volume page and patching the db value
+ *
+ * @param {String} billRunId - The UUID for the bill run
+ * @param {String} licenceId - The UUID of the licence that is being reviewed
+ * @param {String} reviewChargeReferenceId - The UUID of the review charge reference being updated
+ * @param {Object} payload - The submitted form data
+ * @param {Object} yar - The Hapi `request.yar` session manager passed on by the controller
+ *
+ * @returns {Promise<Object>} The updated value for the authorised volume
+ */
+async function go (billRunId, licenceId, reviewChargeReferenceId, payload, yar) {
+  const validationResult = _validate(payload)
+
+  if (!validationResult) {
+    await _persistAuthorisedVolume(reviewChargeReferenceId, payload)
+    yar.flash('banner', 'The authorised volume for this licence have been updated')
+
+    return { error: null }
+  }
+
+  const { billRun, reviewChargeReference } = await FetchAuthorisedVolumeService.go(billRunId, reviewChargeReferenceId)
+
+  const pageData = AmendAuthorisedVolumePresenter.go(billRun, reviewChargeReference, licenceId)
+
+  return {
+    activeNavBar: 'search',
+    pageTitle: 'Set the authorised volume',
+    error: validationResult,
+    ...pageData
+  }
+}
+
+async function _persistAuthorisedVolume (reviewChargeReferenceId, payload) {
+  return ReviewChargeReferenceModel.query()
+    .findById(reviewChargeReferenceId)
+    .patch({ amendedAuthorisedVolume: payload.authorisedVolume })
+}
+
+function _validate (payload) {
+  const validation = AuthorisedVolumeValidator.go(payload)
+
+  if (!validation.error) {
+    return null
+  }
+
+  const authorisedVolume = validation.error.details[0].message
+
+  return {
+    authorisedVolume
+  }
+}
+
+module.exports = {
+  go
+}