Amend the supplementary charge version query

app/presenters/supplementary.presenter.js

@@ -27,6 +27,7 @@ class SupplementaryPresenter {
         licenceRef: chargeVersion.licenceRef,
         licenceId: chargeVersion.licenceId,
         scheme: chargeVersion.scheme,
+        startDate: chargeVersion.startDate,
         endDate: chargeVersion.endDate
       }
     })

app/services/supplementary-billing/fetch-charge-versions.service.js

@@ -8,25 +8,36 @@
 const { db } = require('../../../db/db.js')
 
 class FetchChargeVersionsService {
-  static async go (regionId) {
-    const chargeVersions = await this._fetch(regionId)
+  /**
+   * Fetch all SROC charge versions linked to licences flagged for supplementary billing that are in the period being
+   * billed
+   *
+   * > This is not the final form of the service. It is a 'work in progress' as we implement tickets that gradually
+   * > build up our understanding of SROC supplementary billing
+   *
+   * @param {string} regionId GUID of the region which the licences will be linked to
+   * @param {Object} billingPeriod Object with a `startDate` and `endDate` property representing the period being billed
+   *
+   * @returns an array of Objects containing the relevant charge versions
+   */
+  static async go (regionId, billingPeriod) {
+    const chargeVersions = await this._fetch(regionId, billingPeriod)
 
     return chargeVersions
   }
 
-  static async _fetch (regionId) {
+  static async _fetch (regionId, billingPeriod) {
     const chargeVersions = db
-      .select('chv.chargeVersionId', 'chv.scheme', 'chv.endDate', 'lic.licenceId', 'lic.licenceRef')
+      .select('chv.chargeVersionId', 'chv.scheme', 'chv.startDate', 'chv.endDate', 'lic.licenceId', 'lic.licenceRef')
       .from({ chv: 'water.charge_versions' })
       .innerJoin({ lic: 'water.licences' }, 'chv.licence_id', 'lic.licence_id')
       .where({
         scheme: 'sroc',
-        end_date: null
-      })
-      .andWhere({
         'lic.include_in_supplementary_billing': 'yes',
         'lic.region_id': regionId
       })
+      .andWhere('start_date', '>=', billingPeriod.startDate)
+      .andWhere('start_date', '<=', billingPeriod.endDate)
 
     return chargeVersions
   }

app/services/supplementary-billing/supplementary.service.js

@@ -11,12 +11,21 @@ const FetchLicencesService = require('./fetch-licences.service.js')
 const FetchRegionService = require('./fetch-region.service.js')
 const SupplementaryPresenter = require('../../presenters/supplementary.presenter.js')
 
+/**
+ * WIP: This is currently being used to generate testing data to confirm we are understanding SROC supplementary
+ * billing. We intend to refactor things so that the service starts representing what is actually required.
+ */
 class SupplementaryService {
   static async go (naldRegionId) {
     const region = await FetchRegionService.go(naldRegionId)
     const billingPeriods = BillingPeriodService.go()
     const licences = await FetchLicencesService.go(region)
-    const chargeVersions = await FetchChargeVersionsService.go(region.regionId)
+
+    // We know in the future we will be calculating multiple billing periods and so will have to iterate through each,
+    // generating bill runs and reviewing if there is anything to bill. For now, whilst our knowledge of the process
+    // is low we are focusing on just the current financial year, and intending to ship a working version for just it.
+    // This is why we are only passing through the first billing period; we know there is only one!
+    const chargeVersions = await FetchChargeVersionsService.go(region.regionId, billingPeriods[0])
 
     return this._response({ billingPeriods, licences, chargeVersions })
   }

db/migrations/20221206084612_alter_charge_versions.js

@@ -0,0 +1,21 @@
+'use strict'
+
+const tableName = 'charge_versions'
+
+exports.up = async function (knex) {
+  await knex
+    .schema
+    .withSchema('water')
+    .alterTable(tableName, table => {
+      table.date('start_date')
+    })
+}
+
+exports.down = function (knex) {
+  return knex
+    .schema
+    .withSchema('water')
+    .alterTable(tableName, table => {
+      table.dropColumns('start_date')
+    })
+}

test/presenters/supplementary.presenter.test.js

@@ -26,13 +26,15 @@ describe('Supplementary presenter', () => {
           {
             chargeVersionId: '4b5cbe04-a0e2-468c-909e-1e2d93810ba8',
             scheme: 'sroc',
+            startDate: new Date('2022-04-01'),
             endDate: null,
             licenceRef: 'AT/SROC/SUPB/01',
             licenceId: '0000579f-0f8f-4e21-b63a-063384ad32c8'
           },
           {
             chargeVersionId: '732fde85-fd3b-44e8-811f-8e6f4eb8cf6f',
             scheme: 'sroc',
+            startDate: new Date('2022-04-01'),
             endDate: null,
             licenceRef: 'AT/SROC/SUPB/01',
             licenceId: '0000579f-0f8f-4e21-b63a-063384ad32c8'

test/services/supplementary-billing/fetch-charge-versions.service.test.js

@@ -18,13 +18,19 @@ const FetchChargeVersionsService = require('../../../app/services/supplementary-
 describe('Fetch Charge Versions service', () => {
   const { region_id: regionId } = LicenceHelper.defaults()
   let testRecords
+  let billingPeriod
 
   beforeEach(async () => {
     await DatabaseHelper.clean()
   })
 
   describe('when there are licences to be included in supplementary billing', () => {
     beforeEach(async () => {
+      billingPeriod = {
+        startDate: new Date('2022-04-01'),
+        endDate: new Date('2023-03-31')
+      }
+
       // This creates an SROC charge version linked to a licence marked for supplementary billing
       const srocChargeVersion = await ChargeVersionHelper.add(
         {},
@@ -41,7 +47,7 @@ describe('Fetch Charge Versions service', () => {
     })
 
     it('returns only the current SROC charge versions that are applicable', async () => {
-      const result = await FetchChargeVersionsService.go(regionId)
+      const result = await FetchChargeVersionsService.go(regionId, billingPeriod)
 
       expect(result.length).to.equal(1)
       expect(result[0].charge_version_id).to.equal(testRecords[0].charge_version_id)
@@ -51,21 +57,31 @@ describe('Fetch Charge Versions service', () => {
   describe('when there are no licences to be included in supplementary billing', () => {
     describe("because none of them are marked 'include_in_supplementary_billing'", () => {
       beforeEach(async () => {
+        billingPeriod = {
+          startDate: new Date('2022-04-01'),
+          endDate: new Date('2023-03-31')
+        }
+
         // This creates an SROC charge version linked to a licence. But the licence won't be marked for supplementary
         // billing
         const srocChargeVersion = await ChargeVersionHelper.add()
         testRecords = [srocChargeVersion]
       })
 
       it('returns no applicable charge versions', async () => {
-        const result = await FetchChargeVersionsService.go(regionId)
+        const result = await FetchChargeVersionsService.go(regionId, billingPeriod)
 
         expect(result.length).to.equal(0)
       })
     })
 
     describe("because all the applicable charge versions are 'alcs' (presroc)", () => {
       beforeEach(async () => {
+        billingPeriod = {
+          startDate: new Date('2022-04-01'),
+          endDate: new Date('2023-03-31')
+        }
+
         // This creates an ALCS (presroc) charge version linked to a licence marked for supplementary billing
         const alcsChargeVersion = await ChargeVersionHelper.add(
           { scheme: 'alcs' },
@@ -75,31 +91,67 @@ describe('Fetch Charge Versions service', () => {
       })
 
       it('returns no applicable charge versions', async () => {
-        const result = await FetchChargeVersionsService.go(regionId)
+        const result = await FetchChargeVersionsService.go(regionId, billingPeriod)
 
         expect(result.length).to.equal(0)
       })
     })
 
-    describe('because there are no current charge versions (they all have end dates)', () => {
-      beforeEach(async () => {
-        // This creates an SROC charge version with an end date linked to a licence marked for supplementary billing
-        const alcsChargeVersion = await ChargeVersionHelper.add(
-          { end_date: new Date(2022, 2, 1) }, // 2022-03-01 - Months are zero indexed :-)
-          { include_in_supplementary_billing: 'yes' }
-        )
-        testRecords = [alcsChargeVersion]
+    describe('because there are no current charge versions', () => {
+      describe('as they all have start dates before the billing period', () => {
+        beforeEach(async () => {
+          billingPeriod = {
+            startDate: new Date('2022-04-01'),
+            endDate: new Date('2023-03-31')
+          }
+
+          // This creates an SROC charge version with a start date before the billing period. This would have been
+          // picked up by a previous bill run
+          const alcsChargeVersion = await ChargeVersionHelper.add(
+            { start_date: new Date(2022, 2, 31) }, // 2022-03-01 - Months are zero indexed :-)
+            { include_in_supplementary_billing: 'yes' }
+          )
+          testRecords = [alcsChargeVersion]
+        })
+
+        it('returns no applicable charge versions', async () => {
+          const result = await FetchChargeVersionsService.go(regionId, billingPeriod)
+
+          expect(result.length).to.equal(0)
+        })
       })
 
-      it('returns no applicable charge versions', async () => {
-        const result = await FetchChargeVersionsService.go(regionId)
+      describe('as they all have start dates after the billing period', () => {
+        beforeEach(async () => {
+          billingPeriod = {
+            startDate: new Date('2022-04-01'),
+            endDate: new Date('2023-03-31')
+          }
 
-        expect(result.length).to.equal(0)
+          // This creates an SROC charge version with a start date after the billing period. This will be picked in
+          // next years bill runs
+          const alcsChargeVersion = await ChargeVersionHelper.add(
+            { start_date: new Date(2023, 3, 1) }, // 2023-04-01 - Months are zero indexed :-)
+            { include_in_supplementary_billing: 'yes' }
+          )
+          testRecords = [alcsChargeVersion]
+        })
+
+        it('returns no applicable charge versions', async () => {
+          const result = await FetchChargeVersionsService.go(regionId, billingPeriod)
+
+          expect(result.length).to.equal(0)
+        })
       })
     })
 
     describe('because there are no licences linked to the selected region', () => {
       beforeEach(async () => {
+        billingPeriod = {
+          startDate: new Date('2022-04-01'),
+          endDate: new Date('2023-03-31')
+        }
+
         // This creates an SROC charge version linked to a licence with an different region than selected
         const otherRegionChargeVersion = await ChargeVersionHelper.add(
           {},
@@ -112,7 +164,7 @@ describe('Fetch Charge Versions service', () => {
       })
 
       it('returns no applicable charge versions', async () => {
-        const result = await FetchChargeVersionsService.go(regionId)
+        const result = await FetchChargeVersionsService.go(regionId, billingPeriod)
 
         expect(result.length).to.equal(0)
       })

test/support/helpers/charge-version.helper.js

@@ -49,7 +49,8 @@ class ChargeVersionHelper {
   static defaults (data = {}) {
     const defaults = {
       licence_ref: '01/123',
-      scheme: 'sroc'
+      scheme: 'sroc',
+      start_date: new Date('2022-04-01')
     }
 
     return {