Add history attributes to LicenceVersionModel (#1271)

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

> Part of the work to display NALD mod log records as history in WRLS

So, we are now importing mod logs from NALD and have added a model linked to charge, licence and return version models to allow us to retrieve them from the database.

We are in the process of building [a new licence history page](#1182) and will need to create a view of the licence version in the future.

Because of this, we believe adding a modifier and instance methods to the `LicenceVersionModel` that will handle fetching the mod logs and determining this information is valuable.

This change updates the `LicenceVersionModel` with these properties. This is similar to the work we did in [Add history attributes to ReturnVersionModel](#1267).

app/models/licence-version.model.js

@@ -54,6 +54,149 @@ class LicenceVersionModel extends BaseModel {
       }
     }
   }
+
+  /**
+   * Modifiers allow us to reuse logic in queries, eg. select the licence version and all mod log records:
+   *
+   * return LicenceVersionModel.query()
+   *   .findById(licenceVersionId)
+   *   .modify('history')
+   *
+   * See {@link https://vincit.github.io/objection.js/recipes/modifiers.html | Modifiers} for more details
+   */
+  static get modifiers () {
+    return {
+      // history modifier fetches all the related records needed to determine history properties, for example, created
+      // at, created by, and notes from the record and its NALD mod logs (where they exist)
+      history (query) {
+        query
+          .withGraphFetched('modLogs')
+          .modifyGraph('modLogs', (builder) => {
+            builder.select([
+              'id',
+              'naldDate',
+              'note',
+              'reasonDescription',
+              'userId'
+            ])
+              .orderBy('externalId', 'asc')
+          })
+      }
+    }
+  }
+
+  /**
+   * Determine the created at date of the 'source' record using history
+   *
+   * > We recommend adding the `history` modifier to your query to support this determination
+   *
+   * NALD has a concept called 'mod log'. When someone creates a new licence, charge, or return version, they can
+   * provide a reason and a note, which is saved as the 'mod log'. Who created the 'mod log' and when is also captured.
+   *
+   * It was intended to record a history of changes to the licence.
+   *
+   * Unfortunately, NALD doesn't enforce it's creation. But as the NALD version records don't capture the who and when,
+   * they are the best 'source' we have to determine this information for imported records.
+   *
+   * If there are mod logs for this record, it extracts the date from the first entry, for example, `2019-06-02`, and
+   * returns it. Else, it falls back to using the return version's `createdAt` time stamp.
+   *
+   * > The NALD date takes priority, because all records will have a created at date. But in the case of imported
+   * > records this will be when it was imported to WRLS, which can be some time after it was created in NALD.
+   *
+   * @returns {Date} the date the 'source' record was created
+   */
+  $createdAt () {
+    const firstModLog = this._firstModLog()
+
+    return firstModLog?.naldDate ?? this.createdAt
+  }
+
+  /**
+   * Determine which user created the 'source' record using history
+   *
+   * > We recommend adding the `history` modifier to your query to support this determination
+   *
+   * NALD has a concept called 'mod log'. When someone creates a new licence, charge, or return version, they can
+   * provide a reason and a note, which is saved as the 'mod log'. Who created the 'mod log' and when is also captured.
+   *
+   * It was intended to record a history of changes to the licence.
+   *
+   * Unfortunately, NALD doesn't enforce it's creation. But as the NALD version records don't capture the who and when,
+   * they are the best 'source' we have to determine this information for imported records.
+   *
+   * Licence versions are not managed in WRLS, so we do not capture a `created_by` value. The only source for this is
+   * the mod logs.
+   *
+   * If mod logs exist it extracts the user ID from the first mod log record, for example, `JSMITH`. If one exists it is
+   * the 'source'.
+   *
+   * If no mod logs exist it will return `null`.
+   *
+   * @returns {string} the user name of the user that created the 'source' record, else `null` if it cannot be
+   * determined
+   */
+  $createdBy () {
+    const firstModLog = this._firstModLog()
+
+    return firstModLog?.userId ?? null
+  }
+
+  /**
+   * Determine the notes for the record using its history
+   *
+   * > We recommend adding the `history` modifier to your query to support this determination
+   *
+   * NALD has a concept called 'mod log'. When someone creates a new licence, charge, or return version, they can
+   * provide a reason and a note, which is saved as the 'mod log'. Who created the 'mod log' and when is also captured.
+   *
+   * It was intended to record a history of changes to the licence.
+   *
+   * In NALD a licence version can have multiple mod logs, each with their own note. There is currently no note captured
+   * against the WRLS licence version.
+   *
+   * @returns {string[]} an array of all the notes in ascending date order taken from the record's history
+   */
+  $notes () {
+    const notes = []
+
+    for (const modLog of this.modLogs) {
+      if (modLog.note) {
+        notes.push(modLog.note)
+      }
+    }
+
+    return notes
+  }
+
+  /**
+   * Determine the reason the 'source' record was created using history
+   *
+   * > We recommend adding the `history` modifier to your query to support this determination
+   *
+   * NALD has a concept called 'mod log'. When someone creates a new licence, charge, or return version, they can
+   * provide a reason and a note, which is saved as the 'mod log'. Who created the 'mod log' and when is also captured.
+   *
+   * It was intended to record a history of changes to the licence.
+   *
+   * In NALD a licence version can have multiple mod logs, each with their own reason. There is currently no reason
+   * captured against the WRLS licence version.
+   *
+   * @returns {string} the reason the 'source' record was created, else `null` if it cannot be determined
+   */
+  $reason () {
+    const firstModLog = this._firstModLog()
+
+    return firstModLog?.reasonDescription ?? null
+  }
+
+  _firstModLog () {
+    if (this.modLogs.length > 0) {
+      return this.modLogs[0]
+    }
+
+    return null
+  }
 }
 
 module.exports = LicenceVersionModel

app/models/return-version.model.js

@@ -56,7 +56,7 @@ class ReturnVersionModel extends BaseModel {
    * log records:
    *
    * return ReturnVersionModel.query()
-   *   .findById(licenceId)
+   *   .findById(returnVersionId)
    *   .modify('history')
    *
    * See {@link https://vincit.github.io/objection.js/recipes/modifiers.html | Modifiers} for more details
@@ -92,7 +92,7 @@ class ReturnVersionModel extends BaseModel {
   }
 
   /**
-   * Determine which user created the 'source' record using history
+   * Determine the created at date of the 'source' record using history
    *
    * > We recommend adding the `history` modifier to your query to support this determination
    *
@@ -104,29 +104,22 @@ class ReturnVersionModel extends BaseModel {
    * Unfortunately, NALD doesn't enforce it's creation. But as the NALD version records don't capture the who and when,
    * they are the best 'source' we have to determine this information for imported records.
    *
-   * If a user record exists for this version then it was created in WRLS and it is the 'source'. It extracts the user
-   * name, for example, `[email protected]`.
-   *
-   * If a user record doesn't exist, it falls back to attempting to extract the user ID from the first mod log record,
-   * for example, `JSMITH`. If one exists it is the 'source'.
+   * If there are mod logs for this record, it extracts the date from the first entry, for example, `2019-06-02`, and
+   * returns it. Else, it falls back to using the return version's `createdAt` time stamp.
    *
-   * If neither a user nor any mod logs exist it will return `null`.
+   * > The NALD date takes priority, because all records will have a created at date. But in the case of imported
+   * > records this will be when it was imported to WRLS, which can be some time after it was created in NALD.
    *
-   * @returns {string} the user name of the user that created the 'source' record, else `null` if it cannot be
-   * determined
+   * @returns {Date} the date the 'source' record was created
    */
-  $createdBy () {
-    if (this.user) {
-      return this.user.username
-    }
-
+  $createdAt () {
     const firstModLog = this._firstModLog()
 
-    return firstModLog?.userId ?? null
+    return firstModLog?.naldDate ?? this.createdAt
   }
 
   /**
-   * Determine the created at date of the 'source' record using history
+   * Determine which user created the 'source' record using history
    *
    * > We recommend adding the `history` modifier to your query to support this determination
    *
@@ -138,18 +131,25 @@ class ReturnVersionModel extends BaseModel {
    * Unfortunately, NALD doesn't enforce it's creation. But as the NALD version records don't capture the who and when,
    * they are the best 'source' we have to determine this information for imported records.
    *
-   * If there are mod logs for this record, it extracts the date from the first entry, for example, `2019-06-02`, and
-   * returns it. Else, it falls back to using the return version's `createdAt` time stamp.
+   * If a user record exists for this version then it was created in WRLS and it is the 'source'. It extracts the user
+   * name, for example, `[email protected]`.
    *
-   * > The NALD date takes priority, because all records will have a created at date. But in the case of imported
-   * > records this will be when it was imported to WRLS, which can be some time after it was created in NALD.
+   * If a user record doesn't exist, it falls back to attempting to extract the user ID from the first mod log record,
+   * for example, `JSMITH`. If one exists it is the 'source'.
    *
-   * @returns {Date} the date the 'source' record was created
+   * If neither a user nor any mod logs exist it will return `null`.
+   *
+   * @returns {string} the user name of the user that created the 'source' record, else `null` if it cannot be
+   * determined
    */
-  $createdAt () {
+  $createdBy () {
+    if (this.user) {
+      return this.user.username
+    }
+
     const firstModLog = this._firstModLog()
 
-    return firstModLog?.naldDate ?? this.createdAt
+    return firstModLog?.userId ?? null
   }
 
   /**