Add new bill run volume model (#440)

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

We are currently working on the SROC two-part tariff bill. The first step of the process in the UI is to review how the returns have been matched. Our superstar design team are working on an improved design for the returns review screen but to do that they need data.

Enter our mock data service!

We previously [Create endpoint to generate fake data](#347) which was focused on a bill run. The design team would love it if we could do the same for the data the current returns review page uses.

The page relies on data in the `water.billing_volumes` table. So, the first step in generating the mock data is to add that model.

app/models/water/bill-run-volume.model.js

@@ -0,0 +1,75 @@
+'use strict'
+
+/**
+ * Model for billing_batches
+ * @module BillRunModel
+ */
+
+const { Model } = require('objection')
+
+const WaterBaseModel = require('./water-base.model.js')
+
+class BillRunVolumeModel extends WaterBaseModel {
+  static get tableName () {
+    return 'billingVolumes'
+  }
+
+  static get idColumn () {
+    return 'billingVolumeId'
+  }
+
+  static get translations () {
+    return []
+  }
+
+  static get relationMappings () {
+    return {
+      billRun: {
+        relation: Model.BelongsToOneRelation,
+        modelClass: 'bill-run.model',
+        join: {
+          from: 'billingVolumes.billingBatchId',
+          to: 'billingBatches.billingBatchId'
+        }
+      },
+      chargeReference: {
+        relation: Model.BelongsToOneRelation,
+        modelClass: 'charge-reference.model',
+        join: {
+          from: 'billingVolumes.chargeElementId',
+          to: 'chargeElements.chargeElementId'
+        }
+      }
+    }
+  }
+
+  // NOTE: When we checked the live data the only statuses we could find in use were; 10, 40, 50, 60, 70, 90 and 100
+  static get twoPartTariffStatuses () {
+    return {
+      noReturnsSubmitted: 10,
+      underQuery: 20,
+      received: 30,
+      someReturnsDue: 40,
+      lateReturns: 50,
+      overAbstraction: 60,
+      noReturnsForMatching: 70,
+      notDueForBilling: 80,
+      returnLineOverlapsChargePeriod: 90,
+      noMatchingChargeElement: 100
+    }
+  }
+
+  $twoPartTariffStatus () {
+    const index = Object.values(BillRunVolumeModel.twoPartTariffStatuses).findIndex((value) => {
+      return value === this.twoPartTariffStatus
+    })
+
+    if (index !== -1) {
+      return Object.keys(BillRunVolumeModel.twoPartTariffStatuses)[index]
+    }
+
+    return null
+  }
+}
+
+module.exports = BillRunVolumeModel

app/models/water/bill-run.model.js

@@ -42,6 +42,14 @@ class BillRunModel extends WaterBaseModel {
           from: 'billingBatches.billingBatchId',
           to: 'billingInvoices.billingBatchId'
         }
+      },
+      billRunVolumes: {
+        relation: Model.HasManyRelation,
+        modelClass: 'bill-run-volume.model',
+        join: {
+          from: 'billingBatches.billingBatchId',
+          to: 'billingVolumes.billingBatchId'
+        }
       }
     }
   }

app/models/water/charge-reference.model.js

@@ -31,6 +31,14 @@ class ChargeReferenceModel extends WaterBaseModel {
 
   static get relationMappings () {
     return {
+      billRunVolumes: {
+        relation: Model.HasManyRelation,
+        modelClass: 'bill-run-volume.model',
+        join: {
+          from: 'chargeElements.chargeElementId',
+          to: 'billingVolumes.chargeElementId'
+        }
+      },
       chargeVersion: {
         relation: Model.BelongsToOneRelation,
         modelClass: 'charge-version.model',

app/services/data/mock/generate-returns-review.service.js

@@ -0,0 +1,19 @@
+'use strict'
+
+async function go (id) {
+  const mockedReturnReviewData = {
+    id: '83a67627-f523-4a0b-8875-24e990d1c89c',
+    name: 'boo',
+    otherId: id
+  }
+
+  return _response(mockedReturnReviewData)
+}
+
+function _response (mockedReturnReviewData) {
+  return mockedReturnReviewData
+}
+
+module.exports = {
+  go
+}

app/services/data/mock/mock.service.js

@@ -7,9 +7,11 @@
 
 const ExpandedError = require('../../../errors/expanded.error.js')
 const GenerateBillRunService = require('./generate-bill-run.service.js')
+const GenerateReturnsReviewService = require('./generate-returns-review.service.js')
 
 const types = {
-  'bill-run': _billRun
+  'bill-run': _billRun,
+  'returns-review': _returnsReview
 }
 
 async function go (type, id) {
@@ -34,6 +36,10 @@ async function _billRun (id) {
   return GenerateBillRunService.go(id)
 }
 
+async function _returnsReview (id) {
+  return GenerateReturnsReviewService.go(id)
+}
+
 module.exports = {
   go
 }

db/migrations/20230929085159_create-water-billing-volumes.js

@@ -0,0 +1,33 @@
+'use strict'
+
+const tableName = 'billing_volumes'
+
+exports.up = function (knex) {
+  return knex
+    .schema
+    .withSchema('water')
+    .createTable(tableName, (table) => {
+      // Primary Key
+      table.uuid('billing_volume_id').primary().defaultTo(knex.raw('gen_random_uuid()'))
+
+      // Data
+      table.uuid('charge_element_id').notNullable()
+      table.integer('financial_year').notNullable()
+      table.boolean('is_summer').notNullable()
+      table.decimal('calculated_volume')
+      table.boolean('two_part_tariff_error').notNullable().defaultTo(false)
+      table.integer('two_part_tariff_status')
+      table.jsonb('two_part_tariff_review')
+      table.boolean('is_approved').notNullable().defaultTo(false)
+      table.uuid('billing_batch_id').notNullable()
+      table.decimal('volume')
+      table.timestamp('errored_on')
+    })
+}
+
+exports.down = function (knex) {
+  return knex
+    .schema
+    .withSchema('water')
+    .dropTableIfExists(tableName)
+}

test/models/water/bill-run-volume.model.test.js

@@ -0,0 +1,138 @@
+'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 BillRunHelper = require('../../support/helpers/water/bill-run.helper.js')
+const BillRunModel = require('../../../app/models/water/bill-run.model.js')
+const BillRunVolumeHelper = require('../../support/helpers/water/bill-run-volume.helper.js')
+const ChargeReferenceHelper = require('../../support/helpers/water/charge-reference.helper.js')
+const ChargeReferenceModel = require('../../../app/models/water/charge-reference.model.js')
+const DatabaseHelper = require('../../support/helpers/database.helper.js')
+
+// Thing under test
+const BillRunVolumeModel = require('../../../app/models/water/bill-run-volume.model.js')
+
+describe('Bill Run Volume model', () => {
+  let testRecord
+
+  beforeEach(async () => {
+    await DatabaseHelper.clean()
+  })
+
+  describe('Basic query', () => {
+    beforeEach(async () => {
+      testRecord = await BillRunVolumeHelper.add()
+    })
+
+    it('can successfully run a basic query', async () => {
+      const result = await BillRunVolumeModel.query().findById(testRecord.billingVolumeId)
+
+      expect(result).to.be.an.instanceOf(BillRunVolumeModel)
+      expect(result.billingVolumeId).to.equal(testRecord.billingVolumeId)
+    })
+  })
+
+  describe('Relationships', () => {
+    describe('when linking to bill run', () => {
+      let testBillRun
+
+      beforeEach(async () => {
+        testBillRun = await BillRunHelper.add()
+
+        const { billingBatchId } = testBillRun
+        testRecord = await BillRunVolumeHelper.add({ billingBatchId })
+      })
+
+      it('can successfully run a related query', async () => {
+        const query = await BillRunVolumeModel.query()
+          .innerJoinRelated('billRun')
+
+        expect(query).to.exist()
+      })
+
+      it('can eager load the bill run', async () => {
+        const result = await BillRunVolumeModel.query()
+          .findById(testRecord.billingVolumeId)
+          .withGraphFetched('billRun')
+
+        expect(result).to.be.instanceOf(BillRunVolumeModel)
+        expect(result.billingVolumeId).to.equal(testRecord.billingVolumeId)
+
+        expect(result.billRun).to.be.an.instanceOf(BillRunModel)
+        expect(result.billRun).to.equal(testBillRun)
+      })
+    })
+
+    describe('when linking to charge reference', () => {
+      let testChargeReference
+
+      beforeEach(async () => {
+        testChargeReference = await ChargeReferenceHelper.add()
+
+        const { chargeElementId } = testChargeReference
+        testRecord = await BillRunVolumeHelper.add({ chargeElementId })
+      })
+
+      it('can successfully run a related query', async () => {
+        const query = await BillRunVolumeModel.query()
+          .innerJoinRelated('chargeReference')
+
+        expect(query).to.exist()
+      })
+
+      it('can eager load the charge reference', async () => {
+        const result = await BillRunVolumeModel.query()
+          .findById(testRecord.billingVolumeId)
+          .withGraphFetched('chargeReference')
+
+        expect(result).to.be.instanceOf(BillRunVolumeModel)
+        expect(result.billingVolumeId).to.equal(testRecord.billingVolumeId)
+
+        expect(result.chargeReference).to.be.an.instanceOf(ChargeReferenceModel)
+        expect(result.chargeReference).to.equal(testChargeReference)
+      })
+    })
+  })
+
+  describe('Static getters', () => {
+    describe('Two Part Tariff status codes', () => {
+      it('returns the requested status code', async () => {
+        const result = BillRunVolumeModel.twoPartTariffStatuses.noReturnsSubmitted
+
+        expect(result).to.equal(10)
+      })
+    })
+  })
+
+  describe('$twoPartTariffStatus', () => {
+    describe('when the two-part tariff status is set', () => {
+      beforeEach(async () => {
+        testRecord = await BillRunVolumeHelper.add({ twoPartTariffStatus: 90 })
+      })
+
+      it('returns the status', () => {
+        const result = testRecord.$twoPartTariffStatus()
+
+        expect(result).to.equal('returnLineOverlapsChargePeriod')
+      })
+    })
+
+    describe('when the two-part tariff status is not set', () => {
+      beforeEach(async () => {
+        testRecord = await BillRunVolumeHelper.add()
+      })
+
+      it('returns null', () => {
+        const result = testRecord.$twoPartTariffStatus()
+
+        expect(result).to.be.null()
+      })
+    })
+  })
+})

test/models/water/bill-run.model.test.js

@@ -11,6 +11,8 @@ const { expect } = Code
 const BillHelper = require('../../support/helpers/water/bill.helper.js')
 const BillModel = require('../../../app/models/water/bill.model.js')
 const BillRunHelper = require('../../support/helpers/water/bill-run.helper.js')
+const BillRunVolumeHelper = require('../../support/helpers/water/bill-run-volume.helper.js')
+const BillRunVolumeModel = require('../../../app/models/water/bill-run-volume.model.js')
 const DatabaseHelper = require('../../support/helpers/database.helper.js')
 const RegionHelper = require('../../support/helpers/water/region.helper.js')
 const RegionModel = require('../../../app/models/water/region.model.js')
@@ -102,6 +104,42 @@ describe('Bill Run model', () => {
         expect(result.bills).to.include(testBills[1])
       })
     })
+
+    describe('when linking to bill run volumes', () => {
+      let testBillRunVolumes
+
+      beforeEach(async () => {
+        testRecord = await BillRunHelper.add()
+        const { billingBatchId } = testRecord
+
+        testBillRunVolumes = []
+        for (let i = 0; i < 2; i++) {
+          const billRunVolume = await BillRunVolumeHelper.add({ billingBatchId })
+          testBillRunVolumes.push(billRunVolume)
+        }
+      })
+
+      it('can successfully run a related query', async () => {
+        const query = await BillRunModel.query()
+          .innerJoinRelated('billRunVolumes')
+
+        expect(query).to.exist()
+      })
+
+      it('can eager load the bills', async () => {
+        const result = await BillRunModel.query()
+          .findById(testRecord.billingBatchId)
+          .withGraphFetched('billRunVolumes')
+
+        expect(result).to.be.instanceOf(BillRunModel)
+        expect(result.billingBatchId).to.equal(testRecord.billingBatchId)
+
+        expect(result.billRunVolumes).to.be.an.array()
+        expect(result.billRunVolumes[0]).to.be.an.instanceOf(BillRunVolumeModel)
+        expect(result.billRunVolumes).to.include(testBillRunVolumes[0])
+        expect(result.billRunVolumes).to.include(testBillRunVolumes[1])
+      })
+    })
   })
 
   describe('Static getters', () => {