@hed-hog/operations 0.0.300 → 0.0.302

package/src/operations.service.ts

@@ -1,15 +1,109 @@
 import { PrismaService } from '@hed-hog/api-prisma';
-import { IntegrationDeveloperApiService } from '@hed-hog/core';
+import {
+    AiService,
+    FileService,
+    IntegrationDeveloperApiService,
+    SettingService,
+} from '@hed-hog/core';
 import {
     BadRequestException,
     ForbiddenException,
+    Inject,
     Injectable,
+    InternalServerErrorException,
+    Logger,
     NotFoundException,
+    forwardRef,
 } from '@nestjs/common';
 
 const COLLABORATOR_ROLE = 'admin-operations-collaborator';
 const SUPERVISOR_ROLE = 'admin-operations-supervisor';
 const DIRECTOR_ROLE = 'admin-operations-director';
+const CONTRACT_CATEGORY_VALUES = [
+  'employee',
+  'contractor',
+  'client',
+  'supplier',
+  'vendor',
+  'partner',
+  'internal',
+  'other',
+] as const;
+const CONTRACT_TYPE_VALUES = [
+  'clt',
+  'pj',
+  'freelancer_agreement',
+  'service_agreement',
+  'fixed_term',
+  'recurring_service',
+  'nda',
+  'amendment',
+  'addendum',
+  'other',
+] as const;
+const BILLING_MODEL_VALUES = [
+  'time_and_material',
+  'monthly_retainer',
+  'fixed_price',
+] as const;
+const SIGNATURE_STATUS_VALUES = [
+  'not_started',
+  'pending',
+  'partially_signed',
+  'signed',
+  'expired',
+] as const;
+const CONTRACT_STATUS_VALUES = [
+  'draft',
+  'under_review',
+  'active',
+  'renewal',
+  'expired',
+  'closed',
+  'archived',
+] as const;
+const CONTRACT_CREATION_MODE_VALUES = [
+  'blank',
+  'template',
+  'upload',
+  'duplicate',
+] as const;
+const ORIGIN_TYPE_VALUES = [
+  'manual',
+  'employee_hiring',
+  'client_project',
+  'crm_proposal',
+] as const;
+const CONTRACT_DOCUMENT_TYPE_VALUES = [
+  'source_upload',
+  'generated_pdf',
+  'attachment',
+  'other',
+] as const;
+const CONTRACT_DOCUMENT_EXTRACTION_STATUS_VALUES = [
+  'pending',
+  'processing',
+  'completed',
+  'failed',
+  'skipped',
+] as const;
+const PARTY_ROLE_VALUES = [
+  'employee',
+  'employer',
+  'client',
+  'supplier',
+  'vendor',
+  'partner',
+  'witness',
+  'internal_owner',
+  'other',
+] as const;
+const PARTY_TYPE_VALUES = ['individual', 'company', 'internal_team', 'other'] as const;
+const SIGNATURE_ITEM_STATUS_VALUES = ['pending', 'signed', 'rejected'] as const;
+const FINANCIAL_TERM_TYPE_VALUES = ['value', 'payment', 'revenue', 'fine', 'other'] as const;
+const RECURRENCE_VALUES = ['one_time', 'monthly', 'quarterly', 'yearly', 'other'] as const;
+const REVISION_TYPE_VALUES = ['amendment', 'renewal', 'revision', 'addendum', 'other'] as const;
+const REVISION_STATUS_VALUES = ['draft', 'active', 'completed', 'cancelled'] as const;
 
 type ApprovalAction = 'approve' | 'reject';
 type ApprovalTargetType =
@@ -31,11 +125,13 @@ type ActorContext = {
 };
 
 type CollaboratorPayload = {
-  userId: number;
-  code: string;
-  displayName: string;
+  userId?: number | null;
+  personId?: number | null;
+  code?: string | null;
+  displayName?: string | null;
   collaboratorType?: 'clt' | 'pj' | 'freelancer' | 'intern' | 'other';
   department?: string | null;
+  departmentId?: number | null;
   title?: string | null;
   levelLabel?: string | null;
   supervisorCollaboratorId?: number | null;
@@ -63,10 +159,17 @@ type CollaboratorPayload = {
   notes?: string | null;
 };
 
+type DepartmentPayload = {
+  code?: string | null;
+  name?: string | null;
+  description?: string | null;
+  status?: 'active' | 'inactive';
+};
+
 type ContractPayload = {
-  code: string;
-  name: string;
-  clientName: string;
+  code?: string | null;
+  name?: string | null;
+  clientName?: string | null;
   contractCategory?:
     | 'employee'
     | 'contractor'
@@ -100,9 +203,10 @@ type ContractPayload = {
   isActive?: boolean;
   accountManagerCollaboratorId?: number | null;
   relatedCollaboratorId?: number | null;
-  originType?: 'manual' | 'employee_hiring' | 'client_project';
+  contractTemplateId?: number | null;
+  originType?: 'manual' | 'employee_hiring' | 'client_project' | 'crm_proposal';
   originId?: number | null;
-  startDate: string;
+  startDate?: string | null;
   endDate?: string | null;
   signedAt?: string | null;
   effectiveDate?: string | null;
@@ -116,6 +220,8 @@ type ContractPayload = {
     | 'expired'
     | 'closed'
     | 'archived';
+  creationMode?: 'blank' | 'template' | 'upload' | 'duplicate';
+  wizardStep?: number | null;
   description?: string | null;
   contentHtml?: string | null;
   parties?: Array<{
@@ -159,15 +265,248 @@ type ContractPayload = {
     summary?: string | null;
   }>;
   replaceUploadedPdfDocument?: {
+    fileId?: number | null;
     fileName: string;
     mimeType: string;
-    fileContentBase64: string;
+    fileContentBase64?: string | null;
+    notes?: string | null;
+    extractionStatus?: 'pending' | 'processing' | 'completed' | 'failed' | 'skipped';
+    extractionSummary?: string | null;
+  } | null;
+};
+
+type ContractDraftPayload = {
+  creationMode?: 'blank' | 'template' | 'upload' | 'duplicate' | null;
+  templateId?: number | null;
+  duplicateFromId?: number | null;
+  sourceFileId?: number | null;
+  sourceFileName?: string | null;
+  sourceMimeType?: string | null;
+};
+
+type ProposalApprovedEventPayload = {
+  proposalId?: number;
+  proposalRevisionId?: number | null;
+  personId?: number | null;
+  approvedByUserId?: number | null;
+  approvedAt?: string | null;
+  correlationId?: string | null;
+  sourceModule?: string | null;
+  sourceEntity?: string | null;
+  sourceId?: string | null;
+  source_module?: string | null;
+  source_entity?: string | null;
+  source_id?: string | null;
+  code?: string | null;
+  title?: string | null;
+  version?: number | null;
+  total?: number | null;
+  currency?: string | null;
+  locale?: string | null;
+  validFrom?: string | null;
+  validUntil?: string | null;
+  commercialTerms?: {
+    contractCategory?: ContractPayload['contractCategory'];
+    contractType?: ContractPayload['contractType'];
+    billingModel?: ContractPayload['billingModel'];
+    validFrom?: string | null;
+    validUntil?: string | null;
+    notes?: string | null;
+  } | null;
+  proposal?: {
+    code?: string | null;
+    title?: string | null;
+    contractCategory?: ContractPayload['contractCategory'];
+    contractType?: ContractPayload['contractType'];
+    billingModel?: ContractPayload['billingModel'];
+    validFrom?: string | null;
+    validUntil?: string | null;
+    totalAmount?: number | null;
+    totalAmountCents?: number | null;
     notes?: string | null;
+  };
+  person?: {
+    id?: number | null;
+    name?: string | null;
+    tradeName?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    document?: string | null;
+  } | null;
+  revision?: {
+    id?: number | null;
+    revisionNumber?: number | null;
+    title?: string | null;
+    summary?: string | null;
+    contentHtml?: string | null;
   } | null;
+  items?: Array<{
+    name?: string | null;
+    description?: string | null;
+    termType?: ContractPayload['financialTerms'][number]['termType'];
+    recurrence?: ContractPayload['financialTerms'][number]['recurrence'];
+    dueDay?: number | null;
+    amount?: number | null;
+    totalAmountCents?: number | null;
+  }>;
+};
+
+type ContractTemplatePayload = {
+  code?: string | null;
+  name?: string | null;
+  description?: string | null;
+  contractCategory?:
+    | 'employee'
+    | 'contractor'
+    | 'client'
+    | 'supplier'
+    | 'vendor'
+    | 'partner'
+    | 'internal'
+    | 'other';
+  contractType?:
+    | 'clt'
+    | 'pj'
+    | 'freelancer_agreement'
+    | 'service_agreement'
+    | 'fixed_term'
+    | 'recurring_service'
+    | 'nda'
+    | 'amendment'
+    | 'addendum'
+    | 'other';
+  billingModel?:
+    | 'time_and_material'
+    | 'monthly_retainer'
+    | 'fixed_price';
+  signatureStatus?:
+    | 'not_started'
+    | 'pending'
+    | 'partially_signed'
+    | 'signed'
+    | 'expired';
+  isActive?: boolean;
+  status?: 'draft' | 'active' | 'inactive' | 'archived';
+  contentHtml?: string | null;
+};
+
+type ContractExtractDraftPayload = {
+  contractId?: number | null;
+  fileName?: string | null;
+  mimeType?: string | null;
+  fileContentBase64?: string | null;
+  provider?: 'openai' | 'gemini' | null;
+  promptMessage?: string | null;
+};
+
+type ContractGenerateContentPayload = {
+  provider?: 'openai' | 'gemini' | null;
+  promptMessage?: string | null;
+  overwrite?: boolean;
+};
+
+type ContractLegalReviewPayload = {
+  provider?: 'openai' | 'gemini' | null;
+  promptMessage?: string | null;
+};
+
+type ContractLegalReviewResult = {
+  summary: string;
+  missingFields: string[];
+  warnings: string[];
+  checklist: string[];
+  status: 'ready_for_revision' | 'attention_required';
+  reviewedAt: string;
+};
+
+type ContractProjectSummary = {
+  id: number;
+  code: string;
+  name: string;
+  status: string;
+};
+
+type ContractScheduleDay = {
+  weekday: string;
+  isWorkingDay: boolean;
+  startTime: string | null;
+  endTime: string | null;
+  breakMinutes: number | null;
+};
+
+type ContractDocumentRecord = {
+  id: number;
+  documentType: (typeof CONTRACT_DOCUMENT_TYPE_VALUES)[number];
+  fileId: number | null;
+  fileName: string;
+  mimeType: string;
+  fileContentBase64: string | null;
+  isCurrent: boolean;
+  extractionStatus:
+    | (typeof CONTRACT_DOCUMENT_EXTRACTION_STATUS_VALUES)[number]
+    | null;
+  extractionSummary: string | null;
+  notes: string | null;
+  createdAt: string;
+};
+
+type ContractHistoryRecord = {
+  id: number;
+  actorUserId: number | null;
+  action: string;
+  note: string | null;
+  metadataJson: string | null;
+  createdAt: string;
+};
+
+type ContractDetailRecord = {
+  id: number;
+  code: string;
+  name: string | null;
+  contractCategory: (typeof CONTRACT_CATEGORY_VALUES)[number];
+  contractType: (typeof CONTRACT_TYPE_VALUES)[number];
+  clientName: string | null;
+  signatureStatus: (typeof SIGNATURE_STATUS_VALUES)[number];
+  isActive: boolean;
+  billingModel: (typeof BILLING_MODEL_VALUES)[number];
+  accountManagerCollaboratorId: number | null;
+  relatedCollaboratorId: number | null;
+  contractTemplateId: number | null;
+  contractTemplateName: string | null;
+  contractTemplateSlug: string | null;
+  contractTemplateCode: string | null;
+  originType: (typeof ORIGIN_TYPE_VALUES)[number];
+  originId: number | null;
+  startDate: string | null;
+  endDate: string | null;
+  signedAt: string | null;
+  effectiveDate: string | null;
+  budgetAmount: number | null;
+  monthlyHourCap: number | null;
+  status: (typeof CONTRACT_STATUS_VALUES)[number];
+  creationMode: (typeof CONTRACT_CREATION_MODE_VALUES)[number] | null;
+  wizardStep: number | null;
+  description: string | null;
+  contentHtml: string | null;
+  accountManagerName: string | null;
+  relatedCollaboratorName: string | null;
+};
+
+type ContractDetailsRecord = ContractDetailRecord & {
+  mainRelatedPartyName: string | null;
+  projects: ContractProjectSummary[];
+  scheduleSummary: ContractScheduleDay[];
+  parties: NonNullable<ContractPayload['parties']>;
+  signatures: NonNullable<ContractPayload['signatures']>;
+  financialTerms: NonNullable<ContractPayload['financialTerms']>;
+  documents: ContractDocumentRecord[];
+  revisions: NonNullable<ContractPayload['revisions']>;
+  history: ContractHistoryRecord[];
 };
 
 type ProjectPayload = {
   contractId?: number | null;
+  contractTemplateId?: number | null;
   managerCollaboratorId?: number | null;
   code: string;
   name: string;
@@ -284,9 +623,16 @@ type PublishAccountsPayableReferencePayload = {
 
 @Injectable()
 export class OperationsService {
+  private readonly logger = new Logger(OperationsService.name);
+
   constructor(
     private readonly prisma: PrismaService,
+    private readonly aiService: AiService,
     private readonly integrationApi: IntegrationDeveloperApiService,
+    @Inject(forwardRef(() => FileService))
+    private readonly fileService: FileService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly settingService: SettingService,
   ) {}
 
   async getDashboard(userId: number) {
@@ -416,10 +762,14 @@ export class OperationsService {
     return this.queryRows(
       `SELECT c.id,
               c.user_id AS "userId",
+              c.person_id AS "personId",
               c.code,
               c.collaborator_type AS "collaboratorType",
-              c.display_name AS "displayName",
-              c.department,
+              COALESCE(NULLIF(c.display_name, ''), person_record.name) AS "displayName",
+              person_record.name AS "personName",
+              person_record.avatar_id AS "personAvatarId",
+              c.department_id AS "departmentId",
+              COALESCE(NULLIF(department_record.name, ''), NULLIF(c.department, '')) AS "department",
               c.title,
               c.level_label AS "levelLabel",
               c.weekly_capacity_hours AS "weeklyCapacityHours",
@@ -433,6 +783,11 @@ export class OperationsService {
               hiring_contract.status AS "contractStatus",
               COUNT(DISTINCT pa.id)::int AS "activeAssignments"
          FROM operations_collaborator c
+         LEFT JOIN person person_record
+           ON person_record.id = c.person_id
+         LEFT JOIN operations_department department_record
+           ON department_record.id = c.department_id
+          AND department_record.deleted_at IS NULL
          LEFT JOIN operations_collaborator s
            ON s.id = c.supervisor_collaborator_id
          LEFT JOIN operations_project_assignment pa
@@ -450,8 +805,8 @@ export class OperationsService {
          ) hiring_contract ON TRUE
         WHERE c.deleted_at IS NULL
           AND ${filter.clause}
-        GROUP BY c.id, s.id, hiring_contract.id, hiring_contract.status
-        ORDER BY c.display_name ASC`,
+        GROUP BY c.id, person_record.id, department_record.id, s.id, hiring_contract.id, hiring_contract.status
+        ORDER BY COALESCE(NULLIF(c.display_name, ''), person_record.name) ASC`,
       filter.params
     );
   }
@@ -494,10 +849,14 @@ export class OperationsService {
     const teamMembers = await this.queryRows(
       `SELECT c.id,
               c.user_id AS "userId",
+              c.person_id AS "personId",
               c.code,
-              c.display_name AS "displayName",
+              COALESCE(NULLIF(c.display_name, ''), person_record.name) AS "displayName",
+              person_record.name AS "personName",
+              person_record.avatar_id AS "personAvatarId",
               c.collaborator_type AS "collaboratorType",
-              c.department,
+              c.department_id AS "departmentId",
+              COALESCE(NULLIF(department_record.name, ''), NULLIF(c.department, '')) AS "department",
               c.title,
               c.status,
               COUNT(DISTINCT pa.id)::int AS "activeAssignments",
@@ -505,6 +864,11 @@ export class OperationsService {
               COUNT(DISTINCT tor.id) FILTER (WHERE tor.status = 'submitted')::int AS "pendingTimeOffRequests",
               COUNT(DISTINCT sar.id) FILTER (WHERE sar.status = 'submitted')::int AS "pendingScheduleAdjustmentRequests"
          FROM operations_collaborator c
+         LEFT JOIN person person_record
+           ON person_record.id = c.person_id
+         LEFT JOIN operations_department department_record
+           ON department_record.id = c.department_id
+          AND department_record.deleted_at IS NULL
          LEFT JOIN operations_project_assignment pa
            ON pa.collaborator_id = c.id
           AND pa.deleted_at IS NULL
@@ -522,8 +886,8 @@ export class OperationsService {
           AND sar.deleted_at IS NULL
           AND sar.status = 'submitted'
         WHERE c.deleted_at IS NULL AND ${teamFilter.clause}
-        GROUP BY c.id
-        ORDER BY c.display_name ASC`,
+        GROUP BY c.id, person_record.id, department_record.id
+        ORDER BY COALESCE(NULLIF(c.display_name, ''), person_record.name) ASC`,
       teamFilter.params
     );
 
@@ -694,17 +1058,40 @@ export class OperationsService {
   async createCollaborator(userId: number, data: CollaboratorPayload) {
     const actor = await this.getActorContext(userId);
     this.ensureDirector(actor);
-    this.requireFields(data, ['userId', 'code', 'displayName']);
+
+    const resolvedPerson = data.personId
+      ? await this.getPersonById(Number(data.personId))
+      : null;
+    const resolvedDisplayName =
+      resolvedPerson?.name?.trim() ?? data.displayName?.trim() ?? '';
+
+    if (!resolvedDisplayName) {
+      throw new BadRequestException('Field "personId" is required.');
+    }
 
     const collaboratorId = await this.prisma.$transaction(async (tx) => {
+      const normalizedCode =
+        String(data.code ?? '').trim() ||
+        (await this.generateCollaboratorCode(tx as any));
+
+      const resolvedDepartment = await this.resolveDepartmentReference(
+        tx as any,
+        {
+          departmentId: data.departmentId ?? null,
+          departmentName: data.department,
+        }
+      );
+
       const created = (await (tx as any).$queryRawUnsafe(
         `INSERT INTO operations_collaborator (
           user_id,
+          person_id,
           supervisor_collaborator_id,
           code,
           collaborator_type,
           display_name,
           department,
+          department_id,
           title,
           level_label,
           weekly_capacity_hours,
@@ -715,16 +1102,21 @@ export class OperationsService {
           created_at,
           updated_at
         ) VALUES (
-          $1, $2, $3, COALESCE($4, 'other'), $5, $6, $7, $8, $9,
-          COALESCE($10, 'active'), $11, $12, $13, NOW(), NOW()
+          $1, $2, $3, $4,
+          $5::operations_collaborator_collaborator_type_7dd7b0ada2_enum,
+          $6, $7, $8, $9, $10, $11,
+          $12::operations_collaborator_status_ef779877d4_enum,
+          $13::date, $14::date, $15, NOW(), NOW()
         )
         RETURNING id`,
-        data.userId,
+        data.userId ?? null,
+        resolvedPerson?.id ?? null,
         data.supervisorCollaboratorId ?? null,
-        data.code,
+        normalizedCode,
         data.collaboratorType ?? 'other',
-        data.displayName,
-        data.department ?? null,
+        resolvedDisplayName,
+        resolvedDepartment?.name ?? null,
+        resolvedDepartment?.id ?? null,
         data.title ?? null,
         data.levelLabel ?? null,
         data.weeklyCapacityHours ?? null,
@@ -744,8 +1136,8 @@ export class OperationsService {
       if (data.autoGenerateContractDraft !== false) {
         await this.createHiringContractDraft(tx as any, actor.userId, {
           collaboratorId: createdCollaboratorId,
-          collaboratorCode: data.code,
-          displayName: data.displayName,
+          collaboratorCode: normalizedCode,
+          displayName: resolvedDisplayName,
           collaboratorType: data.collaboratorType ?? 'other',
           supervisorCollaboratorId: data.supervisorCollaboratorId ?? null,
           startDate: data.joinedAt ?? null,
@@ -772,20 +1164,65 @@ export class OperationsService {
 
     const updates: string[] = [];
     const params: unknown[] = [];
-    this.pushUpdate(updates, params, 'supervisor_collaborator_id', data.supervisorCollaboratorId);
-    this.pushUpdate(updates, params, 'code', data.code);
-    this.pushUpdate(updates, params, 'collaborator_type', data.collaboratorType);
-    this.pushUpdate(updates, params, 'display_name', data.displayName);
-    this.pushUpdate(updates, params, 'department', data.department);
+    const resolvedPerson =
+      data.personId !== undefined && data.personId !== null
+        ? await this.getPersonById(Number(data.personId))
+        : null;
+    const resolvedDisplayName =
+      resolvedPerson?.name?.trim() ?? data.displayName?.trim() ?? undefined;
+
+    this.pushUpdate(updates, params, 'user_id', data.userId);
+    this.pushUpdate(updates, params, 'person_id', data.personId);
+    this.pushUpdate(
+      updates,
+      params,
+      'supervisor_collaborator_id',
+      data.supervisorCollaboratorId
+    );
+    this.pushUpdate(updates, params, 'code', data.code?.trim());
+    this.pushUpdate(
+      updates,
+      params,
+      'collaborator_type',
+      data.collaboratorType,
+      'operations_collaborator_collaborator_type_7dd7b0ada2_enum'
+    );
+    if (data.personId !== undefined || data.displayName !== undefined) {
+      this.pushUpdate(updates, params, 'display_name', resolvedDisplayName ?? null);
+    }
     this.pushUpdate(updates, params, 'title', data.title);
     this.pushUpdate(updates, params, 'level_label', data.levelLabel);
     this.pushUpdate(updates, params, 'weekly_capacity_hours', data.weeklyCapacityHours);
-    this.pushUpdate(updates, params, 'status', data.status);
-    this.pushUpdate(updates, params, 'joined_at', data.joinedAt);
-    this.pushUpdate(updates, params, 'left_at', data.leftAt);
+    this.pushUpdate(
+      updates,
+      params,
+      'status',
+      data.status,
+      'operations_collaborator_status_ef779877d4_enum'
+    );
+    this.pushUpdate(updates, params, 'joined_at', data.joinedAt, 'date');
+    this.pushUpdate(updates, params, 'left_at', data.leftAt, 'date');
     this.pushUpdate(updates, params, 'notes', data.notes);
 
     await this.prisma.$transaction(async (tx) => {
+      if (data.department !== undefined || data.departmentId !== undefined) {
+        const resolvedDepartment = await this.resolveDepartmentReference(
+          tx as any,
+          {
+            departmentId: data.departmentId ?? null,
+            departmentName: data.department,
+          }
+        );
+
+        this.pushUpdate(updates, params, 'department', resolvedDepartment?.name ?? null);
+        this.pushUpdate(
+          updates,
+          params,
+          'department_id',
+          resolvedDepartment?.id ?? null
+        );
+      }
+
       if (updates.length) {
         params.push(collaboratorId);
         await (tx as any).$executeRawUnsafe(
@@ -809,6 +1246,152 @@ export class OperationsService {
     return this.getCollaboratorByIdForUser(userId, collaboratorId);
   }
 
+  async listDepartments(userId: number) {
+    const actor = await this.getActorContext(userId);
+    this.ensureCollaborator(actor);
+
+    return this.queryRows(
+      `SELECT d.id,
+              d.slug,
+              d.code,
+              d.name,
+              d.description,
+              CASE WHEN d.deleted_at IS NULL THEN 'active' ELSE 'inactive' END AS status,
+              COUNT(DISTINCT c.id)::int AS "collaboratorCount",
+              d.created_at AS "createdAt",
+              d.updated_at AS "updatedAt"
+         FROM operations_department d
+         LEFT JOIN operations_collaborator c
+           ON c.deleted_at IS NULL
+          AND (
+            c.department_id = d.id
+            OR (
+              c.department_id IS NULL
+              AND LOWER(COALESCE(c.department, '')) = LOWER(d.name)
+            )
+          )
+        GROUP BY d.id
+        ORDER BY CASE WHEN d.deleted_at IS NULL THEN 0 ELSE 1 END ASC,
+                 d.name ASC`
+    );
+  }
+
+  async createDepartment(userId: number, data: DepartmentPayload) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+
+    const name = this.normalizeOptionalText(data.name);
+    if (!name) {
+      throw new BadRequestException('Department name is required.');
+    }
+
+    return this.prisma.$transaction(async (tx) => {
+      await this.assertDepartmentNameAvailable(tx as any, name);
+
+      const normalizedCode =
+        this.normalizeOptionalText(data.code)?.toUpperCase() ?? null;
+
+      if (normalizedCode) {
+        await this.assertDepartmentCodeAvailable(tx as any, normalizedCode);
+      }
+
+      const created = (await (tx as any).$queryRawUnsafe(
+        `INSERT INTO operations_department (
+          slug,
+          code,
+          name,
+          description,
+          deleted_at,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1, $2, $3, $4,
+          CASE WHEN $5 = 'inactive' THEN NOW() ELSE NULL END,
+          NOW(), NOW()
+        )
+        RETURNING id`,
+        await this.generateUniqueDepartmentSlug(tx as any, name),
+        normalizedCode,
+        name,
+        this.normalizeOptionalText(data.description),
+        data.status ?? 'active'
+      )) as { id: number }[];
+
+      const createdDepartmentId = created[0]?.id;
+      if (!createdDepartmentId) {
+        throw new BadRequestException('Unable to create the department.');
+      }
+
+      return this.getDepartmentById(tx as any, createdDepartmentId, true);
+    });
+  }
+
+  async updateDepartment(
+    userId: number,
+    departmentId: number,
+    data: Partial<DepartmentPayload>
+  ) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+
+    return this.prisma.$transaction(async (tx) => {
+      const current = await this.getDepartmentById(tx as any, departmentId, true);
+      const nextName =
+        data.name !== undefined
+          ? this.normalizeOptionalText(data.name)
+          : current.name;
+
+      if (!nextName) {
+        throw new BadRequestException('Department name is required.');
+      }
+
+      if (String(nextName).toLowerCase() !== String(current.name).toLowerCase()) {
+        await this.assertDepartmentNameAvailable(tx as any, nextName, departmentId);
+      }
+
+      const nextCode =
+        data.code !== undefined
+          ? this.normalizeOptionalText(data.code)?.toUpperCase() ?? null
+          : (current.code ?? null);
+
+      if (nextCode) {
+        await this.assertDepartmentCodeAvailable(tx as any, nextCode, departmentId);
+      }
+
+      const nextDescription =
+        data.description !== undefined
+          ? this.normalizeOptionalText(data.description)
+          : (current.description ?? null);
+      const nextStatus = data.status ?? current.status ?? 'active';
+      const nextSlug =
+        String(nextName).toLowerCase() !== String(current.name).toLowerCase()
+          ? await this.generateUniqueDepartmentSlug(tx as any, nextName, departmentId)
+          : current.slug;
+
+      await (tx as any).$executeRawUnsafe(
+        `UPDATE operations_department
+            SET slug = $1,
+                code = $2,
+                name = $3,
+                description = $4,
+                deleted_at = CASE
+                  WHEN $5 = 'inactive' THEN COALESCE(deleted_at, NOW())
+                  ELSE NULL
+                END,
+                updated_at = NOW()
+          WHERE id = $6`,
+        nextSlug,
+        nextCode,
+        nextName,
+        nextDescription,
+        nextStatus,
+        departmentId
+      );
+
+      return this.getDepartmentById(tx as any, departmentId, true);
+    });
+  }
+
   async listProjects(userId: number) {
     const actor = await this.getActorContext(userId);
     const filter = this.buildIdFilter(actor.visibleProjectIds, 'p.id', actor.isDirector);
@@ -887,8 +1470,11 @@ export class OperationsService {
           created_at,
           updated_at
         ) VALUES (
-          $1, $2, $3, $4, $5, $6, COALESCE($7, 'planning'), $8,
-          COALESCE($9, 'project_delivery'), $10, $11, $12, NOW(), NOW()
+          $1, $2, $3, $4, $5, $6,
+          $7::operations_project_status_965e8d4b2d_enum,
+          $8,
+          $9::operations_project_delivery_model_75ee11b3b7_enum,
+          $10, $11::date, $12::date, NOW(), NOW()
         )
         RETURNING id`,
         data.contractId ?? null,
@@ -921,6 +1507,7 @@ export class OperationsService {
           actor.userId,
           {
             projectId,
+            contractTemplateId: data.contractTemplateId ?? null,
             projectCode: data.code,
             projectName: data.name,
             clientName: data.clientName ?? data.name,
@@ -955,7 +1542,7 @@ export class OperationsService {
   async updateProject(userId: number, projectId: number, data: Partial<ProjectPayload>) {
     const actor = await this.getActorContext(userId);
     this.ensureDirector(actor);
-    await this.getProjectById(userId, projectId);
+    const currentProject = await this.getProjectById(userId, projectId);
 
     const updates: string[] = [];
     const params: unknown[] = [];
@@ -965,12 +1552,24 @@ export class OperationsService {
     this.pushUpdate(updates, params, 'name', data.name);
     this.pushUpdate(updates, params, 'client_name', data.clientName);
     this.pushUpdate(updates, params, 'summary', data.summary);
-    this.pushUpdate(updates, params, 'status', data.status);
+    this.pushUpdate(
+      updates,
+      params,
+      'status',
+      data.status,
+      'operations_project_status_965e8d4b2d_enum'
+    );
     this.pushUpdate(updates, params, 'progress_percent', data.progressPercent);
-    this.pushUpdate(updates, params, 'delivery_model', data.deliveryModel);
+    this.pushUpdate(
+      updates,
+      params,
+      'delivery_model',
+      data.deliveryModel,
+      'operations_project_delivery_model_75ee11b3b7_enum'
+    );
     this.pushUpdate(updates, params, 'budget_amount', data.budgetAmount);
-    this.pushUpdate(updates, params, 'start_date', data.startDate);
-    this.pushUpdate(updates, params, 'end_date', data.endDate);
+    this.pushUpdate(updates, params, 'start_date', data.startDate, 'date');
+    this.pushUpdate(updates, params, 'end_date', data.endDate, 'date');
 
     await this.prisma.$transaction(async (tx) => {
       if (updates.length) {
@@ -991,102 +1590,374 @@ export class OperationsService {
           data.teamAssignments
         );
       }
+
+      const nextContractId =
+        data.contractId !== undefined
+          ? data.contractId
+          : (currentProject.contractId ?? null);
+      const shouldGenerateDraft =
+        !nextContractId && data.autoGenerateContractDraft === true;
+
+      if (shouldGenerateDraft) {
+        const contractId = await this.createProjectContractDraft(
+          tx as any,
+          actor.userId,
+          {
+            projectId,
+            contractTemplateId: data.contractTemplateId ?? null,
+            projectCode: data.code ?? currentProject.code,
+            projectName: data.name ?? currentProject.name,
+            clientName:
+              data.clientName ??
+              currentProject.clientName ??
+              currentProject.name,
+            managerCollaboratorId:
+              data.managerCollaboratorId ??
+              currentProject.managerCollaboratorId ??
+              null,
+            startDate: data.startDate ?? currentProject.startDate ?? null,
+            endDate: data.endDate ?? currentProject.endDate ?? null,
+            budgetAmount: data.budgetAmount ?? currentProject.budgetAmount ?? null,
+            monthlyHourCap:
+              data.monthlyHourCap ??
+              currentProject.relatedContract?.monthlyHourCap ??
+              null,
+            billingModel:
+              data.billingModel ??
+              currentProject.relatedContract?.billingModel ??
+              'time_and_material',
+            contractCode:
+              data.contractCode ?? currentProject.relatedContract?.code ?? null,
+            contractName:
+              data.contractName ?? currentProject.relatedContract?.name ?? null,
+            description:
+              data.contractDescription ??
+              currentProject.relatedContract?.description ??
+              data.summary ??
+              currentProject.summary ??
+              null,
+          }
+        );
+
+        await (tx as any).$executeRawUnsafe(
+          `UPDATE operations_project
+              SET contract_id = $1,
+                  updated_at = NOW()
+            WHERE id = $2`,
+          contractId,
+          projectId
+        );
+      }
     });
 
     return this.getProjectById(userId, projectId);
   }
 
-  async listContracts(userId: number) {
+  async listContractTemplates(userId: number) {
     const actor = await this.getActorContext(userId);
-    const params: unknown[] = [];
-    const accessClause = actor.isDirector
-      ? 'c.deleted_at IS NULL'
-      : `c.deleted_at IS NULL AND (
-          c.related_collaborator_id = ANY(${this.param(params, actor.visibleCollaboratorIds)}::int[])
-          OR EXISTS (
-            SELECT 1
-              FROM operations_project p_access
-             WHERE p_access.contract_id = c.id
-               AND p_access.deleted_at IS NULL
-               AND p_access.id = ANY(${this.param(params, actor.visibleProjectIds)}::int[])
-          )
-        )`;
+    this.ensureDirector(actor);
 
     return this.queryRows(
-      `SELECT c.id,
-              c.code,
-              c.name,
-              c.contract_category AS "contractCategory",
-              c.contract_type AS "contractType",
-              c.client_name AS "clientName",
-              c.signature_status AS "signatureStatus",
-              c.is_active AS "isActive",
-              c.billing_model AS "billingModel",
-              c.account_manager_collaborator_id AS "accountManagerCollaboratorId",
-              c.related_collaborator_id AS "relatedCollaboratorId",
-              c.origin_type AS "originType",
-              c.origin_id AS "originId",
-              c.start_date AS "startDate",
-              c.end_date AS "endDate",
-              c.signed_at AS "signedAt",
-              c.effective_date AS "effectiveDate",
-              c.budget_amount AS "budgetAmount",
-              c.monthly_hour_cap AS "monthlyHourCap",
-              c.status,
-              c.description,
-              m.display_name AS "accountManagerName",
-              linked.display_name AS "relatedCollaboratorName",
-              COALESCE(primary_party.display_name, linked.display_name, c.client_name) AS "mainRelatedPartyName",
-              COALESCE(financials.value_amount, 0) AS "valueAmount",
-              COALESCE(financials.payment_amount, 0) AS "paymentAmount",
-              COALESCE(financials.revenue_amount, 0) AS "revenueAmount",
-              COALESCE(financials.fine_amount, 0) AS "fineAmount",
-              COALESCE(pdf_document.file_name, '') AS "currentPdfFileName",
-              COUNT(DISTINCT p.id)::int AS "projectCount"
-         FROM operations_contract c
-         LEFT JOIN operations_collaborator m ON m.id = c.account_manager_collaborator_id
-         LEFT JOIN operations_collaborator linked ON linked.id = c.related_collaborator_id
-         LEFT JOIN LATERAL (
-           SELECT cp.display_name
-             FROM operations_contract_party cp
-            WHERE cp.contract_id = c.id
-              AND cp.deleted_at IS NULL
-            ORDER BY cp.is_primary DESC, cp.id ASC
-            LIMIT 1
-         ) primary_party ON TRUE
-         LEFT JOIN LATERAL (
-           SELECT
-             SUM(CASE WHEN term_type = 'value' THEN amount ELSE 0 END) AS value_amount,
-             SUM(CASE WHEN term_type = 'payment' THEN amount ELSE 0 END) AS payment_amount,
-             SUM(CASE WHEN term_type = 'revenue' THEN amount ELSE 0 END) AS revenue_amount,
-             SUM(CASE WHEN term_type = 'fine' THEN amount ELSE 0 END) AS fine_amount
-           FROM operations_contract_financial_term ft
-          WHERE ft.contract_id = c.id
-            AND ft.deleted_at IS NULL
-         ) financials ON TRUE
-         LEFT JOIN LATERAL (
-           SELECT cd.file_name
-             FROM operations_contract_document cd
-            WHERE cd.contract_id = c.id
-              AND cd.deleted_at IS NULL
-              AND cd.is_current = true
-              AND cd.document_type IN ('uploaded_pdf', 'generated_pdf')
-            ORDER BY cd.id DESC
-            LIMIT 1
-         ) pdf_document ON TRUE
+      `SELECT t.id,
+              t.slug,
+              t.code,
+              t.name,
+              t.description,
+              t.contract_category AS "contractCategory",
+              t.contract_type AS "contractType",
+              t.billing_model AS "billingModel",
+              t.signature_status AS "signatureStatus",
+              t.is_active AS "isActive",
+              t.status,
+              t.content_html AS "contentHtml",
+              t.created_at AS "createdAt",
+              t.updated_at AS "updatedAt",
+              COUNT(DISTINCT c.id)::int AS "usageCount"
+         FROM operations_contract_template t
+         LEFT JOIN operations_contract c
+           ON c.contract_template_id = t.id
+          AND c.deleted_at IS NULL
+        WHERE t.deleted_at IS NULL
+        GROUP BY t.id
+        ORDER BY CASE
+                   WHEN t.status = 'active' THEN 0
+                   WHEN t.status = 'draft' THEN 1
+                   WHEN t.status = 'inactive' THEN 2
+                   ELSE 3
+                 END,
+                 t.name ASC`
+    );
+  }
+
+  async getContractTemplateById(userId: number, templateId: number) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+
+    return this.getContractTemplateRecord(this.prisma as any, templateId);
+  }
+
+  async createContractTemplate(userId: number, data: ContractTemplatePayload) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+
+    const name = this.normalizeOptionalText(data.name);
+    if (!name) {
+      throw new BadRequestException('Contract template name is required.');
+    }
+
+    return this.prisma.$transaction(async (tx) => {
+      await this.assertContractTemplateNameAvailable(tx as any, name);
+
+      const nextCode =
+        this.normalizeOptionalText(data.code)?.toUpperCase() ?? null;
+
+      if (nextCode) {
+        await this.assertContractTemplateCodeAvailable(tx as any, nextCode);
+      }
+
+      const nextStatus = data.status ?? 'active';
+      const isActive =
+        data.isActive ?? !['inactive', 'archived'].includes(nextStatus);
+
+      const created = (await (tx as any).$queryRawUnsafe(
+        `INSERT INTO operations_contract_template (
+          slug,
+          code,
+          name,
+          description,
+          contract_category,
+          contract_type,
+          billing_model,
+          signature_status,
+          is_active,
+          status,
+          content_html,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1, $2, $3, $4,
+          $5, $6, $7, $8, $9, $10, $11,
+          NOW(), NOW()
+        )
+        RETURNING id`,
+        await this.generateUniqueContractTemplateSlug(tx as any, name),
+        nextCode,
+        name,
+        this.normalizeOptionalText(data.description),
+        data.contractCategory ?? 'client',
+        data.contractType ?? 'service_agreement',
+        data.billingModel ?? 'time_and_material',
+        data.signatureStatus ?? 'not_started',
+        isActive,
+        nextStatus,
+        this.normalizeOptionalText(data.contentHtml)
+      )) as { id: number }[];
+
+      const templateId = created[0]?.id;
+      if (!templateId) {
+        throw new BadRequestException('Unable to create the contract template.');
+      }
+
+      return this.getContractTemplateRecord(tx as any, templateId, true);
+    });
+  }
+
+  async updateContractTemplate(
+    userId: number,
+    templateId: number,
+    data: Partial<ContractTemplatePayload>
+  ) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+
+    return this.prisma.$transaction(async (tx) => {
+      const current = await this.getContractTemplateRecord(
+        tx as any,
+        templateId,
+        true
+      );
+
+      const nextName =
+        data.name !== undefined
+          ? this.normalizeOptionalText(data.name)
+          : current.name;
+
+      if (!nextName) {
+        throw new BadRequestException('Contract template name is required.');
+      }
+
+      if (String(nextName).toLowerCase() !== String(current.name).toLowerCase()) {
+        await this.assertContractTemplateNameAvailable(
+          tx as any,
+          nextName,
+          templateId
+        );
+      }
+
+      const nextCode =
+        data.code !== undefined
+          ? this.normalizeOptionalText(data.code)?.toUpperCase() ?? null
+          : (current.code ?? null);
+
+      if (nextCode) {
+        await this.assertContractTemplateCodeAvailable(
+          tx as any,
+          nextCode,
+          templateId
+        );
+      }
+
+      const nextStatus = data.status ?? current.status ?? 'active';
+      const nextIsActive =
+        data.isActive ?? !['inactive', 'archived'].includes(nextStatus);
+      const nextSlug =
+        String(nextName).toLowerCase() !== String(current.name).toLowerCase()
+          ? await this.generateUniqueContractTemplateSlug(
+              tx as any,
+              nextName,
+              templateId
+            )
+          : current.slug;
+
+      await (tx as any).$executeRawUnsafe(
+        `UPDATE operations_contract_template
+            SET slug = $1,
+                code = $2,
+                name = $3,
+                description = $4,
+                contract_category = $5,
+                contract_type = $6,
+                billing_model = $7,
+                signature_status = $8,
+                is_active = $9,
+                status = $10,
+                content_html = $11,
+                updated_at = NOW()
+          WHERE id = $12`,
+        nextSlug,
+        nextCode,
+        nextName,
+        data.description !== undefined
+          ? this.normalizeOptionalText(data.description)
+          : (current.description ?? null),
+        data.contractCategory ?? current.contractCategory ?? 'client',
+        data.contractType ?? current.contractType ?? 'service_agreement',
+        data.billingModel ?? current.billingModel ?? 'time_and_material',
+        data.signatureStatus ?? current.signatureStatus ?? 'not_started',
+        nextIsActive,
+        nextStatus,
+        data.contentHtml !== undefined
+          ? this.normalizeOptionalText(data.contentHtml)
+          : (current.contentHtml ?? null),
+        templateId
+      );
+
+      return this.getContractTemplateRecord(tx as any, templateId, true);
+    });
+  }
+
+  async listContracts(userId: number) {
+    const actor = await this.getActorContext(userId);
+    const params: unknown[] = [];
+    const accessClause = actor.isDirector
+      ? 'c.deleted_at IS NULL'
+      : `c.deleted_at IS NULL AND (
+          c.related_collaborator_id = ANY(${this.param(params, actor.visibleCollaboratorIds)}::int[])
+          OR EXISTS (
+            SELECT 1
+              FROM operations_project p_access
+             WHERE p_access.contract_id = c.id
+               AND p_access.deleted_at IS NULL
+               AND p_access.id = ANY(${this.param(params, actor.visibleProjectIds)}::int[])
+          )
+        )`;
+
+    return this.queryRows(
+      `SELECT c.id,
+              c.code,
+              c.name,
+              c.contract_category AS "contractCategory",
+              c.contract_type AS "contractType",
+              c.client_name AS "clientName",
+              c.signature_status AS "signatureStatus",
+              c.is_active AS "isActive",
+              c.billing_model AS "billingModel",
+              c.account_manager_collaborator_id AS "accountManagerCollaboratorId",
+              c.related_collaborator_id AS "relatedCollaboratorId",
+              c.contract_template_id AS "contractTemplateId",
+              template.name AS "contractTemplateName",
+              template.slug AS "contractTemplateSlug",
+              template.code AS "contractTemplateCode",
+              c.origin_type AS "originType",
+              c.origin_id AS "originId",
+              c.start_date AS "startDate",
+              c.end_date AS "endDate",
+              c.signed_at AS "signedAt",
+              c.effective_date AS "effectiveDate",
+              c.budget_amount AS "budgetAmount",
+              c.monthly_hour_cap AS "monthlyHourCap",
+              c.status,
+              c.creation_mode AS "creationMode",
+              c.wizard_step AS "wizardStep",
+              c.description,
+              m.display_name AS "accountManagerName",
+              linked.display_name AS "relatedCollaboratorName",
+              MAX(COALESCE(primary_party.display_name, linked.display_name, c.client_name)) AS "mainRelatedPartyName",
+              MAX(COALESCE(financials.value_amount, 0)) AS "valueAmount",
+              MAX(COALESCE(financials.payment_amount, 0)) AS "paymentAmount",
+              MAX(COALESCE(financials.revenue_amount, 0)) AS "revenueAmount",
+              MAX(COALESCE(financials.fine_amount, 0)) AS "fineAmount",
+              MAX(COALESCE(pdf_document.file_name, '')) AS "currentPdfFileName",
+              COUNT(DISTINCT p.id)::int AS "projectCount"
+         FROM operations_contract c
+         LEFT JOIN operations_collaborator m ON m.id = c.account_manager_collaborator_id
+         LEFT JOIN operations_collaborator linked ON linked.id = c.related_collaborator_id
+         LEFT JOIN operations_contract_template template
+           ON template.id = c.contract_template_id
+         LEFT JOIN LATERAL (
+           SELECT cp.display_name
+             FROM operations_contract_party cp
+            WHERE cp.contract_id = c.id
+              AND cp.deleted_at IS NULL
+            ORDER BY cp.is_primary DESC, cp.id ASC
+            LIMIT 1
+         ) primary_party ON TRUE
+         LEFT JOIN LATERAL (
+           SELECT
+             SUM(CASE WHEN term_type = 'value' THEN amount ELSE 0 END) AS value_amount,
+             SUM(CASE WHEN term_type = 'payment' THEN amount ELSE 0 END) AS payment_amount,
+             SUM(CASE WHEN term_type = 'revenue' THEN amount ELSE 0 END) AS revenue_amount,
+             SUM(CASE WHEN term_type = 'fine' THEN amount ELSE 0 END) AS fine_amount
+           FROM operations_contract_financial_term ft
+          WHERE ft.contract_id = c.id
+            AND ft.deleted_at IS NULL
+         ) financials ON TRUE
+         LEFT JOIN LATERAL (
+           SELECT cd.file_name
+             FROM operations_contract_document cd
+            WHERE cd.contract_id = c.id
+              AND cd.deleted_at IS NULL
+              AND cd.is_current = true
+              AND cd.document_type IN ('source_upload', 'generated_pdf')
+            ORDER BY cd.id DESC
+            LIMIT 1
+         ) pdf_document ON TRUE
          LEFT JOIN operations_project p
            ON p.contract_id = c.id
           AND p.deleted_at IS NULL
         WHERE ${accessClause}
-        GROUP BY c.id, m.id, linked.id
-        ORDER BY c.name ASC`,
+        GROUP BY c.id, m.id, linked.id, template.id
+        ORDER BY COALESCE(c.name, c.code, CONCAT('draft-', c.id)) ASC`,
       params
     );
   }
 
-  async getContractById(userId: number, contractId: number) {
+  async getContractById(
+    userId: number,
+    contractId: number
+  ): Promise<ContractDetailsRecord> {
     const actor = await this.getActorContext(userId);
-    const contract = await this.querySingle(
+    const contract = await this.querySingle<ContractDetailRecord>(
       `SELECT c.id,
               c.code,
               c.name,
@@ -1098,6 +1969,10 @@ export class OperationsService {
               c.billing_model AS "billingModel",
               c.account_manager_collaborator_id AS "accountManagerCollaboratorId",
               c.related_collaborator_id AS "relatedCollaboratorId",
+              c.contract_template_id AS "contractTemplateId",
+              template.name AS "contractTemplateName",
+              template.slug AS "contractTemplateSlug",
+              template.code AS "contractTemplateCode",
               c.origin_type AS "originType",
               c.origin_id AS "originId",
               c.start_date AS "startDate",
@@ -1107,6 +1982,8 @@ export class OperationsService {
               c.budget_amount AS "budgetAmount",
               c.monthly_hour_cap AS "monthlyHourCap",
               c.status,
+              c.creation_mode AS "creationMode",
+              c.wizard_step AS "wizardStep",
               c.description,
               c.content_html AS "contentHtml",
               m.display_name AS "accountManagerName",
@@ -1114,6 +1991,8 @@ export class OperationsService {
          FROM operations_contract c
          LEFT JOIN operations_collaborator m ON m.id = c.account_manager_collaborator_id
          LEFT JOIN operations_collaborator linked ON linked.id = c.related_collaborator_id
+         LEFT JOIN operations_contract_template template
+           ON template.id = c.contract_template_id
         WHERE c.id = $1
           AND c.deleted_at IS NULL`,
       [contractId]
@@ -1149,7 +2028,7 @@ export class OperationsService {
 
     const [projects, scheduleSummary, parties, signatures, financialTerms, documents, revisions, history] =
       await Promise.all([
-        this.queryRows(
+        this.queryRows<ContractProjectSummary>(
           `SELECT id, code, name, status
              FROM operations_project
             WHERE contract_id = $1
@@ -1158,7 +2037,7 @@ export class OperationsService {
           [contractId]
         ),
         contract.relatedCollaboratorId
-          ? this.queryRows(
+          ? this.queryRows<ContractScheduleDay>(
               `SELECT weekday,
                       is_working_day AS "isWorkingDay",
                       start_time AS "startTime",
@@ -1170,8 +2049,8 @@ export class OperationsService {
                 ORDER BY id ASC`,
               [contract.relatedCollaboratorId]
             )
-          : Promise.resolve([]),
-        this.queryRows(
+          : Promise.resolve<ContractScheduleDay[]>([]),
+        this.queryRows<NonNullable<ContractPayload['parties']>[number]>(
           `SELECT id,
                   party_role AS "partyRole",
                   party_type AS "partyType",
@@ -1186,7 +2065,7 @@ export class OperationsService {
             ORDER BY is_primary DESC, id ASC`,
           [contractId]
         ),
-        this.queryRows(
+        this.queryRows<NonNullable<ContractPayload['signatures']>[number]>(
           `SELECT id,
                   signer_name AS "signerName",
                   signer_role AS "signerRole",
@@ -1199,7 +2078,7 @@ export class OperationsService {
             ORDER BY id ASC`,
           [contractId]
         ),
-        this.queryRows(
+        this.queryRows<NonNullable<ContractPayload['financialTerms']>[number]>(
           `SELECT id,
                   term_type AS "termType",
                   label,
@@ -1213,13 +2092,16 @@ export class OperationsService {
             ORDER BY id ASC`,
           [contractId]
         ),
-        this.queryRows(
+        this.queryRows<ContractDocumentRecord>(
           `SELECT id,
                   document_type AS "documentType",
+                  file_id AS "fileId",
                   file_name AS "fileName",
                   mime_type AS "mimeType",
                   file_content_base64 AS "fileContentBase64",
                   is_current AS "isCurrent",
+                  extraction_status AS "extractionStatus",
+                  extraction_summary AS "extractionSummary",
                   notes,
                   created_at AS "createdAt"
              FROM operations_contract_document
@@ -1228,7 +2110,7 @@ export class OperationsService {
             ORDER BY is_current DESC, id DESC`,
           [contractId]
         ),
-        this.queryRows(
+        this.queryRows<NonNullable<ContractPayload['revisions']>[number]>(
           `SELECT id,
                   revision_type AS "revisionType",
                   title,
@@ -1241,7 +2123,7 @@ export class OperationsService {
             ORDER BY effective_date DESC NULLS LAST, id DESC`,
           [contractId]
         ),
-        this.queryRows(
+        this.queryRows<ContractHistoryRecord>(
           `SELECT id,
                   actor_user_id AS "actorUserId",
                   action,
@@ -1275,9 +2157,11 @@ export class OperationsService {
   async createContract(userId: number, data: ContractPayload) {
     const actor = await this.getActorContext(userId);
     this.ensureDirector(actor);
-    this.requireFields(data, ['code', 'name', 'clientName', 'startDate']);
 
     const createdId = await this.prisma.$transaction(async (tx) => {
+      const normalizedCode =
+        this.normalizeOptionalText(data.code)?.toUpperCase() ??
+        (await this.generateContractCode(tx as any));
       const created = await (tx as any).$queryRawUnsafe(
         `INSERT INTO operations_contract (
           code,
@@ -1290,6 +2174,7 @@ export class OperationsService {
           billing_model,
           account_manager_collaborator_id,
           related_collaborator_id,
+          contract_template_id,
           origin_type,
           origin_id,
           start_date,
@@ -1299,35 +2184,57 @@ export class OperationsService {
           budget_amount,
           monthly_hour_cap,
           status,
+          creation_mode,
+          wizard_step,
           description,
           content_html,
           created_at,
           updated_at
         ) VALUES (
-          $1, $2, COALESCE($3, 'client'), COALESCE($4, 'service_agreement'), $5, COALESCE($6, 'not_started'),
-          COALESCE($7, true), COALESCE($8, 'time_and_material'), $9, $10, COALESCE($11, 'manual'), $12, $13,
-          $14, $15, $16, $17, $18, COALESCE($19, 'draft'), $20, $21, NOW(), NOW()
+          $1, $2,
+          $3::operations_contract_contract_category_70d553ea09_enum,
+          $4::operations_contract_contract_type_48331e2ebf_enum,
+          $5,
+          $6::operations_contract_signature_status_2cb7282a7b_enum,
+          $7,
+          $8::operations_contract_billing_model_409dc7fea2_enum,
+          $9,
+          $10,
+          $11,
+          $12::operations_contract_origin_type_07a7cc2b5d_enum,
+          $13,
+          $14::date,
+          $15::date, $16::date, $17::date, $18, $19,
+          $20::operations_contract_status_a0395962df_enum,
+          $21::operations_contract_creation_mode_98ba669209_enum,
+          $22,
+          $23,
+          $24,
+          NOW(), NOW()
         )
         RETURNING id`,
-        data.code,
-        data.name,
+        normalizedCode,
+        this.normalizeOptionalText(data.name),
         data.contractCategory ?? 'client',
         data.contractType ?? 'service_agreement',
-        data.clientName,
+        this.normalizeOptionalText(data.clientName),
         data.signatureStatus ?? 'not_started',
         data.isActive ?? true,
         data.billingModel ?? 'time_and_material',
         data.accountManagerCollaboratorId ?? null,
         data.relatedCollaboratorId ?? null,
+        data.contractTemplateId ?? null,
         data.originType ?? 'manual',
         data.originId ?? null,
-        data.startDate,
+        this.normalizeOptionalText(data.startDate ?? null),
         data.endDate ?? null,
         data.signedAt ?? null,
-        data.effectiveDate ?? data.startDate,
+        data.effectiveDate ?? data.startDate ?? null,
         data.budgetAmount ?? null,
         data.monthlyHourCap ?? null,
         data.status ?? 'draft',
+        data.creationMode ?? 'blank',
+        data.wizardStep ?? 0,
         data.description ?? null,
         data.contentHtml ?? null
       );
@@ -1342,9 +2249,10 @@ export class OperationsService {
       );
       await this.replaceContractRevisions(tx as any, contractId, data.revisions);
       if (data.replaceUploadedPdfDocument) {
-        await this.replaceContractPdfDocument(
+        await this.replaceContractDocument(
           tx as any,
           contractId,
+          'source_upload',
           data.replaceUploadedPdfDocument
         );
       }
@@ -1363,94 +2271,1263 @@ export class OperationsService {
     return this.getContractById(userId, createdId);
   }
 
-  async updateContract(userId: number, contractId: number, data: Partial<ContractPayload>) {
+  async createContractDraft(userId: number, data: ContractDraftPayload) {
     const actor = await this.getActorContext(userId);
     this.ensureDirector(actor);
-    await this.getContractById(userId, contractId);
 
-    const updates: string[] = [];
-    const params: unknown[] = [];
-    this.pushUpdate(updates, params, 'code', data.code);
-    this.pushUpdate(updates, params, 'name', data.name);
-    this.pushUpdate(updates, params, 'contract_category', data.contractCategory);
-    this.pushUpdate(updates, params, 'contract_type', data.contractType);
-    this.pushUpdate(updates, params, 'client_name', data.clientName);
-    this.pushUpdate(updates, params, 'signature_status', data.signatureStatus);
-    this.pushUpdate(updates, params, 'is_active', data.isActive);
-    this.pushUpdate(updates, params, 'billing_model', data.billingModel);
-    this.pushUpdate(updates, params, 'account_manager_collaborator_id', data.accountManagerCollaboratorId);
-    this.pushUpdate(updates, params, 'related_collaborator_id', data.relatedCollaboratorId);
-    this.pushUpdate(updates, params, 'origin_type', data.originType);
-    this.pushUpdate(updates, params, 'origin_id', data.originId);
-    this.pushUpdate(updates, params, 'start_date', data.startDate);
-    this.pushUpdate(updates, params, 'end_date', data.endDate);
-    this.pushUpdate(updates, params, 'signed_at', data.signedAt);
-    this.pushUpdate(updates, params, 'effective_date', data.effectiveDate);
-    this.pushUpdate(updates, params, 'budget_amount', data.budgetAmount);
-    this.pushUpdate(updates, params, 'monthly_hour_cap', data.monthlyHourCap);
-    this.pushUpdate(updates, params, 'status', data.status);
-    this.pushUpdate(updates, params, 'description', data.description);
-    this.pushUpdate(updates, params, 'content_html', data.contentHtml);
+    const creationMode = this.normalizeEnumValue(
+      data.creationMode,
+      CONTRACT_CREATION_MODE_VALUES,
+      'blank'
+    );
+    const selectedTemplate =
+      data.templateId && data.templateId > 0
+        ? await this.getContractTemplateById(userId, data.templateId)
+        : null;
+    const duplicateSource =
+      data.duplicateFromId && data.duplicateFromId > 0
+        ? await this.getContractById(userId, data.duplicateFromId)
+        : null;
+    const storedSourceFile =
+      data.sourceFileId && data.sourceFileId > 0
+        ? await this.prisma.file.findUnique({
+            where: { id: data.sourceFileId },
+            include: { file_mimetype: true },
+          })
+        : null;
+
+    if (data.sourceFileId && !storedSourceFile) {
+      throw new NotFoundException('Source contract file not found.');
+    }
 
-    await this.prisma.$transaction(async (tx) => {
-      if (updates.length) {
-        params.push(contractId);
-        await (tx as any).$executeRawUnsafe(
-          `UPDATE operations_contract
-              SET ${updates.join(', ')},
-                  updated_at = NOW()
-            WHERE id = $${params.length}`,
-          ...params
-        );
-      }
+    const createdId = await this.prisma.$transaction(async (tx) => {
+      const generatedCode = await this.generateContractCode(tx as any);
+      const duplicateNameBase =
+        this.normalizeOptionalText(duplicateSource?.name) ??
+        this.normalizeOptionalText(duplicateSource?.code) ??
+        'Contract';
+      const created = await (tx as any).$queryRawUnsafe(
+        `INSERT INTO operations_contract (
+          code,
+          name,
+          contract_category,
+          contract_type,
+          client_name,
+          signature_status,
+          is_active,
+          billing_model,
+          account_manager_collaborator_id,
+          related_collaborator_id,
+          contract_template_id,
+          origin_type,
+          origin_id,
+          start_date,
+          end_date,
+          signed_at,
+          effective_date,
+          budget_amount,
+          monthly_hour_cap,
+          status,
+          creation_mode,
+          wizard_step,
+          description,
+          content_html,
+          created_by_user_id,
+          updated_by_user_id,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1,
+          $2,
+          $3::operations_contract_contract_category_70d553ea09_enum,
+          $4::operations_contract_contract_type_48331e2ebf_enum,
+          $5,
+          $6::operations_contract_signature_status_2cb7282a7b_enum,
+          $7,
+          $8::operations_contract_billing_model_409dc7fea2_enum,
+          $9,
+          $10,
+          $11,
+          $12::operations_contract_origin_type_07a7cc2b5d_enum,
+          $13,
+          $14::date,
+          $15::date,
+          $16::date,
+          $17::date,
+          $18,
+          $19,
+          $20::operations_contract_status_a0395962df_enum,
+          $21::operations_contract_creation_mode_98ba669209_enum,
+          $22,
+          $23,
+          $24,
+          $25,
+          $25,
+          NOW(),
+          NOW()
+        )
+        RETURNING id`,
+        generatedCode,
+        creationMode === 'duplicate'
+          ? `${duplicateNameBase} Copy`
+          : this.normalizeOptionalText(selectedTemplate?.name),
+        duplicateSource?.contractCategory ??
+          selectedTemplate?.contractCategory ??
+          'client',
+        duplicateSource?.contractType ??
+          selectedTemplate?.contractType ??
+          'service_agreement',
+        this.normalizeOptionalText(duplicateSource?.clientName),
+        duplicateSource?.signatureStatus ??
+          selectedTemplate?.signatureStatus ??
+          'not_started',
+        duplicateSource?.isActive ?? true,
+        duplicateSource?.billingModel ??
+          selectedTemplate?.billingModel ??
+          'time_and_material',
+        duplicateSource?.accountManagerCollaboratorId ?? null,
+        duplicateSource?.relatedCollaboratorId ?? null,
+        duplicateSource?.contractTemplateId ?? selectedTemplate?.id ?? null,
+        duplicateSource?.originType ?? 'manual',
+        duplicateSource?.originId ?? null,
+        duplicateSource?.startDate ?? null,
+        duplicateSource?.endDate ?? null,
+        duplicateSource?.signedAt ?? null,
+        duplicateSource?.effectiveDate ?? null,
+        duplicateSource?.budgetAmount ?? null,
+        duplicateSource?.monthlyHourCap ?? null,
+        'draft',
+        creationMode,
+        creationMode === 'upload' ? 0 : creationMode === 'blank' ? 0 : 1,
+        duplicateSource?.description ?? selectedTemplate?.description ?? null,
+        duplicateSource?.contentHtml ?? selectedTemplate?.contentHtml ?? null,
+        userId
+      );
 
-      if (data.parties) {
-        await this.replaceContractParties(tx as any, contractId, data.parties);
-      }
-      if (data.signatures) {
+      const contractId = (created as { id: number }[])[0]?.id;
+
+      if (duplicateSource) {
+        await this.replaceContractParties(
+          tx as any,
+          contractId,
+          duplicateSource.parties
+        );
         await this.replaceContractSignatures(
           tx as any,
           contractId,
-          data.signatures
+          duplicateSource.signatures
         );
-      }
-      if (data.financialTerms) {
         await this.replaceContractFinancialTerms(
           tx as any,
           contractId,
-          data.financialTerms
+          duplicateSource.financialTerms
         );
-      }
-      if (data.revisions) {
         await this.replaceContractRevisions(
           tx as any,
           contractId,
-          data.revisions
+          duplicateSource.revisions
         );
+
+        const currentSourceDocument =
+          duplicateSource.documents.find(
+            (document) => document.isCurrent && document.documentType === 'source_upload'
+          ) ?? null;
+
+        if (currentSourceDocument) {
+          await this.replaceContractDocument(
+            tx as any,
+            contractId,
+            'source_upload',
+            {
+              fileId: currentSourceDocument.fileId ?? null,
+              fileName: currentSourceDocument.fileName,
+              mimeType: currentSourceDocument.mimeType,
+              fileContentBase64: currentSourceDocument.fileContentBase64 ?? null,
+              notes: currentSourceDocument.notes ?? null,
+              extractionStatus: currentSourceDocument.extractionStatus ?? 'skipped',
+              extractionSummary: currentSourceDocument.extractionSummary ?? null,
+            }
+          );
+        }
       }
-      if (data.replaceUploadedPdfDocument) {
-        await this.replaceContractPdfDocument(
-          tx as any,
-          contractId,
-          data.replaceUploadedPdfDocument
-        );
+
+      if (storedSourceFile) {
+        await this.replaceContractDocument(tx as any, contractId, 'source_upload', {
+          fileId: storedSourceFile.id,
+          fileName:
+            this.normalizeOptionalText(data.sourceFileName) ??
+            storedSourceFile.filename,
+          mimeType:
+            this.normalizeOptionalText(data.sourceMimeType) ??
+            storedSourceFile.file_mimetype?.name ??
+            'application/pdf',
+          notes: 'Source contract document uploaded during draft creation.',
+          extractionStatus: 'pending',
+          extractionSummary: null,
+        });
       }
 
       await this.insertContractHistory(
         tx as any,
         contractId,
         userId,
-        'updated',
-        'Contract registry data updated.'
+        'draft_created',
+        `Contract draft created with mode ${creationMode}.`,
+        JSON.stringify({
+          creationMode,
+          templateId: selectedTemplate?.id ?? null,
+          duplicateFromId: duplicateSource?.id ?? null,
+          sourceFileId: storedSourceFile?.id ?? null,
+        })
       );
+
+      return contractId;
     });
 
-    return this.getContractById(userId, contractId);
+    return this.getContractById(userId, createdId);
   }
 
-  async listTimesheets(userId: number) {
+  async extractContractSource(
+    userId: number,
+    contractId: number,
+    data: Omit<ContractExtractDraftPayload, 'fileName' | 'mimeType' | 'fileContentBase64' | 'contractId'>
+  ) {
     const actor = await this.getActorContext(userId);
-    const filter = this.buildIdFilter(actor.visibleCollaboratorIds, 't.collaborator_id', actor.isDirector);
+    this.ensureDirector(actor);
+
+    const contract = await this.getContractById(userId, contractId);
+    const sourceDocument = contract.documents.find(
+      (document) => document.isCurrent && document.documentType === 'source_upload'
+    );
+
+    if (!sourceDocument) {
+      throw new BadRequestException(
+        'No source document is attached to this contract draft.'
+      );
+    }
+
+    await this.prisma.$executeRawUnsafe(
+      `UPDATE operations_contract_document
+          SET extraction_status = 'processing',
+              updated_at = NOW()
+        WHERE id = $1`,
+      sourceDocument.id
+    );
+
+    try {
+      const extracted = await this.extractContractDraft(userId, {
+        contractId,
+        provider: data.provider ?? null,
+        promptMessage: data.promptMessage ?? null,
+      });
+
+      await this.prisma.$executeRawUnsafe(
+        `UPDATE operations_contract_document
+            SET extraction_status = 'completed',
+                extraction_summary = $2,
+                updated_at = NOW()
+          WHERE id = $1`,
+        sourceDocument.id,
+        extracted.summary || extracted.description || extracted.name || null
+      );
+
+      await this.insertContractHistory(
+        this.prisma,
+        contractId,
+        userId,
+        'source_extracted',
+        'Source contract document extracted with AI.'
+      );
+
+      return extracted;
+    } catch (error) {
+      await this.prisma.$executeRawUnsafe(
+        `UPDATE operations_contract_document
+            SET extraction_status = 'failed',
+                updated_at = NOW()
+          WHERE id = $1`,
+        sourceDocument.id
+      );
+      throw error;
+    }
+  }
+
+  async generateContractContent(
+    userId: number,
+    contractId: number,
+    data: ContractGenerateContentPayload = {}
+  ) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+
+    const contract = await this.getContractById(userId, contractId);
+    const contentHtml = await this.generateContractContentHtml(contract, data);
+
+    await this.prisma.$transaction(async (tx) => {
+      await (tx as any).$executeRawUnsafe(
+        `UPDATE operations_contract
+            SET content_html = $2,
+                wizard_step = CASE
+                  WHEN COALESCE(wizard_step, 0) < 4 THEN 4
+                  ELSE wizard_step
+                END,
+                updated_by_user_id = $3,
+                updated_at = NOW()
+          WHERE id = $1`,
+        contractId,
+        contentHtml,
+        userId
+      );
+
+      await this.insertContractHistory(
+        tx as any,
+        contractId,
+        userId,
+        'content_generated',
+        'Contract content generated automatically for editing.',
+        JSON.stringify({
+          provider: data.provider ?? null,
+          overwrite: Boolean(data.overwrite),
+          hasPrompt: Boolean(this.normalizeOptionalText(data.promptMessage)),
+        })
+      );
+    });
+
+    return this.getContractById(userId, contractId);
+  }
+
+  async reviewContractLegally(
+    userId: number,
+    contractId: number,
+    data: ContractLegalReviewPayload = {}
+  ) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+
+    const contract = await this.getContractById(userId, contractId);
+    const review = await this.buildContractLegalReview(contract, data);
+
+    await this.insertContractHistory(
+      this.prisma,
+      contractId,
+      userId,
+      'legal_reviewed',
+      'Advisory legal checklist updated for this contract.',
+      JSON.stringify(review)
+    );
+
+    return review;
+  }
+
+  async generateContractPdf(userId: number, contractId: number) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+
+    const contract = await this.getContractById(userId, contractId);
+    const pdfBuffer = await this.renderContractPdfBuffer(contract);
+    const fileName = this.buildContractPdfFileName(contract);
+    const uploadedFile = await this.fileService.upload('operations/contracts/generated', {
+      fieldname: 'file',
+      originalname: fileName,
+      encoding: '7bit',
+      mimetype: 'application/pdf',
+      size: pdfBuffer.length,
+      destination: '',
+      filename: fileName,
+      path: '',
+      buffer: pdfBuffer,
+    });
+
+    await this.prisma.$transaction(async (tx) => {
+      await this.replaceContractDocument(tx as any, contractId, 'generated_pdf', {
+        fileId: uploadedFile.id,
+        fileName,
+        mimeType: 'application/pdf',
+        notes: 'PDF generated from contract rich text content.',
+        extractionStatus: 'skipped',
+        extractionSummary: null,
+      });
+
+      await this.insertContractHistory(
+        tx as any,
+        contractId,
+        userId,
+        'pdf_generated',
+        'Generated a branded PDF version of the contract.'
+      );
+    });
+
+    return {
+      contractId,
+      fileId: uploadedFile.id,
+      fileName,
+      mimeType: 'application/pdf',
+      documentType: 'generated_pdf',
+      downloadUrl: `/file/open/${uploadedFile.id}`,
+    };
+  }
+
+  async extractContractDraft(
+    userId: number,
+    data: ContractExtractDraftPayload
+  ) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+
+    const uploadFile = await this.resolveContractExtractionFile(userId, data);
+
+    const aiResult = await this.aiService.chat(
+      {
+        provider: data.provider === 'gemini' ? 'gemini' : 'openai',
+        model: data.provider === 'gemini' ? 'gemini-1.5-flash' : 'gpt-4o-mini',
+        message:
+          this.normalizeExtractionString(data.promptMessage) ||
+          'Analyze the attached contract and extract a structured draft for the contract form.',
+        systemPrompt: this.buildContractExtractionSystemPrompt(),
+      },
+      uploadFile,
+    );
+
+    const parsed = this.parseAiJsonPayload(String(aiResult?.content ?? ''));
+    const draft = this.normalizeContractExtractDraft(parsed);
+    const warnings = [...draft.warnings];
+
+    if (
+      uploadFile.mimetype === 'application/msword' ||
+      uploadFile.mimetype ===
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+    ) {
+      warnings.push(
+        'Word extraction is best-effort. Review names, dates, and values before saving.'
+      );
+    }
+
+    return {
+      ...draft,
+      warnings: Array.from(new Set(warnings.filter(Boolean))),
+    };
+  }
+
+  async createContractFromProposalIntegration(
+    payload: ProposalApprovedEventPayload,
+  ) {
+    const sourceEntityId = String(payload.proposalId || '').trim();
+
+    if (!sourceEntityId) {
+      throw new BadRequestException('proposalId is required for CRM proposal integration.');
+    }
+
+    const proposal = payload.proposal || {
+      code: payload.code ?? null,
+      title: payload.title ?? null,
+      contractCategory: payload.commercialTerms?.contractCategory ?? 'client',
+      contractType: payload.commercialTerms?.contractType ?? 'service_agreement',
+      billingModel: payload.commercialTerms?.billingModel ?? 'fixed_price',
+      validFrom: payload.commercialTerms?.validFrom ?? null,
+      validUntil:
+        payload.validUntil ?? payload.commercialTerms?.validUntil ?? null,
+      totalAmount: payload.total ?? null,
+      totalAmountCents:
+        payload.total != null ? Math.round(Number(payload.total) * 100) : null,
+      notes: payload.commercialTerms?.notes ?? null,
+    };
+    const person = payload.person || {};
+    const items = Array.isArray(payload.items) ? payload.items : [];
+    const contractCategory = proposal.contractCategory ?? 'client';
+    const contractType = proposal.contractType ?? 'service_agreement';
+    const billingModel = proposal.billingModel ?? 'fixed_price';
+    const clientName =
+      this.normalizeOptionalText(person.tradeName) ??
+      this.normalizeOptionalText(person.name) ??
+      this.normalizeOptionalText(proposal.title) ??
+      `Proposal ${sourceEntityId}`;
+    const contractName =
+      this.normalizeOptionalText(proposal.title) ?? `Proposal ${sourceEntityId}`;
+
+    const financialTerms = items
+      .map((item) => ({
+        termType: this.normalizeEnumValue(
+          item.termType,
+          FINANCIAL_TERM_TYPE_VALUES,
+          'value',
+        ),
+        label: this.normalizeOptionalText(item.name) ?? 'Commercial term',
+        amount: Number(item.amount ?? Number(item.totalAmountCents || 0) / 100),
+        recurrence: this.normalizeEnumValue(
+          item.recurrence,
+          RECURRENCE_VALUES,
+          'one_time',
+        ),
+        dueDay: item.dueDay ?? null,
+        notes: this.normalizeOptionalText(item.description),
+      }))
+      .filter((term) => Number.isFinite(term.amount) && term.amount > 0);
+
+    const fallbackAmount = Number(proposal.totalAmount ?? 0);
+    if (financialTerms.length === 0 && Number.isFinite(fallbackAmount) && fallbackAmount > 0) {
+      financialTerms.push({
+        termType: 'revenue',
+        label: contractName,
+        amount: fallbackAmount,
+        recurrence: 'one_time',
+        dueDay: null,
+        notes: this.normalizeOptionalText(proposal.notes),
+      });
+    }
+
+    const primaryPartyRole = ['employee', 'contractor'].includes(contractCategory)
+      ? 'employee'
+      : ['supplier', 'vendor'].includes(contractCategory)
+        ? 'supplier'
+        : contractCategory === 'partner'
+          ? 'partner'
+          : 'client';
+
+    return this.prisma.$transaction(async (tx) => {
+      await (tx as any).$queryRawUnsafe(
+        `SELECT pg_advisory_xact_lock(hashtext($1))`,
+        `operations:crm_proposal:${sourceEntityId}`,
+      );
+
+      const existingContracts = await (tx as any).$queryRawUnsafe(
+        `SELECT id, code
+           FROM operations_contract
+          WHERE deleted_at IS NULL
+            AND origin_type = $1::operations_contract_origin_type_07a7cc2b5d_enum
+            AND origin_id::text = $2
+          ORDER BY id DESC
+          LIMIT 1`,
+        'crm_proposal',
+        sourceEntityId,
+      );
+
+      const existingContract = (
+        existingContracts as Array<{ id: number; code: string | null }>
+      )[0];
+
+      if (existingContract?.id) {
+        return {
+          id: existingContract.id,
+          code: existingContract.code ?? `CONTRACT-${existingContract.id}`,
+        };
+      }
+
+      const generatedCode = await this.generateContractCode(tx as any);
+      const created = await (tx as any).$queryRawUnsafe(
+        `INSERT INTO operations_contract (
+          code,
+          name,
+          contract_category,
+          contract_type,
+          client_name,
+          signature_status,
+          is_active,
+          billing_model,
+          account_manager_collaborator_id,
+          related_collaborator_id,
+          contract_template_id,
+          origin_type,
+          origin_id,
+          start_date,
+          end_date,
+          signed_at,
+          effective_date,
+          budget_amount,
+          monthly_hour_cap,
+          status,
+          creation_mode,
+          wizard_step,
+          description,
+          content_html,
+          created_by_user_id,
+          updated_by_user_id,
+          created_at,
+          updated_at
+        ) VALUES (
+          $1,
+          $2,
+          $3::operations_contract_contract_category_70d553ea09_enum,
+          $4::operations_contract_contract_type_48331e2ebf_enum,
+          $5,
+          $6::operations_contract_signature_status_2cb7282a7b_enum,
+          $7,
+          $8::operations_contract_billing_model_409dc7fea2_enum,
+          $9,
+          $10,
+          $11,
+          $12::operations_contract_origin_type_07a7cc2b5d_enum,
+          $13,
+          $14::date,
+          $15::date,
+          $16::date,
+          $17::date,
+          $18,
+          $19,
+          $20::operations_contract_status_a0395962df_enum,
+          $21::operations_contract_creation_mode_98ba669209_enum,
+          $22,
+          $23,
+          $24,
+          $25,
+          $25,
+          NOW(),
+          NOW()
+        )
+        RETURNING id`,
+        generatedCode,
+        contractName,
+        contractCategory,
+        contractType,
+        clientName,
+        'not_started',
+        true,
+        billingModel,
+        null,
+        null,
+        null,
+        'crm_proposal',
+        sourceEntityId,
+        proposal.validFrom ?? null,
+        proposal.validUntil ?? null,
+        null,
+        proposal.validFrom ?? null,
+        fallbackAmount > 0 ? fallbackAmount : null,
+        null,
+        'draft',
+        'blank',
+        1,
+        this.normalizeOptionalText(proposal.notes),
+        this.normalizeOptionalText(payload.revision?.contentHtml),
+        Number(payload.approvedByUserId) || null,
+      );
+
+      const contractId = (created as { id: number }[])[0]?.id;
+      if (!contractId) {
+        throw new BadRequestException('Could not create contract draft from proposal.');
+      }
+
+      await this.replaceContractParties(tx as any, contractId, [
+        {
+          partyRole: primaryPartyRole as any,
+          partyType: person.tradeName ? 'company' : 'individual',
+          displayName: clientName,
+          documentNumber: this.normalizeOptionalText(person.document),
+          email: this.normalizeOptionalText(person.email),
+          phone: this.normalizeOptionalText(person.phone),
+          isPrimary: true,
+        },
+      ]);
+
+      await this.replaceContractFinancialTerms(
+        tx as any,
+        contractId,
+        financialTerms.map((term) => ({
+          termType: term.termType as any,
+          label: term.label,
+          amount: term.amount,
+          recurrence: term.recurrence as any,
+          dueDay: term.dueDay,
+          notes: term.notes,
+        })),
+      );
+
+      await this.replaceContractRevisions(tx as any, contractId, [
+        {
+          revisionType: 'revision',
+          title: payload.revision?.title ?? contractName,
+          effectiveDate: proposal.validFrom ?? null,
+          status: 'draft',
+          summary:
+            this.normalizeOptionalText(payload.revision?.summary) ??
+            this.normalizeOptionalText(proposal.notes),
+        },
+      ]);
+
+      await this.insertContractHistory(
+        tx as any,
+        contractId,
+        Number(payload.approvedByUserId) || null,
+        'created',
+        `Draft contract generated from CRM proposal ${proposal.code ?? sourceEntityId}.`,
+        JSON.stringify({
+          correlationId: payload.correlationId || `proposal:${sourceEntityId}`,
+          proposalId:
+            payload.proposalId ??
+            (Number(sourceEntityId) > 0 ? Number(sourceEntityId) : null),
+          proposalRevisionId: payload.proposalRevisionId ?? null,
+          sourceModule: 'contact',
+          sourceEntity: 'proposal',
+          sourceId: sourceEntityId,
+          approvedByUserId: Number(payload.approvedByUserId) || null,
+        }),
+      );
+
+      await this.integrationApi.publishEvent(
+        {
+          eventName: 'operations.contract.created',
+          sourceModule: 'operations',
+          aggregateType: 'contract',
+          aggregateId: String(contractId),
+          payload: this.buildContractCreatedEventPayload(
+            {
+              id: contractId,
+              code: generatedCode,
+              name: contractName,
+              clientName,
+              contractCategory,
+              contractType,
+              billingModel,
+              originType: 'crm_proposal',
+              originId: sourceEntityId,
+              startDate: proposal.validFrom ?? null,
+              endDate: proposal.validUntil ?? null,
+              description: this.normalizeOptionalText(proposal.notes),
+              financialTerms,
+            },
+            payload,
+            String(payload.locale || '').trim() || 'en',
+            Number(payload.approvedByUserId) || undefined,
+          ),
+          metadata: {
+            producer: 'operations',
+            correlationId:
+              payload.correlationId || `proposal:${sourceEntityId}`,
+            sourceModule: 'operations',
+            sourceEntity: 'contract',
+            sourceId: String(contractId),
+            originType: 'crm_proposal',
+            originId: sourceEntityId,
+          },
+        },
+        {
+          persistenceClient: tx as any,
+        },
+      );
+
+      return {
+        id: contractId,
+        code: generatedCode,
+      };
+    });
+  }
+
+  private buildContractCreatedEventPayload(
+    contract: {
+      id: number;
+      code?: string | null;
+      name?: string | null;
+      clientName?: string | null;
+      contractCategory?: ContractPayload['contractCategory'];
+      contractType?: ContractPayload['contractType'];
+      billingModel?: ContractPayload['billingModel'];
+      originType?: ContractPayload['originType'];
+      originId?: string | number | null;
+      startDate?: string | null;
+      endDate?: string | null;
+      description?: string | null;
+      financialTerms?: ContractPayload['financialTerms'];
+    },
+    payload: ProposalApprovedEventPayload,
+    locale = 'en',
+    createdByUserId?: number,
+  ) {
+    return {
+      contractId: contract.id,
+      proposalId: payload.proposalId ?? null,
+      proposalRevisionId: payload.proposalRevisionId ?? null,
+      personId: payload.personId ?? payload.person?.id ?? null,
+      createdByUserId: createdByUserId ?? null,
+      createdAt: new Date().toISOString(),
+      locale,
+      correlationId:
+        payload.correlationId || `proposal:${payload.proposalId ?? contract.originId ?? contract.id}`,
+      sourceModule: 'operations',
+      sourceEntity: 'contract',
+      sourceId: String(contract.id),
+      source_module: 'operations',
+      source_entity: 'contract',
+      source_id: String(contract.id),
+      contract: {
+        id: contract.id,
+        code: contract.code ?? null,
+        name: contract.name ?? null,
+        clientName: contract.clientName ?? null,
+        status: 'draft',
+        contractCategory: contract.contractCategory ?? 'client',
+        contractType: contract.contractType ?? 'service_agreement',
+        billingModel: contract.billingModel ?? 'fixed_price',
+        originType: contract.originType ?? 'manual',
+        originId: contract.originId ?? null,
+        startDate: contract.startDate ?? null,
+        endDate: contract.endDate ?? null,
+        description: contract.description ?? null,
+        financialTerms: contract.financialTerms ?? [],
+      },
+      proposal: payload.proposal ?? {
+        code: payload.code ?? null,
+        title: payload.title ?? null,
+        totalAmount: payload.total ?? null,
+        notes: payload.commercialTerms?.notes ?? null,
+      },
+      person: payload.person ?? null,
+    };
+  }
+
+  private async buildContractActivatedEventPayload(
+    contract: {
+      id: number;
+      code?: string | null;
+      name?: string | null;
+      clientName?: string | null;
+      contractCategory?: ContractPayload['contractCategory'];
+      contractType?: ContractPayload['contractType'];
+      billingModel?: ContractPayload['billingModel'];
+      originType?: ContractPayload['originType'];
+      originId?: string | number | null;
+      startDate?: string | null;
+      endDate?: string | null;
+      signedAt?: string | null;
+      effectiveDate?: string | null;
+      budgetAmount?: number | null;
+      description?: string | null;
+      financialTerms?: ContractPayload['financialTerms'];
+      parties?: ContractPayload['parties'];
+    },
+    locale = 'en',
+    activatedByUserId?: number,
+  ) {
+    let personId: number | null = null;
+    let proposalId: number | null = null;
+    let personRecord: any = null;
+
+    if (contract.originType === 'crm_proposal' && contract.originId) {
+      const parsedProposalId = Number(contract.originId);
+      if (Number.isInteger(parsedProposalId) && parsedProposalId > 0) {
+        proposalId = parsedProposalId;
+        const proposal = await (this.prisma as any).proposal.findUnique({
+          where: { id: parsedProposalId },
+          include: {
+            person: {
+              select: {
+                id: true,
+                name: true,
+              },
+            },
+          },
+        });
+
+        if (proposal) {
+          personId = proposal.person_id ?? proposal.person?.id ?? null;
+
+          const [companyRow, contactRows, documentRows] =
+            personId != null
+              ? await Promise.all([
+                  (this.prisma as any).person_company.findUnique({
+                    where: { id: personId },
+                    select: { trade_name: true },
+                  }),
+                  (this.prisma as any).contact.findMany({
+                    where: { person_id: personId },
+                    include: {
+                      contact_type: {
+                        select: { code: true },
+                      },
+                    },
+                    orderBy: [{ is_primary: 'desc' }, { id: 'asc' }],
+                  }),
+                  (this.prisma as any).document.findMany({
+                    where: { person_id: personId },
+                    select: { value: true },
+                    orderBy: [{ id: 'asc' }],
+                  }),
+                ])
+              : [null, [], []];
+
+          const resolveContactValue = (codes: string[]) => {
+            const normalizedCodes = new Set(codes.map((code) => code.toUpperCase()));
+            const items = Array.isArray(contactRows)
+              ? contactRows.filter((contact: any) =>
+                  normalizedCodes.has(
+                    String(contact?.contact_type?.code || '').toUpperCase(),
+                  ),
+                )
+              : [];
+            const primary = items.find((contact: any) => contact?.is_primary);
+            const fallback = items[0];
+            return primary?.value ?? fallback?.value ?? null;
+          };
+
+          personRecord = proposal.person
+            ? {
+                ...proposal.person,
+                trade_name: companyRow?.trade_name ?? null,
+                email: resolveContactValue(['EMAIL']),
+                phone: resolveContactValue(['PHONE', 'MOBILE', 'WHATSAPP']),
+                document: documentRows[0]?.value ?? null,
+              }
+            : null;
+        }
+      }
+    }
+
+    const financialTerms = (contract.financialTerms ?? []).map((term) => ({
+      label: term.label,
+      termType: term.termType ?? 'value',
+      amount: Number(term.amount ?? 0),
+      recurrence: term.recurrence ?? 'one_time',
+      dueDay: term.dueDay ?? null,
+      notes: term.notes ?? null,
+    }));
+
+    const totalAmount =
+      financialTerms.reduce(
+        (sum, term) => sum + (Number.isFinite(term.amount) ? term.amount : 0),
+        0,
+      ) || Number(contract.budgetAmount ?? 0);
+
+    return {
+      contractId: contract.id,
+      proposalId,
+      personId,
+      activatedByUserId: activatedByUserId ?? null,
+      signedByUserId: activatedByUserId ?? null,
+      activatedAt: new Date().toISOString(),
+      signedAt: contract.signedAt ?? contract.effectiveDate ?? contract.startDate ?? null,
+      locale,
+      correlationId: proposalId ? `proposal:${proposalId}` : `contract:${contract.id}`,
+      sourceModule: 'operations',
+      sourceEntity: 'contract',
+      sourceId: String(contract.id),
+      source_module: 'operations',
+      source_entity: 'contract',
+      source_id: String(contract.id),
+      contract: {
+        code: contract.code ?? null,
+        name: contract.name ?? null,
+        clientName: contract.clientName ?? null,
+        contractCategory: contract.contractCategory ?? 'client',
+        contractType: contract.contractType ?? 'service_agreement',
+        billingModel: contract.billingModel ?? 'fixed_price',
+        originType: contract.originType ?? 'manual',
+        originId: contract.originId ?? null,
+        startDate: contract.startDate ?? null,
+        endDate: contract.endDate ?? null,
+        signedAt: contract.signedAt ?? null,
+        effectiveDate: contract.effectiveDate ?? null,
+        budgetAmount: contract.budgetAmount ?? null,
+        description: contract.description ?? null,
+        financialTerms,
+        parties: contract.parties ?? [],
+      },
+      person: personRecord
+        ? {
+            id: personRecord.id ?? null,
+            name: personRecord.name ?? null,
+            tradeName: personRecord.trade_name ?? null,
+            email: personRecord.email ?? null,
+            phone: personRecord.phone ?? null,
+            document: personRecord.document ?? null,
+          }
+        : null,
+      receivable: {
+        personId,
+        documentNumber: contract.code ?? `CONTRACT-${contract.id}`,
+        totalAmount,
+        description:
+          contract.description ?? contract.name ?? contract.code ?? null,
+      },
+    };
+  }
+
+  async updateContract(userId: number, contractId: number, data: Partial<ContractPayload>) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+    const current = await this.getContractById(userId, contractId);
+    const nextStatus = this.normalizeEnumValue(
+      data.status,
+      CONTRACT_STATUS_VALUES,
+      current.status ?? 'draft',
+    );
+    const nextSignatureStatus = this.normalizeEnumValue(
+      data.signatureStatus,
+      SIGNATURE_STATUS_VALUES,
+      current.signatureStatus ?? 'not_started',
+    );
+    const shouldPublishSigned =
+      current.signatureStatus !== 'signed' && nextSignatureStatus === 'signed';
+    const shouldPublishActivation =
+      current.status !== 'active' && nextStatus === 'active';
+
+    const updates: string[] = [];
+    const params: unknown[] = [];
+    this.pushUpdate(updates, params, 'code', data.code);
+    this.pushUpdate(updates, params, 'name', data.name);
+    this.pushUpdate(
+      updates,
+      params,
+      'contract_category',
+      data.contractCategory,
+      'operations_contract_contract_category_70d553ea09_enum'
+    );
+    this.pushUpdate(
+      updates,
+      params,
+      'contract_type',
+      data.contractType,
+      'operations_contract_contract_type_48331e2ebf_enum'
+    );
+    this.pushUpdate(updates, params, 'client_name', data.clientName);
+    this.pushUpdate(
+      updates,
+      params,
+      'signature_status',
+      data.signatureStatus,
+      'operations_contract_signature_status_2cb7282a7b_enum'
+    );
+    this.pushUpdate(updates, params, 'is_active', data.isActive);
+    this.pushUpdate(
+      updates,
+      params,
+      'billing_model',
+      data.billingModel,
+      'operations_contract_billing_model_409dc7fea2_enum'
+    );
+    this.pushUpdate(updates, params, 'account_manager_collaborator_id', data.accountManagerCollaboratorId);
+    this.pushUpdate(updates, params, 'related_collaborator_id', data.relatedCollaboratorId);
+    this.pushUpdate(updates, params, 'contract_template_id', data.contractTemplateId);
+    this.pushUpdate(
+      updates,
+      params,
+      'origin_type',
+      data.originType,
+      'operations_contract_origin_type_07a7cc2b5d_enum'
+    );
+    this.pushUpdate(updates, params, 'origin_id', data.originId);
+    this.pushUpdate(updates, params, 'start_date', data.startDate, 'date');
+    this.pushUpdate(updates, params, 'end_date', data.endDate, 'date');
+    this.pushUpdate(updates, params, 'signed_at', data.signedAt, 'date');
+    this.pushUpdate(updates, params, 'effective_date', data.effectiveDate, 'date');
+    this.pushUpdate(updates, params, 'budget_amount', data.budgetAmount);
+    this.pushUpdate(updates, params, 'monthly_hour_cap', data.monthlyHourCap);
+    this.pushUpdate(
+      updates,
+      params,
+      'status',
+      data.status,
+      'operations_contract_status_a0395962df_enum'
+    );
+    this.pushUpdate(
+      updates,
+      params,
+      'creation_mode',
+      data.creationMode,
+      'operations_contract_creation_mode_98ba669209_enum'
+    );
+    this.pushUpdate(updates, params, 'wizard_step', data.wizardStep);
+    this.pushUpdate(updates, params, 'description', data.description);
+    this.pushUpdate(updates, params, 'content_html', data.contentHtml);
+
+    await this.prisma.$transaction(async (tx) => {
+      if (updates.length) {
+        params.push(contractId);
+        await (tx as any).$executeRawUnsafe(
+          `UPDATE operations_contract
+              SET ${updates.join(', ')},
+                  updated_at = NOW()
+            WHERE id = $${params.length}`,
+          ...params
+        );
+      }
+
+      if (data.parties) {
+        await this.replaceContractParties(tx as any, contractId, data.parties);
+      }
+      if (data.signatures) {
+        await this.replaceContractSignatures(
+          tx as any,
+          contractId,
+          data.signatures
+        );
+      }
+      if (data.financialTerms) {
+        await this.replaceContractFinancialTerms(
+          tx as any,
+          contractId,
+          data.financialTerms
+        );
+      }
+      if (data.revisions) {
+        await this.replaceContractRevisions(
+          tx as any,
+          contractId,
+          data.revisions
+        );
+      }
+      if (data.replaceUploadedPdfDocument) {
+        await this.replaceContractDocument(
+          tx as any,
+          contractId,
+          'source_upload',
+          data.replaceUploadedPdfDocument
+        );
+      }
+
+      await this.insertContractHistory(
+        tx as any,
+        contractId,
+        userId,
+        'updated',
+        'Contract registry data updated.'
+      );
+
+      if (shouldPublishSigned || shouldPublishActivation) {
+        const contractEventPayload = await this.buildContractActivatedEventPayload(
+          {
+            id: current.id,
+            code: data.code ?? current.code,
+            name: data.name ?? current.name,
+            clientName: data.clientName ?? current.clientName,
+            contractCategory: data.contractCategory ?? current.contractCategory,
+            contractType: data.contractType ?? current.contractType,
+            billingModel: data.billingModel ?? current.billingModel,
+            originType: data.originType ?? current.originType,
+            originId: data.originId ?? current.originId,
+            startDate: data.startDate ?? current.startDate,
+            endDate: data.endDate ?? current.endDate,
+            signedAt: data.signedAt ?? current.signedAt,
+            effectiveDate: data.effectiveDate ?? current.effectiveDate,
+            budgetAmount: data.budgetAmount ?? current.budgetAmount,
+            description: data.description ?? current.description,
+            financialTerms: data.financialTerms ?? current.financialTerms,
+            parties: data.parties ?? current.parties,
+          },
+          'en',
+          userId,
+        );
+
+        if (shouldPublishSigned) {
+          await this.integrationApi.publishEvent(
+            {
+              eventName: 'operations.contract.signed',
+              sourceModule: 'operations',
+              aggregateType: 'contract',
+              aggregateId: String(contractId),
+              payload: {
+                ...contractEventPayload,
+                signedByUserId: userId ?? null,
+                signedAt:
+                  data.signedAt ??
+                  current.signedAt ??
+                  contractEventPayload.signedAt ??
+                  new Date().toISOString(),
+              },
+              metadata: {
+                producer: 'operations',
+                correlationId:
+                  contractEventPayload.correlationId || `contract:${contractId}`,
+                sourceModule: 'operations',
+                sourceEntity: 'contract',
+                sourceId: String(contractId),
+                originType: data.originType ?? current.originType,
+                originId: data.originId ?? current.originId,
+                lifecycle: 'signed',
+              },
+            },
+            {
+              persistenceClient: tx as any,
+            },
+          );
+        }
+
+        if (shouldPublishActivation) {
+          await this.integrationApi.publishEvent(
+            {
+              eventName: 'operations.contract.activated',
+              sourceModule: 'operations',
+              aggregateType: 'contract',
+              aggregateId: String(contractId),
+              payload: contractEventPayload,
+              metadata: {
+                producer: 'operations',
+                correlationId:
+                  contractEventPayload.correlationId || `contract:${contractId}`,
+                sourceModule: 'operations',
+                sourceEntity: 'contract',
+                sourceId: String(contractId),
+                originType: data.originType ?? current.originType,
+                originId: data.originId ?? current.originId,
+                lifecycle: 'activated',
+              },
+            },
+            {
+              persistenceClient: tx as any,
+            },
+          );
+        }
+      }
+    });
+
+    return this.getContractById(userId, contractId);
+  }
+
+  async removeContract(userId: number, contractId: number) {
+    const actor = await this.getActorContext(userId);
+    this.ensureDirector(actor);
+    const current = await this.getContractById(userId, contractId);
+
+    await this.prisma.$transaction(async (tx) => {
+      await (tx as any).$executeRawUnsafe(
+        `UPDATE operations_project
+            SET contract_id = NULL,
+                updated_at = NOW()
+          WHERE contract_id = $1
+            AND deleted_at IS NULL`,
+        contractId
+      );
+
+      for (const tableName of [
+        'operations_contract_party',
+        'operations_contract_signature',
+        'operations_contract_financial_term',
+        'operations_contract_document',
+        'operations_contract_revision',
+      ]) {
+        await (tx as any).$executeRawUnsafe(
+          `UPDATE ${tableName}
+              SET deleted_at = NOW(),
+                  updated_at = NOW()
+            WHERE contract_id = $1
+              AND deleted_at IS NULL`,
+          contractId
+        );
+      }
+
+      await this.insertContractHistory(
+        tx as any,
+        contractId,
+        userId,
+        'deleted',
+        `Contract "${current.name ?? current.code ?? `#${contractId}`}" removed from registry.`
+      );
+
+      await (tx as any).$executeRawUnsafe(
+        `UPDATE operations_contract
+            SET deleted_at = NOW(),
+                is_active = false,
+                status = 'archived',
+                updated_at = NOW()
+          WHERE id = $1
+            AND deleted_at IS NULL`,
+        contractId
+      );
+    });
+
+    return { success: true };
+  }
+
+  async listTimesheets(userId: number) {
+    const actor = await this.getActorContext(userId);
+    const filter = this.buildIdFilter(actor.visibleCollaboratorIds, 't.collaborator_id', actor.isDirector);
 
     const headers = await this.queryRows<{
       id: number;
@@ -1563,7 +3640,7 @@ export class OperationsService {
           status,
           created_at,
           updated_at
-        ) VALUES ($1, $2, $3, $4, $5, 'draft', NOW(), NOW())
+        ) VALUES ($1, $2, $3::date, $4::date, $5, 'draft', NOW(), NOW())
         RETURNING id`,
         collaboratorId,
         collaborator.supervisorId ?? null,
@@ -1603,8 +3680,8 @@ export class OperationsService {
     await this.prisma.$transaction(async (tx) => {
       const updates: string[] = [];
       const params: unknown[] = [];
-      this.pushUpdate(updates, params, 'week_start_date', data.weekStartDate);
-      this.pushUpdate(updates, params, 'week_end_date', data.weekEndDate);
+      this.pushUpdate(updates, params, 'week_start_date', data.weekStartDate, 'date');
+      this.pushUpdate(updates, params, 'week_end_date', data.weekEndDate, 'date');
       this.pushUpdate(updates, params, 'notes', data.notes);
 
       if (updates.length) {
@@ -1732,7 +3809,17 @@ export class OperationsService {
           submitted_at,
           created_at,
           updated_at
-        ) VALUES ($1, $2, COALESCE($3, 'vacation'), $4, $5, $6, 'submitted', $7, NOW(), NOW(), NOW())
+        ) VALUES (
+          $1,
+          $2,
+          $3::operations_time_off_request_request_type_fdcf258f8e_enum,
+          $4::date,
+          $5::date,
+          $6,
+          'submitted',
+          $7,
+          NOW(), NOW(), NOW()
+        )
         RETURNING id`,
         collaboratorId,
         collaborator.supervisorId ?? null,
@@ -1909,7 +3996,14 @@ export class OperationsService {
           created_at,
           updated_at
         ) VALUES (
-          $1, $2, COALESCE($3, 'temporary'), $4, $5, 'submitted', $6, NOW(), NOW(), NOW()
+          $1,
+          $2,
+          $3::operations_schedule_adjustment_request_request__d3f1202fa6_enum,
+          $4::date,
+          $5::date,
+          'submitted',
+          $6,
+          NOW(), NOW(), NOW()
         )
         RETURNING id`,
         collaboratorId,
@@ -1932,7 +4026,11 @@ export class OperationsService {
             break_minutes,
             created_at,
             updated_at
-          ) VALUES ($1, $2, $3, $4, $5, $6, NOW(), NOW())`,
+          ) VALUES (
+            $1,
+            $2::operations_schedule_adjustment_day_weekday_ba6542bf86_enum,
+            $3, $4::time, $5::time, $6, NOW(), NOW()
+          )`,
           requestId,
           day.weekday,
           day.isWorkingDay ?? true,
@@ -2151,7 +4249,7 @@ export class OperationsService {
     await this.prisma.$transaction(async (tx) => {
       await (tx as any).$executeRawUnsafe(
         `UPDATE operations_approval
-            SET status = $1,
+            SET status = $1::operations_approval_status_747aa313d9_enum,
                 decided_at = NOW(),
                 decision_note = $2,
                 updated_at = NOW()
@@ -2164,7 +4262,7 @@ export class OperationsService {
       if (approval.targetType === 'timesheet') {
         await (tx as any).$executeRawUnsafe(
           `UPDATE operations_timesheet
-              SET status = $1,
+              SET status = $1::operations_timesheet_status_128a8ecd30_enum,
                   reviewed_at = NOW(),
                   approver_collaborator_id = $2,
                   updated_at = NOW()
@@ -2178,7 +4276,7 @@ export class OperationsService {
       if (approval.targetType === 'time_off_request') {
         await (tx as any).$executeRawUnsafe(
         `UPDATE operations_time_off_request
-            SET status = $1,
+            SET status = $1::operations_time_off_request_status_c0b28799ee_enum,
                 reviewed_at = NOW(),
                 approver_collaborator_id = $2,
                 submitted_at = COALESCE(submitted_at, NOW()),
@@ -2193,7 +4291,7 @@ export class OperationsService {
       if (approval.targetType === 'schedule_adjustment_request') {
         await (tx as any).$executeRawUnsafe(
         `UPDATE operations_schedule_adjustment_request
-            SET status = $1,
+            SET status = $1::operations_schedule_adjustment_request_status_159e10f34e_enum,
                 reviewed_at = NOW(),
                 approver_collaborator_id = $2,
                 submitted_at = COALESCE(submitted_at, NOW()),
@@ -2294,10 +4392,12 @@ export class OperationsService {
       supervisorName: string | null;
     }>(
       `SELECT c.id,
-              c.display_name AS "displayName",
+              COALESCE(NULLIF(c.display_name, ''), person_record.name) AS "displayName",
               s.id AS "supervisorId",
               s.display_name AS "supervisorName"
          FROM operations_collaborator c
+         LEFT JOIN person person_record
+           ON person_record.id = c.person_id
          LEFT JOIN operations_collaborator s
            ON s.id = c.supervisor_collaborator_id
         WHERE c.user_id = $1
@@ -2314,10 +4414,12 @@ export class OperationsService {
       supervisorName: string | null;
     }>(
       `SELECT c.id,
-              c.display_name AS "displayName",
+              COALESCE(NULLIF(c.display_name, ''), person_record.name) AS "displayName",
               s.id AS "supervisorId",
               s.display_name AS "supervisorName"
          FROM operations_collaborator c
+         LEFT JOIN person person_record
+           ON person_record.id = c.person_id
          LEFT JOIN operations_collaborator s
            ON s.id = c.supervisor_collaborator_id
         WHERE c.id = $1
@@ -2330,6 +4432,361 @@ export class OperationsService {
     return collaborator;
   }
 
+  private async getPersonById(personId: number) {
+    const person = await this.querySingle<{
+      id: number;
+      name: string;
+      type: 'individual' | 'company' | null;
+    }>(
+      `SELECT id, name, type
+         FROM person
+        WHERE id = $1`,
+      [personId]
+    );
+
+    if (!person) {
+      throw new NotFoundException('Person not found.');
+    }
+
+    return person;
+  }
+
+  private async getDepartmentById(
+    client: any,
+    departmentId: number,
+    includeInactive = false
+  ) {
+    const departments = (await client.$queryRawUnsafe(
+      `SELECT id,
+              slug,
+              code,
+              name,
+              description,
+              created_at AS "createdAt",
+              updated_at AS "updatedAt",
+              deleted_at AS "deletedAt",
+              CASE WHEN deleted_at IS NULL THEN 'active' ELSE 'inactive' END AS status
+         FROM operations_department
+        WHERE id = $1
+          AND ($2::boolean OR deleted_at IS NULL)`,
+      departmentId,
+      includeInactive
+    )) as Array<{
+      id: number;
+      slug: string;
+      code: string | null;
+      name: string;
+      description: string | null;
+      createdAt: string | null;
+      updatedAt: string | null;
+      deletedAt: string | null;
+      status: 'active' | 'inactive';
+    }>;
+
+    const department = departments[0] ?? null;
+    if (!department) {
+      throw new NotFoundException('Department not found.');
+    }
+
+    return department;
+  }
+
+  private async assertDepartmentNameAvailable(
+    client: any,
+    name: string,
+    excludeDepartmentId?: number | null
+  ) {
+    const existing = (await client.$queryRawUnsafe(
+      `SELECT id
+         FROM operations_department
+        WHERE LOWER(name) = LOWER($1)
+          AND ($2::int IS NULL OR id <> $2)
+        LIMIT 1`,
+      name,
+      excludeDepartmentId ?? null
+    )) as { id: number }[];
+
+    if (existing[0]) {
+      throw new BadRequestException('A department with this name already exists.');
+    }
+  }
+
+  private async assertDepartmentCodeAvailable(
+    client: any,
+    code: string,
+    excludeDepartmentId?: number | null
+  ) {
+    const existing = (await client.$queryRawUnsafe(
+      `SELECT id
+         FROM operations_department
+        WHERE UPPER(COALESCE(code, '')) = UPPER($1)
+          AND ($2::int IS NULL OR id <> $2)
+        LIMIT 1`,
+      code,
+      excludeDepartmentId ?? null
+    )) as { id: number }[];
+
+    if (existing[0]) {
+      throw new BadRequestException('A department with this code already exists.');
+    }
+  }
+
+  private async resolveDepartmentReference(
+    client: any,
+    input: {
+      departmentId?: number | null;
+      departmentName?: string | null;
+    }
+  ) {
+    if (input.departmentName !== undefined) {
+      const normalizedDepartmentName = this.normalizeOptionalText(
+        input.departmentName
+      );
+
+      if (!normalizedDepartmentName) {
+        return null;
+      }
+
+      const existingByName = (await client.$queryRawUnsafe(
+        `SELECT id, name
+           FROM operations_department
+          WHERE deleted_at IS NULL
+            AND LOWER(name) = LOWER($1)
+          ORDER BY id ASC
+          LIMIT 1`,
+        normalizedDepartmentName
+      )) as { id: number; name: string }[];
+
+      if (existingByName[0]) {
+        return existingByName[0];
+      }
+
+      const slug = await this.generateUniqueDepartmentSlug(
+        client,
+        normalizedDepartmentName
+      );
+      const created = (await client.$queryRawUnsafe(
+        `INSERT INTO operations_department (
+          slug,
+          code,
+          name,
+          description,
+          created_at,
+          updated_at
+        ) VALUES ($1, NULL, $2, NULL, NOW(), NOW())
+        RETURNING id, name`,
+        slug,
+        normalizedDepartmentName
+      )) as { id: number; name: string }[];
+
+      return created[0] ?? null;
+    }
+
+    if (
+      typeof input.departmentId === 'number' &&
+      Number.isInteger(input.departmentId) &&
+      input.departmentId > 0
+    ) {
+      return this.getDepartmentById(client, input.departmentId);
+    }
+
+    return null;
+  }
+
+  private async generateUniqueDepartmentSlug(
+    client: any,
+    label: string,
+    excludeDepartmentId?: number | null
+  ) {
+    const baseSlug =
+      this.slugifyValue(label) || `department-${Date.now().toString(36)}`;
+
+    for (let attempt = 0; attempt < 25; attempt += 1) {
+      const candidate =
+        attempt === 0 ? baseSlug : `${baseSlug}-${attempt + 1}`;
+      const existing = (await client.$queryRawUnsafe(
+        `SELECT id
+           FROM operations_department
+          WHERE slug = $1
+            AND ($2::int IS NULL OR id <> $2)
+          LIMIT 1`,
+        candidate,
+        excludeDepartmentId ?? null
+      )) as { id: number }[];
+
+      if (!existing.length) {
+        return candidate;
+      }
+    }
+
+    return `${baseSlug}-${Date.now().toString(36)}`;
+  }
+
+  private async getContractTemplateRecord(
+    client: any,
+    templateId: number,
+    includeInactive = false
+  ): Promise<{
+    id: number;
+    slug: string;
+    code: string | null;
+    name: string;
+    description: string | null;
+    contractCategory: string | null;
+    contractType: string | null;
+    billingModel: string | null;
+    signatureStatus: string | null;
+    isActive: boolean;
+    status: string | null;
+    contentHtml: string | null;
+    usageCount: number;
+    createdAt: Date;
+    updatedAt: Date;
+  }> {
+    const template = (await client.$queryRawUnsafe(
+      `SELECT t.id,
+              t.slug,
+              t.code,
+              t.name,
+              t.description,
+              t.contract_category AS "contractCategory",
+              t.contract_type AS "contractType",
+              t.billing_model AS "billingModel",
+              t.signature_status AS "signatureStatus",
+              t.is_active AS "isActive",
+              t.status,
+              t.content_html AS "contentHtml",
+              COUNT(DISTINCT c.id)::int AS "usageCount",
+              t.created_at AS "createdAt",
+              t.updated_at AS "updatedAt"
+         FROM operations_contract_template t
+         LEFT JOIN operations_contract c
+           ON c.contract_template_id = t.id
+          AND c.deleted_at IS NULL
+        WHERE t.id = $1
+          AND ($2::boolean = true OR t.deleted_at IS NULL)
+        GROUP BY t.id
+        LIMIT 1`,
+      templateId,
+      includeInactive
+    )) as Array<{
+      id: number;
+      slug: string;
+      code: string | null;
+      name: string;
+      description: string | null;
+      contractCategory: string | null;
+      contractType: string | null;
+      billingModel: string | null;
+      signatureStatus: string | null;
+      isActive: boolean;
+      status: string | null;
+      contentHtml: string | null;
+      usageCount: number;
+      createdAt: Date;
+      updatedAt: Date;
+    }>;
+
+    const record = template[0];
+
+    if (!record) {
+      throw new NotFoundException('Contract template not found.');
+    }
+
+    return record;
+  }
+
+  private async assertContractTemplateNameAvailable(
+    client: any,
+    name: string,
+    excludeTemplateId?: number | null
+  ) {
+    const existing = (await client.$queryRawUnsafe(
+      `SELECT id
+         FROM operations_contract_template
+        WHERE LOWER(name) = LOWER($1)
+          AND deleted_at IS NULL
+          AND ($2::int IS NULL OR id <> $2)
+        LIMIT 1`,
+      name,
+      excludeTemplateId ?? null
+    )) as { id: number }[];
+
+    if (existing[0]) {
+      throw new BadRequestException(
+        'A contract template with this name already exists.'
+      );
+    }
+  }
+
+  private async assertContractTemplateCodeAvailable(
+    client: any,
+    code: string,
+    excludeTemplateId?: number | null
+  ) {
+    const existing = (await client.$queryRawUnsafe(
+      `SELECT id
+         FROM operations_contract_template
+        WHERE UPPER(COALESCE(code, '')) = UPPER($1)
+          AND deleted_at IS NULL
+          AND ($2::int IS NULL OR id <> $2)
+        LIMIT 1`,
+      code,
+      excludeTemplateId ?? null
+    )) as { id: number }[];
+
+    if (existing[0]) {
+      throw new BadRequestException(
+        'A contract template with this code already exists.'
+      );
+    }
+  }
+
+  private async generateUniqueContractTemplateSlug(
+    client: any,
+    label: string,
+    excludeTemplateId?: number | null
+  ) {
+    const baseSlug =
+      this.slugifyValue(label) || `contract-template-${Date.now().toString(36)}`;
+
+    for (let attempt = 0; attempt < 25; attempt += 1) {
+      const candidate =
+        attempt === 0 ? baseSlug : `${baseSlug}-${attempt + 1}`;
+      const existing = (await client.$queryRawUnsafe(
+        `SELECT id
+           FROM operations_contract_template
+          WHERE slug = $1
+            AND ($2::int IS NULL OR id <> $2)
+          LIMIT 1`,
+        candidate,
+        excludeTemplateId ?? null
+      )) as { id: number }[];
+
+      if (!existing.length) {
+        return candidate;
+      }
+    }
+
+    return `${baseSlug}-${Date.now().toString(36)}`;
+  }
+
+  private slugifyValue(value: string | null | undefined) {
+    return (value ?? '')
+      .normalize('NFKD')
+      .replace(/[\u0300-\u036f]/g, '')
+      .toLowerCase()
+      .trim()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 80);
+  }
+
+  private normalizeOptionalText(value: string | null | undefined) {
+    const normalized = String(value ?? '').trim();
+    return normalized || null;
+  }
+
   private async getProjectDetails(
     projectId: number,
     actorCollaboratorId?: number | null
@@ -2521,10 +4978,14 @@ export class OperationsService {
   private async getCollaboratorDetails(collaboratorId: number) {
     const collaborator = await this.querySingle<{
       id: number;
-      userId: number;
+      userId: number | null;
+      personId: number | null;
+      personName: string | null;
+      personAvatarId: number | null;
       code: string;
       collaboratorType: string;
       displayName: string;
+      departmentId: number | null;
       department: string | null;
       title: string | null;
       levelLabel: string | null;
@@ -2541,10 +5002,14 @@ export class OperationsService {
     }>(
       `SELECT c.id,
               c.user_id AS "userId",
+              c.person_id AS "personId",
+              person_record.name AS "personName",
+              person_record.avatar_id AS "personAvatarId",
               c.code,
               c.collaborator_type AS "collaboratorType",
-              c.display_name AS "displayName",
-              c.department,
+              COALESCE(NULLIF(c.display_name, ''), person_record.name) AS "displayName",
+              c.department_id AS "departmentId",
+              COALESCE(NULLIF(department_record.name, ''), NULLIF(c.department, '')) AS "department",
               c.title,
               c.level_label AS "levelLabel",
               c.weekly_capacity_hours AS "weeklyCapacityHours",
@@ -2558,6 +5023,11 @@ export class OperationsService {
               hiring_contract.status AS "contractStatus",
               COUNT(DISTINCT pa.id)::int AS "activeAssignments"
          FROM operations_collaborator c
+         LEFT JOIN person person_record
+           ON person_record.id = c.person_id
+         LEFT JOIN operations_department department_record
+           ON department_record.id = c.department_id
+          AND department_record.deleted_at IS NULL
          LEFT JOIN operations_collaborator s
            ON s.id = c.supervisor_collaborator_id
          LEFT JOIN operations_project_assignment pa
@@ -2575,7 +5045,7 @@ export class OperationsService {
          ) hiring_contract ON TRUE
         WHERE c.id = $1
           AND c.deleted_at IS NULL
-        GROUP BY c.id, s.id, hiring_contract.id, hiring_contract.status`,
+        GROUP BY c.id, person_record.id, department_record.id, s.id, hiring_contract.id, hiring_contract.status`,
       [collaboratorId]
     );
 
@@ -2799,7 +5269,7 @@ export class OperationsService {
           description,
           created_at,
           updated_at
-        ) VALUES ($1, $2, $3, $4, $5, $6, NOW(), NOW())`,
+        ) VALUES ($1, $2, $3, $4::date, $5, $6, NOW(), NOW())`,
         timesheetId,
         entry.projectAssignmentId ?? null,
         entry.activityLabel ?? null,
@@ -2837,7 +5307,7 @@ export class OperationsService {
     const existing = (await client.$queryRawUnsafe(
       `SELECT id
          FROM operations_approval
-        WHERE target_type = $1
+        WHERE target_type = $1::operations_approval_target_type_32d3f04385_enum
           AND target_id = $2
           AND deleted_at IS NULL`,
       input.targetType,
@@ -2856,7 +5326,10 @@ export class OperationsService {
           submitted_at,
           created_at,
           updated_at
-        ) VALUES ($1, $2, $3, $4, 'pending', NOW(), NOW(), NOW())
+        ) VALUES (
+          $1::operations_approval_target_type_32d3f04385_enum,
+          $2, $3, $4, 'pending', NOW(), NOW(), NOW()
+        )
         RETURNING id`,
         input.targetType,
         input.targetId,
@@ -2924,7 +5397,13 @@ export class OperationsService {
         action,
         note,
         created_at
-      ) VALUES ($1, $2, $3, $4, NOW())`,
+      ) VALUES (
+        $1,
+        $2,
+        $3::operations_approval_history_action_c8478a05d6_enum,
+        $4,
+        NOW()
+      )`,
       approvalId,
       actorCollaboratorId,
       action,
@@ -3061,7 +5540,7 @@ export class OperationsService {
           break_minutes,
           created_at,
           updated_at
-        ) VALUES ($1, $2, $3, $4, $5, $6, NOW(), NOW())`,
+        ) VALUES ($1, $2::operations_collaborator_schedule_day_weekday_5d79528f6c_enum, $3, $4::time, $5::time, $6, NOW(), NOW())`,
         collaboratorId,
         day.weekday,
         day.isWorkingDay ?? true,
@@ -3101,7 +5580,9 @@ export class OperationsService {
           created_at,
           updated_at
         ) VALUES (
-          $1, $2, $3, $4, $5, $6, $7, $8, COALESCE($9, 'active'), NOW(), NOW()
+          $1, $2, $3, $4, $5, $6, $7::date, $8::date,
+          $9::operations_project_assignment_status_155b459bbf_enum,
+          NOW(), NOW()
         )`,
         projectId,
         assignment.collaboratorId,
@@ -3204,8 +5685,13 @@ export class OperationsService {
         created_at,
         updated_at
       ) VALUES (
-        $1, $2, $3, $4, $5, 'not_started', true, $6, $7, $8, 'employee_hiring', $9, $10, NULL,
-        NULL, $10, $11, $12, 'draft', $13, NULL, $14, $14, NOW(), NOW()
+        $1, $2,
+        $3::operations_contract_contract_category_70d553ea09_enum,
+        $4::operations_contract_contract_type_48331e2ebf_enum,
+        $5, 'not_started', true,
+        $6::operations_contract_billing_model_409dc7fea2_enum,
+        $7, $8, 'employee_hiring', $9, $10::date, NULL,
+        NULL, $10::date, $11, $12, 'draft', $13, NULL, $14, $14, NOW(), NOW()
       )`,
       contractCode,
       contractName,
@@ -3231,6 +5717,7 @@ export class OperationsService {
     createdByUserId: number,
     input: {
       projectId: number;
+      contractTemplateId: number | null;
       projectCode: string;
       projectName: string;
       clientName: string;
@@ -3248,6 +5735,83 @@ export class OperationsService {
       description: string | null;
     }
   ) {
+    const templateRows = input.contractTemplateId
+      ? ((await client.$queryRawUnsafe(
+          `SELECT id,
+                  code,
+                  name,
+                  description,
+                  contract_category AS "contractCategory",
+                  contract_type AS "contractType",
+                  billing_model AS "billingModel",
+                  signature_status AS "signatureStatus",
+                  content_html AS "contentHtml"
+             FROM operations_contract_template
+            WHERE id = $1
+              AND deleted_at IS NULL
+            LIMIT 1`,
+          input.contractTemplateId
+        )) as Array<{
+          id: number;
+          code?: string | null;
+          name?: string | null;
+          description?: string | null;
+          contractCategory?: string | null;
+          contractType?: string | null;
+          billingModel?: string | null;
+          signatureStatus?: string | null;
+          contentHtml?: string | null;
+        }>)
+      : [];
+
+    const selectedTemplate = templateRows[0] ?? null;
+    const templateContext = {
+      project_code: input.projectCode,
+      project_name: input.projectName,
+      client_name: input.clientName,
+      start_date: input.startDate ?? '',
+      end_date: input.endDate ?? '',
+      budget_amount:
+        input.budgetAmount !== null && input.budgetAmount !== undefined
+          ? String(input.budgetAmount)
+          : '',
+      monthly_hour_cap:
+        input.monthlyHourCap !== null && input.monthlyHourCap !== undefined
+          ? String(input.monthlyHourCap)
+          : '',
+    };
+
+    const applyTemplateVariables = (value: string | null | undefined) => {
+      const source = value ?? '';
+      return Object.entries(templateContext).reduce(
+        (result, [key, replacement]) =>
+          result.split(`{{${key}}}`).join(replacement || ''),
+        source
+      );
+    };
+
+    const templateCodePrefix = this.normalizeOptionalText(selectedTemplate?.code);
+    const generatedContractCode = (
+      this.normalizeOptionalText(input.contractCode) ??
+      (templateCodePrefix
+        ? `${templateCodePrefix}-${input.projectCode}`
+        : null) ??
+      `PRJ-${input.projectCode}`
+    ).slice(0, 40);
+
+    const generatedContractName =
+      this.normalizeOptionalText(input.contractName) ??
+      this.normalizeOptionalText(applyTemplateVariables(selectedTemplate?.name)) ??
+      `${input.projectName} Service Agreement`;
+
+    const generatedDescription = this.normalizeOptionalText(
+      applyTemplateVariables(input.description ?? selectedTemplate?.description)
+    );
+
+    const generatedContentHtml = this.normalizeOptionalText(
+      applyTemplateVariables(selectedTemplate?.contentHtml)
+    );
+
     const created = await client.$queryRawUnsafe(
       `INSERT INTO operations_contract (
         code,
@@ -3260,6 +5824,7 @@ export class OperationsService {
         billing_model,
         account_manager_collaborator_id,
         related_collaborator_id,
+        contract_template_id,
         origin_type,
         origin_id,
         start_date,
@@ -3276,21 +5841,50 @@ export class OperationsService {
         created_at,
         updated_at
       ) VALUES (
-        $1, $2, 'client', 'service_agreement', $3, 'not_started', true, $4, $5, NULL, 'client_project', $6,
-        $7, $8, NULL, $7, $9, $10, 'draft', $11, NULL, $12, $12, NOW(), NOW()
+        $1,
+        $2,
+        $3::operations_contract_contract_category_70d553ea09_enum,
+        $4::operations_contract_contract_type_48331e2ebf_enum,
+        $5,
+        $6::operations_contract_signature_status_2cb7282a7b_enum,
+        true,
+        $7::operations_contract_billing_model_409dc7fea2_enum,
+        $8,
+        NULL,
+        $9,
+        'client_project',
+        $10,
+        $11::date,
+        $12::date,
+        NULL,
+        $11::date,
+        $13,
+        $14,
+        'draft',
+        $15,
+        $16,
+        $17,
+        $17,
+        NOW(),
+        NOW()
       )
       RETURNING id`,
-      input.contractCode ?? `PRJ-${input.projectCode}`,
-      input.contractName ?? `${input.projectName} Service Agreement`,
+      generatedContractCode,
+      generatedContractName,
+      selectedTemplate?.contractCategory ?? 'client',
+      selectedTemplate?.contractType ?? 'service_agreement',
       input.clientName,
-      input.billingModel,
+      selectedTemplate?.signatureStatus ?? 'not_started',
+      selectedTemplate?.billingModel ?? input.billingModel,
       input.managerCollaboratorId,
+      selectedTemplate?.id ?? null,
       input.projectId,
       input.startDate ?? new Date().toISOString().slice(0, 10),
       input.endDate ?? null,
       input.budgetAmount ?? null,
       input.monthlyHourCap ?? null,
-      input.description ?? null,
+      generatedDescription,
+      generatedContentHtml,
       createdByUserId
     );
 
@@ -3325,7 +5919,10 @@ export class OperationsService {
           created_at,
           updated_at
         ) VALUES (
-          $1, COALESCE($2, 'other'), COALESCE($3, 'company'), $4, $5, $6, $7, COALESCE($8, false), NOW(), NOW()
+          $1,
+          $2::operations_contract_party_party_role_b66e8515fc_enum,
+          $3::operations_contract_party_party_type_1383bb371c_enum,
+          $4, $5, $6, $7, $8, NOW(), NOW()
         )`,
         contractId,
         party.partyRole ?? 'other',
@@ -3365,7 +5962,9 @@ export class OperationsService {
           created_at,
           updated_at
         ) VALUES (
-          $1, $2, $3, $4, COALESCE($5, 'pending'), $6, NOW(), NOW()
+          $1, $2, $3, $4,
+          $5::operations_contract_signature_signer_status_1e6fbe2519_enum,
+          $6::timestamp, NOW(), NOW()
         )`,
         contractId,
         signature.signerName,
@@ -3404,7 +6003,14 @@ export class OperationsService {
           created_at,
           updated_at
         ) VALUES (
-          $1, COALESCE($2, 'value'), $3, $4, COALESCE($5, 'one_time'), $6, $7, NOW(), NOW()
+          $1,
+          $2::operations_contract_financial_term_term_type_700635c06a_enum,
+          $3,
+          $4,
+          $5::operations_contract_financial_term_recurrence_ba90bbe3bf_enum,
+          $6,
+          $7,
+          NOW(), NOW()
         )`,
         contractId,
         term.termType ?? 'value',
@@ -3443,7 +6049,13 @@ export class OperationsService {
           created_at,
           updated_at
         ) VALUES (
-          $1, COALESCE($2, 'revision'), $3, $4, COALESCE($5, 'draft'), $6, NOW(), NOW()
+          $1,
+          $2::operations_contract_revision_revision_type_cf5ba1a538_enum,
+          $3,
+          $4::date,
+          $5::operations_contract_revision_status_f44f35bb66_enum,
+          $6,
+          NOW(), NOW()
         )`,
         contractId,
         revision.revisionType ?? 'revision',
@@ -3455,9 +6067,10 @@ export class OperationsService {
     }
   }
 
-  private async replaceContractPdfDocument(
+  private async replaceContractDocument(
     client: any,
     contractId: number,
+    documentType: (typeof CONTRACT_DOCUMENT_TYPE_VALUES)[number],
     document: NonNullable<ContractPayload['replaceUploadedPdfDocument']>
   ) {
     await client.$executeRawUnsafe(
@@ -3466,32 +6079,461 @@ export class OperationsService {
               updated_at = NOW()
         WHERE contract_id = $1
           AND deleted_at IS NULL
-          AND document_type IN ('uploaded_pdf', 'generated_pdf')`,
-      contractId
+          AND document_type = $2`,
+      contractId,
+      documentType
     );
 
     await client.$executeRawUnsafe(
       `INSERT INTO operations_contract_document (
         contract_id,
         document_type,
+        file_id,
         file_name,
         mime_type,
         file_content_base64,
         is_current,
+        extraction_status,
+        extraction_summary,
         notes,
         created_at,
         updated_at
       ) VALUES (
-        $1, 'uploaded_pdf', $2, $3, $4, true, $5, NOW(), NOW()
+        $1, $2, $3, $4, $5, $6, true, $7, $8, $9, NOW(), NOW()
       )`,
       contractId,
+      documentType,
+      document.fileId ?? null,
       document.fileName,
       document.mimeType,
-      document.fileContentBase64,
+      document.fileContentBase64 ?? null,
+      document.extractionStatus ?? 'skipped',
+      document.extractionSummary ?? null,
       document.notes ?? null
     );
   }
 
+  private async resolveContractExtractionFile(
+    userId: number,
+    data: ContractExtractDraftPayload
+  ): Promise<MulterFile> {
+    if (data.contractId && data.contractId > 0) {
+      const contract = await this.getContractById(userId, data.contractId);
+      const sourceDocument = contract.documents.find(
+        (document: any) =>
+          document.isCurrent && document.documentType === 'source_upload'
+      );
+
+      if (!sourceDocument) {
+        throw new BadRequestException(
+          'No source document is attached to this contract draft.'
+        );
+      }
+
+      if (sourceDocument.fileId) {
+        const { buffer } = await this.fileService.getBuffer(sourceDocument.fileId);
+        return this.buildContractExtractionFile(
+          sourceDocument.fileName,
+          sourceDocument.mimeType,
+          buffer
+        );
+      }
+
+      const base64 = this.normalizeExtractionString(
+        sourceDocument.fileContentBase64
+      );
+
+      if (!base64) {
+        throw new BadRequestException(
+          'The current source document does not contain readable file content.'
+        );
+      }
+
+      return this.buildContractExtractionFile(
+        sourceDocument.fileName,
+        sourceDocument.mimeType,
+        Buffer.from(base64, 'base64')
+      );
+    }
+
+    const fileName = this.normalizeExtractionString(data.fileName);
+    const fileContentBase64 = this.normalizeExtractionString(
+      data.fileContentBase64
+    );
+    const mimeType = this.normalizeContractExtractionMimeType(
+      data.mimeType,
+      fileName
+    );
+
+    if (!fileName || !fileContentBase64) {
+      throw new BadRequestException(
+        'fileName and fileContentBase64 are required.'
+      );
+    }
+
+    return this.buildContractExtractionFile(
+      fileName,
+      mimeType,
+      Buffer.from(fileContentBase64, 'base64')
+    );
+  }
+
+  private buildContractExtractionFile(
+    fileName: string,
+    mimeType: string,
+    buffer: Buffer
+  ): MulterFile {
+    if (!this.isAllowedContractExtractionMimeType(mimeType)) {
+      throw new BadRequestException(
+        'Only PDF, DOC, and DOCX files are supported for contract extraction.'
+      );
+    }
+
+    if (!buffer.length) {
+      throw new BadRequestException(
+        'Unable to decode the uploaded contract document.'
+      );
+    }
+
+    if (buffer.length > 12 * 1024 * 1024) {
+      throw new BadRequestException(
+        'The uploaded contract document must be smaller than 12 MB.'
+      );
+    }
+
+    return {
+      fieldname: 'file',
+      originalname: fileName,
+      encoding: 'base64',
+      mimetype: mimeType,
+      size: buffer.length,
+      destination: '',
+      filename: fileName,
+      path: '',
+      buffer,
+    };
+  }
+
+  private async renderContractPdfBuffer(contract: any) {
+    const html = await this.buildContractPdfHtml(contract);
+
+    let browser: any = null;
+
+    try {
+      const importPlaywright = new Function(
+        'moduleName',
+        'return import(moduleName);'
+      ) as (moduleName: string) => Promise<any>;
+      const playwright = await importPlaywright('playwright');
+      browser = await playwright.chromium.launch({ headless: true });
+      const page = await browser.newPage();
+      await page.setContent(html, { waitUntil: 'networkidle' });
+      return Buffer.from(
+        await page.pdf({
+          format: 'A4',
+          printBackground: true,
+          margin: {
+            top: '72px',
+            right: '18px',
+            bottom: '56px',
+            left: '18px',
+          },
+        })
+      );
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      const errorStack =
+        error instanceof Error ? (error.stack ?? error.message) : String(error);
+      const missingPlaywrightRuntime =
+        /Cannot find package ['"]playwright['"]|Cannot find module ['"]playwright['"]|Executable doesn't exist|browserType\.launch|Failed to launch|Please run the following command to download new browsers/i.test(
+          errorMessage
+        );
+
+      this.logger.error(
+        `Failed to generate contract PDF for contract ${contract?.id ?? 'unknown'}. ${errorMessage}`,
+        errorStack
+      );
+
+      throw new InternalServerErrorException(
+        missingPlaywrightRuntime
+          ? 'PDF generation is unavailable because Playwright/Chromium is not installed on the server. Run `pnpm --filter api run playwright:install` in the API environment.'
+          : 'Failed to generate the PDF document. Check server logs for details.'
+      );
+    } finally {
+      await browser?.close?.();
+    }
+  }
+
+  private async buildContractPdfHtml(contract: any) {
+    const logoUrl = await this.resolveContractPdfLogoUrl();
+    const contentHtml =
+      this.normalizeOptionalText(contract.contentHtml) ??
+      this.normalizeOptionalText(contract.description)
+        ?.split(/\n{2,}/)
+        .map((paragraph) => `<p>${this.escapeHtml(paragraph)}</p>`)
+        .join('') ??
+      '<p>No contract body was provided yet.</p>';
+    const partiesHtml = (contract.parties ?? []).length
+      ? contract.parties
+          .map(
+            (party: any) => `
+              <li>
+                <strong>${this.escapeHtml(party.displayName || 'Party')}</strong>
+                <span>${this.escapeHtml(
+                  [party.partyRole, party.partyType].filter(Boolean).join(' • ')
+                )}</span>
+              </li>`
+          )
+          .join('')
+      : '<li><strong>No parties registered yet.</strong><span>Complete this contract later if needed.</span></li>';
+    const financialTermsHtml = (contract.financialTerms ?? []).length
+      ? contract.financialTerms
+          .map(
+            (term: any) => `
+              <li>
+                <strong>${this.escapeHtml(term.label || 'Term')}</strong>
+                <span>${this.escapeHtml(
+                  [term.termType, term.amount, term.recurrence]
+                    .filter((item) => item !== null && item !== undefined && String(item).trim())
+                    .join(' • ')
+                )}</span>
+              </li>`
+          )
+          .join('')
+      : '<li><strong>No financial terms registered yet.</strong><span>The draft is intentionally lightweight.</span></li>';
+
+    return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      @page {
+        size: A4;
+        margin: 72px 18px 56px 18px;
+      }
+      body {
+        color: #0f172a;
+        font-family: Arial, sans-serif;
+        font-size: 12px;
+        line-height: 1.5;
+        margin: 0;
+      }
+      header {
+        align-items: center;
+        border-bottom: 2px solid #dbeafe;
+        display: flex;
+        gap: 16px;
+        justify-content: space-between;
+        margin-bottom: 24px;
+        padding-bottom: 16px;
+      }
+      .brand {
+        align-items: center;
+        display: flex;
+        gap: 12px;
+      }
+      .brand img {
+        height: 42px;
+        max-width: 140px;
+        object-fit: contain;
+      }
+      .eyebrow {
+        color: #2563eb;
+        font-size: 10px;
+        font-weight: 700;
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+      }
+      h1 {
+        font-size: 22px;
+        margin: 4px 0 0;
+      }
+      .meta-grid {
+        display: grid;
+        gap: 12px;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        margin: 20px 0;
+      }
+      .meta-card {
+        background: #f8fafc;
+        border: 1px solid #dbeafe;
+        border-radius: 12px;
+        padding: 12px;
+      }
+      .meta-card strong {
+        display: block;
+        font-size: 10px;
+        letter-spacing: 0.08em;
+        margin-bottom: 4px;
+        text-transform: uppercase;
+      }
+      section {
+        margin-top: 20px;
+      }
+      h2 {
+        color: #1d4ed8;
+        font-size: 14px;
+        margin: 0 0 10px;
+      }
+      ul {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+      }
+      li {
+        border: 1px solid #e2e8f0;
+        border-radius: 10px;
+        margin-bottom: 8px;
+        padding: 10px 12px;
+      }
+      li strong {
+        display: block;
+        margin-bottom: 2px;
+      }
+      footer {
+        border-top: 1px solid #dbeafe;
+        color: #475569;
+        font-size: 10px;
+        margin-top: 28px;
+        padding-top: 12px;
+      }
+      .content {
+        border: 1px solid #e2e8f0;
+        border-radius: 14px;
+        padding: 18px;
+      }
+      .content p:first-child {
+        margin-top: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <header>
+      <div class="brand">
+        <img src="${logoUrl}" alt="System logo" />
+        <div>
+          <div class="eyebrow">Contract Document</div>
+          <h1>${this.escapeHtml(
+            contract.name || contract.code || 'Contract draft'
+          )}</h1>
+        </div>
+      </div>
+      <div>
+        <div><strong>Code:</strong> ${this.escapeHtml(
+          contract.code || 'Draft'
+        )}</div>
+        <div><strong>Status:</strong> ${this.escapeHtml(
+          this.humanizeEnumLabel(contract.status || 'draft')
+        )}</div>
+      </div>
+    </header>
+
+    <div class="meta-grid">
+      <div class="meta-card">
+        <strong>Client</strong>
+        ${this.escapeHtml(contract.clientName || 'Not informed yet')}
+      </div>
+      <div class="meta-card">
+        <strong>Type</strong>
+        ${this.escapeHtml(
+          this.humanizeEnumLabel(contract.contractType || 'service_agreement')
+        )}
+      </div>
+      <div class="meta-card">
+        <strong>Period</strong>
+        ${this.escapeHtml(
+          [contract.startDate || 'Open start', contract.endDate || 'Open end'].join(
+            ' - '
+          )
+        )}
+      </div>
+      <div class="meta-card">
+        <strong>Billing</strong>
+        ${this.escapeHtml(
+          this.humanizeEnumLabel(contract.billingModel || 'time_and_material')
+        )}
+      </div>
+    </div>
+
+    <section>
+      <h2>Related Parties</h2>
+      <ul>${partiesHtml}</ul>
+    </section>
+
+    <section>
+      <h2>Financial Terms</h2>
+      <ul>${financialTermsHtml}</ul>
+    </section>
+
+    <section>
+      <h2>Contract Body</h2>
+      <div class="content">${contentHtml}</div>
+    </section>
+
+    <footer>
+      Generated on ${this.escapeHtml(new Date().toISOString())} for ${
+        this.escapeHtml(contract.code || 'draft')
+      }.
+    </footer>
+  </body>
+</html>`;
+  }
+
+  private async resolveContractPdfLogoUrl() {
+    const settings = await this.settingService.getSettingValues([
+      'image-url',
+      'icon-url',
+    ]);
+    const configuredUrl =
+      this.normalizeOptionalText(settings['image-url']) ??
+      this.normalizeOptionalText(settings['icon-url']);
+
+    if (configuredUrl && /^https?:\/\//i.test(configuredUrl)) {
+      return configuredUrl;
+    }
+
+    const inlineSvg = encodeURIComponent(
+      `<svg xmlns="http://www.w3.org/2000/svg" width="240" height="72" viewBox="0 0 240 72">
+        <rect width="240" height="72" rx="18" fill="#0f172a"/>
+        <circle cx="38" cy="36" r="18" fill="#3b82f6"/>
+        <text x="72" y="43" fill="#ffffff" font-size="26" font-family="Arial, sans-serif" font-weight="700">HedHog</text>
+      </svg>`
+    );
+
+    return `data:image/svg+xml;charset=UTF-8,${inlineSvg}`;
+  }
+
+  private buildContractPdfFileName(contract: any) {
+    const base =
+      this.normalizeOptionalText(contract.code) ??
+      this.normalizeOptionalText(contract.name) ??
+      `contract-${contract.id}`;
+
+    return `${base
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 80) || `contract-${contract.id}`}.pdf`;
+  }
+
+  private humanizeEnumLabel(value: string) {
+    return String(value ?? '')
+      .split('_')
+      .filter(Boolean)
+      .map((part) => part[0]?.toUpperCase() + part.slice(1))
+      .join(' ');
+  }
+
+  private escapeHtml(value: string) {
+    return String(value ?? '')
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
   private async insertContractHistory(
     client: any,
     contractId: number,
@@ -3519,6 +6561,745 @@ export class OperationsService {
     );
   }
 
+  private async generateCollaboratorCode(client: any) {
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      const candidate = `COL-${Date.now().toString(36).toUpperCase()}${Math.random()
+        .toString(36)
+        .slice(2, 6)
+        .toUpperCase()}`;
+      const existing = (await client.$queryRawUnsafe(
+        `SELECT code
+           FROM operations_collaborator
+          WHERE code = $1
+          LIMIT 1`,
+        candidate
+      )) as { code: string }[];
+
+      if (!existing.length) {
+        return candidate;
+      }
+    }
+
+    throw new BadRequestException('Unable to generate collaborator code.');
+  }
+
+  private async generateContractCode(client: any) {
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      const candidate = `CTR-${Date.now().toString(36).toUpperCase()}${Math.random()
+        .toString(36)
+        .slice(2, 6)
+        .toUpperCase()}`.slice(0, 40);
+      const existing = (await client.$queryRawUnsafe(
+        `SELECT code
+           FROM operations_contract
+          WHERE code = $1
+          LIMIT 1`,
+        candidate
+      )) as { code: string }[];
+
+      if (!existing.length) {
+        return candidate;
+      }
+    }
+
+    throw new BadRequestException('Unable to generate contract code.');
+  }
+
+  private async generateContractContentHtml(
+    contract: any,
+    data: ContractGenerateContentPayload = {}
+  ) {
+    const currentContent = this.normalizeOptionalText(contract.contentHtml);
+
+    const primaryParty =
+      (contract.parties ?? []).find((party: any) => party.isPrimary) ??
+      (contract.parties ?? [])[0] ??
+      null;
+    const templateContext = {
+      contract_code: this.normalizeOptionalText(contract.code) ?? '',
+      contract_name: this.normalizeOptionalText(contract.name) ?? '',
+      client_name:
+        this.normalizeOptionalText(contract.clientName) ??
+        this.normalizeOptionalText(primaryParty?.displayName) ??
+        '',
+      contract_category: this.normalizeOptionalText(contract.contractCategory) ?? '',
+      contract_type: this.normalizeOptionalText(contract.contractType) ?? '',
+      start_date: this.normalizeOptionalText(contract.startDate) ?? '',
+      end_date: this.normalizeOptionalText(contract.endDate) ?? '',
+      effective_date: this.normalizeOptionalText(contract.effectiveDate) ?? '',
+      signed_at: this.normalizeOptionalText(contract.signedAt) ?? '',
+      budget_amount:
+        contract.budgetAmount !== null && contract.budgetAmount !== undefined
+          ? String(contract.budgetAmount)
+          : '',
+      monthly_hour_cap:
+        contract.monthlyHourCap !== null &&
+        contract.monthlyHourCap !== undefined
+          ? String(contract.monthlyHourCap)
+          : '',
+      primary_party_name:
+        this.normalizeOptionalText(primaryParty?.displayName) ?? '',
+      primary_party_document:
+        this.normalizeOptionalText(primaryParty?.documentNumber) ?? '',
+      primary_party_email: this.normalizeOptionalText(primaryParty?.email) ?? '',
+      primary_party_phone: this.normalizeOptionalText(primaryParty?.phone) ?? '',
+      description: this.normalizeOptionalText(contract.description) ?? '',
+    };
+
+    const applyTemplateVariables = (value: string | null | undefined) => {
+      const source = value ?? '';
+      return Object.entries(templateContext).reduce(
+        (result, [key, replacement]) =>
+          result.split(`{{${key}}}`).join(replacement || ''),
+        source
+      );
+    };
+
+    const currentHtmlWithVariables = this.normalizeOptionalText(
+      applyTemplateVariables(currentContent)
+    );
+
+    if (currentHtmlWithVariables && data.overwrite !== true) {
+      return currentHtmlWithVariables;
+    }
+
+    const baseHtml =
+      currentHtmlWithVariables ?? this.buildFallbackContractContent(contract);
+    const promptMessage =
+      this.normalizeOptionalText(data.promptMessage) ??
+      'Generate an initial contract body using the registered metadata and keep the language concise, professional, and ready for legal review.';
+
+    try {
+      const aiResult = await this.aiService.chat({
+        provider: data.provider === 'gemini' ? 'gemini' : 'openai',
+        model: data.provider === 'gemini' ? 'gemini-1.5-flash' : 'gpt-4o-mini',
+        message: promptMessage,
+        systemPrompt: [
+          'You draft professional business contract content for an operations back-office system.',
+          'Return ONLY clean HTML suitable for a rich text editor preview.',
+          'Do not include Markdown fences, commentary, or legal disclaimers inside the HTML.',
+          'Keep the output concise, well-structured, and ready for legal revision.',
+          'If a specific detail is missing, preserve placeholders like {{client_name}}, {{start_date}}, {{end_date}}, {{budget_amount}}, and {{monthly_hour_cap}} instead of inventing facts.',
+          `Contract context:\n${JSON.stringify(templateContext, null, 2)}`,
+          baseHtml
+            ? `Current base HTML:\n${baseHtml}`
+            : 'There is no current HTML yet.',
+        ].join('\n\n'),
+      });
+
+      return (
+        this.normalizeOptionalText(String(aiResult?.content ?? '')) ?? baseHtml
+      );
+    } catch {
+      return baseHtml;
+    }
+  }
+
+  private buildFallbackContractContent(contract: any) {
+    const title = this.escapeHtml(
+      this.normalizeOptionalText(contract.name) ??
+        this.normalizeOptionalText(contract.code) ??
+        'Contract Draft'
+    );
+    const description = this.escapeHtml(
+      this.normalizeOptionalText(contract.description) ??
+        'This draft summarizes the main commercial and operational conditions agreed between the parties.'
+    );
+    const validityItems = [
+      contract.startDate ? `Start date: ${contract.startDate}` : null,
+      contract.endDate ? `End date: ${contract.endDate}` : null,
+      contract.effectiveDate ? `Effective date: ${contract.effectiveDate}` : null,
+      contract.signedAt ? `Signed at: ${contract.signedAt}` : null,
+    ]
+      .filter(Boolean)
+      .map((item) => `<li>${this.escapeHtml(String(item))}</li>`)
+      .join('');
+    const partiesHtml = (contract.parties ?? []).length
+      ? (contract.parties ?? [])
+          .map(
+            (party: any) => `
+              <li>
+                <strong>${this.escapeHtml(party.displayName || 'Party')}</strong>
+                <span>${this.escapeHtml(
+                  [party.partyRole, party.partyType, party.documentNumber]
+                    .filter(Boolean)
+                    .join(' • ')
+                )}</span>
+              </li>`
+          )
+          .join('')
+      : '<li><strong>Main party</strong><span>{{client_name}}</span></li>';
+    const financialTermsHtml = (contract.financialTerms ?? []).length
+      ? (contract.financialTerms ?? [])
+          .map(
+            (term: any) => `
+              <li>
+                <strong>${this.escapeHtml(term.label || 'Financial term')}</strong>
+                <span>${this.escapeHtml(
+                  [term.termType, term.amount, term.recurrence]
+                    .filter(
+                      (item) =>
+                        item !== null &&
+                        item !== undefined &&
+                        String(item).trim()
+                    )
+                    .join(' • ')
+                )}</span>
+              </li>`
+          )
+          .join('')
+      : '<li><strong>Commercial conditions</strong><span>Define prices, billing cadence, and penalties before signature.</span></li>';
+
+    return `
+      <h1>${title}</h1>
+      <p>${description}</p>
+      <h2>1. Parties</h2>
+      <ul>${partiesHtml}</ul>
+      <h2>2. Scope and object</h2>
+      <p>The parties agree to execute the services and obligations described in this contract, according to the agreed operational, technical, and commercial conditions.</p>
+      <h2>3. Validity</h2>
+      ${validityItems ? `<ul>${validityItems}</ul>` : '<p>Define start date, term, renewal, and termination conditions.</p>'}
+      <h2>4. Financial terms</h2>
+      <ul>${financialTermsHtml}</ul>
+      <h2>5. General obligations</h2>
+      <p>Review confidentiality, data protection, service levels, termination, and liability clauses before formal approval.</p>
+    `;
+  }
+
+  private async buildContractLegalReview(
+    contract: any,
+    data: ContractLegalReviewPayload = {}
+  ): Promise<ContractLegalReviewResult> {
+    const heuristicReview = this.buildHeuristicContractLegalReview(contract);
+    const promptMessage =
+      this.normalizeOptionalText(data.promptMessage) ??
+      'Review this contract draft and return an advisory legal checklist with practical warnings and missing items.';
+
+    try {
+      const aiResult = await this.aiService.chat({
+        provider: data.provider === 'gemini' ? 'gemini' : 'openai',
+        model: data.provider === 'gemini' ? 'gemini-1.5-flash' : 'gpt-4o-mini',
+        message: promptMessage,
+        systemPrompt: [
+          'You are an advisory legal-review assistant for business contracts.',
+          'Return ONLY valid JSON. Do not include Markdown fences or commentary.',
+          'This review is non-blocking and should help a human reviewer spot likely gaps.',
+          'Expected JSON shape:',
+          JSON.stringify(
+            {
+              summary: '',
+              missingFields: [],
+              warnings: [],
+              checklist: [],
+              status: 'attention_required',
+            },
+            null,
+            2
+          ),
+          `Contract metadata:\n${JSON.stringify(
+            {
+              code: contract.code,
+              name: contract.name,
+              clientName: contract.clientName,
+              contractCategory: contract.contractCategory,
+              contractType: contract.contractType,
+              startDate: contract.startDate,
+              endDate: contract.endDate,
+              effectiveDate: contract.effectiveDate,
+              signatureStatus: contract.signatureStatus,
+              parties: contract.parties,
+              financialTerms: contract.financialTerms,
+            },
+            null,
+            2
+          )}`,
+          `Contract HTML:\n${this.normalizeOptionalText(contract.contentHtml) ?? ''}`,
+        ].join('\n\n'),
+      });
+
+      const parsed = this.parseAiJsonPayload(String(aiResult?.content ?? ''));
+      const missingFields = Array.from(
+        new Set([
+          ...heuristicReview.missingFields,
+          ...this.normalizeStringList(parsed.missingFields),
+        ])
+      );
+      const warnings = Array.from(
+        new Set([
+          ...heuristicReview.warnings,
+          ...this.normalizeStringList(parsed.warnings),
+        ])
+      );
+      const checklist = Array.from(
+        new Set([
+          ...this.normalizeStringList(parsed.checklist),
+          ...heuristicReview.checklist,
+        ])
+      );
+      const parsedStatus = this.normalizeExtractionString(parsed.status);
+      const status: ContractLegalReviewResult['status'] =
+        parsedStatus === 'ready_for_revision' ||
+        parsedStatus === 'attention_required'
+          ? parsedStatus
+          : missingFields.length || warnings.length
+            ? 'attention_required'
+            : 'ready_for_revision';
+
+      return {
+        summary:
+          this.normalizeExtractionString(parsed.summary) ||
+          heuristicReview.summary,
+        missingFields,
+        warnings,
+        checklist,
+        status,
+        reviewedAt: new Date().toISOString(),
+      };
+    } catch {
+      return heuristicReview;
+    }
+  }
+
+  private buildHeuristicContractLegalReview(
+    contract: any
+  ): ContractLegalReviewResult {
+    const contentText = (
+      this.normalizeOptionalText(contract.contentHtml) ?? ''
+    )
+      .replace(/<[^>]+>/g, ' ')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .toLowerCase();
+    const primaryParty =
+      (contract.parties ?? []).find((party: any) => party.isPrimary) ??
+      (contract.parties ?? [])[0] ??
+      null;
+    const missingFields: string[] = [];
+    const warnings: string[] = [];
+    const checklist: string[] = [];
+
+    if (!this.normalizeOptionalText(contract.name)) {
+      missingFields.push('Contract title');
+      checklist.push('Attention: define a clear contract title.');
+    } else {
+      checklist.push('OK: contract title is registered.');
+    }
+
+    if (!this.normalizeOptionalText(contract.clientName)) {
+      missingFields.push('Client or primary party name');
+      checklist.push('Attention: confirm the client or main party identification.');
+    } else {
+      checklist.push('OK: the main party is identified.');
+    }
+
+    if (!contract.startDate && !contract.effectiveDate) {
+      missingFields.push('Start or effective date');
+      checklist.push('Attention: define the term start or effective date.');
+    } else {
+      checklist.push('OK: validity dates were provided.');
+    }
+
+    if (!(contract.parties ?? []).length) {
+      missingFields.push('Related parties');
+      warnings.push('No related parties are registered in the contract draft.');
+    }
+
+    if (!this.normalizeOptionalText(primaryParty?.documentNumber)) {
+      warnings.push('Consider confirming the primary party document number.');
+    }
+
+    if (!(contract.financialTerms ?? []).length && contract.budgetAmount == null) {
+      warnings.push('Commercial conditions are still generic; define prices, recurrence, and penalties.');
+      checklist.push('Attention: validate billing, adjustments, and penalties.');
+    } else {
+      checklist.push('OK: there is at least one financial reference to review.');
+    }
+
+    if (!contentText) {
+      missingFields.push('Contract body content');
+      warnings.push('The contract body is still empty and needs a first draft.');
+    } else {
+      if (contentText.length < 600) {
+        warnings.push('The contract body is still brief; validate scope, obligations, and exceptions in detail.');
+      }
+      if (!/(rescis|terminat|cancel)/.test(contentText)) {
+        warnings.push('Add a termination / rescission clause with notice and penalty rules.');
+      }
+      if (!/(confiden|sigil|data protect|privacy)/.test(contentText)) {
+        warnings.push('Review confidentiality and data protection clauses when applicable.');
+      }
+      if (!/(foro|jurisd|governing law|applicable law)/.test(contentText)) {
+        warnings.push('Review the governing law / forum clause before signature.');
+      }
+    }
+
+    const summary =
+      missingFields.length || warnings.length
+        ? `Advisory legal review found ${missingFields.length} missing item(s) and ${warnings.length} point(s) for attention before final approval.`
+        : 'Advisory legal review found the draft structurally consistent for human legal revision.';
+
+    return {
+      summary,
+      missingFields: Array.from(new Set(missingFields)),
+      warnings: Array.from(new Set(warnings)),
+      checklist: Array.from(new Set(checklist)),
+      status:
+        missingFields.length || warnings.length
+          ? 'attention_required'
+          : 'ready_for_revision',
+      reviewedAt: new Date().toISOString(),
+    };
+  }
+
+  private buildContractExtractionSystemPrompt() {
+    return [
+      'You extract structured draft data from uploaded business contracts.',
+      'Return ONLY valid JSON. Do not include Markdown fences, prose, or comments.',
+      'Use empty strings or empty arrays when the document is unclear; never invent legal facts.',
+      'Dates must use YYYY-MM-DD whenever the document provides enough confidence.',
+      'For contentHtml, return clean HTML suitable for a rich text editor preview.',
+      'Expected JSON shape:',
+      JSON.stringify(
+        {
+          code: '',
+          name: '',
+          clientName: '',
+          contractCategory: 'client',
+          contractType: 'service_agreement',
+          signatureStatus: 'not_started',
+          billingModel: 'time_and_material',
+          originType: 'manual',
+          originId: '',
+          startDate: '',
+          endDate: '',
+          signedAt: '',
+          effectiveDate: '',
+          budgetAmount: '',
+          monthlyHourCap: '',
+          status: 'draft',
+          description: '',
+          contentHtml: '',
+          parties: [
+            {
+              displayName: '',
+              partyRole: 'client',
+              partyType: 'company',
+              documentNumber: '',
+              email: '',
+              phone: '',
+              isPrimary: true,
+            },
+          ],
+          signatures: [
+            {
+              signerName: '',
+              signerRole: '',
+              signerEmail: '',
+              status: 'pending',
+              signedAt: '',
+            },
+          ],
+          financialTerms: [
+            {
+              label: '',
+              termType: 'value',
+              amount: '',
+              recurrence: 'one_time',
+              dueDay: '',
+              notes: '',
+            },
+          ],
+          revisions: [
+            {
+              title: '',
+              revisionType: 'revision',
+              effectiveDate: '',
+              status: 'draft',
+              summary: '',
+            },
+          ],
+          summary: '',
+          missingFields: [],
+          warnings: [],
+        },
+        null,
+        2
+      ),
+    ].join('\n\n');
+  }
+
+  private parseAiJsonPayload(content: string): Record<string, unknown> {
+    const trimmed = String(content ?? '').trim();
+
+    if (!trimmed) {
+      throw new BadRequestException('AI returned an empty contract draft response.');
+    }
+
+    const fencedMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+    const candidate = fencedMatch?.[1]?.trim() || trimmed;
+
+    try {
+      return JSON.parse(candidate) as Record<string, unknown>;
+    } catch {
+      const firstBraceIndex = candidate.indexOf('{');
+      const lastBraceIndex = candidate.lastIndexOf('}');
+
+      if (firstBraceIndex >= 0 && lastBraceIndex > firstBraceIndex) {
+        try {
+          return JSON.parse(
+            candidate.slice(firstBraceIndex, lastBraceIndex + 1)
+          ) as Record<string, unknown>;
+        } catch {
+          throw new BadRequestException(
+            'AI returned an invalid contract draft payload.'
+          );
+        }
+      }
+
+      throw new BadRequestException('AI returned an invalid contract draft payload.');
+    }
+  }
+
+  private normalizeContractExtractDraft(raw: Record<string, unknown>) {
+    const warnings = this.normalizeStringList(raw.warnings);
+    const missingFields = this.normalizeStringList(raw.missingFields);
+
+    const draft = {
+      code: this.normalizeExtractionString(raw.code),
+      name: this.normalizeExtractionString(raw.name),
+      clientName: this.normalizeExtractionString(raw.clientName),
+      contractCategory: this.normalizeEnumValue(
+        raw.contractCategory,
+        CONTRACT_CATEGORY_VALUES,
+        'client'
+      ),
+      contractType: this.normalizeEnumValue(
+        raw.contractType,
+        CONTRACT_TYPE_VALUES,
+        'service_agreement'
+      ),
+      signatureStatus: this.normalizeEnumValue(
+        raw.signatureStatus,
+        SIGNATURE_STATUS_VALUES,
+        'not_started'
+      ),
+      isActive: raw.isActive === false ? false : true,
+      billingModel: this.normalizeEnumValue(
+        raw.billingModel,
+        BILLING_MODEL_VALUES,
+        'time_and_material'
+      ),
+      originType: this.normalizeEnumValue(
+        raw.originType,
+        ORIGIN_TYPE_VALUES,
+        'manual'
+      ),
+      originId: this.normalizeExtractionString(raw.originId),
+      startDate: this.normalizeExtractionDate(raw.startDate),
+      endDate: this.normalizeExtractionDate(raw.endDate),
+      signedAt: this.normalizeExtractionDate(raw.signedAt),
+      effectiveDate: this.normalizeExtractionDate(raw.effectiveDate),
+      budgetAmount: this.normalizeExtractionNumber(raw.budgetAmount),
+      monthlyHourCap: this.normalizeExtractionNumber(raw.monthlyHourCap),
+      status: this.normalizeEnumValue(raw.status, CONTRACT_STATUS_VALUES, 'draft'),
+      description: this.normalizeExtractionString(raw.description),
+      contentHtml: this.normalizeExtractionString(raw.contentHtml),
+      summary: this.normalizeExtractionString(raw.summary),
+      parties: this.normalizeObjectList(raw.parties)
+        .map((party) => ({
+          displayName: this.normalizeExtractionString(party.displayName),
+          partyRole: this.normalizeEnumValue(
+            party.partyRole,
+            PARTY_ROLE_VALUES,
+            'client'
+          ),
+          partyType: this.normalizeEnumValue(
+            party.partyType,
+            PARTY_TYPE_VALUES,
+            'company'
+          ),
+          documentNumber: this.normalizeExtractionString(party.documentNumber),
+          email: this.normalizeExtractionString(party.email),
+          phone: this.normalizeExtractionString(party.phone),
+          isPrimary: this.normalizeExtractionBoolean(party.isPrimary),
+        }))
+        .filter((party) => party.displayName),
+      signatures: this.normalizeObjectList(raw.signatures)
+        .map((signature) => ({
+          signerName: this.normalizeExtractionString(signature.signerName),
+          signerRole: this.normalizeExtractionString(signature.signerRole),
+          signerEmail: this.normalizeExtractionString(signature.signerEmail),
+          status: this.normalizeEnumValue(
+            signature.status,
+            SIGNATURE_ITEM_STATUS_VALUES,
+            'pending'
+          ),
+          signedAt: this.normalizeExtractionDate(signature.signedAt),
+        }))
+        .filter((signature) => signature.signerName),
+      financialTerms: this.normalizeObjectList(raw.financialTerms)
+        .map((term) => ({
+          label: this.normalizeExtractionString(term.label),
+          termType: this.normalizeEnumValue(
+            term.termType,
+            FINANCIAL_TERM_TYPE_VALUES,
+            'value'
+          ),
+          amount: this.normalizeExtractionNumber(term.amount),
+          recurrence: this.normalizeEnumValue(
+            term.recurrence,
+            RECURRENCE_VALUES,
+            'one_time'
+          ),
+          dueDay: this.normalizeExtractionNumber(term.dueDay),
+          notes: this.normalizeExtractionString(term.notes),
+        }))
+        .filter((term) => term.label),
+      revisions: this.normalizeObjectList(raw.revisions)
+        .map((revision) => ({
+          title: this.normalizeExtractionString(revision.title),
+          revisionType: this.normalizeEnumValue(
+            revision.revisionType,
+            REVISION_TYPE_VALUES,
+            'revision'
+          ),
+          effectiveDate: this.normalizeExtractionDate(revision.effectiveDate),
+          status: this.normalizeEnumValue(
+            revision.status,
+            REVISION_STATUS_VALUES,
+            'draft'
+          ),
+          summary: this.normalizeExtractionString(revision.summary),
+        }))
+        .filter((revision) => revision.title),
+    };
+
+    if (!draft.name) missingFields.push('Contract title');
+    if (!draft.clientName) missingFields.push('Client name');
+    if (!draft.startDate) missingFields.push('Start date');
+    if (!draft.contentHtml && !draft.summary && !draft.description) {
+      warnings.push(
+        'The contract body was not extracted with enough confidence. Use the editor to complete it.'
+      );
+    }
+    if (!draft.parties.length) {
+      warnings.push('No related parties were identified with confidence.');
+    }
+
+    return {
+      ...draft,
+      summary: draft.summary || draft.description || draft.name,
+      missingFields: Array.from(new Set(missingFields.filter(Boolean))),
+      warnings: Array.from(new Set(warnings.filter(Boolean))),
+    };
+  }
+
+  private normalizeExtractionString(value: unknown) {
+    return typeof value === 'string'
+      ? value.trim()
+      : value === null || value === undefined
+        ? ''
+        : String(value).trim();
+  }
+
+  private normalizeExtractionBoolean(value: unknown) {
+    if (typeof value === 'boolean') {
+      return value;
+    }
+
+    const normalized = this.normalizeExtractionString(value).toLowerCase();
+    return normalized === 'true' || normalized === '1' || normalized === 'yes';
+  }
+
+  private normalizeExtractionNumber(value: unknown) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return value;
+    }
+
+    const normalized = this.normalizeExtractionString(value);
+    if (!normalized) {
+      return '';
+    }
+
+    const direct = Number(normalized);
+    if (Number.isFinite(direct)) {
+      return direct;
+    }
+
+    const ptBr = normalized
+      .split('.')
+      .join('')
+      .replace(',', '.');
+    const parsed = Number(ptBr);
+
+    return Number.isFinite(parsed) ? parsed : normalized;
+  }
+
+  private normalizeExtractionDate(value: unknown) {
+    const normalized = this.normalizeExtractionString(value);
+    if (!normalized) {
+      return '';
+    }
+
+    const match = normalized.match(/\d{4}-\d{2}-\d{2}/);
+    return match?.[0] ?? '';
+  }
+
+  private normalizeStringList(value: unknown) {
+    return Array.isArray(value)
+      ? value
+          .map((item) => this.normalizeExtractionString(item))
+          .filter(Boolean)
+      : [];
+  }
+
+  private normalizeObjectList(value: unknown): Record<string, unknown>[] {
+    if (!Array.isArray(value)) {
+      return [];
+    }
+
+    return value.filter(
+      (item): item is Record<string, unknown> =>
+        Boolean(item) && typeof item === 'object'
+    );
+  }
+
+  private normalizeEnumValue<T extends string>(
+    value: unknown,
+    allowed: readonly T[],
+    fallback: T
+  ): T {
+    const normalized = this.normalizeExtractionString(value) as T;
+    return allowed.includes(normalized) ? normalized : fallback;
+  }
+
+  private normalizeContractExtractionMimeType(
+    mimeType?: string | null,
+    fileName?: string | null
+  ) {
+    const current = this.normalizeExtractionString(mimeType).toLowerCase();
+    if (current && current !== 'application/octet-stream') {
+      return current;
+    }
+
+    const name = this.normalizeExtractionString(fileName).toLowerCase();
+    if (name.endsWith('.pdf')) return 'application/pdf';
+    if (name.endsWith('.doc')) return 'application/msword';
+    if (name.endsWith('.docx')) {
+      return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+    }
+
+    return current || 'application/octet-stream';
+  }
+
+  private isAllowedContractExtractionMimeType(mimeType: string) {
+    return [
+      'application/pdf',
+      'application/msword',
+      'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    ].includes(mimeType);
+  }
+
   private requireFields(input: Record<string, unknown>, required: string[]) {
     for (const field of required) {
       const value = input[field];
@@ -3553,16 +7334,20 @@ export class OperationsService {
     updates: string[],
     params: unknown[],
     column: string,
-    value: unknown
+    value: unknown,
+    castType?: string
   ) {
     if (value === undefined) return;
     params.push(value);
-    updates.push(`${column} = $${params.length}`);
+    const placeholder = castType
+      ? `$${params.length}::${castType}`
+      : `$${params.length}`;
+    updates.push(`${column} = ${placeholder}`);
   }
 
-  private param(params: unknown[], value: unknown) {
+  private param(params: unknown[], value: unknown, castType?: string) {
     params.push(value);
-    return `$${params.length}`;
+    return castType ? `$${params.length}::${castType}` : `$${params.length}`;
   }
 
   private groupBy<T extends Record<string, any>>(items: T[], key: keyof T) {