Create new quarterly return versions for water companies (#1648)

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

As part of our work in setting up quarterly returns for water companies we need to run a one off migration for each of them to create a new return version. This PR creates an end point that can be hit as part of a job. It will loop through each of the water companies that do not have a return version starting next year and create one.

app/controllers/jobs.controller.js

@@ -10,6 +10,7 @@ const ProcessLicenceUpdates = require('../services/jobs/licence-updates/process-
 const ProcessReturnLogsService = require('../services/jobs/return-logs/process-return-logs.service.js')
 const ProcessSessionStorageCleanupService = require('../services/jobs/session-cleanup/process-session-storage-cleanup.service.js')
 const ProcessTimeLimitedLicencesService = require('../services/jobs/time-limited/process-time-limited-licences.service.js')
+const ReturnVersionMigrationService = require('../services/jobs/return-logs/return-version-migration.service.js')
 
 const NO_CONTENT_STATUS_CODE = 204
 const NOT_FOUND_STATUS_CODE = 404
@@ -59,10 +60,17 @@ async function returnLogs(request, h) {
   return h.response().code(NO_CONTENT_STATUS_CODE)
 }
 
+async function returnVersionMigration(request, h) {
+  ReturnVersionMigrationService.go()
+
+  return h.response().code(NO_CONTENT_STATUS_CODE)
+}
+
 module.exports = {
   exportDb,
   licenceUpdates,
   returnLogs,
+  returnVersionMigration,
   sessionCleanup,
   timeLimited
 }

app/routes/jobs.routes.js

@@ -72,6 +72,20 @@ const routes = [
         crumb: false
       }
     }
+  },
+  {
+    method: 'POST',
+    path: '/jobs/return-version-migration',
+    options: {
+      handler: JobsController.returnVersionMigration,
+      app: {
+        plainOutput: true
+      },
+      auth: false,
+      plugins: {
+        crumb: false
+      }
+    }
   }
 ]
 

app/services/jobs/return-logs/fetch-water-undertakers.service.js

@@ -0,0 +1,74 @@
+'use strict'
+
+/**
+ * Fetches all water undertakers that have a valid licence after 1/04/2025
+ * @module FetchWaterUndertakersService
+ */
+
+const { db } = require('../../../../db/db.js')
+const LicenceModel = require('../../../models/licence.model.js')
+const ReturnRequirementModel = require('../../../models/return-requirement.model.js')
+const ReturnVersionModel = require('../../../models/return-version.model.js')
+
+/**
+ * Fetches all water undertaker licences that will have not been ended before 1/04/2025
+ *
+ * @returns {Promise<module:LicenceModel>} the matching licences
+ */
+async function go() {
+  const quarterlyStartDate = new Date('2025-04-01')
+
+  return await LicenceModel.query()
+    .select([
+      'id',
+      'expiredDate',
+      'lapsedDate',
+      'licenceRef',
+      'revokedDate',
+      'startDate',
+      'waterUndertaker',
+      db.raw("regions->>'regionalChargeArea' as regionalChargeArea")
+    ])
+    .withGraphFetched('returnVersions')
+    .modifyGraph('returnVersions', (builder) => {
+      builder
+        .select(['id', 'startDate', 'reason'])
+        .where('startDate', '<', quarterlyStartDate)
+        .where('status', 'current')
+        // A return version must include return requirements in order for us to be able to copy from it
+        .whereExists(
+          ReturnRequirementModel.query()
+            .select(1)
+            .whereColumn('returnVersions.id', 'returnRequirements.returnVersionId')
+        )
+        .orderBy('startDate', 'desc')
+    })
+    .where('waterUndertaker', true)
+    .where((builder) => {
+      builder.whereNull('expiredDate').orWhere('expiredDate', '>=', quarterlyStartDate)
+    })
+    .where((builder) => {
+      builder.whereNull('lapsedDate').orWhere('lapsedDate', '>=', quarterlyStartDate)
+    })
+    .where((builder) => {
+      builder.whereNull('revokedDate').orWhere('revokedDate', '>=', quarterlyStartDate)
+    })
+    .whereNotExists(
+      ReturnVersionModel.query()
+        .where('returnVersions.status', 'current')
+        .where('startDate', '>=', quarterlyStartDate)
+        .whereColumn('returnVersions.licenceId', 'licences.id')
+    )
+    .whereExists(
+      ReturnVersionModel.query()
+        .where('returnVersions.status', 'current')
+        .where('quarterlyReturns', false)
+        .where('startDate', '<', quarterlyStartDate)
+        .whereColumn('returnVersions.licenceId', 'licences.id')
+    )
+    .whereIn('id', ['5599e2b2-4047-48e6-84aa-f6fc23741e05', '95de4f0f-f13f-4ea6-9460-b7f5d6ce8381'])
+}
+
+module.exports = {
+  go
+}

app/services/jobs/return-logs/return-version-migration.service.js

@@ -0,0 +1,65 @@
+'use strict'
+
+/**
+ * Determines which licences need new return versions created for quarterly returns
+ * @module ReturnVersionMigrationService
+ */
+
+const { calculateAndLogTimeTaken, currentTimeInNanoseconds } = require('../../../lib/general.lib.js')
+const FetchWaterUndertakersService = require('./fetch-water-undertakers.service.js')
+const GenerateFromExisintRequirementsService = require('../../return-versions/setup/existing/generate-from-existing-requirements.service.js')
+const GenerateReturnVersionService = require('../../return-versions/setup/check/generate-return-version.service.js')
+const LicencesConfig = require('../../../../config/licences.config.js')
+const PersistReturnVersionService = require('../../return-versions/setup/check/persist-return-version.service.js')
+const UserModel = require('../../../models/user.model.js')
+
+/**
+ * Determines which licences need new return versions created for quarterly returns
+ *
+ * This service will generate new return versions for each current licence that is a water undertaker (a water company).
+ * The new return version will start on 1/04/2025.
+ */
+async function go() {
+  try {
+    const startTime = currentTimeInNanoseconds()
+
+    const usernames = ['[email protected]']
+
+    if (LicencesConfig.returnVersionBatchUser) {
+      usernames.unshift(LicencesConfig.returnVersionBatchUser)
+    }
+
+    const user = await UserModel.query().select(['id']).whereIn('username', usernames).first()
+
+    const licences = await FetchWaterUndertakersService.go()
+
+    for (const licence of licences) {
+      const returnRequirements = await GenerateFromExisintRequirementsService.go(licence.returnVersions[0].id)
+
+      const data = {
+        licence: {
+          id: licence.id
+        },
+        multipleUpload: returnRequirements.multipleUpload,
+        note: {
+          content: 'Changed due to water company licences moving to quarterly returns'
+        },
+        reason: 'change-to-return-requirements',
+        returnVersionStartDate: new Date('2025-04-01'),
+        requirements: returnRequirements.requirements,
+        quarterlyReturns: true
+      }
+
+      const returnVersionData = await GenerateReturnVersionService.go(data, user.id)
+      await PersistReturnVersionService.go(returnVersionData)
+    }
+
+    calculateAndLogTimeTaken(startTime, 'Return version migration job complete')
+  } catch (error) {
+    global.GlobalNotifier.omfg('Return version migration job failed', null, error)
+  }
+}
+
+module.exports = {
+  go
+}

app/services/return-versions/setup/existing/fetch-existing-requirements.service.js

@@ -25,7 +25,7 @@ async function go(returnVersionId) {
 async function _fetch(returnVersionId) {
   return ReturnVersionModel.query()
     .findById(returnVersionId)
-    .select(['id', 'multipleUpload', 'quarterlyReturns'])
+    .select(['id', 'multipleUpload', 'startDate', 'quarterlyReturns'])
     .withGraphFetched('returnRequirements')
     .modifyGraph('returnRequirements', (returnRequirementsBuilder) => {
       returnRequirementsBuilder

app/services/return-versions/setup/existing/generate-from-existing-requirements.service.js

@@ -30,7 +30,8 @@ async function go(returnVersionId) {
   return {
     multipleUpload: returnVersion.multipleUpload,
     quarterlyReturns: returnVersion.quarterlyReturns,
-    requirements: _transformForSetup(returnVersion)
+    requirements: _transformForSetup(returnVersion),
+    startDate: returnVersion.startDate
   }
 }
 

config/licences.config.js

@@ -12,7 +12,8 @@ require('dotenv').config()
 const config = {
   endDates: {
     batchSize: parseInt(process.env.LICENCE_END_DATES_BATCH_SIZE) || 10
-  }
+  },
+  returnVersionBatchUser: process.env.RETURN_VERSION_BATCH_USER
 }
 
 module.exports = config

test/services/return-versions/setup/existing/fetch-existing-requirements.service.test.js

@@ -34,6 +34,7 @@ describe('Return Versions Setup - Fetch Existing Requirements service', () => {
         id: seededReturnVersion.id,
         multipleUpload: false,
         quarterlyReturns: false,
+        startDate: seededReturnVersion.startDate,
         returnRequirements: [
           {
             abstractionPeriodEndDay: 31,