feat: implement migration command and service for forced execution

- Added a new command `MigrationsForceCommand` to allow forcing the execution of specific migrations by timestamp or filename.
- Enhanced the `MigrationsService` with a `forceRun` method to handle the logic for executing migrations even when the lock is active.
- Introduced a new migration job `IdentitiesEmployeeTypeLocalToLOCAL` to update employee types in the database, ensuring proper handling of unique constraints during the migration process.
- Updated the `MigrationsModule` to register the new command for CLI usage.

Author: tacxou

apps/api/src/migrations/jobs/1775547941-identities-employeeType-local-to-LOCAL.ts

@@ -0,0 +1,91 @@
+import { Logger } from '@nestjs/common'
+import { InjectConnection } from '@nestjs/mongoose'
+import { Connection } from 'mongoose'
+
+export default class IdentitiesEmployeeTypeLocalToLOCAL1775547941 {
+  private readonly logger = new Logger(IdentitiesEmployeeTypeLocalToLOCAL1775547941.name)
+
+  public constructor(@InjectConnection() private mongo: Connection) {}
+
+  public async up(): Promise<void> {
+    this.logger.log('IdentitiesEmployeeTypeLocalToLOCAL1775547941 up started')
+
+    const identitiesCollection = this.mongo.collection('identities')
+
+    // Important: on ne peut pas faire updateMany(local->LOCAL) avant de réallouer employeeNumber,
+    // sinon on peut violer l'index unique (employeeNumber, employeeType).
+    const cursor = identitiesCollection
+      .find({
+        'inetOrgPerson.employeeType': "local",
+      })
+      .project({ _id: 1 })
+      .sort({ _id: 1 })
+
+    const toMigrate = await identitiesCollection.countDocuments({
+      'inetOrgPerson.employeeType': "local",
+    })
+    this.logger.log(`Identities matched for migration: ${toMigrate}`)
+
+    let migrated = 0
+    let failed = 0
+    for await (const doc of cursor) {
+      try {
+        const newNumber = await this.allocateNextEmployeeNumber()
+        await identitiesCollection.updateOne(
+          { _id: doc._id },
+          {
+            $set: {
+              'inetOrgPerson.employeeType': 'LOCAL',
+              'inetOrgPerson.employeeNumber': [String(newNumber)],
+            },
+          },
+        )
+        migrated += 1
+      } catch (e: any) {
+        failed += 1
+        this.logger.error(`Failed to migrate identity <${doc._id}>: ${e?.message || e}`)
+      }
+    }
+
+    this.logger.log(`EmployeeType migration done (migrated=${migrated}, failed=${failed})`)
+
+    this.logger.log('Migration terminée avec succès')
+  }
+
+  /**
+   * Réattribue un nouvel employeeNumber aux identités migrées, en utilisant la même source de vérité
+   * que l'auto-incrément Mongoose: la collection `identitycounters`.
+   *
+   * On fait un `findOneAndUpdate($inc)` par identité, ce qui garantit l'unicité et évite
+   * toute approximation (max en base / overflow / compteur en retard).
+   */
+  private async allocateNextEmployeeNumber(): Promise<number> {
+    const counters = this.mongo.collection('identitycounters')
+    const filter = { field: 'inetOrgPerson.employeeNumber', modelName: 'Identities' }
+    const opts: any = { upsert: true, returnDocument: 'after', returnOriginal: false }
+
+    // MongoDB interdit de modifier le même champ dans $setOnInsert et $inc dans la même requête.
+    // On s'assure d'abord que le document compteur existe, puis on incrémente.
+    await counters.updateOne(
+      filter,
+      {
+        $setOnInsert: {
+          ...filter,
+          // Mimics AutoIncrementPlugin initialization for startAt=1, incrementBy=1
+          count: 0,
+        },
+      },
+      { upsert: true },
+    )
+
+    const counter = await counters.findOneAndUpdate(filter, { $inc: { count: 1 } }, opts)
+
+    const counterDoc = counter?.value || (await counters.findOne(filter))
+    const allocated = Number(counterDoc?.count)
+    if (!Number.isFinite(allocated) || allocated <= 0) {
+      throw new Error(`Failed to allocate employeeNumber (allocated=${allocated})`)
+    }
+    return allocated
+  }
+}
+

apps/api/src/migrations/migrations.command.ts

@@ -0,0 +1,40 @@
+import { Logger } from '@nestjs/common'
+import { ModuleRef } from '@nestjs/core'
+import { Command, CommandRunner, SubCommand } from 'nest-commander'
+import { MigrationsService } from './migrations.service'
+
+@SubCommand({ name: 'force' })
+export class MigrationsForceCommand extends CommandRunner {
+  private readonly logger = new Logger(MigrationsForceCommand.name)
+
+  public constructor(
+    protected moduleRef: ModuleRef,
+    private readonly migrationsService: MigrationsService,
+  ) {
+    super()
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async run(inputs: string[], options: any): Promise<void> {
+    const selector = inputs?.[0]
+    if (!selector) {
+      console.error('Usage: yarn run console migrations force <timestamp|filename>')
+      return
+    }
+
+    this.logger.warn(`Forcing migration <${selector}> ...`)
+    await this.migrationsService.forceRun(selector)
+    this.logger.log('Done.')
+  }
+}
+
+@Command({ name: 'migrations', arguments: '<task>', subCommands: [MigrationsForceCommand] })
+export class MigrationsCommand extends CommandRunner {
+  public constructor(protected moduleRef: ModuleRef) {
+    super()
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async run(inputs: string[], options: any): Promise<void> {}
+}
+

apps/api/src/migrations/migrations.module.ts

@@ -1,5 +1,7 @@
 import { DynamicModule, Module } from '@nestjs/common'
 import { MigrationsService } from './migrations.service'
+import { useOnCli } from '~/_common/functions/is-cli'
+import { MigrationsCommand } from './migrations.command'
 
 /**
  * Module NestJS pour la gestion des migrations de base de données
@@ -12,6 +14,9 @@ import { MigrationsService } from './migrations.service'
 @Module({
   providers: [
     MigrationsService,
+    ...useOnCli([
+      ...MigrationsCommand.registerWithSubCommands(),
+    ]),
   ],
 })
 export class MigrationsModule {

apps/api/src/migrations/migrations.service.ts

@@ -261,4 +261,60 @@ export class MigrationsService implements OnModuleInit {
       throw new Error('Error while updating migration lock file !')
     }
   }
+
+  /**
+   * Exécute une migration spécifique en la forçant, même si le lock est au-dessus.
+   *
+   * @param selector Timestamp (ex: "1775547941") ou nom de fichier (ex: "jobs/1775547941-foo.js")
+   */
+  public async forceRun(selector: string): Promise<void> {
+    if (!selector || typeof selector !== 'string') {
+      throw new Error('Missing migration selector (timestamp or filename)')
+    }
+
+    let files = await glob(`./jobs/*.js`, {
+      cwd: __dirname,
+      root: __dirname,
+    })
+
+    const normalizedSelector = selector.trim()
+    const selectorTimestamp = (normalizedSelector.match(/\d{10,}/) || [])[0]
+
+    const matches = files.filter((file) => {
+      if (normalizedSelector.includes('/') || normalizedSelector.includes('.js')) {
+        return file.endsWith(normalizedSelector.replace(/^.*jobs\//, 'jobs/'))
+      }
+      if (selectorTimestamp) {
+        return file.includes(selectorTimestamp)
+      }
+      return false
+    })
+
+    if (matches.length === 0) {
+      throw new Error(`No migration file found for selector <${selector}>`)
+    }
+    if (matches.length > 1) {
+      throw new Error(`Multiple migrations match selector <${selector}>: ${matches.join(', ')}`)
+    }
+
+    const key = matches[0]
+    const [migrationTimestamp] = key.match(/\d{10,}/) || []
+    if (!migrationTimestamp) {
+      throw new Error(`Selected migration <${key}> has no timestamp in filename`)
+    }
+
+    const migration = await import(`${__dirname}/${key}`)
+    if (!migration?.default) {
+      throw new Error(`Migration <${key}> does not have a default export`)
+    }
+
+    const instance = await this.moduleRef.create(migration.default)
+    if (typeof instance.up !== 'function') {
+      throw new Error(`Migration <${key}> does not have an up method`)
+    }
+
+    this.logger.warn(chalk.yellow(`Forcing migration ${chalk.bold('<' + key + '>')}...`))
+    await instance.up()
+    await this._writeMigrationLockFile(key, migrationTimestamp)
+  }
 }