Add create licence supplementary years service (#1256)

https://eaflood.atlassian.net/browse/WATER-4588
#1236

The new two-part tariff supplementary bill run requires licences to be recorded in our new LicenceSupplementaryYears table, along with the years they affect. The first ticket we picked up for this new process was amending the existing annual two-part tariff review pages. A licence can be removed from the bill run there and this should be flagged. This was added to the existing review page journey. Since starting work on the other flagging tickets it became clear that the process of adding the licence into our LicenceSupplementaryYears table is going to be repeated if we don't pull this out into its own service. So that is what this PR is for, making a service just for creating the licence record that can be shared amongst the various ways a licence can be flagged.

app/services/bill-runs/two-part-tariff/submit-remove-bill-run-licence.service.js

@@ -6,8 +6,8 @@
  */
 
 const BillRunModel = require('../../../models/bill-run.model.js')
+const CreateLicenceSupplementaryYearService = require('../../licences/supplementary/create-licence-supplementary-year.service.js')
 const LicenceModel = require('../../../models/licence.model.js')
-const LicenceSupplementaryYearModel = require('../../../models/licence-supplementary-year.model.js')
 const RemoveReviewDataService = require('./remove-review-data.service.js')
 const ReviewLicenceModel = require('../../../models/review-licence.model.js')
 
@@ -57,15 +57,11 @@ async function _allLicencesRemoved (billRunId) {
 }
 
 async function _flagForSupplementaryBilling (licenceId, billRunId) {
+  const twoPartTariff = true
   const { toFinancialYearEnding } = await BillRunModel.query()
     .findById(billRunId)
 
-  return LicenceSupplementaryYearModel.query()
-    .insert({
-      licenceId,
-      twoPartTariff: true,
-      financialYearEnd: toFinancialYearEnding
-    })
+  return CreateLicenceSupplementaryYearService.go(licenceId, [toFinancialYearEnding], twoPartTariff)
 }
 
 module.exports = {

app/services/licences/supplementary/create-licence-supplementary-year.service.js

@@ -0,0 +1,52 @@
+'use strict'
+
+/**
+ * Creates a licenceSupplementaryYears record based on the provided licence data
+ * @module CreateLicenceSupplementaryYearService
+ */
+
+const LicenceSupplementaryYearModel = require('../../../models/licence-supplementary-year.model.js')
+
+/**
+ * Creates a licenceSupplementaryYears record based on the provided licence data
+ *
+ * @param {module:LicenceModel} licenceId - The UUID of the licence to be persisted
+ * @param {Object[]} financialYearEnds - An array of the financial year ends to be persisted as individual records
+ * @param {Boolean} twoPartTariff - If there are any two-part tariff indicators on the licence
+ */
+async function go (licenceId, financialYearEnds, twoPartTariff) {
+  for (const financialYearEnd of financialYearEnds) {
+    const match = await _fetchExistingLicenceSupplementaryYears(licenceId, financialYearEnd, twoPartTariff)
+
+    // Create a new record only if no existing record matches all the provided properties, and where 'billRunId' is null
+    if (match) {
+      continue
+    }
+
+    await _persistSupplementaryBillingYearsData(licenceId, financialYearEnd, twoPartTariff)
+  }
+}
+
+async function _fetchExistingLicenceSupplementaryYears (licenceId, financialYearEnd, twoPartTariff) {
+  return LicenceSupplementaryYearModel.query()
+    .select('id')
+    .where('licenceId', licenceId)
+    .where('financialYearEnd', financialYearEnd)
+    .where('twoPartTariff', twoPartTariff)
+    .where('billRunId', null)
+    .limit(1)
+    .first()
+}
+
+async function _persistSupplementaryBillingYearsData (licenceId, financialYearEnd, twoPartTariff) {
+  return LicenceSupplementaryYearModel.query()
+    .insert({
+      licenceId,
+      financialYearEnd,
+      twoPartTariff
+    })
+}
+
+module.exports = {
+  go
+}

test/services/licences/supplementary/create-licence-supplementary-year.service.test.js

@@ -0,0 +1,98 @@
+'use strict'
+
+// Test framework dependencies
+const Lab = require('@hapi/lab')
+const Code = require('@hapi/code')
+
+const { describe, it, beforeEach } = exports.lab = Lab.script()
+const { expect } = Code
+
+// Test helpers
+const { generateUUID } = require('../../../../app/lib/general.lib.js')
+const LicenceSupplementaryYearHelper = require('../../../support/helpers/licence-supplementary-year.helper.js')
+const LicenceSupplementaryYearModel = require('../../../../app/models/licence-supplementary-year.model.js')
+
+// Thing under test
+const CreateLicenceSupplementaryYearService = require('../../../../app/services/licences/supplementary/create-licence-supplementary-year.service.js')
+
+describe('Create Licence Supplementary Years Service', () => {
+  let licenceId
+  let twoPartTariff
+  let financialYearEnds
+
+  describe('when provided a licenceId, years and twoPartTariff data', () => {
+    beforeEach(async () => {
+      licenceId = generateUUID()
+      twoPartTariff = true
+      financialYearEnds = [2023]
+    })
+
+    describe('that does not already exist', () => {
+      it('persists the data', async () => {
+        await CreateLicenceSupplementaryYearService.go(licenceId, financialYearEnds, twoPartTariff)
+
+        const result = await _fetchLicenceSupplementaryYears(licenceId)
+
+        expect(result).to.have.length(1)
+        expect(result[0]).to.equal({
+          licenceId,
+          billRunId: null,
+          financialYearEnd: financialYearEnds[0],
+          twoPartTariff
+        }, { skip: ['id'] })
+      })
+    })
+
+    describe('that already exist', () => {
+      beforeEach(async () => {
+        await LicenceSupplementaryYearHelper.add({ licenceId, financialYearEnd: 2023, twoPartTariff: true })
+      })
+
+      describe('without the billRunId', () => {
+        it('does not persist the data', async () => {
+          await CreateLicenceSupplementaryYearService.go(licenceId, financialYearEnds, twoPartTariff)
+
+          const result = await _fetchLicenceSupplementaryYears(licenceId)
+
+          expect(result).to.have.length(1)
+          expect(result[0].licenceId).to.equal(licenceId)
+        })
+      })
+
+      describe('with the billRunId', () => {
+        let billRunId
+
+        beforeEach(async () => {
+          billRunId = generateUUID()
+
+          await LicenceSupplementaryYearModel.query()
+            .update({ billRunId })
+            .where('licenceId', licenceId)
+            .orderBy('billRunId')
+        })
+
+        it('persist the data', async () => {
+          await CreateLicenceSupplementaryYearService.go(licenceId, financialYearEnds, twoPartTariff)
+
+          const result = await _fetchLicenceSupplementaryYears(licenceId)
+
+          expect(result).to.have.length(2)
+          expect(result[0].billRunId).to.equal(billRunId)
+          expect(result[1].billRunId).to.equal(null)
+        })
+      })
+    })
+  })
+})
+
+function _fetchLicenceSupplementaryYears (licenceId) {
+  return LicenceSupplementaryYearModel.query()
+    .select([
+      'id',
+      'licenceId',
+      'billRunId',
+      'financialYearEnd',
+      'twoPartTariff'
+    ])
+    .where('licenceId', licenceId)
+}