feat(schema): createdAt/updatedAt on every domain entity (P4-K)

CHANGELOG.md

@@ -8,6 +8,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **`createdAt` / `updatedAt` on every domain entity** (P4-K). New
+  migration adds two `TIMESTAMPTZ NOT NULL DEFAULT now()` columns to
+  18 tables (everything except `IdempotencyKey`, which already
+  tracks its own time fields). All 18 models flip
+  `timestamps: false` → `true` so Sequelize auto-populates the
+  columns on every `.create()` / `.update()`. Existing rows are
+  backfilled to `now()` at apply time; operators with the original
+  SQL Server timestamps from the Atbash legacy can patch real values
+  post-migration via a one-off UPDATE.
 - **Prometheus `/metrics` endpoint** (P4-J). Exposes prom-client's
   default Node.js metrics (event-loop lag, heap, GC, etc.) plus
   per-request `http_requests_total{method,route,status}` and

app/migrations/20260520000000-timestamps.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Aaron K. Clark
+//
+// Add `createdAt` / `updatedAt` (TIMESTAMPTZ NOT NULL DEFAULT now())
+// to every domain table so Sequelize models can flip
+// `timestamps: false` → `timestamps: true`.
+//
+// Why P4-K:
+//   - Auditability: every row carries its creation + last-modification
+//     time without each controller having to maintain it by hand.
+//   - Sync clients: third-party integrations get a reliable
+//     "what's changed since T" boundary for delta-pull workflows.
+//   - Observability: SQL ad-hoc analysis on "new customers per day"
+//     etc. trivially works off `createdAt` rather than a row-counter.
+//
+// IdempotencyKey is intentionally NOT in this list — it already
+// manages its own ikCreatedAt/ikExpiresAt and a parallel
+// createdAt/updatedAt pair would be redundant + confusing.
+//
+// Backfill strategy:
+//   Existing rows have no recorded history, so we backfill both
+//   columns to now() at migration-apply time. Operators with the
+//   original SQL Server timestamps (Atbash legacy) can patch
+//   real values post-migration via a one-off UPDATE.
+//
+// Down: simply DROP the two columns from each table. Safe — no
+// FKs reference these columns.
+
+'use strict';
+
+const TABLES = [
+    'ApiKey',
+    'ApiMaster',
+    'BillingType',
+    'Company',
+    'Customer',
+    'CustomerPayment',
+    'InventoryItem',
+    'InventoryTransactions',
+    'Invoice',
+    'InvoiceJob',
+    'Job',
+    'ProductEntry',
+    'PurchaseOrderHeaders',
+    'PurchaseOrderLines',
+    'PurchaseOrderVendors',
+    'TimeEntry',
+    'VersionInfo',
+    'Worker',
+];
+
+module.exports = {
+    async up(queryInterface, Sequelize) {
+        const SCHEMA = 'dbo';
+        const sequelize = queryInterface.sequelize;
+        for (const table of TABLES) {
+            await sequelize.query(`
+                ALTER TABLE "${SCHEMA}"."${table}"
+                    ADD COLUMN IF NOT EXISTS "createdAt" TIMESTAMPTZ NOT NULL DEFAULT now(),
+                    ADD COLUMN IF NOT EXISTS "updatedAt" TIMESTAMPTZ NOT NULL DEFAULT now()
+            `);
+        }
+    },
+
+    async down(queryInterface, Sequelize) {
+        const SCHEMA = 'dbo';
+        const sequelize = queryInterface.sequelize;
+        for (const table of TABLES) {
+            await sequelize.query(`
+                ALTER TABLE "${SCHEMA}"."${table}"
+                    DROP COLUMN IF EXISTS "updatedAt",
+                    DROP COLUMN IF EXISTS "createdAt"
+            `);
+        }
+    },
+};

app/models/apikey.model.js

@@ -30,7 +30,7 @@ module.exports = (sequelize, Sequelize) => {
     },
         {
             tableName: 'ApiKey',
-            timestamps: false,
+            timestamps: true,
             defaultScope: { where: { akArchive: false } }
         }
     );

app/models/apimaster.model.js

@@ -25,7 +25,7 @@ module.exports = (sequelize, Sequelize) => {
     },
         {
             tableName: 'ApiMaster',
-            timestamps: false,
+            timestamps: true,
             defaultScope: { where: { amArchive: false } }
         }
     );

app/models/billingtype.model.js

@@ -37,7 +37,7 @@ module.exports = (sequelize, Sequelize) => {
         },
     }, {
         tableName: 'BillingType',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { btArch: false } }
     });
 

app/models/company.model.js

@@ -37,7 +37,7 @@ module.exports = (sequelize, Sequelize) => {
         },
     }, {
         tableName: 'Company',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { compArch: false } }
     });
 

app/models/customer.model.js

@@ -66,7 +66,7 @@ module.exports = (sequelize, Sequelize) => {
     },
         {
             tableName: 'Customer',
-            timestamps: false,
+            timestamps: true,
             defaultScope: { where: { custArch: false } }
         }
     );

app/models/customerpayment.model.js

@@ -41,7 +41,7 @@ module.exports = (sequelize, Sequelize) => {
         },
     }, {
         tableName: 'CustomerPayment',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { cpayArch: false } }
     });
 

app/models/inventoryitem.model.js

@@ -39,7 +39,7 @@ module.exports = (sequelize, Sequelize) => {
         },
     }, {
         tableName: 'InventoryItem',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { invitArch: false } }
     });
 

app/models/inventorytransaction.model.js

@@ -26,7 +26,7 @@ module.exports = (sequelize, Sequelize) => {
         invtInitId:     { field: 'invtInitId',     type: Sequelize.INTEGER, allowNull: false },
     }, {
         tableName: 'InventoryTransactions',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { invtArch: false } }
     });
 

app/models/invoice.model.js

@@ -45,7 +45,7 @@ module.exports = (sequelize, Sequelize) => {
         },
     }, {
         tableName: 'Invoice',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { invArch: false } }
     });
 

app/models/invoicejob.model.js

@@ -41,7 +41,7 @@ module.exports = (sequelize, Sequelize) => {
         },
     }, {
         tableName: 'InvoiceJob',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { injbArch: false } }
     });
 

app/models/job.model.js

@@ -39,7 +39,7 @@ module.exports = (sequelize, Sequelize) => {
         },
     }, {
         tableName: 'Job',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { jobArch: false } }
     });
 

app/models/productentry.model.js

@@ -45,7 +45,7 @@ module.exports = (sequelize, Sequelize) => {
         },
     }, {
         tableName: 'ProductEntry',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { penArch: false } }
     });
 

app/models/purchaseorderheader.model.js

@@ -22,7 +22,7 @@ module.exports = (sequelize, Sequelize) => {
         pohArch:       { field: 'pohArch',      type: Sequelize.BOOLEAN, defaultValue: false },
     }, {
         tableName: 'PurchaseOrderHeaders',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { pohArch: false } }
     });
 

app/models/purchaseorderline.model.js

@@ -28,7 +28,7 @@ module.exports = (sequelize, Sequelize) => {
         polArch:      { field: 'polArch',     type: Sequelize.BOOLEAN, defaultValue: false },
     }, {
         tableName: 'PurchaseOrderLines',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { polArch: false } }
     });
 

app/models/purchaseordervendor.model.js

@@ -35,7 +35,7 @@ module.exports = (sequelize, Sequelize) => {
         povArch:             { field: 'povArch',             type: Sequelize.BOOLEAN, defaultValue: false },
     }, {
         tableName: 'PurchaseOrderVendors',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { povArch: false } }
     });
 

app/models/timeentry.model.js

@@ -65,7 +65,7 @@ module.exports = (sequelize, Sequelize) => {
         },
     }, {
         tableName: 'TimeEntry',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { teArch: false } }
     });
 

app/models/versioninfo.model.js

@@ -27,7 +27,7 @@ module.exports = (sequelize, Sequelize) => {
         },
     }, {
         tableName: 'VersionInfo',
-        timestamps: false,
+        timestamps: true,
     });
 
     return VersionInfo;

app/models/worker.model.js

@@ -54,7 +54,7 @@ module.exports = (sequelize, Sequelize) => {
         },
     }, {
         tableName: 'Worker',
-        timestamps: false,
+        timestamps: true,
         defaultScope: { where: { workerArch: false } }
     });
 

tests/unit/timestamps.test.js

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 Aaron K. Clark
+//
+// Verifies every domain model has `timestamps: true` so Sequelize
+// auto-populates `createdAt`/`updatedAt` on every write. Paired
+// with migration `20260520000000-timestamps.js` which adds the
+// underlying columns.
+
+import { describe, test, expect } from 'vitest';
+
+const db = require('../../app/config/db.config.js');
+
+// IdempotencyKey manages its own ikCreatedAt/ikExpiresAt columns
+// and is intentionally excluded from the auto-timestamp set.
+const MODELS_WITH_TIMESTAMPS = [
+    'ApiKey',
+    'ApiMaster',
+    'BillingType',
+    'Company',
+    'Customer',
+    'CustomerPayment',
+    'InventoryItem',
+    'InventoryTransaction',
+    'Invoice',
+    'InvoiceJob',
+    'Job',
+    'ProductEntry',
+    'PurchaseOrderHeader',
+    'PurchaseOrderLine',
+    'PurchaseOrderVendor',
+    'TimeEntry',
+    'VersionInfo',
+    'Worker',
+];
+
+describe('every domain model has timestamps enabled', () => {
+    test.each(MODELS_WITH_TIMESTAMPS)(
+        '%s carries timestamps:true on its options',
+        (modelName) => {
+            const model = db[modelName];
+            expect(model, `${modelName} should be defined on db`).toBeDefined();
+            expect(model.options.timestamps).toBe(true);
+        },
+    );
+
+    test.each(MODELS_WITH_TIMESTAMPS)(
+        '%s exposes createdAt / updatedAt attributes on the model',
+        (modelName) => {
+            const attrs = db[modelName].rawAttributes;
+            expect(attrs).toBeDefined();
+            // Sequelize names them according to the model's defaults
+            // (camelCase here since none of the models override
+            // createdAt/updatedAt keys).
+            expect(attrs.createdAt).toBeDefined();
+            expect(attrs.updatedAt).toBeDefined();
+        },
+    );
+});