Add return requirements models to project (#1071)

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

So far, the new returns requirements functionality supports setting up a new return version and its requirements. But the data is held only in a temporary session.

Alongside this, we've been making changes to the legacy return requirements tables so they can support the new properties we will record in our version of the returns requirement setup journey.

We now want to create new return requirements by copying an existing one, persist those that have been setup during the journey, and in the future, generate return logs using this information.

All this will require the tables to be represented as [Objection.js models](https://vincit.github.io/objection.js/). This change adds the models, the views, and all the supporting elements in preparation for this work.

app/models/licence.model.js

@@ -72,6 +72,14 @@ class LicenceModel extends BaseModel {
           to: 'returnLogs.licenceRef'
         }
       },
+      returnVersions: {
+        relation: Model.HasManyRelation,
+        modelClass: 'return-version.model',
+        join: {
+          from: 'licences.id',
+          to: 'returnVersions.licenceId'
+        }
+      },
       reviewLicences: {
         relation: Model.HasManyRelation,
         modelClass: 'review-licence.model',

app/models/purpose.model.js

@@ -39,6 +39,14 @@ class PurposeModel extends BaseModel {
           from: 'purposes.id',
           to: 'licenceVersionPurposes.purposeId'
         }
+      },
+      returnRequirementPurposes: {
+        relation: Model.HasManyRelation,
+        modelClass: 'return-requirement-purpose.model',
+        join: {
+          from: 'purposes.id',
+          to: 'returnRequirementPurposes.purposeId'
+        }
       }
     }
   }

app/models/return-requirement-point.model.js

@@ -0,0 +1,31 @@
+'use strict'
+
+/**
+ * Model for return_requirement_points (water.return_requirement_points)
+ * @module ReturnRequirementPointModel
+ */
+
+const { Model } = require('objection')
+
+const BaseModel = require('./base.model.js')
+
+class ReturnRequirementPointModel extends BaseModel {
+  static get tableName () {
+    return 'returnRequirementPoints'
+  }
+
+  static get relationMappings () {
+    return {
+      returnRequirement: {
+        relation: Model.BelongsToOneRelation,
+        modelClass: 'return-requirement.model',
+        join: {
+          from: 'returnRequirementPoints.returnRequirementId',
+          to: 'returnRequirements.id'
+        }
+      }
+    }
+  }
+}
+
+module.exports = ReturnRequirementPointModel

app/models/return-requirement-purpose.model.js

@@ -0,0 +1,39 @@
+'use strict'
+
+/**
+ * Model for return_requirement_purposes (water.return_requirement_purposes)
+ * @module ReturnRequirementPurposeModel
+ */
+
+const { Model } = require('objection')
+
+const BaseModel = require('./base.model.js')
+
+class ReturnRequirementPurposeModel extends BaseModel {
+  static get tableName () {
+    return 'returnRequirementPurposes'
+  }
+
+  static get relationMappings () {
+    return {
+      purpose: {
+        relation: Model.BelongsToOneRelation,
+        modelClass: 'purpose.model',
+        join: {
+          from: 'returnRequirementPurposes.purposeId',
+          to: 'purposes.id'
+        }
+      },
+      returnRequirement: {
+        relation: Model.BelongsToOneRelation,
+        modelClass: 'return-requirement.model',
+        join: {
+          from: 'returnRequirementPurposes.returnRequirementId',
+          to: 'returnRequirements.id'
+        }
+      }
+    }
+  }
+}
+
+module.exports = ReturnRequirementPurposeModel

app/models/return-requirement.model.js

@@ -0,0 +1,47 @@
+'use strict'
+
+/**
+ * Model for return_requirements (water.return_requirements)
+ * @module ReturnRequirementModel
+ */
+
+const { Model } = require('objection')
+
+const BaseModel = require('./base.model.js')
+
+class ReturnRequirementModel extends BaseModel {
+  static get tableName () {
+    return 'returnRequirements'
+  }
+
+  static get relationMappings () {
+    return {
+      returnRequirementPoints: {
+        relation: Model.HasManyRelation,
+        modelClass: 'return-requirement-point.model',
+        join: {
+          from: 'returnRequirements.id',
+          to: 'returnRequirementPoints.returnRequirementId'
+        }
+      },
+      returnRequirementPurposes: {
+        relation: Model.HasManyRelation,
+        modelClass: 'return-requirement-purpose.model',
+        join: {
+          from: 'returnRequirements.id',
+          to: 'returnRequirementPurposes.returnRequirementId'
+        }
+      },
+      returnVersion: {
+        relation: Model.BelongsToOneRelation,
+        modelClass: 'return-version.model',
+        join: {
+          from: 'returnRequirements.returnVersionId',
+          to: 'returnVersions.id'
+        }
+      }
+    }
+  }
+}
+
+module.exports = ReturnRequirementModel

app/models/return-version.model.js

@@ -0,0 +1,39 @@
+'use strict'
+
+/**
+ * Model for return_versions (water.return_versions)
+ * @module ReturnVersionModel
+ */
+
+const { Model } = require('objection')
+
+const BaseModel = require('./base.model.js')
+
+class ReturnVersionModel extends BaseModel {
+  static get tableName () {
+    return 'returnVersions'
+  }
+
+  static get relationMappings () {
+    return {
+      licence: {
+        relation: Model.BelongsToOneRelation,
+        modelClass: 'licence.model',
+        join: {
+          from: 'returnVersions.licenceId',
+          to: 'licences.id'
+        }
+      },
+      returnRequirements: {
+        relation: Model.HasManyRelation,
+        modelClass: 'return-requirement.model',
+        join: {
+          from: 'returnVersions.id',
+          to: 'returnRequirements.returnVersionId'
+        }
+      }
+    }
+  }
+}
+
+module.exports = ReturnVersionModel

db/migrations/legacy/20221108007023_water-return-versions.js

@@ -15,12 +15,15 @@ exports.up = function (knex) {
       table.integer('version_number').notNullable()
       table.date('start_date').notNullable()
       table.date('end_date')
-      table.string('status water').notNullable()
+      table.string('status').notNullable()
       table.string('external_id')
+      table.text('reason')
+      table.boolean('multiple_upload').notNullable().defaultTo(false)
+      table.text('notes')
 
       // Legacy timestamps
-      table.timestamp('date_created', { useTz: false }).notNullable()
-      table.timestamp('date_updated', { useTz: false })
+      table.timestamp('date_created', { useTz: false }).notNullable().defaultTo(knex.fn.now())
+      table.timestamp('date_updated', { useTz: false }).notNullable().defaultTo(knex.fn.now())
 
       // Constraints
       table.unique(['external_id'], { useConstraint: true })

db/migrations/legacy/20221108007024_water-return-requirements.js

@@ -13,8 +13,8 @@ exports.up = function (knex) {
       // Data
       table.uuid('return_version_id').notNullable()
       table.string('returns_frequency').notNullable()
-      table.boolean('is_summer').notNullable()
-      table.boolean('is_upload').notNullable()
+      table.boolean('is_summer').notNullable().defaultTo(false)
+      table.boolean('is_upload').notNullable().defaultTo(false)
       table.smallint('abstraction_period_start_day')
       table.smallint('abstraction_period_start_month')
       table.smallint('abstraction_period_end_day')
@@ -23,10 +23,15 @@ exports.up = function (knex) {
       table.string('description')
       table.integer('legacy_id')
       table.string('external_id')
+      table.text('collection_frequency').notNullable().defaultTo('day')
+      table.boolean('gravity_fill').notNullable().defaultTo(false)
+      table.boolean('reabstraction').notNullable().defaultTo(false)
+      table.boolean('two_part_tariff').notNullable().defaultTo(false)
+      table.boolean('fifty_six_exception').notNullable().defaultTo(false)
 
       // Legacy timestamps
-      table.timestamp('date_created', { useTz: false }).notNullable()
-      table.timestamp('date_updated', { useTz: false })
+      table.timestamp('date_created', { useTz: false }).notNullable().defaultTo(knex.fn.now())
+      table.timestamp('date_updated', { useTz: false }).notNullable().defaultTo(knex.fn.now())
 
       // Constraints
       table.unique(['external_id'], { useConstraint: true })

db/migrations/legacy/20221108007025_water-return-requirement-purposes.js

@@ -19,8 +19,8 @@ exports.up = function (knex) {
       table.string('external_id')
 
       // Legacy timestamps
-      table.timestamp('date_created', { useTz: false }).notNullable()
-      table.timestamp('date_updated', { useTz: false })
+      table.timestamp('date_created', { useTz: false }).notNullable().defaultTo(knex.fn.now())
+      table.timestamp('date_updated', { useTz: false }).notNullable().defaultTo(knex.fn.now())
 
       // Constraints
       table.unique(['external_id'], { useConstraint: true })

db/migrations/legacy/20221108007034_water-return-requirement-points.js

@@ -0,0 +1,37 @@
+'use strict'
+
+const tableName = 'return_requirement_points'
+
+exports.up = function (knex) {
+  return knex
+    .schema
+    .withSchema('water')
+    .createTable(tableName, (table) => {
+      // Primary Key
+      table.uuid('id').primary().defaultTo(knex.raw('gen_random_uuid()'))
+
+      // Data
+      table.uuid('return_requirement_id').notNullable()
+      table.text('description')
+      table.text('ngr_1').notNullable()
+      table.text('ngr_2')
+      table.text('ngr_3')
+      table.text('ngr_4')
+      table.text('external_id')
+      table.integer('nald_point_id')
+
+      // Legacy timestamps
+      table.timestamp('date_created', { useTz: false }).notNullable().defaultTo(knex.fn.now())
+      table.timestamp('date_updated', { useTz: false }).notNullable().defaultTo(knex.fn.now())
+
+      // Constraints
+      table.unique(['external_id'], { useConstraint: true })
+    })
+}
+
+exports.down = function (knex) {
+  return knex
+    .schema
+    .withSchema('water')
+    .dropTableIfExists(tableName)
+}

db/migrations/public/20240606103641_create-return-versions-view.js

@@ -0,0 +1,30 @@
+'use strict'
+
+const viewName = 'return_versions'
+
+exports.up = function (knex) {
+  return knex
+    .schema
+    .createView(viewName, (view) => {
+      view.as(knex('return_versions').withSchema('water').select([
+        'return_version_id AS id',
+        'licence_id',
+        'version_number AS version',
+        'start_date',
+        'end_date',
+        'status',
+        'external_id',
+        'reason',
+        'multiple_upload',
+        'notes',
+        'date_created AS created_at',
+        'date_updated AS updated_at'
+      ]))
+    })
+}
+
+exports.down = function (knex) {
+  return knex
+    .schema
+    .dropViewIfExists(viewName)
+}

db/migrations/public/20240606104018_create-return-requirements-view.js

@@ -0,0 +1,37 @@
+'use strict'
+
+const viewName = 'return_requirements'
+
+exports.up = function (knex) {
+  return knex
+    .schema
+    .createView(viewName, (view) => {
+      view.as(knex('return_requirements').withSchema('water').select([
+        'return_requirement_id AS id',
+        'return_version_id',
+        'returns_frequency',
+        'is_summer AS summer',
+        'is_upload AS upload',
+        'abstraction_period_start_day',
+        'abstraction_period_start_month',
+        'abstraction_period_end_day',
+        'abstraction_period_end_month',
+        'site_description',
+        'legacy_id',
+        'external_id',
+        'collection_frequency',
+        'gravity_fill',
+        'reabstraction',
+        'two_part_tariff',
+        'fifty_six_exception',
+        'date_created AS created_at',
+        'date_updated AS updated_at'
+      ]))
+    })
+}
+
+exports.down = function (knex) {
+  return knex
+    .schema
+    .dropViewIfExists(viewName)
+}

db/migrations/public/20240606104927_create-return-requirement-purposes-view.js

@@ -0,0 +1,27 @@
+'use strict'
+
+const viewName = 'return_requirement_purposes'
+
+exports.up = function (knex) {
+  return knex
+    .schema
+    .createView(viewName, (view) => {
+      view.as(knex('return_requirement_purposes').withSchema('water').select([
+        'return_requirement_purpose_id AS id',
+        'return_requirement_id',
+        'purpose_primary_id',
+        'purpose_secondary_id',
+        'purpose_use_id AS purpose_id',
+        'purpose_alias AS alias',
+        'external_id',
+        'date_created AS created_at',
+        'date_updated AS updated_at'
+      ]))
+    })
+}
+
+exports.down = function (knex) {
+  return knex
+    .schema
+    .dropViewIfExists(viewName)
+}