Add cancel bill run page (#780)

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

We need to add this to support our work to improve how bill runs are cancelled. Basically, replace the crummy legacy one!

Rather than invest time in updating the existing cancel bill run page to point to what will be our new cancel endpoint we instead are investing in rebuilding it. There are already changes we'll need to make to support work on [cancelling a two-part tariff bill run](https://eaflood.atlassian.net/browse/WATER-4189) so we may as well focus our efforts on building a replacement page.

This change adds the route, controller, presenter, service and view for a new cancel bill run page.

app/controllers/bill-runs.controller.js

@@ -7,12 +7,25 @@
 
 const Boom = require('@hapi/boom')
 
+const CancelBillRunService = require('../services/bill-runs/cancel-bill-run.service.js')
 const CreateBillRunValidator = require('../validators/create-bill-run.validator.js')
 const StartBillRunProcessService = require('../services/bill-runs/start-bill-run-process.service.js')
 const ViewBillRunService = require('../services/bill-runs/view-bill-run.service.js')
 const ReviewBillRunService = require('../services/bill-runs/two-part-tariff/review-bill-run.service.js')
 const ReviewLicenceService = require('../services/bill-runs/two-part-tariff/review-licence.service.js')
 
+async function cancel (request, h) {
+  const { id } = request.params
+
+  const pageData = await CancelBillRunService.go(id)
+
+  return h.view('bill-runs/cancel.njk', {
+    pageTitle: "You're about to cancel this bill run",
+    activeNavBar: 'bill-runs',
+    ...pageData
+  })
+}
+
 async function create (request, h) {
   const validatedData = CreateBillRunValidator.go(request.payload)
 
@@ -80,6 +93,7 @@ function _formattedInitiateBillRunError (error) {
 }
 
 module.exports = {
+  cancel,
   create,
   review,
   reviewLicence,

app/presenters/bill-runs/cancel-bill-run.presenter.js

@@ -0,0 +1,81 @@
+'use strict'
+
+/**
+ * Formats the bill run data ready for presenting in the cancel bill run confirmation page
+ * @module CancelBillRunPresenter
+ */
+
+const { capitalize, formatLongDate } = require('../base.presenter.js')
+
+/**
+ * Prepares and processes bill run data for presentation
+ *
+ * @param {module:BillRunModel} billRun - an instance of `BillRunModel`
+ *
+ * @returns {Object} - the prepared bill run data to be passed to the cancel bill run confirmation page
+ */
+function go (billRun) {
+  const {
+    batchType,
+    billRunNumber,
+    createdAt,
+    id,
+    region,
+    scheme,
+    status,
+    summer,
+    toFinancialYearEnding
+  } = billRun
+
+  return {
+    backLink: _backLink(id, status),
+    billRunId: id,
+    billRunNumber,
+    billRunStatus: status,
+    billRunType: _billRunType(batchType, summer, scheme),
+    chargeScheme: _chargeScheme(scheme),
+    dateCreated: formatLongDate(createdAt),
+    financialYear: _financialYear(toFinancialYearEnding),
+    region: capitalize(region.displayName)
+  }
+}
+
+function _backLink (id, status) {
+  if (status === 'review') {
+    return `/system/bill-runs/${id}/review`
+  }
+
+  return `/system/bill-runs/${id}`
+}
+
+function _billRunType (batchType, summer, scheme) {
+  if (batchType !== 'two_part_tariff') {
+    return capitalize(batchType)
+  }
+
+  if (scheme === 'sroc') {
+    return 'Two-part tariff'
+  }
+
+  if (summer) {
+    return 'Two-part tariff summer'
+  }
+
+  return 'Two-part tariff winter and all year'
+}
+
+function _chargeScheme (scheme) {
+  if (scheme === 'sroc') {
+    return 'Current'
+  }
+
+  return 'Old'
+}
+
+function _financialYear (financialYearEnding) {
+  return `${financialYearEnding - 1} to ${financialYearEnding}`
+}
+
+module.exports = {
+  go
+}

app/routes/bill-runs.routes.js

@@ -32,6 +32,19 @@ const routes = [
       description: 'View a bill run'
     }
   },
+  {
+    method: 'GET',
+    path: '/bill-runs/{id}/cancel',
+    handler: BillRunsController.cancel,
+    options: {
+      auth: {
+        access: {
+          scope: ['billing']
+        }
+      },
+      description: 'Confirm cancel a bill run'
+    }
+  },
   {
     method: 'GET',
     path: '/bill-runs/{id}/review',

app/services/bill-runs/cancel-bill-run.service.js

@@ -0,0 +1,51 @@
+'use strict'
+
+/**
+ * Orchestrates fetching and presenting the data needed for the cancel bill run confirmation page
+ * @module CancelBillRunService
+ */
+
+const BillRunModel = require('../../models/bill-run.model.js')
+const CancelBillRunPresenter = require('../../presenters/bill-runs/cancel-bill-run.presenter.js')
+
+/**
+ * Orchestrates fetching and presenting the data needed for the cancel bill run confirmation page
+ *
+ * @param {string} id - The UUID of the bill run to cancel
+ *
+ * @returns {Promise<Object}> an object representing the `pageData` needed by the cancel bill run template. It contains
+ * details of the bill run.
+ */
+async function go (id) {
+  const billRun = await _fetchBillRun(id)
+
+  const pageData = CancelBillRunPresenter.go(billRun)
+
+  return pageData
+}
+
+async function _fetchBillRun (id) {
+  return BillRunModel.query()
+    .findById(id)
+    .select([
+      'id',
+      'batchType',
+      'billRunNumber',
+      'createdAt',
+      'scheme',
+      'status',
+      'summer',
+      'toFinancialYearEnding'
+    ])
+    .withGraphFetched('region')
+    .modifyGraph('region', (builder) => {
+      builder.select([
+        'id',
+        'displayName'
+      ])
+    })
+}
+
+module.exports = {
+  go
+}

app/views/bill-runs/cancel.njk

@@ -0,0 +1,84 @@
+{% extends 'layout.njk' %}
+{% from "govuk/components/back-link/macro.njk" import govukBackLink %}
+{% from "govuk/components/button/macro.njk" import govukButton %}
+{% from "govuk/components/details/macro.njk" import govukDetails %}
+{% from "govuk/components/summary-list/macro.njk" import govukSummaryList %}
+{% from "govuk/components/table/macro.njk" import govukTable %}
+
+{% from "macros/badge.njk" import badge %}
+
+{% block breadcrumbs %}
+  {# Back link #}
+  {{
+    govukBackLink({
+      text: 'Back',
+      href: backLink
+    })
+  }}
+{% endblock %}
+
+{% block content %}
+  {# Main heading #}
+  <div class="govuk-body">
+    <h1 class="govuk-heading-xl govuk-!-margin-bottom-3">
+      <span class="govuk-caption-l">Bill run {{ billRunNumber }}</span>{{ pageTitle }}
+    </h1>
+  </div>
+
+  <div class="govuk-grid-row govuk-!-margin-bottom-0">
+    <div class="govuk-grid-column-full">
+
+      {# Status badge #}
+      {% if billRunStatus === 'ready' %}
+        {% set badgeType = 'info' %}
+      {% elif billRunStatus === 'sent' %}
+        {% set badgeType = 'success' %}
+      {% endif %}
+      <p class="govuk-body">
+        {{ badge(billRunStatus, badgeType) }}
+      </p>
+
+      {# Bill run meta-data #}
+      {#
+        GOV.UK summary lists only allow us to assign attributes at the top level and not to each row. This means we
+        can't assign our data-test attribute using the component. Our solution is to use the html option for each row
+        instead of text and wrap each value in a <span>. That way we can manually assign our data-test attribute to the
+        span.
+      #}
+      {{
+        govukSummaryList({
+          classes: 'govuk-summary-list--no-border',
+          attributes: {
+            'data-test': 'meta-data'
+          },
+          rows: [
+            {
+              key: { text: "Date created", classes: "meta-data__label" },
+              value: { html: '<span data-test="meta-data-created">' + dateCreated + '</span>', classes: "meta-data__value" }
+            },
+            {
+              key: { text: "Region", classes: "meta-data__label" },
+              value: { html: '<span data-test="meta-data-region">' + region + '</span>', classes: "meta-data__value" }
+            },
+            {
+              key: { text: "Bill run type", classes: "meta-data__label" },
+              value: { html: '<span data-test="meta-data-type">' + billRunType + '</span>', classes: "meta-data__value" }
+            },
+            {
+              key: { text: "Charge scheme", classes: "meta-data__label" },
+              value: { html: '<span data-test="meta-data-scheme">' + chargeScheme + '</span>', classes: "meta-data__value" }
+            },
+            {
+              key: { text: "Financial year", classes: "meta-data__label" },
+              value: { html: '<span data-test="meta-data-year">' + financialYear + '</span>', classes: "meta-data__value" }
+            }
+          ]
+        })
+      }}
+
+      <form method="post">
+        {{ govukButton({ text: "Cancel bill run" }) }}
+      </form>
+    </div>
+  </div>
+{% endblock %}

app/views/bill-runs/view.njk

@@ -116,7 +116,7 @@
 
   {# Confirm and cancel buttons #}
   {% if billRunStatus === 'ready' %}
-    {% set cancelBillRunLink = '/billing/batch/' + billRunId + '/cancel' %}
+    {% set cancelBillRunLink = '/system/bill-runs/' + billRunId + '/cancel' %}
     {% set confirmBillRunLink = '/billing/batch/' + billRunId + '/confirm' %}
     <div class="govuk-grid-row govuk-!-margin-bottom-3">
       <div class="govuk-grid-column-two-thirds">