Flag licences removed from workflow for supp billing

app/services/licences/supplementary/determine-workflow-years.service.js

@@ -0,0 +1,60 @@
+'use strict'
+
+/**
+ * Determines if a licence being removed from workflow should be flagged for supplementary billing
+ * @module DetermineWorkflowYearsService
+ */
+
+const FetchLicenceService = require('./fetch-licence.service.js')
+const { determineCurrentFinancialYear } = require('../../../lib/general.lib.js')
+const LicenceModel = require('../../../models/licence.model.js')
+
+/**
+ * Determines if a licence being removed from workflow should be flagged for supplementary billing and two-part tariff
+ * supplementary billing.
+ *
+ * The service is passed the id of a workflow record and determines if it should be flagged for any supplementary
+ * billing. This is worked out based on the licences charge information data. If the licence has any charge versions
+ * that are sroc we can flag it for supplementary billing and two-part tariff then we set flagForBilling to true.
+ *
+ * The flags are then passed back to the service this was called from, where it works out which years the two-part
+ * tariff flags should be put on.
+ *
+ * @param {string} workflowId - The UUID for the workflow record to fetch
+ *
+ * @returns {object} - An object containing the related licence, charge information start and end date and if the
+ * licence should be flagged for two-part tariff supplementary billing
+ */
+async function go (workflowId) {
+  const licence = await FetchLicenceService.go(workflowId)
+  const { endDate } = determineCurrentFinancialYear()
+
+  // Due to the fact the database gives us the licence back in snake case, we need to convert the references to camel
+  // case so the other services can use the result
+  const result = {
+    licence: {
+      id: licence.id,
+      regionId: licence.region_id
+    },
+    startDate: licence.created_at,
+    endDate,
+    twoPartTariff: licence.two_part_tariff_charge_versions,
+    flagForBilling: false
+  }
+
+  if (!licence.include_in_sroc_billing && licence.sroc_charge_versions) {
+    await _flagForSrocSupplementary(licence.id)
+  }
+
+  result.flagForBilling = result.twoPartTariff
+
+  return result
+}
+
+async function _flagForSrocSupplementary (id) {
+  return LicenceModel.query().patch({ includeInSrocBilling: true }).where('id', id)
+}
+
+module.exports = {
+  go
+}

app/services/licences/supplementary/fetch-licence.service.js

@@ -0,0 +1,72 @@
+'use strict'
+
+/**
+ * Fetches existing supplementary details about a licence being removed from workflow
+ * @module FetchLicenceService
+ */
+
+const { db } = require('../../../../db/db.js')
+
+/**
+ * Fetches existing supplementary details about a licence being removed from workflow
+ *
+ * We need to get the `created at` date from the workflow record to determine which supplementary years we need to flag.
+ * The query also determines what sroc or two-part tariff charge versions the licence has.
+ *
+ * When processing the flags we have to work out whether to include the licence in sroc supplementary billing or in
+ * two-part tariff supplementary billing.
+ *
+ * NOTE: We do not care about pre sroc charge versions. We are not setting the `include_in_pre_sroc_billing` flag due to
+ * using the old billing engine that then generates £0 bill runs. Only our new sroc billing engines can handle £0 bill
+ * runs.
+ *
+ * @param {string} workflowId - The UUID for the workflow record related to the licence
+ *
+ * @returns {Promise<object>} - The data needed to determine which supplementary flags the licence needs
+ */
+async function go (workflowId) {
+  const query = _query()
+
+  const { rows: [row] } = await db.raw(query, [workflowId])
+
+  return row
+}
+
+function _query () {
+  return `
+    SELECT
+    l.include_in_sroc_billing,
+    l.id,
+    l.region_id,
+    EXISTS (
+      SELECT 1
+      FROM public.charge_versions cv
+      WHERE cv.licence_id = l.id
+        AND cv.start_date > '2022-03-31'
+    ) AS sroc_charge_versions,
+    EXISTS (
+      SELECT 1
+      FROM public.charge_references cr
+      INNER JOIN public.charge_elements ce
+        ON ce.charge_reference_id = cr.id
+      WHERE cr.charge_version_id = (
+        SELECT cv.id
+        FROM public.charge_versions cv
+        WHERE cv.licence_id = l.id
+          AND cv.start_date > '2022-03-31'
+        LIMIT 1
+      )
+      AND ce.section_127_Agreement = TRUE
+      AND cr.adjustments->>'s127' = 'true'
+    ) AS two_part_tariff_charge_versions,
+    w.created_at
+    FROM licences l
+    INNER JOIN workflows w
+      ON l.id = w.licence_id
+    WHERE w.id = ?
+`
+}
+
+module.exports = {
+  go
+}

app/services/licences/supplementary/process-billing-flag.service.js

@@ -10,13 +10,15 @@ const DetermineBillingYearsService = require('./determine-billing-years.service.
 const DetermineExistingBillRunYearsService = require('./determine-existing-bill-run-years.service.js')
 const DetermineChargeVersionYearsService = require('./determine-charge-version-years.service.js')
 const DetermineReturnLogYearsService = require('./determine-return-log-years.service.js')
+const DetermineWorkflowYearsService = require('./determine-workflow-years.service.js')
 const { calculateAndLogTimeTaken, currentTimeInNanoseconds } = require('../../../lib/general.lib.js')
 
 /**
  * Orchestrates flagging a licence for supplementary billing
  *
  * This service orchestrates the process of flagging a licence for supplementary billing.
- * It retrieves details of the charge version, including the licence information, start and end dates, whether the
+ * Based on the ID the service receives (chargeVersionId, returnId, workflowId) it retrieves details of the related
+ * charge version, including the licence information, start and end dates, whether the
  * charge version has two-part tariff indicators, and if it should be flagged for supplementary billing.
  *
  * If the licence qualifies for flagging, the relevant dates are passed to the `DetermineBillingYearsService`, which
@@ -42,6 +44,8 @@ async function go (payload) {
       result = await DetermineChargeVersionYearsService.go(payload.chargeVersionId)
     } else if (payload.returnId) {
       result = await DetermineReturnLogYearsService.go(payload.returnId)
+    } else if (payload.workflowId) {
+      result = await DetermineWorkflowYearsService.go(payload.workflowId)
     } else {
       return
     }

test/services/licences/supplementary/determine-workflow-years.service.test.js

@@ -0,0 +1,119 @@
+'use strict'
+
+// Test framework dependencies
+const Lab = require('@hapi/lab')
+const Code = require('@hapi/code')
+const Sinon = require('sinon')
+
+const { describe, it, before, beforeEach, afterEach } = exports.lab = Lab.script()
+const { expect } = Code
+
+// Test helpers
+const { determineCurrentFinancialYear } = require('../../../../app/lib/general.lib.js')
+const LicenceHelper = require('../../../support/helpers/licence.helper.js')
+const LicenceModel = require('../../../../app/models/licence.model.js')
+
+// Things we need to stub
+const FetchLicenceService = require('../../../../app/services/licences/supplementary/fetch-licence.service.js')
+
+// Thing under test
+const DetermineWorkflowYearsService = require('../../../../app/services/licences/supplementary/determine-workflow-years.service.js')
+
+describe('Determine Workflow Years Service', () => {
+  const currentFinancialYear = determineCurrentFinancialYear()
+  const workflowId = '1c995768-35fe-45c4-bb80-dc242052e94d'
+
+  let licence
+  let licenceData
+
+  before(async () => {
+    licence = await LicenceHelper.add()
+    licenceData = {
+      include_in_sroc_billing: false,
+      id: licence.id,
+      region_id: licence.regionId,
+      sroc_charge_versions: false,
+      two_part_tariff_charge_versions: false,
+      created_at: new Date('2024-04-01')
+    }
+  })
+
+  afterEach(() => {
+    Sinon.restore()
+  })
+
+  describe('when passed a workflowId', () => {
+    describe('that relates to a licence with no sroc charge versions', () => {
+      beforeEach(async () => {
+        Sinon.stub(FetchLicenceService, 'go').resolves(licenceData)
+      })
+
+      it('returns flagForBilling and twoPartTariff as false', async () => {
+        const result = await DetermineWorkflowYearsService.go(workflowId)
+
+        expect(result.twoPartTariff).to.equal(false)
+        expect(result.flagForBilling).to.equal(false)
+      })
+
+      it('does not flag the licence for sroc supplementary billing', async () => {
+        await DetermineWorkflowYearsService.go(workflowId)
+
+        const result = await LicenceModel.query().findById(licence.id)
+
+        expect(result.includeInSrocBilling).to.equal(false)
+      })
+    })
+
+    describe('that relates to a licence with sroc charge versions', () => {
+      describe('but has no two-part tariff indicators', () => {
+        beforeEach(async () => {
+          licenceData.sroc_charge_versions = true
+
+          Sinon.stub(FetchLicenceService, 'go').resolves(licenceData)
+        })
+
+        it('flags the licence for sroc supplementary billing', async () => {
+          await DetermineWorkflowYearsService.go(workflowId)
+
+          const result = await LicenceModel.query().findById(licence.id)
+
+          expect(result.includeInSrocBilling).to.equal(true)
+        })
+
+        it('returns the licence data', async () => {
+          const result = await DetermineWorkflowYearsService.go(workflowId)
+
+          expect(result.licence.id).to.equal(licence.id)
+          expect(result.licence.regionId).to.equal(licence.regionId)
+          expect(result.startDate).to.equal(new Date('2024-04-01'))
+          expect(result.endDate).to.equal(currentFinancialYear.endDate)
+        })
+
+        it('returns the flagForBilling and twoPartTariff as false', async () => {
+          const result = await DetermineWorkflowYearsService.go(workflowId)
+
+          expect(result.twoPartTariff).to.equal(false)
+          expect(result.flagForBilling).to.equal(false)
+        })
+      })
+    })
+
+    describe('that relates to a licence with sroc two-part tariff charge versions', () => {
+      describe('and the licence is already flagged for sroc supplementary billing', () => {
+        before(async () => {
+          licenceData.two_part_tariff_charge_versions = true
+          licenceData.include_in_sroc_billing = true
+
+          Sinon.stub(FetchLicenceService, 'go').resolves(licenceData)
+        })
+
+        it('returns flagForBilling and twoPartTariff as true', async () => {
+          const result = await DetermineWorkflowYearsService.go(workflowId)
+
+          expect(result.twoPartTariff).to.equal(true)
+          expect(result.flagForBilling).to.equal(true)
+        })
+      })
+    })
+  })
+})

test/services/licences/supplementary/fetch-licence.service.test.js

@@ -0,0 +1,58 @@
+'use strict'
+
+// Test framework dependencies
+const Lab = require('@hapi/lab')
+const Code = require('@hapi/code')
+
+const { describe, it, before } = exports.lab = Lab.script()
+const { expect } = Code
+
+// Test helpers
+const ChargeElementHelper = require('../../../support/helpers/charge-element.helper.js')
+const ChargeReferenceHelper = require('../../../support/helpers/charge-reference.helper.js')
+const ChargeVersionHelper = require('../../../support/helpers/charge-version.helper.js')
+const LicenceHelper = require('../../../support/helpers/licence.helper.js')
+const WorkflowHelper = require('../../../support/helpers/workflow.helper.js')
+
+// Thing under test
+const FetchLicenceService = require('../../../../app/services/licences/supplementary/fetch-licence.service.js')
+
+describe('Fetch Licence Service', () => {
+  let workflow
+
+  describe('when passed a valid workflow id', () => {
+    let licence
+
+    before(async () => {
+      licence = await LicenceHelper.add()
+
+      workflow = await WorkflowHelper.add({ licenceId: licence.id })
+
+      // sroc charge version
+      const chargeVersion = await ChargeVersionHelper.add({ licenceId: licence.id })
+
+      // two-part tariff indicators
+      const chargeReference = await ChargeReferenceHelper.add(
+        { chargeVersionId: chargeVersion.id, adjustments: { s127: true } }
+      )
+
+      await ChargeElementHelper.add({ chargeReferenceId: chargeReference.id })
+    })
+
+    it('fetches the licence data related to that workflow record', async () => {
+      const result = await FetchLicenceService.go(workflow.id)
+
+      expect(result.id).to.equal(licence.id)
+      expect(result.region_id).to.equal(licence.regionId)
+      expect(result.include_in_sroc_billing).to.equal(licence.includeInSrocBilling)
+      expect(result.created_at).to.equal(workflow.createdAt)
+    })
+
+    it('outlines which charge versions the licence has', async () => {
+      const result = await FetchLicenceService.go(workflow.id)
+
+      expect(result.sroc_charge_versions).to.equal(true)
+      expect(result.two_part_tariff_charge_versions).to.equal(true)
+    })
+  })
+})