Match CV data to returns data for 2PT billing (#328)

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

First iteration of matching returns to charge versions. This covers the first example which is a one-to-one match.

We also have updated the results to include charge versions, charge elements and charge purposes. We intend to refine this in future iterations but we are adding them to confirm the matching algorithm is working correctly.

app/models/legacy-base.model.js

@@ -24,6 +24,7 @@ class LegacyBaseModel extends BaseModel {
     const currentPath = __dirname
     return [
       currentPath,
+      path.join(currentPath, 'returns'),
       path.join(currentPath, 'water'),
       path.join(currentPath, 'crm-v2')
     ]

app/models/returns/return.model.js

@@ -0,0 +1,31 @@
+'use strict'
+
+/**
+ * Model for return
+ * @module ReturnModel
+ */
+
+const ReturnsBaseModel = require('./returns-base.model.js')
+
+class ReturnModel extends ReturnsBaseModel {
+  static get tableName () {
+    return 'returns'
+  }
+
+  static get idColumn () {
+    return 'returnId'
+  }
+
+  static get translations () {
+    return []
+  }
+
+  // Defining which fields contain json allows us to insert an object without needing to stringify it first
+  static get jsonAttributes () {
+    return [
+      'metadata'
+    ]
+  }
+}
+
+module.exports = ReturnModel

app/models/returns/returns-base.model.js

@@ -0,0 +1,16 @@
+'use strict'
+
+/**
+ * Base class for all models based on the legacy 'returns' schema
+ * @module ReturnsBaseModel
+ */
+
+const LegacyBaseModel = require('../legacy-base.model.js')
+
+class ReturnsBaseModel extends LegacyBaseModel {
+  static get schema () {
+    return 'returns'
+  }
+}
+
+module.exports = ReturnsBaseModel

app/services/check/two-part.service.js

@@ -2,29 +2,39 @@
 
 /**
  * Used to test the Two-part tariff matching logic
- * @module SupplementaryDataService
+ * @module TwoPartService
  */
 
-const ChargeVersion = require('../../models/water/charge-version.model.js')
 const DetermineBillingPeriodsService = require('../billing/determine-billing-periods.service.js')
-const FetchRegionService = require('../billing/fetch-region.service.js')
+const LicenceModel = require('../../models/water/licence.model.js')
+const ReturnModel = require('../../models/returns/return.model.js')
 
 async function go (naldRegionId) {
-  const region = await FetchRegionService.go(naldRegionId)
   const billingPeriods = DetermineBillingPeriodsService.go()
 
   const billingPeriod = billingPeriods[1]
 
-  const licenceRefs = await ChargeVersion.query()
-    .select('licenceRef')
-    .innerJoinRelated('chargeElements')
-    .where('regionCode', naldRegionId)
+  const licences = await LicenceModel.query()
+    .select('licences.licenceRef', 'licences.licenceId')
+    .innerJoinRelated('chargeVersions.chargeElements')
+    .where('chargeVersions.regionCode', naldRegionId)
     .where('chargeVersions.scheme', 'sroc')
-    .where('startDate', '<=', billingPeriod.endDate)
-    .where('isSection127AgreementEnabled', true)
-    .whereNot('status', 'draft')
+    .where('chargeVersions.startDate', '<=', billingPeriod.endDate)
+    .where('chargeVersions:chargeElements.isSection127AgreementEnabled', true)
+    .whereNot('chargeVersions.status', 'draft')
+    .withGraphFetched('chargeVersions.chargeElements.chargePurposes')
 
-  return [region.name, billingPeriod, licenceRefs]
+  for (const licence of licences) {
+    licence.returns = await ReturnModel.query()
+      .select('returnId', 'returnRequirement', 'startDate', 'endDate')
+      .where('licenceRef', licence.licenceRef)
+      // used in the service to filter out old returns here `src/lib/services/returns/api-connector.js`
+      .where('startDate', '>=', '2008-04-01')
+      .where('startDate', '<=', billingPeriod.endDate)
+      .where('endDate', '>=', billingPeriod.startDate)
+  }
+
+  return licences
 }
 
 module.exports = {

db/migrations/20230802134043_create_returns_schema.js

@@ -0,0 +1,13 @@
+'use strict'
+
+exports.up = function (knex) {
+  return knex.raw(`
+    CREATE SCHEMA IF NOT EXISTS "returns";
+  `)
+}
+
+exports.down = function (knex) {
+  return knex.raw(`
+    DROP SCHEMA IF EXISTS "returns";
+  `)
+}

db/migrations/20230802134153_create_returns_returns.js

@@ -0,0 +1,42 @@
+'use strict'
+
+const tableName = 'returns'
+
+exports.up = async function (knex) {
+  await knex
+    .schema
+    .withSchema('returns')
+    .createTable(tableName, table => {
+      // Primary Key
+      table.string('return_id').primary()
+
+      // Data
+      table.string('regime')
+      table.string('licence_type')
+      table.string('licence_ref')
+      table.date('start_date')
+      table.date('end_date')
+      table.string('returns_frequency')
+      table.string('status')
+      table.string('source')
+      table.jsonb('metadata')
+      table.date('received_date')
+      table.string('return_requirement')
+      table.date('due_date')
+      table.boolean('under_query')
+      table.string('under_query_comment')
+      table.boolean('is_test')
+      table.uuid('return_cycle_id')
+
+      // Legacy timestamps
+      table.timestamp('created_at', { useTz: false }).notNullable().defaultTo(knex.fn.now())
+      table.timestamp('updated_at', { useTz: false }).notNullable().defaultTo(knex.fn.now())
+    })
+}
+
+exports.down = function (knex) {
+  return knex
+    .schema
+    .withSchema('returns')
+    .dropTableIfExists(tableName)
+}

test/models/returns/return.model.test.js

@@ -0,0 +1,34 @@
+'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 DatabaseHelper = require('../../support/helpers/database.helper.js')
+const ReturnHelper = require('../../support/helpers/returns/return.helper.js')
+
+// Thing under test
+const ReturnModel = require('../../../app/models/returns/return.model.js')
+
+describe('Return model', () => {
+  let testRecord
+
+  beforeEach(async () => {
+    await DatabaseHelper.clean()
+
+    testRecord = await ReturnHelper.add()
+  })
+
+  describe('Basic query', () => {
+    it('can successfully run a basic query', async () => {
+      const result = await ReturnModel.query().findById(testRecord.returnId)
+
+      expect(result).to.be.an.instanceOf(ReturnModel)
+      expect(result.returnId).to.equal(testRecord.returnId)
+    })
+  })
+})

test/support/helpers/database.helper.js

@@ -19,7 +19,7 @@ const { db } = require('../../../db/db.js')
  * identity columns. For example, if a table relies on an incrementing ID the query will reset that to 1.
  */
 async function clean () {
-  const schemas = ['water']
+  const schemas = ['water', 'returns']
 
   for (const schema of schemas) {
     const tables = await _tableNames(schema)

test/support/helpers/returns/return.helper.js

@@ -0,0 +1,74 @@
+'use strict'
+
+/**
+ * @module ReturnHelper
+ */
+
+const ReturnModel = require('../../../../app/models/returns/return.model.js')
+
+/**
+ * Add a new return
+ *
+ * If no `data` is provided, default values will be used. These are
+ *
+ * - `returnId` - v1:1:9/99/99/99/9999:10021668:2022-04-01:2023-03-31
+ * - `regime` - water
+ * - `licenceType` - abstraction
+ * - `startDate` - 2022-04-01
+ * - `endDate` - 2023-03-31
+ * - `returnsFrequency` - month
+ * - `status` - completed
+ * - `source` - NALD
+ * - `metadata` - {}
+ * - `receivedDate` - 2023-04-12
+ * - `returnRequirement` - 99999
+ * - `dueDate` - 2023-04-28
+ * - `returnCycleId` - 2eb314fe-da45-4ae9-b418-7d89a8c49c51
+ *
+ * @param {Object} [data] Any data you want to use instead of the defaults used here or in the database
+ *
+ * @returns {module:ReturnModel} The instance of the newly created record
+ */
+function add (data = {}) {
+  const insertData = defaults(data)
+
+  return ReturnModel.query()
+    .insert({ ...insertData })
+    .returning('*')
+}
+
+/**
+ * Returns the defaults used when creating a new return
+ *
+ * It will override or append to them any data provided. Mainly used by the `add()` method, we make it available
+ * for use in tests to avoid having to duplicate values.
+ *
+ * @param {Object} [data] Any data you want to use instead of the defaults used here or in the database
+ */
+function defaults (data = {}) {
+  const defaults = {
+    returnId: 'v1:1:9/99/99/99/9999:10021668:2022-04-01:2023-03-31',
+    regime: 'water',
+    licenceType: 'abstraction',
+    startDate: '2022-04-01',
+    endDate: '2023-03-31',
+    returnsFrequency: 'month',
+    status: 'completed',
+    source: 'NALD',
+    metadata: {},
+    receivedDate: '2023-04-12',
+    returnRequirement: '99999',
+    dueDate: '2023-04-28',
+    returnCycleId: '2eb314fe-da45-4ae9-b418-7d89a8c49c51'
+  }
+
+  return {
+    ...defaults,
+    ...data
+  }
+}
+
+module.exports = {
+  add,
+  defaults
+}