@hed-hog/finance 0.0.233 → 0.0.236

package/src/finance.service.ts

@@ -3,18 +3,27 @@ import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
 import { PrismaService } from '@hed-hog/api-prisma';
 import { AiService } from '@hed-hog/core';
 import {
-  BadRequestException,
-  Injectable,
-  NotFoundException
+    BadRequestException,
+    Injectable,
+    Logger,
+    NotFoundException
 } from '@nestjs/common';
 import { CreateBankAccountDto } from './dto/create-bank-account.dto';
+import { CreateCostCenterDto } from './dto/create-cost-center.dto';
+import { CreateFinanceCategoryDto } from './dto/create-finance-category.dto';
 import { CreateFinancialTitleDto } from './dto/create-financial-title.dto';
+import { CreatePeriodCloseDto } from './dto/create-period-close.dto';
+import { MoveFinanceCategoryDto } from './dto/move-finance-category.dto';
 import { UpdateBankAccountDto } from './dto/update-bank-account.dto';
+import { UpdateCostCenterDto } from './dto/update-cost-center.dto';
+import { UpdateFinanceCategoryDto } from './dto/update-finance-category.dto';
 
 type TitleType = 'payable' | 'receivable';
 
 @Injectable()
 export class FinanceService {
+  private readonly logger = new Logger(FinanceService.name);
+
   constructor(
     private readonly prisma: PrismaService,
     private readonly paginationService: PaginationService,
@@ -34,20 +43,25 @@ export class FinanceService {
     const slug = isPayable
       ? 'finance-payable-extractor'
       : 'finance-receivable-extractor';
+    const llmAttachmentDebug = await this.ai.debugAttachmentForLlm(file, fileId);
+    this.logger.warn(
+      `[FINANCE-EXTRACT] start type=${titleType} fileId=${fileId || 'upload'} mode=${llmAttachmentDebug?.mode || 'none'} mime=${llmAttachmentDebug?.mimeType || 'n/a'} textLength=${llmAttachmentDebug?.textLength || 0}`,
+    );
 
     const schema = isPayable
       ? '{"documento":"string|null","fornecedor_nome":"string|null","categoria_nome":"string|null","centro_custo_nome":"string|null","competencia":"YYYY-MM|null","vencimento":"YYYY-MM-DD|null","valor":number|null,"metodo":"boleto|pix|transferencia|cartao|dinheiro|cheque|null","descricao":"string|null","confidence":number|null}'
       : '{"documento":"string|null","cliente_nome":"string|null","categoria_nome":"string|null","centro_custo_nome":"string|null","competencia":"YYYY-MM|null","vencimento":"YYYY-MM-DD|null","valor":number|null,"canal":"boleto|pix|transferencia|cartao|null","descricao":"string|null","confidence":number|null}';
 
     const extractionMessage = isPayable
-      ? 'Extract the payable form fields from the attached file. If uncertain, return null for that field. Response must be JSON only.'
-      : 'Extract the receivable form fields from the attached file. If uncertain, return null for that field. Response must be JSON only.';
+      ? 'Extract the payable form fields from the attached file. IMPORTANT: prioritize Brazilian invoice formats (pt-BR). Monetary values may come as 1.900,00 or 1900.00. Always return numeric value in JSON (example: 1900). Prefer the field explicitly labeled as valor total / total da nota / total a pagar. Never guess; if uncertain, return null. Response must be JSON only.'
+      : 'Extract the receivable form fields from the attached file. IMPORTANT: prioritize Brazilian invoice formats (pt-BR). Monetary values may come as 1.900,00 or 1900.00. Always return numeric value in JSON (example: 1900). Prefer the field explicitly labeled as valor total / total da nota / total a receber. Never guess; if uncertain, return null. Response must be JSON only.';
 
     await this.ai.createAgent({
       slug,
       provider: 'openai',
+      model: 'gpt-4o',
       instructions:
-        `You are a financial OCR extraction assistant. Extract only ${titleType} title fields from invoice/bill files. Always return valid JSON only, no markdown. Use this schema: ${schema}.`,
+        `You are a financial OCR extraction assistant. Extract only ${titleType} title fields from invoice/bill files. Be strict with monetary values in pt-BR format: 1.900,00 means 1900.00. Never confuse punctuation separators. Prefer explicit labels in this order: "valor dos serviços" > "valor total da nota" > "valor líquido". For vencimento, use fields like "vencimento" or "data de vencimento" only; do not use data de emissão as vencimento. If confidence is low, return null. Always return valid JSON only, no markdown. Use this schema: ${schema}.`,
     });
 
     const result = await this.ai.chatWithAgent(
@@ -60,35 +74,415 @@ export class FinanceService {
     );
 
     const parsed = this.parseAiJson(result?.content || '{}');
+    this.logger.warn(
+      `[FINANCE-EXTRACT] pass1 type=${titleType} hasDocumento=${!!this.toNullableString(parsed?.documento)} hasValor=${this.toNullableNumber(parsed?.valor) !== null} hasVencimento=${!!this.normalizeDate(parsed?.vencimento)}`,
+    );
+    const mergedParsed = await this.enhanceParsedExtraction(
+      parsed,
+      slug,
+      isPayable,
+      llmAttachmentDebug,
+      fileId,
+      file,
+    );
 
-    const personName = isPayable ? parsed.fornecedor_nome : parsed.cliente_nome;
+    const personName = isPayable
+      ? mergedParsed.fornecedor_nome
+      : mergedParsed.cliente_nome;
     const personId = await this.matchPersonId(personName);
-    const categoriaId = await this.matchCategoryId(parsed.categoria_nome);
-    const centroCustoId = await this.matchCostCenterId(parsed.centro_custo_nome);
+    const categoriaId = await this.matchCategoryId(mergedParsed.categoria_nome);
+    const centroCustoId = await this.matchCostCenterId(
+      mergedParsed.centro_custo_nome,
+    );
+
+    const metodo = this.normalizePaymentMethod(
+      mergedParsed.metodo || mergedParsed.canal,
+    );
+    const documento = this.toNullableString(mergedParsed.documento);
+    const categoriaNome = this.toNullableString(mergedParsed.categoria_nome);
+    const centroCustoNome = this.toNullableString(mergedParsed.centro_custo_nome);
+    const competencia = this.normalizeMonth(mergedParsed.competencia);
+    const vencimento = this.normalizeDate(mergedParsed.vencimento);
+    const valor = this.toNullableNumber(mergedParsed.valor);
+    const descricao = this.toNullableString(mergedParsed.descricao);
+    const confidence = this.resolveExtractionConfidence(
+      this.toNullableNumber(mergedParsed.confidence),
+      {
+        documento,
+        personId,
+        categoriaId,
+        centroCustoId,
+        vencimento,
+        valor,
+      },
+    );
+    const warnings = this.buildExtractionWarnings(confidence, {
+      valor,
+      vencimento,
+    });
 
-    const metodo = this.normalizePaymentMethod(parsed.metodo || parsed.canal);
+    this.logger.warn(
+      `[FINANCE-EXTRACT] done type=${titleType} confidence=${confidence ?? 'null'} valor=${valor ?? 'null'} vencimento=${vencimento || 'null'} fallback=${mergedParsed?.__fallbackSource || 'none'}`,
+    );
 
     return {
-      documento: this.toNullableString(parsed.documento),
+      documento,
       fornecedorId: isPayable ? personId : '',
       fornecedorNome: isPayable ? this.toNullableString(personName) : null,
       clienteId: !isPayable ? personId : '',
       clienteNome: !isPayable ? this.toNullableString(personName) : null,
       categoriaId,
-      categoriaNome: this.toNullableString(parsed.categoria_nome),
+      categoriaNome,
       centroCustoId,
-      centroCustoNome: this.toNullableString(parsed.centro_custo_nome),
-      competencia: this.normalizeMonth(parsed.competencia),
-      vencimento: this.normalizeDate(parsed.vencimento),
-      valor: this.toNullableNumber(parsed.valor),
+      centroCustoNome,
+      competencia,
+      vencimento,
+      valor,
       metodo,
       canal: metodo,
-      descricao: this.toNullableString(parsed.descricao),
-      confidence: this.toNullableNumber(parsed.confidence),
-      raw: parsed,
+      descricao,
+      confidence,
+      confidenceLevel:
+        confidence === null ? null : confidence < 70 ? 'low' : 'high',
+      warnings,
+      raw: {
+        ...mergedParsed,
+        __llmAttachmentDebug: llmAttachmentDebug,
+      },
+    };
+  }
+
+  private async enhanceParsedExtraction(
+    parsed: any,
+    slug: string,
+    isPayable: boolean,
+    llmAttachmentDebug?: any,
+    fileId?: number,
+    file?: MulterFile,
+  ) {
+    const base = parsed || {};
+
+    const hasDocumento = !!this.toNullableString(base.documento);
+    const hasValor = this.toNullableNumber(base.valor) !== null;
+    const hasVencimento = !!this.normalizeDate(base.vencimento);
+    const hasPessoa = !!this.toNullableString(
+      isPayable ? base.fornecedor_nome : base.cliente_nome,
+    );
+
+    if (hasDocumento || hasValor || hasVencimento || hasPessoa) {
+      this.logger.warn('[FINANCE-EXTRACT] pass2 skipped: pass1 already has key fields');
+      return base;
+    }
+
+    const fallbackSchema = isPayable
+      ? '{"documento":"string|null","fornecedor_nome":"string|null","vencimento":"YYYY-MM-DD|null","valor":number|null,"confidence":number|null}'
+      : '{"documento":"string|null","cliente_nome":"string|null","vencimento":"YYYY-MM-DD|null","valor":number|null,"confidence":number|null}';
+
+    const fallbackMessage = isPayable
+      ? `Second pass. Extract ONLY documento, fornecedor_nome, vencimento, valor. Prefer "valor dos serviços" then "valor total" then "valor líquido". Return JSON only with this schema: ${fallbackSchema}`
+      : `Second pass. Extract ONLY documento, cliente_nome, vencimento, valor. Prefer "valor dos serviços" then "valor total" then "valor líquido". Return JSON only with this schema: ${fallbackSchema}`;
+
+    const retry = await this.ai.chatWithAgent(
+      slug,
+      {
+        message: fallbackMessage,
+        file_id: fileId,
+      },
+      file,
+    );
+
+    const retryParsed = this.parseAiJson(retry?.content || '{}');
+    this.logger.warn(
+      `[FINANCE-EXTRACT] pass2 hasDocumento=${!!this.toNullableString(retryParsed?.documento)} hasValor=${this.toNullableNumber(retryParsed?.valor) !== null} hasVencimento=${!!this.normalizeDate(retryParsed?.vencimento)}`,
+    );
+
+    const mergedAfterRetry = {
+      ...retryParsed,
+      ...base,
+      documento: this.toNullableString(base.documento)
+        ? base.documento
+        : retryParsed.documento,
+      valor:
+        this.toNullableNumber(base.valor) !== null ? base.valor : retryParsed.valor,
+      vencimento: this.normalizeDate(base.vencimento)
+        ? base.vencimento
+        : retryParsed.vencimento,
+      fornecedor_nome: isPayable
+        ? this.toNullableString(base.fornecedor_nome)
+          ? base.fornecedor_nome
+          : retryParsed.fornecedor_nome
+        : base.fornecedor_nome,
+      cliente_nome: !isPayable
+        ? this.toNullableString(base.cliente_nome)
+          ? base.cliente_nome
+          : retryParsed.cliente_nome
+        : base.cliente_nome,
+      confidence:
+        this.toNullableNumber(base.confidence) !== null
+          ? base.confidence
+          : retryParsed.confidence,
+    };
+
+    const stillEmpty =
+      !this.toNullableString(mergedAfterRetry.documento) &&
+      this.toNullableNumber(mergedAfterRetry.valor) === null &&
+      !this.normalizeDate(mergedAfterRetry.vencimento) &&
+      !this.toNullableString(
+        isPayable
+          ? mergedAfterRetry.fornecedor_nome
+          : mergedAfterRetry.cliente_nome,
+      );
+
+    if (!stillEmpty) {
+      this.logger.warn('[FINANCE-EXTRACT] regex fallback skipped: pass2 produced data');
+      return mergedAfterRetry;
+    }
+
+    const rawText = await this.ai.extractAttachmentText(file, fileId);
+    const regexFallback = this.extractFinancialFieldsFromRawText(rawText, isPayable);
+    this.logger.warn(
+      `[FINANCE-EXTRACT] regex fallback activated hasText=${!!rawText} hasDocumento=${!!this.toNullableString(regexFallback?.documento)} hasValor=${this.toNullableNumber(regexFallback?.valor) !== null} hasVencimento=${!!this.normalizeDate(regexFallback?.vencimento)}`,
+    );
+
+    const stillEmptyAfterRegex =
+      !this.toNullableString(regexFallback.documento) &&
+      this.toNullableNumber(regexFallback.valor) === null &&
+      !this.normalizeDate(regexFallback.vencimento);
+
+    if (
+      stillEmptyAfterRegex &&
+      llmAttachmentDebug?.mode === 'pdf-text' &&
+      Number(llmAttachmentDebug?.textLength || 0) === 0
+    ) {
+      this.logger.warn(
+        '[FINANCE-EXTRACT] gemini fallback activated for scanned PDF (no text layer)',
+      );
+
+      const geminiSchema = isPayable
+        ? '{"documento":"string|null","fornecedor_nome":"string|null","vencimento":"YYYY-MM-DD|null","valor":number|null,"confidence":number|null}'
+        : '{"documento":"string|null","cliente_nome":"string|null","vencimento":"YYYY-MM-DD|null","valor":number|null,"confidence":number|null}';
+
+      const geminiPrompt = isPayable
+        ? `Extract documento, fornecedor_nome, vencimento and valor from this invoice PDF. For valor, prefer 'valor dos serviços', then 'valor total', then 'valor líquido'. Return JSON only using schema: ${geminiSchema}`
+        : `Extract documento, cliente_nome, vencimento and valor from this invoice PDF. For valor, prefer 'valor dos serviços', then 'valor total', then 'valor líquido'. Return JSON only using schema: ${geminiSchema}`;
+
+      const geminiModels = [
+        'gemini-2.5-flash',
+        'gemini-2.5-pro',
+        'gemini-2.0-flash',
+        'gemini-2.0-flash-lite',
+        'gemini-1.5-flash',
+        'gemini-1.5-pro',
+        'gemini-1.5-flash-latest',
+        'gemini-1.5-pro-latest',
+      ];
+
+      for (const model of geminiModels) {
+        try {
+          this.logger.warn(
+            `[FINANCE-EXTRACT] gemini fallback trying model=${model}`,
+          );
+
+          const geminiResult = await this.ai.chat(
+            {
+              provider: 'gemini',
+              model,
+              message: geminiPrompt,
+              file_id: fileId,
+            },
+            file,
+          );
+
+          const geminiParsed = this.parseAiJson(geminiResult?.content || '{}');
+          this.logger.warn(
+            `[FINANCE-EXTRACT] gemini fallback result model=${model} hasDocumento=${!!this.toNullableString(geminiParsed?.documento)} hasValor=${this.toNullableNumber(geminiParsed?.valor) !== null} hasVencimento=${!!this.normalizeDate(geminiParsed?.vencimento)}`,
+          );
+
+          return {
+            ...geminiParsed,
+            ...regexFallback,
+            documento: this.toNullableString(geminiParsed?.documento)
+              ? geminiParsed.documento
+              : regexFallback.documento,
+            valor:
+              this.toNullableNumber(geminiParsed?.valor) !== null
+                ? geminiParsed.valor
+                : regexFallback.valor,
+            vencimento: this.normalizeDate(geminiParsed?.vencimento)
+              ? geminiParsed.vencimento
+              : regexFallback.vencimento,
+            competencia: this.normalizeMonth(geminiParsed?.competencia)
+              ? geminiParsed.competencia
+              : regexFallback.competencia,
+            fornecedor_nome: isPayable
+              ? this.toNullableString(geminiParsed?.fornecedor_nome)
+                ? geminiParsed.fornecedor_nome
+                : regexFallback.fornecedor_nome
+              : null,
+            cliente_nome: !isPayable
+              ? this.toNullableString(geminiParsed?.cliente_nome)
+                ? geminiParsed.cliente_nome
+                : regexFallback.cliente_nome
+              : null,
+            confidence:
+              this.toNullableNumber(geminiParsed?.confidence) ?? regexFallback.confidence,
+            __fallbackSource: 'gemini-pdf-binary',
+            __fallbackModel: model,
+            __fallbackHasText: !!rawText,
+          };
+        } catch (error) {
+          const statusCode = (error as any)?.response?.status;
+          const message = (error as any)?.message || 'unknown error';
+          const apiError =
+            (error as any)?.response?.data?.error?.message ||
+            JSON.stringify((error as any)?.response?.data || {});
+          this.logger.warn(
+            `[FINANCE-EXTRACT] gemini fallback failed model=${model} status=${statusCode ?? 'n/a'} message=${message} apiError=${apiError}`,
+          );
+        }
+      }
+    }
+
+    return {
+      ...regexFallback,
+      ...mergedAfterRetry,
+      documento: this.toNullableString(mergedAfterRetry.documento)
+        ? mergedAfterRetry.documento
+        : regexFallback.documento,
+      valor:
+        this.toNullableNumber(mergedAfterRetry.valor) !== null
+          ? mergedAfterRetry.valor
+          : regexFallback.valor,
+      vencimento: this.normalizeDate(mergedAfterRetry.vencimento)
+        ? mergedAfterRetry.vencimento
+        : regexFallback.vencimento,
+      competencia: this.normalizeMonth(mergedAfterRetry.competencia)
+        ? mergedAfterRetry.competencia
+        : regexFallback.competencia,
+      fornecedor_nome: isPayable
+        ? this.toNullableString(mergedAfterRetry.fornecedor_nome)
+          ? mergedAfterRetry.fornecedor_nome
+          : regexFallback.fornecedor_nome
+        : mergedAfterRetry.fornecedor_nome,
+      cliente_nome: !isPayable
+        ? this.toNullableString(mergedAfterRetry.cliente_nome)
+          ? mergedAfterRetry.cliente_nome
+          : regexFallback.cliente_nome
+        : mergedAfterRetry.cliente_nome,
+      __fallbackSource: 'regex-pdf-text',
+      __fallbackHasText: !!rawText,
     };
   }
 
+  private extractFinancialFieldsFromRawText(text: string, isPayable: boolean) {
+    const source = text || '';
+
+    const documento =
+      this.firstMatch(
+        source,
+        [
+          /\b(?:n[úu]mero\s+da\s+nota|nota\s+fiscal|nfs-?e|nf-?e|nf)\s*[:#-]?\s*([a-z0-9._\/-]{4,})/i,
+        ],
+      ) || null;
+
+    const emissao = this.firstMatch(source, [
+      /\b(?:data\s+de\s+emiss[aã]o|emiss[aã]o)\s*[:#-]?\s*(\d{2}\/\d{2}\/\d{4})/i,
+    ]);
+
+    const vencimento = this.firstMatch(source, [
+      /\b(?:data\s+de\s+vencimento|vencimento)\s*[:#-]?\s*(\d{2}\/\d{2}\/\d{4})/i,
+    ]);
+
+    const valorLabeled = this.firstMatch(source, [
+      /\bvalor\s+dos\s+servi[cç]os\b[^\d]{0,20}(?:r\$\s*)?([\d.,]+)/i,
+      /\bvalor\s+total\b[^\d]{0,20}(?:r\$\s*)?([\d.,]+)/i,
+      /\btotal\s+da\s+nota\b[^\d]{0,20}(?:r\$\s*)?([\d.,]+)/i,
+      /\bvalor\s+l[ií]quido\b[^\d]{0,20}(?:r\$\s*)?([\d.,]+)/i,
+    ]);
+
+    const fallbackAnyMoney = this.firstMatch(source, [
+      /(?:r\$\s*)([\d]{1,3}(?:\.[\d]{3})*,\d{2})/i,
+    ]);
+
+    const valor = this.toNullableNumber(valorLabeled || fallbackAnyMoney);
+
+    const personName = this.firstMatch(source, [
+      /\b(?:tomador|cliente|fornecedor|prestador)\b\s*[:#-]?\s*([^\n\r]{3,80})/i,
+    ]);
+
+    return {
+      documento,
+      fornecedor_nome: isPayable ? this.toNullableString(personName) : null,
+      cliente_nome: !isPayable ? this.toNullableString(personName) : null,
+      competencia: emissao ? this.normalizeMonth(emissao) : null,
+      vencimento: vencimento ? this.normalizeDate(vencimento) : null,
+      valor,
+      confidence: valor !== null ? 68 : 52,
+    };
+  }
+
+  private firstMatch(text: string, patterns: RegExp[]): string {
+    for (const pattern of patterns) {
+      const match = text.match(pattern);
+      if (match?.[1]) {
+        return match[1].trim();
+      }
+    }
+
+    return '';
+  }
+
+  private resolveExtractionConfidence(
+    aiConfidence: number | null,
+    data: {
+      documento: string | null;
+      personId: string;
+      categoriaId: string;
+      centroCustoId: string;
+      vencimento: string;
+      valor: number | null;
+    },
+  ): number | null {
+    if (aiConfidence !== null) {
+      const normalized = aiConfidence <= 1 ? aiConfidence * 100 : aiConfidence;
+      return Math.max(0, Math.min(100, Math.round(normalized)));
+    }
+
+    let score = 35;
+    if (data.documento) score += 15;
+    if (data.vencimento) score += 10;
+    if (data.valor !== null && data.valor > 0) score += 20;
+    if (data.personId) score += 10;
+    if (data.categoriaId) score += 5;
+    if (data.centroCustoId) score += 5;
+
+    return Math.max(0, Math.min(100, score));
+  }
+
+  private buildExtractionWarnings(
+    confidence: number | null,
+    data: {
+      valor: number | null;
+      vencimento: string;
+    },
+  ): string[] {
+    const warnings: string[] = [];
+
+    if (confidence !== null && confidence < 70) {
+      warnings.push('Baixa confiança na extração. Revise os campos antes de salvar.');
+    }
+
+    if (data.valor === null || data.valor <= 0) {
+      warnings.push('Valor não identificado com segurança no documento.');
+    }
+
+    if (!data.vencimento) {
+      warnings.push('Data de vencimento não identificada com segurança.');
+    }
+
+    return warnings;
+  }
+
   private parseAiJson(content: string): any {
     const trimmed = (content || '').trim();
     if (!trimmed) {
@@ -263,7 +657,41 @@ export class FinanceService {
 
   private toNullableNumber(value: any): number | null {
     if (value === null || value === undefined || value === '') return null;
-    const num = Number(value);
+    if (typeof value === 'number') {
+      return Number.isFinite(value) ? value : null;
+    }
+
+    const raw = String(value).trim();
+    if (!raw) return null;
+
+    const cleaned = raw.replace(/[^\d,.-]/g, '');
+    if (!cleaned) return null;
+
+    const lastComma = cleaned.lastIndexOf(',');
+    const lastDot = cleaned.lastIndexOf('.');
+
+    let normalized = cleaned;
+
+    if (lastComma >= 0 && lastDot >= 0) {
+      if (lastComma > lastDot) {
+        normalized = cleaned.replace(/\./g, '').replace(',', '.');
+      } else {
+        normalized = cleaned.replace(/,/g, '');
+      }
+    } else if (lastComma >= 0) {
+      normalized = cleaned.replace(/\./g, '').replace(',', '.');
+    } else {
+      const dotParts = cleaned.split('.');
+      if (
+        dotParts.length > 1 &&
+        dotParts[dotParts.length - 1].length === 3 &&
+        dotParts.length <= 4
+      ) {
+        normalized = cleaned.replace(/\./g, '');
+      }
+    }
+
+    const num = Number(normalized);
     return Number.isFinite(num) ? num : null;
   }
 
@@ -375,6 +803,221 @@ export class FinanceService {
     return bankAccounts.map((bankAccount) => this.mapBankAccountToFront(bankAccount));
   }
 
+  async listCostCenters() {
+    const costCenters = await this.prisma.cost_center.findMany({
+      orderBy: [{ code: 'asc' }, { name: 'asc' }],
+    });
+
+    return costCenters.map((costCenter) => this.mapCostCenterToFront(costCenter));
+  }
+
+  async listAuditLogs(
+    paginationParams,
+    filters?: {
+      search?: string;
+      action?: string;
+      entity_table?: string;
+      actor_user_id?: string;
+      from?: string;
+      to?: string;
+    },
+  ) {
+    const actorUserId = filters?.actor_user_id
+      ? Number.parseInt(filters.actor_user_id, 10)
+      : undefined;
+
+    const fromDate = filters?.from ? new Date(filters.from) : undefined;
+    const toDate = filters?.to ? new Date(filters.to) : undefined;
+
+    const where: any = {
+      ...(filters?.action ? { action: filters.action } : {}),
+      ...(filters?.entity_table ? { entity_table: filters.entity_table } : {}),
+      ...(Number.isNaN(actorUserId) || !actorUserId
+        ? {}
+        : { actor_user_id: actorUserId }),
+      ...((fromDate || toDate) &&
+      !(fromDate && Number.isNaN(fromDate.getTime())) &&
+      !(toDate && Number.isNaN(toDate.getTime()))
+        ? {
+            created_at: {
+              ...(fromDate ? { gte: fromDate } : {}),
+              ...(toDate ? { lte: toDate } : {}),
+            },
+          }
+        : {}),
+    };
+
+    const search = filters?.search?.trim();
+    if (search) {
+      where.OR = [
+        { action: { contains: search, mode: 'insensitive' } },
+        { entity_table: { contains: search, mode: 'insensitive' } },
+        { entity_id: { contains: search, mode: 'insensitive' } },
+        { summary: { contains: search, mode: 'insensitive' } },
+        { ip_address: { contains: search, mode: 'insensitive' } },
+      ];
+    }
+
+    const paginated = await this.paginationService.paginatePrismaModel(
+      this.prisma.audit_log,
+      {
+        page: paginationParams?.page,
+        pageSize: paginationParams?.pageSize,
+        sortField: paginationParams?.sortField || 'created_at',
+        sortOrder: paginationParams?.sortOrder || 'desc',
+        validSortFields: [
+          'id',
+          'created_at',
+          'action',
+          'entity_table',
+          'entity_id',
+        ],
+        where,
+        include: {
+          user: {
+            select: {
+              id: true,
+              name: true,
+            },
+          },
+        },
+      },
+    );
+
+    return {
+      ...paginated,
+      data: (paginated.data || []).map((log) => ({
+        id: String(log.id),
+        actorUserId: log.actor_user_id ? String(log.actor_user_id) : null,
+        actorName: log.user?.name || '-',
+        actorEmail: '',
+        action: log.action,
+        entityTable: log.entity_table,
+        entityId: log.entity_id,
+        summary: log.summary || '',
+        ipAddress: log.ip_address || '',
+        beforeData: log.before_data || '',
+        afterData: log.after_data || '',
+        createdAt: log.created_at?.toISOString?.() || null,
+      })),
+    };
+  }
+
+  async listFinanceCategories() {
+    const categories = await this.prisma.finance_category.findMany({
+      orderBy: [{ parent_id: 'asc' }, { updated_at: 'asc' }, { name: 'asc' }],
+    });
+
+    return categories.map((category) => this.mapFinanceCategoryToFront(category));
+  }
+
+  async listPeriodClose(
+    paginationParams: PaginationDTO,
+    filters?: {
+      search?: string;
+      status?: string;
+      user?: string;
+      from?: string;
+      to?: string;
+    },
+  ) {
+    const fromDate = filters?.from ? new Date(filters.from) : undefined;
+    const toDate = filters?.to ? new Date(filters.to) : undefined;
+    const userNumericId = filters?.user
+      ? Number.parseInt(filters.user, 10)
+      : undefined;
+
+    const andConditions: any[] = [];
+
+    if (filters?.status && filters.status !== 'all') {
+      andConditions.push({ status: filters.status });
+    }
+
+    if (
+      (fromDate && !Number.isNaN(fromDate.getTime())) ||
+      (toDate && !Number.isNaN(toDate.getTime()))
+    ) {
+      andConditions.push({
+        period_start: {
+          ...(fromDate && !Number.isNaN(fromDate.getTime())
+            ? { gte: fromDate }
+            : {}),
+        },
+      });
+
+      andConditions.push({
+        period_end: {
+          ...(toDate && !Number.isNaN(toDate.getTime()) ? { lte: toDate } : {}),
+        },
+      });
+    }
+
+    const search = filters?.search?.trim();
+    if (search) {
+      andConditions.push({
+        OR: [
+          { notes: { contains: search, mode: 'insensitive' } },
+          { user: { is: { name: { contains: search, mode: 'insensitive' } } } },
+          {
+            user: { is: { email: { contains: search, mode: 'insensitive' } } },
+          },
+        ],
+      });
+    }
+
+    if (filters?.user?.trim()) {
+      andConditions.push({
+        OR: [
+          ...(Number.isNaN(userNumericId) || !userNumericId
+            ? []
+            : [{ closed_by_user_id: userNumericId }]),
+          { user: { is: { name: { contains: filters.user, mode: 'insensitive' } } } },
+          {
+            user: {
+              is: { email: { contains: filters.user, mode: 'insensitive' } },
+            },
+          },
+        ],
+      });
+    }
+
+    const where = andConditions.length > 0 ? { AND: andConditions } : {};
+
+    const paginated = await this.paginationService.paginatePrismaModel(
+      this.prisma.period_close,
+      {
+        page: paginationParams?.page,
+        pageSize: paginationParams?.pageSize,
+        sortField: paginationParams?.sortField || 'period_start',
+        sortOrder: paginationParams?.sortOrder || 'desc',
+        validSortFields: [
+          'id',
+          'period_start',
+          'period_end',
+          'status',
+          'closed_at',
+          'created_at',
+        ],
+        where,
+        include: {
+          user: {
+            select: {
+              id: true,
+              name: true,
+            },
+          },
+        },
+      },
+    );
+
+    return {
+      ...paginated,
+      data: (paginated.data || []).map((period) =>
+        this.mapPeriodCloseToFront(period),
+      ),
+    };
+  }
+
   async listBankStatements(bankAccountId?: number) {
     const statements = await this.prisma.bank_statement_line.findMany({
       where: {
@@ -457,6 +1100,89 @@ export class FinanceService {
     return this.mapBankAccountToFront(account);
   }
 
+  async createCostCenter(data: CreateCostCenterDto) {
+    const code = await this.generateCostCenterCode(data.name);
+
+    const created = await this.prisma.cost_center.create({
+      data: {
+        code,
+        name: data.name.trim(),
+        status: 'active',
+      },
+    });
+
+    return this.mapCostCenterToFront(created);
+  }
+
+  async createFinanceCategory(data: CreateFinanceCategoryDto) {
+    if (data.parent_id) {
+      await this.ensureFinanceCategoryExists(data.parent_id);
+    }
+
+    const created = await this.prisma.finance_category.create({
+      data: {
+        code: await this.generateFinanceCategoryCode(),
+        name: data.name.trim(),
+        kind: this.mapCategoryKindFromPt(data.kind),
+        status: 'active',
+        parent_id: data.parent_id || null,
+      },
+    });
+
+    return this.mapFinanceCategoryToFront(created);
+  }
+
+  async createPeriodClose(data: CreatePeriodCloseDto, userId?: number) {
+    const periodStart = new Date(data.period_start);
+    const periodEnd = new Date(data.period_end);
+
+    if (
+      Number.isNaN(periodStart.getTime()) ||
+      Number.isNaN(periodEnd.getTime())
+    ) {
+      throw new BadRequestException('Invalid period dates');
+    }
+
+    if (periodStart > periodEnd) {
+      throw new BadRequestException('period_start must be before period_end');
+    }
+
+    const overlapped = await this.prisma.period_close.findFirst({
+      where: {
+        period_start: { lte: periodEnd },
+        period_end: { gte: periodStart },
+      },
+      select: { id: true },
+    });
+
+    if (overlapped) {
+      throw new BadRequestException('There is already a period in this range');
+    }
+
+    const status = data.status || 'closed';
+
+    const created = await this.prisma.period_close.create({
+      data: {
+        period_start: periodStart,
+        period_end: periodEnd,
+        status,
+        closed_at: status === 'closed' ? new Date() : null,
+        closed_by_user_id: status === 'closed' ? userId || null : null,
+        notes: data.notes?.trim() || null,
+      },
+      include: {
+        user: {
+          select: {
+            id: true,
+            name: true,
+          },
+        },
+      },
+    });
+
+    return this.mapPeriodCloseToFront(created);
+  }
+
   async updateBankAccount(id: number, data: UpdateBankAccountDto) {
     const current = await this.prisma.bank_account.findUnique({
       where: { id },
@@ -490,6 +1216,104 @@ export class FinanceService {
     return this.mapBankAccountToFront(updated);
   }
 
+  async updateCostCenter(id: number, data: UpdateCostCenterDto) {
+    const current = await this.prisma.cost_center.findUnique({
+      where: { id },
+      select: { id: true },
+    });
+
+    if (!current) {
+      throw new NotFoundException('Cost center not found');
+    }
+
+    const updated = await this.prisma.cost_center.update({
+      where: { id },
+      data: {
+        name: data.name?.trim(),
+        status: data.status,
+      },
+    });
+
+    return this.mapCostCenterToFront(updated);
+  }
+
+  async updateFinanceCategory(id: number, data: UpdateFinanceCategoryDto) {
+    const current = await this.prisma.finance_category.findUnique({
+      where: { id },
+      select: { id: true },
+    });
+
+    if (!current) {
+      throw new NotFoundException('Finance category not found');
+    }
+
+    if (data.parent_id) {
+      await this.ensureFinanceCategoryExists(data.parent_id);
+      await this.ensureNoFinanceCategoryCycle(id, data.parent_id);
+    }
+
+    const updated = await this.prisma.finance_category.update({
+      where: { id },
+      data: {
+        name: data.name?.trim(),
+        kind: data.kind ? this.mapCategoryKindFromPt(data.kind) : undefined,
+        parent_id: data.parent_id,
+        status: data.status,
+      },
+    });
+
+    return this.mapFinanceCategoryToFront(updated);
+  }
+
+  async moveFinanceCategory(id: number, data: MoveFinanceCategoryDto) {
+    const current = await this.prisma.finance_category.findUnique({
+      where: { id },
+      select: { id: true, parent_id: true },
+    });
+
+    if (!current) {
+      throw new NotFoundException('Finance category not found');
+    }
+
+    const targetParentId = data.parent_id || null;
+
+    if (targetParentId) {
+      await this.ensureFinanceCategoryExists(targetParentId);
+      await this.ensureNoFinanceCategoryCycle(id, targetParentId);
+    }
+
+    await this.prisma.finance_category.update({
+      where: { id },
+      data: { parent_id: targetParentId },
+    });
+
+    const siblings = await this.prisma.finance_category.findMany({
+      where: { parent_id: targetParentId },
+      select: { id: true },
+      orderBy: [{ updated_at: 'asc' }, { name: 'asc' }],
+    });
+
+    const siblingIds = siblings.map((item) => item.id).filter((item) => item !== id);
+    const targetPosition = Math.max(
+      0,
+      Math.min(data.position ?? siblingIds.length, siblingIds.length),
+    );
+    siblingIds.splice(targetPosition, 0, id);
+
+    await this.prisma.$transaction(
+      siblingIds.map((categoryId) =>
+        this.prisma.finance_category.update({
+          where: { id: categoryId },
+          data: {
+            parent_id: targetParentId,
+          },
+        }),
+      ),
+    );
+
+    return { success: true };
+  }
+
   async deleteBankAccount(id: number) {
     const current = await this.prisma.bank_account.findUnique({
       where: { id },
@@ -510,6 +1334,46 @@ export class FinanceService {
     return { success: true };
   }
 
+  async deleteCostCenter(id: number) {
+    const current = await this.prisma.cost_center.findUnique({
+      where: { id },
+      select: { id: true },
+    });
+
+    if (!current) {
+      throw new NotFoundException('Cost center not found');
+    }
+
+    await this.prisma.cost_center.update({
+      where: { id },
+      data: {
+        status: 'inactive',
+      },
+    });
+
+    return { success: true };
+  }
+
+  async deleteFinanceCategory(id: number) {
+    const current = await this.prisma.finance_category.findUnique({
+      where: { id },
+      select: { id: true },
+    });
+
+    if (!current) {
+      throw new NotFoundException('Finance category not found');
+    }
+
+    await this.prisma.finance_category.update({
+      where: { id },
+      data: {
+        status: 'inactive',
+      },
+    });
+
+    return { success: true };
+  }
+
   private async listTitles(
     titleType: TitleType,
     paginationParams: PaginationDTO,
@@ -674,14 +1538,6 @@ export class FinanceService {
 
   private async loadPeople() {
     const people = await this.prisma.person.findMany({
-      include: {
-        document: {
-          select: {
-            value: true,
-          },
-          take: 1,
-        },
-      },
       orderBy: { name: 'asc' },
     });
 
@@ -689,7 +1545,7 @@ export class FinanceService {
       id: String(person.id),
       nome: person.name,
       tipo: 'ambos',
-      documento: person.document[0]?.value || '',
+      documento: '',
     }));
   }
 
@@ -972,6 +1828,76 @@ export class FinanceService {
     };
   }
 
+  private mapCostCenterToFront(costCenter: any) {
+    return {
+      id: String(costCenter.id),
+      codigo: costCenter.code,
+      nome: costCenter.name,
+      status: costCenter.status,
+      ativo: costCenter.status === 'active',
+    };
+  }
+
+  private mapCategoryKindToPt(kind?: string | null) {
+    const kindMap = {
+      revenue: 'receita',
+      expense: 'despesa',
+      transfer: 'transferencia',
+      adjustment: 'ajuste',
+      other: 'outro',
+    };
+
+    return kindMap[kind] || 'outro';
+  }
+
+  private mapCategoryKindFromPt(kind?: string | null) {
+    const normalized = (kind || '').toLowerCase();
+    const kindMap = {
+      receita: 'revenue',
+      revenue: 'revenue',
+      despesa: 'expense',
+      expense: 'expense',
+      transferencia: 'transfer',
+      transferência: 'transfer',
+      transfer: 'transfer',
+      ajuste: 'adjustment',
+      adjustment: 'adjustment',
+      outro: 'other',
+      other: 'other',
+    };
+
+    return kindMap[normalized] || 'other';
+  }
+
+  private mapFinanceCategoryToFront(category: any) {
+    return {
+      id: String(category.id),
+      codigo: category.code,
+      nome: category.name,
+      parentId: category.parent_id ? String(category.parent_id) : null,
+      natureza: this.mapCategoryKindToPt(category.kind),
+      status: category.status,
+      ativo: category.status === 'active',
+    };
+  }
+
+  private mapPeriodCloseToFront(period: any) {
+    return {
+      id: String(period.id),
+      periodStart: period.period_start?.toISOString?.() || null,
+      periodEnd: period.period_end?.toISOString?.() || null,
+      status: period.status,
+      closedAt: period.closed_at?.toISOString?.() || null,
+      closedByUserId: period.closed_by_user_id
+        ? String(period.closed_by_user_id)
+        : null,
+      closedByName: period.user?.name || '-',
+      closedByEmail: '',
+      notes: period.notes || '',
+      createdAt: period.created_at?.toISOString?.() || null,
+    };
+  }
+
   private mapStatementStatusToPt(status?: string | null) {
     const statusMap = {
       pending: 'pendente',
@@ -997,6 +1923,71 @@ export class FinanceService {
     return `${bankPrefix || 'ACC'}-${accountSuffix}`;
   }
 
+  private async generateCostCenterCode(name?: string) {
+    const sanitizedName = (name || 'CENTRO')
+      .trim()
+      .replace(/\s+/g, '-')
+      .replace(/[^A-Za-z0-9-]/g, '')
+      .toUpperCase();
+
+    const basePrefix = sanitizedName.slice(0, 8) || 'CENTRO';
+
+    const lastCostCenter = await this.prisma.cost_center.findFirst({
+      orderBy: { id: 'desc' },
+      select: { id: true },
+    });
+
+    const suffix = String((lastCostCenter?.id || 0) + 1).padStart(4, '0');
+
+    return `${basePrefix}-${suffix}`;
+  }
+
+  private async generateFinanceCategoryCode() {
+    const lastCategory = await this.prisma.finance_category.findFirst({
+      orderBy: { id: 'desc' },
+      select: { id: true },
+    });
+
+    const suffix = String((lastCategory?.id || 0) + 1).padStart(4, '0');
+
+    return `CAT-${suffix}`;
+  }
+
+  private async ensureFinanceCategoryExists(id: number) {
+    const category = await this.prisma.finance_category.findUnique({
+      where: { id },
+      select: { id: true },
+    });
+
+    if (!category) {
+      throw new NotFoundException('Finance category not found');
+    }
+  }
+
+  private async ensureNoFinanceCategoryCycle(
+    categoryId: number,
+    targetParentId: number,
+  ) {
+    if (categoryId === targetParentId) {
+      throw new BadRequestException('Category cannot be parent of itself');
+    }
+
+    let currentParentId: number | null = targetParentId;
+
+    while (currentParentId) {
+      if (currentParentId === categoryId) {
+        throw new BadRequestException('Invalid parent category hierarchy');
+      }
+
+      const parent = await this.prisma.finance_category.findUnique({
+        where: { id: currentParentId },
+        select: { parent_id: true },
+      });
+
+      currentParentId = parent?.parent_id || null;
+    }
+  }
+
   private toCents(value: number) {
     return Math.round(value * 100);
   }