feat: implement manual lifecycle transition management in API and UI

- Added functionality to manage manual lifecycle transitions, including retrieval and updates through new endpoints in LifecycleController.
- Introduced ManualTransitions schema and DTOs for validation and processing of manual transition rules.
- Enhanced LifecycleConfigService to handle loading and updating of manual transitions, ensuring proper validation and error handling.
- Updated UI components to display and manage manual transitions, including options for adding, editing, and removing rules.
- Integrated checks for manual lifecycle transition permissions in the identities CRUD operations, improving user experience and control.

Author: tacxou

apps/api/defaults/lifecycle/manual-transitions.yml

@@ -0,0 +1,32 @@
+# Transitions manuelles uniquement (changement via l'interface identité).
+# N'affecte pas les règles automatiques (cron, fichiers rules/*.yml).
+# Si un état source n'est pas listé ici, toutes les destinations restent autorisées.
+
+manualTransitions:
+  # Officiel (O) : activation courante, pas de passage direct vers « A détruire » ou « Caché »
+  - source: O
+    targets: [I, M, A, P, V]
+
+  # Inactif (I) : réactivation ou mise en file de suppression
+  - source: I
+    targets: [O, M, D]
+
+  # Manuel (M) : état opérateur, retours usuels
+  - source: M
+    targets: [O, I, A, P]
+
+  # En attente (A) : validation ou retour provisoire
+  - source: A
+    targets: [O, P, I]
+
+  # Provisoire (P) : promotion ou mise en attente
+  - source: P
+    targets: [O, A, I]
+
+  # A détruire (D) : uniquement sortie de la file (pas de nouveau cycle destructeur)
+  - source: D
+    targets: [I, O]
+
+  # Verrouillé (V) : déverrouillage vers états stables
+  - source: V
+    targets: [O, I]

apps/api/src/_common/abstracts/abstract.service.schema.ts

@@ -18,6 +18,7 @@ import { ServiceSchemaInterface } from './interfaces/service.schema.interface';
 import { AbstractSchema } from './schemas/abstract.schema';
 import mongodb from 'mongodb';
 import { omit } from 'radash';
+import { normalizeMongoFilterValues } from '~/_common/functions/normalize-mongo-filter-values';
 
 @Injectable()
 export abstract class AbstractServiceSchema<T extends AbstractSchema | Document = AbstractSchema | Document>
@@ -54,6 +55,7 @@ export abstract class AbstractServiceSchema<T extends AbstractSchema | Document
       }
     }
     this.logger.debug(['find', JSON.stringify(Object.values(arguments))].join(' '))
+    filter = normalizeMongoFilterValues(filter)
     return await this._model.find<Query<Array<T>, T, any, T>>(filter, projection, options).exec()
   }
 
@@ -71,6 +73,7 @@ export abstract class AbstractServiceSchema<T extends AbstractSchema | Document
       }
     }
     this.logger.debug(['count', JSON.stringify(Object.values(arguments))].join(' '))
+    filter = normalizeMongoFilterValues(filter)
     return await this._model.countDocuments(filter, options as any).exec()
   }
 
@@ -104,6 +107,7 @@ export abstract class AbstractServiceSchema<T extends AbstractSchema | Document
     }
     const softDelete = { deletedFlag: { $ne: true } }
     filter = { ...filter, ...softDelete }
+    filter = normalizeMongoFilterValues(filter)
     let count = await this._model.countDocuments(filter).exec()
     let data = await this._model.find<T & Query<T, T, any, T>>(filter, projection, options).exec()
 

apps/api/src/_common/functions/normalize-mongo-filter-values.ts

@@ -0,0 +1,43 @@
+import { Types } from 'mongoose';
+
+function isObjectIdLike(value: unknown): value is { _bsontype?: 'ObjectId'; toString(): string } {
+  return (
+    value instanceof Types.ObjectId ||
+    (value !== null &&
+      typeof value === 'object' &&
+      '_bsontype' in value &&
+      (value as { _bsontype: string })._bsontype === 'ObjectId')
+  );
+}
+
+/**
+ * Re-hydrates ObjectId instances from foreign bson/mongoose copies (e.g. nested deps)
+ * so MongoDB queries use the same bson version as the application mongoose driver.
+ */
+export function normalizeMongoFilterValues<T>(filter: T): T {
+  if (filter === null || filter === undefined) {
+    return filter;
+  }
+
+  if (isObjectIdLike(filter)) {
+    if (filter instanceof Types.ObjectId) {
+      return filter as T;
+    }
+
+    return new Types.ObjectId(filter.toString()) as T;
+  }
+
+  if (Array.isArray(filter)) {
+    return filter.map((item) => normalizeMongoFilterValues(item)) as T;
+  }
+
+  if (typeof filter === 'object') {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(filter)) {
+      result[key] = normalizeMongoFilterValues(value);
+    }
+    return result as T;
+  }
+
+  return filter;
+}

apps/api/src/management/identities/identities-crud.controller.ts

@@ -1,3 +1,5 @@
+import { loadManualTransitions } from '~/management/lifecycle/_functions/load-manual-transitions.function';
+import { isManualLifecycleTransitionAllowed } from '~/management/lifecycle/_functions/is-manual-lifecycle-transition-allowed.function';
 import { BadRequestException, Body, Controller, Get, HttpStatus, Param, Patch, Post, Query, Res } from '@nestjs/common';
 import { ApiOperation, ApiParam, ApiTags } from '@nestjs/swagger';
 import {
@@ -357,6 +359,16 @@ export class IdentitiesCrudController extends AbstractController {
     if (!identity) {
       throw new BadRequestException('Identity not found');
     }
+
+    if (body.lifecycle && body.lifecycle !== identity.lifecycle) {
+      const manualTransitions = await loadManualTransitions();
+      if (!isManualLifecycleTransitionAllowed(identity.lifecycle, body.lifecycle, manualTransitions)) {
+        throw new BadRequestException(
+          `Changement manuel de cycle de vie non autorisé : <${identity.lifecycle}> → <${body.lifecycle}>`,
+        );
+      }
+    }
+
     const data = await this._service.updateLifecycle(_id, body.lifecycle);
     return res.status(HttpStatus.OK).json({
       statusCode: HttpStatus.OK,

apps/api/src/management/lifecycle/_dto/manual-transitions.dto.ts

@@ -0,0 +1,50 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsArray, IsNotEmpty, IsString, ValidateNested } from 'class-validator';
+
+export class ManualTransitionRuleDto {
+  @IsString()
+  @IsNotEmpty()
+  @ApiProperty({
+    type: String,
+    description: 'État source (cycle de vie actuel)',
+    example: 'I',
+    required: true,
+  })
+  source: string;
+
+  @IsArray()
+  @IsString({ each: true })
+  @IsNotEmpty({ each: true })
+  @ApiProperty({
+    type: [String],
+    description: 'États cibles autorisés pour un changement manuel depuis cet état source',
+    example: ['D', 'O'],
+    required: true,
+  })
+  targets: string[];
+}
+
+export class ManualTransitionsSchemaDto {
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => ManualTransitionRuleDto)
+  @ApiProperty({
+    type: [ManualTransitionRuleDto],
+    description: 'Règles de filtrage des changements de cycle de vie manuels uniquement',
+    required: true,
+  })
+  manualTransitions: ManualTransitionRuleDto[];
+}
+
+export class ManualTransitionsUpdateDto {
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => ManualTransitionRuleDto)
+  @ApiProperty({
+    type: [ManualTransitionRuleDto],
+    description: 'Règles de filtrage des changements de cycle de vie manuels uniquement',
+    required: true,
+  })
+  manualTransitions: ManualTransitionRuleDto[];
+}

apps/api/src/management/lifecycle/_functions/is-manual-lifecycle-transition-allowed.function.ts

@@ -0,0 +1,30 @@
+import { ManualTransitionRuleDto } from '../_dto/manual-transitions.dto';
+
+export function getAllowedManualLifecycleTargets(
+  source: string,
+  rules: ManualTransitionRuleDto[],
+): string[] | null {
+  const rule = rules.find((item) => item.source === source);
+  if (!rule) {
+    return null;
+  }
+
+  return [...new Set(rule.targets || [])];
+}
+
+export function isManualLifecycleTransitionAllowed(
+  from: string,
+  to: string,
+  rules: ManualTransitionRuleDto[],
+): boolean {
+  if (!from || !to || from === to) {
+    return true;
+  }
+
+  const allowedTargets = getAllowedManualLifecycleTargets(from, rules);
+  if (allowedTargets === null) {
+    return true;
+  }
+
+  return allowedTargets.includes(to);
+}

apps/api/src/management/lifecycle/_functions/load-manual-transitions.function.ts

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { plainToInstance } from 'class-transformer';
+import { parse } from 'yaml';
+import { validateOrReject } from 'class-validator';
+import { Logger } from '@nestjs/common';
+import { formatValidationErrors } from '../../../_common/functions/format-validation-errors.function';
+import { ManualTransitionRuleDto, ManualTransitionsSchemaDto } from '../_dto/manual-transitions.dto';
+
+let __manualTransitionsCache: ManualTransitionRuleDto[] | null = null;
+let __manualTransitionsCacheMtime: number | null = null;
+
+export function clearManualTransitionsCache(): void {
+  __manualTransitionsCache = null;
+  __manualTransitionsCacheMtime = null;
+}
+
+export function getManualTransitionsFilePath(): string {
+  return `${process.cwd()}/configs/lifecycle/manual-transitions.yml`;
+}
+
+export async function loadManualTransitions(): Promise<ManualTransitionRuleDto[]> {
+  const logger = new Logger(loadManualTransitions.name);
+  const filePath = getManualTransitionsFilePath();
+
+  if (!existsSync(filePath)) {
+    logger.debug('No manual transitions file found, returning empty rules array.');
+    return [];
+  }
+
+  try {
+    const { mtimeMs } = statSync(filePath);
+    if (__manualTransitionsCache && __manualTransitionsCacheMtime === mtimeMs) {
+      logger.debug('Returning cached manual lifecycle transitions (manual-transitions.yml unchanged)');
+      return __manualTransitionsCache;
+    }
+
+    const data = readFileSync(filePath, 'utf-8');
+    const yml = parse(data) || {};
+    const schema = plainToInstance(ManualTransitionsSchemaDto, yml);
+
+    if (!schema?.manualTransitions || !Array.isArray(schema.manualTransitions)) {
+      logger.warn('Invalid manual transitions schema, returning empty rules array.');
+      return [];
+    }
+
+    await validateOrReject(schema, { whitelist: true });
+
+    const usedSources = new Set<string>();
+    for (const rule of schema.manualTransitions) {
+      if (usedSources.has(rule.source)) {
+        throw new Error(`Duplicate manual transition source '${rule.source}' found in manual-transitions.yml`);
+      }
+      usedSources.add(rule.source);
+    }
+
+    __manualTransitionsCache = schema.manualTransitions;
+    __manualTransitionsCacheMtime = mtimeMs;
+
+    logger.log(`Loaded <${schema.manualTransitions.length}> manual lifecycle transition rules.`);
+    return schema.manualTransitions;
+  } catch (error) {
+    logger.error('Error loading manual lifecycle transitions', error?.message, error?.stack);
+    clearManualTransitionsCache();
+    throw error;
+  }
+}

apps/api/src/management/lifecycle/lifecycle-config.service.ts

@@ -24,6 +24,8 @@ import { validateLifecycleCronRules } from './_functions/validate-lifecycle-cron
 import { LifecyclePreviewFilterDto, LifecyclePreviewMutationDto } from './_dto/lifecycle-config.dto';
 import { LifecycleCrudService } from './lifecycle-crud.service';
 import { LifecycleHooksService } from './lifecycle-hooks.service';
+import { ManualTransitionRuleDto, ManualTransitionsSchemaDto, ManualTransitionsUpdateDto } from './_dto/manual-transitions.dto';
+import { clearManualTransitionsCache, loadManualTransitions } from './_functions/load-manual-transitions.function';
 
 export type LifecycleRuleFileSummary = {
   name: string;
@@ -157,6 +159,38 @@ export class LifecycleConfigService {
     );
   }
 
+
+  public async getManualTransitions(): Promise<ManualTransitionRuleDto[]> {
+    return loadManualTransitions();
+  }
+
+  public async updateManualTransitions(payload: ManualTransitionsUpdateDto): Promise<ManualTransitionRuleDto[]> {
+    const schema = plainToInstance(ManualTransitionsSchemaDto, {
+      manualTransitions: payload.manualTransitions || [],
+    });
+
+    try {
+      await validateOrReject(schema, { whitelist: true });
+    } catch (errors) {
+      throw new BadRequestException(formatValidationErrors(errors, 'manual-transitions.yml'));
+    }
+
+    const usedSources = new Set<string>();
+    for (const rule of schema.manualTransitions) {
+      if (usedSources.has(rule.source)) {
+        throw new BadRequestException(`La source <${rule.source}> est définie plusieurs fois.`);
+      }
+      usedSources.add(rule.source);
+    }
+
+    this.ensureLifecycleDir();
+    writeFileSync(this.getManualTransitionsFilePath(), stringify({ manualTransitions: schema.manualTransitions }));
+    clearManualTransitionsCache();
+
+    await this.syncAfterConfigChange();
+    return loadManualTransitions();
+  }
+
   public getCustomStates(): IdentityLifecycleState[] {
     return this.lifecycleCrudService.getCustomStates();
   }
@@ -298,6 +332,10 @@ export class LifecycleConfigService {
     return path.join(process.cwd(), 'configs', 'lifecycle');
   }
 
+  private getManualTransitionsFilePath(): string {
+    return path.join(this.getLifecycleDir(), 'manual-transitions.yml');
+  }
+
   private getStatesFilePath(): string {
     return path.join(this.getLifecycleDir(), 'states.yml');
   }

apps/api/src/management/lifecycle/lifecycle-hooks.service.ts

@@ -72,6 +72,9 @@ export class LifecycleHooksService extends AbstractLifecycleService {
     }
 
     for (const file of defaultFiles) {
+      if (file === 'rules') {
+        continue;
+      }
       if (!files.includes(file)) {
         try {
           const defaultFile = readFileSync(`${process.cwd()}/defaults/lifecycle/${file}`, 'utf-8');

apps/api/src/management/lifecycle/lifecycle.controller.ts

@@ -30,6 +30,7 @@ import {
   LifecycleRuleFileUpdateDto,
   LifecycleStatesUpdateDto,
 } from './_dto/lifecycle-config.dto';
+import { ManualTransitionsUpdateDto } from './_dto/manual-transitions.dto';
 import { LifecycleConfigService } from './lifecycle-config.service';
 import { LifecycleCrudService } from './lifecycle-crud.service';
 import { LifecycleHooksService } from './lifecycle-hooks.service';
@@ -346,6 +347,40 @@ export class LifecycleController extends AbstractController {
     });
   }
 
+
+  @Get('config/manual-transitions')
+  @UseRoles({
+    resource: '/management/lifecycle',
+    action: AC_ACTIONS.READ,
+    possession: AC_DEFAULT_POSSESSION,
+  })
+  public async getConfigManualTransitions(@Res() res: Response): Promise<Response> {
+    const data = await this.lifecycleConfigService.getManualTransitions();
+
+    return res.json({
+      statusCode: HttpStatus.OK,
+      data: { manualTransitions: data },
+    });
+  }
+
+  @Put('config/manual-transitions')
+  @UseRoles({
+    resource: '/management/lifecycle',
+    action: AC_ACTIONS.UPDATE,
+    possession: AC_DEFAULT_POSSESSION,
+  })
+  public async updateConfigManualTransitions(
+    @Body() body: ManualTransitionsUpdateDto,
+    @Res() res: Response,
+  ): Promise<Response> {
+    const data = await this.lifecycleConfigService.updateManualTransitions(body);
+
+    return res.json({
+      statusCode: HttpStatus.OK,
+      data: { manualTransitions: data },
+    });
+  }
+
   @Put('config/states')
   @UseRoles({
     resource: '/management/lifecycle',