@hed-hog/finance 0.0.237 → 0.0.239

package/src/finance.service.ts

@@ -6,19 +6,37 @@ import {
     BadRequestException,
     Injectable,
     Logger,
-    NotFoundException
+    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 { CreateFinanceTagDto } from './dto/create-finance-tag.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 { RejectTitleDto } from './dto/reject-title.dto';
+import { ReverseSettlementDto } from './dto/reverse-settlement.dto';
+import { SettleInstallmentDto } from './dto/settle-installment.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';
+type InstallmentStatus =
+  | 'open'
+  | 'partial'
+  | 'settled'
+  | 'canceled'
+  | 'overdue';
+type TitleStatus =
+  | 'draft'
+  | 'approved'
+  | 'open'
+  | 'partial'
+  | 'settled'
+  | 'canceled'
+  | 'overdue';
 
 @Injectable()
 export class FinanceService {
@@ -697,15 +715,15 @@ export class FinanceService {
 
   async getData() {
     const [
-      payables,
-      receivables,
-      people,
-      categories,
-      costCenters,
-      bankAccounts,
-      tags,
-      auditLogs,
-    ] = await Promise.all([
+      payablesResult,
+      receivablesResult,
+      peopleResult,
+      categoriesResult,
+      costCentersResult,
+      bankAccountsResult,
+      tagsResult,
+      auditLogsResult,
+    ] = await Promise.allSettled([
       this.loadTitles('payable'),
       this.loadTitles('receivable'),
       this.loadPeople(),
@@ -716,6 +734,57 @@ export class FinanceService {
       this.loadAuditLogs(),
     ]);
 
+    const payables = payablesResult.status === 'fulfilled' ? payablesResult.value : [];
+    const receivables =
+      receivablesResult.status === 'fulfilled' ? receivablesResult.value : [];
+    const people = peopleResult.status === 'fulfilled' ? peopleResult.value : [];
+    const categories =
+      categoriesResult.status === 'fulfilled' ? categoriesResult.value : [];
+    const costCenters =
+      costCentersResult.status === 'fulfilled' ? costCentersResult.value : [];
+    const bankAccounts =
+      bankAccountsResult.status === 'fulfilled' ? bankAccountsResult.value : [];
+    const tags = tagsResult.status === 'fulfilled' ? tagsResult.value : [];
+    const auditLogs =
+      auditLogsResult.status === 'fulfilled' ? auditLogsResult.value : [];
+
+    if (payablesResult.status === 'rejected') {
+      this.logger.error('Failed to load finance payables', payablesResult.reason);
+    }
+    if (receivablesResult.status === 'rejected') {
+      this.logger.error('Failed to load finance receivables', receivablesResult.reason);
+    }
+    if (peopleResult.status === 'rejected') {
+      this.logger.error('Failed to load finance people', peopleResult.reason);
+    }
+    if (categoriesResult.status === 'rejected') {
+      this.logger.error('Failed to load finance categories', categoriesResult.reason);
+    }
+    if (costCentersResult.status === 'rejected') {
+      this.logger.error('Failed to load finance cost centers', costCentersResult.reason);
+    }
+    if (bankAccountsResult.status === 'rejected') {
+      this.logger.error('Failed to load finance bank accounts', bankAccountsResult.reason);
+    }
+    if (tagsResult.status === 'rejected') {
+      this.logger.error('Failed to load finance tags', tagsResult.reason);
+    }
+    if (auditLogsResult.status === 'rejected') {
+      this.logger.error('Failed to load finance audit logs', auditLogsResult.reason);
+    }
+
+    const aprovacoesPendentes = payables
+      .filter((title: any) => title.status === 'rascunho')
+      .map((title: any) => ({
+        id: String(title.id),
+        tituloId: String(title.id),
+        solicitante: '-',
+        valor: Number(title.valorTotal || 0),
+        politica: 'Aprovação financeira',
+        urgencia: 'media',
+        dataSolicitacao: title.criadoEm,
+      }));
+
     return {
       kpis: {
         saldoCaixa: 0,
@@ -733,7 +802,7 @@ export class FinanceService {
       pessoas: people,
       categorias: categories,
       centrosCusto: costCenters,
-      aprovacoesPendentes: [],
+      aprovacoesPendentes,
       agingInadimplencia: [],
       cenarios: [],
       transferencias: [],
@@ -779,6 +848,45 @@ export class FinanceService {
     return this.createTitle(data, 'payable', locale, userId);
   }
 
+  async approveAccountsPayableTitle(id: number, locale: string, userId?: number) {
+    return this.approveTitle(id, 'payable', locale, userId);
+  }
+
+  async rejectAccountsPayableTitle(
+    id: number,
+    data: RejectTitleDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.rejectTitle(id, data, 'payable', locale, userId);
+  }
+
+  async settleAccountsPayableInstallment(
+    id: number,
+    data: SettleInstallmentDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.settleTitleInstallment(id, data, 'payable', locale, userId);
+  }
+
+  async reverseAccountsPayableSettlement(
+    id: number,
+    settlementId: number,
+    data: ReverseSettlementDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.reverseTitleSettlement(
+      id,
+      settlementId,
+      data,
+      'payable',
+      locale,
+      userId,
+    );
+  }
+
   async createAccountsReceivableTitle(
     data: CreateFinancialTitleDto,
     locale: string,
@@ -787,6 +895,102 @@ export class FinanceService {
     return this.createTitle(data, 'receivable', locale, userId);
   }
 
+  async approveAccountsReceivableTitle(
+    id: number,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.approveTitle(id, 'receivable', locale, userId);
+  }
+
+  async settleAccountsReceivableInstallment(
+    id: number,
+    data: SettleInstallmentDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.settleTitleInstallment(id, data, 'receivable', locale, userId);
+  }
+
+  async reverseAccountsReceivableSettlement(
+    id: number,
+    settlementId: number,
+    data: ReverseSettlementDto,
+    locale: string,
+    userId?: number,
+  ) {
+    return this.reverseTitleSettlement(
+      id,
+      settlementId,
+      data,
+      'receivable',
+      locale,
+      userId,
+    );
+  }
+
+  async createTag(data: CreateFinanceTagDto) {
+    const slug = this.normalizeTagSlug(data.name);
+
+    if (!slug) {
+      throw new BadRequestException('Tag name is required');
+    }
+
+    const existingTag = await this.prisma.tag.findFirst({
+      where: {
+        slug,
+      },
+      select: {
+        id: true,
+        slug: true,
+        color: true,
+      },
+    });
+
+    if (existingTag) {
+      return {
+        id: String(existingTag.id),
+        nome: existingTag.slug,
+        cor: existingTag.color,
+      };
+    }
+
+    const createdTag = await this.prisma.tag.create({
+      data: {
+        slug,
+        color: data.color || '#000000',
+        status: 'active',
+      },
+      select: {
+        id: true,
+        slug: true,
+        color: true,
+      },
+    });
+
+    return {
+      id: String(createdTag.id),
+      nome: createdTag.slug,
+      cor: createdTag.color,
+    };
+  }
+
+  async updateAccountsPayableInstallmentTags(
+    id: number,
+    tagIds: number[],
+    locale: string,
+  ) {
+    return this.updateTitleTags(id, 'payable', tagIds, locale);
+  }
+
+  async updateAccountsReceivableInstallmentTags(
+    id: number,
+    tagIds: number[],
+    locale: string,
+  ) {
+    return this.updateTitleTags(id, 'receivable', tagIds, locale);
+  }
+
   async listBankAccounts() {
     const bankAccounts = await this.prisma.bank_account.findMany({
       include: {
@@ -1427,197 +1631,924 @@ export class FinanceService {
     locale: string,
     userId?: number,
   ) {
-    const person = await this.prisma.person.findUnique({
-      where: { id: data.person_id },
-      select: { id: true },
-    });
-
-    if (!person) {
-      throw new BadRequestException(
-        getLocaleText('personNotFound', locale, 'Person not found'),
-      );
-    }
+    const installments = this.normalizeAndValidateInstallments(data, locale);
 
-    if (data.finance_category_id) {
-      const category = await this.prisma.finance_category.findUnique({
-        where: { id: data.finance_category_id },
+    const createdTitleId = await this.prisma.$transaction(async (tx) => {
+      const person = await tx.person.findUnique({
+        where: { id: data.person_id },
         select: { id: true },
       });
 
-      if (!category) {
+      if (!person) {
         throw new BadRequestException(
-          getLocaleText('categoryNotFound', locale, 'Category not found'),
+          getLocaleText('personNotFound', locale, 'Person not found'),
         );
       }
-    }
 
-    if (data.cost_center_id) {
-      const costCenter = await this.prisma.cost_center.findUnique({
-        where: { id: data.cost_center_id },
-        select: { id: true },
-      });
+      if (data.finance_category_id) {
+        const category = await tx.finance_category.findUnique({
+          where: { id: data.finance_category_id },
+          select: { id: true },
+        });
 
-      if (!costCenter) {
-        throw new BadRequestException(
-          getLocaleText('costCenterNotFound', locale, 'Cost center not found'),
-        );
+        if (!category) {
+          throw new BadRequestException(
+            getLocaleText('categoryNotFound', locale, 'Category not found'),
+          );
+        }
       }
-    }
 
-    const installments =
-      data.installments && data.installments.length > 0
-        ? data.installments
-        : [
-            {
-              installment_number: 1,
-              due_date: data.due_date,
-              amount: data.total_amount,
-            },
-          ];
+      if (data.cost_center_id) {
+        const costCenter = await tx.cost_center.findUnique({
+          where: { id: data.cost_center_id },
+          select: { id: true },
+        });
 
-    const title = await this.prisma.financial_title.create({
-      data: {
-        person_id: data.person_id,
-        title_type: titleType,
-        status: 'open',
-        document_number: data.document_number,
-        description: data.description,
-        competence_date: data.competence_date
-          ? new Date(data.competence_date)
-          : null,
-        issue_date: data.issue_date ? new Date(data.issue_date) : null,
-        total_amount_cents: this.toCents(data.total_amount),
-        finance_category_id: data.finance_category_id,
-        created_by_user_id: userId,
-      },
-    });
+        if (!costCenter) {
+          throw new BadRequestException(
+            getLocaleText('costCenterNotFound', locale, 'Cost center not found'),
+          );
+        }
+      }
+
+      const attachmentFileIds = [
+        ...new Set((data.attachment_file_ids || []).filter((fileId) => fileId > 0)),
+      ];
+
+      if (attachmentFileIds.length > 0) {
+        const existingFiles = await tx.file.findMany({
+          where: {
+            id: { in: attachmentFileIds },
+          },
+          select: {
+            id: true,
+          },
+        });
+
+        const existingFileIds = new Set(existingFiles.map((file) => file.id));
+        const invalidFileIds = attachmentFileIds.filter(
+          (fileId) => !existingFileIds.has(fileId),
+        );
+
+        if (invalidFileIds.length > 0) {
+          throw new BadRequestException(
+            `Invalid attachment file IDs: ${invalidFileIds.join(', ')}`,
+          );
+        }
+      }
 
-    for (let index = 0; index < installments.length; index++) {
-      const installment = installments[index];
-      const amountCents = this.toCents(installment.amount);
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        data.competence_date
+          ? new Date(data.competence_date)
+          : new Date(installments[0].due_date),
+        'create title',
+      );
 
-      const createdInstallment = await this.prisma.financial_installment.create({
+      const title = await tx.financial_title.create({
         data: {
-          title_id: title.id,
-          installment_number: installment.installment_number || index + 1,
+          person_id: data.person_id,
+          title_type: titleType,
+          status: 'draft',
+          document_number: data.document_number,
+          description: data.description,
           competence_date: data.competence_date
             ? new Date(data.competence_date)
-            : new Date(installment.due_date),
-          due_date: new Date(installment.due_date),
-          amount_cents: amountCents,
-          open_amount_cents: amountCents,
-          status: 'open',
-          notes: data.description,
+            : null,
+          issue_date: data.issue_date ? new Date(data.issue_date) : null,
+          total_amount_cents: this.toCents(data.total_amount),
+          finance_category_id: data.finance_category_id,
+          created_by_user_id: userId,
         },
       });
 
-      if (data.cost_center_id) {
-        await this.prisma.installment_allocation.create({
+      if (attachmentFileIds.length > 0) {
+        await tx.financial_title_attachment.createMany({
+          data: attachmentFileIds.map((fileId) => ({
+            title_id: title.id,
+            file_id: fileId,
+            uploaded_by_user_id: userId,
+          })),
+        });
+      }
+
+      for (let index = 0; index < installments.length; index++) {
+        const installment = installments[index];
+        const amountCents = installment.amount_cents;
+
+        const createdInstallment = await tx.financial_installment.create({
           data: {
-            installment_id: createdInstallment.id,
-            cost_center_id: data.cost_center_id,
-            allocated_amount_cents: amountCents,
+            title_id: title.id,
+            installment_number: installment.installment_number,
+            competence_date: data.competence_date
+              ? new Date(data.competence_date)
+              : new Date(installment.due_date),
+            due_date: new Date(installment.due_date),
+            amount_cents: amountCents,
+            open_amount_cents: amountCents,
+            status: this.resolveInstallmentStatus(
+              amountCents,
+              amountCents,
+              new Date(installment.due_date),
+            ),
+            notes: data.description,
           },
         });
+
+        if (data.cost_center_id) {
+          await tx.installment_allocation.create({
+            data: {
+              installment_id: createdInstallment.id,
+              cost_center_id: data.cost_center_id,
+              allocated_amount_cents: amountCents,
+            },
+          });
+        }
       }
-    }
 
-    const createdTitle = await this.getTitleById(title.id, titleType, locale);
-    return this.mapTitleToFront(createdTitle, data.payment_channel);
-  }
+      await this.createAuditLog(tx, {
+        action: 'CREATE_TITLE',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Created ${titleType} title ${title.id} in draft`,
+        afterData: JSON.stringify({
+          status: 'draft',
+          total_amount_cents: this.toCents(data.total_amount),
+        }),
+      });
 
-  private async loadTitles(type: TitleType) {
-    const titles = await this.prisma.financial_title.findMany({
-      where: { title_type: type },
-      include: this.defaultTitleInclude(),
-      orderBy: { created_at: 'desc' },
+      return title.id;
     });
 
-    return titles.map((title) => this.mapTitleToFront(title));
+    const createdTitle = await this.getTitleById(createdTitleId, titleType, locale);
+    return this.mapTitleToFront(createdTitle, data.payment_channel);
   }
 
-  private async loadPeople() {
-    const people = await this.prisma.person.findMany({
-      orderBy: { name: 'asc' },
-    });
+  private normalizeAndValidateInstallments(
+    data: CreateFinancialTitleDto,
+    locale: string,
+  ) {
+    const fallbackDueDate = data.due_date;
+    const totalAmountCents = this.toCents(data.total_amount);
+    const sourceInstallments =
+      data.installments && data.installments.length > 0
+        ? data.installments
+        : [
+            {
+              installment_number: 1,
+              due_date: fallbackDueDate,
+              amount: data.total_amount,
+            },
+          ];
 
-    return people.map((person) => ({
-      id: String(person.id),
-      nome: person.name,
-      tipo: 'ambos',
-      documento: '',
-    }));
-  }
+    const normalizedInstallments = sourceInstallments.map(
+      (installment, index) => {
+        const installmentDueDate = installment.due_date || fallbackDueDate;
+
+        if (!installmentDueDate) {
+          throw new BadRequestException(
+            getLocaleText(
+              'installmentDueDateRequired',
+              locale,
+              'Installment due date is required',
+            ),
+          );
+        }
 
-  private async loadCategories() {
-    const categories = await this.prisma.finance_category.findMany({
-      orderBy: [{ code: 'asc' }, { name: 'asc' }],
-    });
+        const amountCents = this.toCents(installment.amount);
 
-    return categories.map((category) => ({
-      id: String(category.id),
-      codigo: category.code,
-      nome: category.name,
-      natureza:
-        category.kind === 'revenue'
-          ? 'receita'
-          : category.kind === 'expense'
-            ? 'despesa'
-            : category.kind,
-      status: category.status,
-    }));
-  }
+        if (amountCents <= 0) {
+          throw new BadRequestException(
+            getLocaleText(
+              'installmentAmountInvalid',
+              locale,
+              'Installment amount must be greater than zero',
+            ),
+          );
+        }
 
-  private async loadCostCenters() {
-    const costCenters = await this.prisma.cost_center.findMany({
-      orderBy: [{ code: 'asc' }, { name: 'asc' }],
-    });
+        return {
+          installment_number: installment.installment_number || index + 1,
+          due_date: installmentDueDate,
+          amount_cents: amountCents,
+        };
+      },
+    );
 
-    return costCenters.map((costCenter) => ({
-      id: String(costCenter.id),
-      codigo: costCenter.code,
-      nome: costCenter.name,
-      status: costCenter.status,
-    }));
-  }
+    const installmentsTotalCents = normalizedInstallments.reduce(
+      (acc, installment) => acc + installment.amount_cents,
+      0,
+    );
 
-  private async loadBankAccounts() {
-    const bankAccounts = await this.prisma.bank_account.findMany({
-      include: {
-        bank_statement_line: {
-          select: {
-            amount_cents: true,
-            status: true,
-          },
-        },
-      },
-      orderBy: [{ code: 'asc' }, { name: 'asc' }],
-    });
+    if (installmentsTotalCents !== totalAmountCents) {
+      throw new BadRequestException(
+        getLocaleText(
+          'installmentsTotalMismatch',
+          locale,
+          'Installments total must be equal to title total amount',
+        ),
+      );
+    }
 
-    return bankAccounts.map((bankAccount) => this.mapBankAccountToFront(bankAccount));
+    return normalizedInstallments;
   }
 
-  private async loadTags() {
-    const tags = await this.prisma.tag.findMany({
-      orderBy: { slug: 'asc' },
-    });
+  private async approveTitle(
+    titleId: number,
+    titleType: TitleType,
+    locale: string,
+    userId?: number,
+  ) {
+    const updatedTitle = await this.prisma.$transaction(async (tx) => {
+      const title = await tx.financial_title.findFirst({
+        where: {
+          id: titleId,
+          title_type: titleType,
+        },
+        select: {
+          id: true,
+          status: true,
+          competence_date: true,
+        },
+      });
 
-    return tags.map((tag) => ({
-      id: String(tag.id),
-      nome: tag.slug,
-      cor: tag.color,
-    }));
-  }
+      if (!title) {
+        throw new NotFoundException(
+          getLocaleText(
+            'itemNotFound',
+            locale,
+            `Financial title with ID ${titleId} not found`,
+          ).replace('{{item}}', 'Financial title'),
+        );
+      }
 
-  private async loadAuditLogs() {
-    const logs = await this.prisma.audit_log.findMany({
-      orderBy: { created_at: 'desc' },
-      take: 500,
-    });
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        title.competence_date,
+        'approve title',
+      );
 
-    return logs.map((log) => ({
-      id: String(log.id),
-      entidade: log.entity_table === 'financial_title' ? 'TituloPagar' : log.entity_table,
+      if (title.status !== 'draft') {
+        throw new BadRequestException('Only draft titles can be approved');
+      }
+
+      await tx.financial_title.update({
+        where: { id: title.id },
+        data: {
+          status: 'approved',
+        },
+      });
+
+      await this.createAuditLog(tx, {
+        action: 'APPROVE_TITLE',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Approved ${titleType} title ${title.id}`,
+        beforeData: JSON.stringify({ status: title.status }),
+        afterData: JSON.stringify({ status: 'approved' }),
+      });
+
+      return tx.financial_title.findFirst({
+        where: {
+          id: title.id,
+          title_type: titleType,
+        },
+        include: this.defaultTitleInclude(),
+      });
+    });
+
+    if (!updatedTitle) {
+      throw new NotFoundException('Financial title not found');
+    }
+
+    return this.mapTitleToFront(updatedTitle);
+  }
+
+  private async rejectTitle(
+    titleId: number,
+    data: RejectTitleDto,
+    titleType: TitleType,
+    locale: string,
+    userId?: number,
+  ) {
+    const updatedTitle = await this.prisma.$transaction(async (tx) => {
+      const title = await tx.financial_title.findFirst({
+        where: {
+          id: titleId,
+          title_type: titleType,
+        },
+        select: {
+          id: true,
+          status: true,
+          competence_date: true,
+        },
+      });
+
+      if (!title) {
+        throw new NotFoundException(
+          getLocaleText(
+            'itemNotFound',
+            locale,
+            `Financial title with ID ${titleId} not found`,
+          ).replace('{{item}}', 'Financial title'),
+        );
+      }
+
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        title.competence_date,
+        'reject title',
+      );
+
+      if (title.status !== 'draft') {
+        throw new BadRequestException('Only draft titles can be rejected');
+      }
+
+      await tx.financial_title.update({
+        where: { id: title.id },
+        data: {
+          status: 'canceled',
+        },
+      });
+
+      await this.createAuditLog(tx, {
+        action: 'REJECT_TITLE',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Rejected ${titleType} title ${title.id}`,
+        beforeData: JSON.stringify({ status: title.status }),
+        afterData: JSON.stringify({
+          status: 'canceled',
+          reason: data?.reason || null,
+        }),
+      });
+
+      return tx.financial_title.findFirst({
+        where: {
+          id: title.id,
+          title_type: titleType,
+        },
+        include: this.defaultTitleInclude(),
+      });
+    });
+
+    if (!updatedTitle) {
+      throw new NotFoundException('Financial title not found');
+    }
+
+    return this.mapTitleToFront(updatedTitle);
+  }
+
+  private async settleTitleInstallment(
+    titleId: number,
+    data: SettleInstallmentDto,
+    titleType: TitleType,
+    locale: string,
+    userId?: number,
+  ) {
+    const amountCents = this.toCents(data.amount);
+
+    if (amountCents <= 0) {
+      throw new BadRequestException('Settlement amount must be greater than zero');
+    }
+
+    const settledAt = data.settled_at ? new Date(data.settled_at) : new Date();
+    if (Number.isNaN(settledAt.getTime())) {
+      throw new BadRequestException('Invalid settlement date');
+    }
+
+    const result = await this.prisma.$transaction(async (tx) => {
+      const title = await tx.financial_title.findFirst({
+        where: {
+          id: titleId,
+          title_type: titleType,
+        },
+        select: {
+          id: true,
+          person_id: true,
+          status: true,
+          competence_date: true,
+        },
+      });
+
+      if (!title) {
+        throw new NotFoundException(
+          getLocaleText(
+            'itemNotFound',
+            locale,
+            `Financial title with ID ${titleId} not found`,
+          ).replace('{{item}}', 'Financial title'),
+        );
+      }
+
+      if (!['approved', 'open', 'partial'].includes(title.status)) {
+        throw new BadRequestException(
+          'Only approved/open/partial titles can be settled',
+        );
+      }
+
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        title.competence_date,
+        'settle installment',
+      );
+
+      const installment = await tx.financial_installment.findFirst({
+        where: {
+          id: data.installment_id,
+          title_id: title.id,
+        },
+        select: {
+          id: true,
+          title_id: true,
+          amount_cents: true,
+          open_amount_cents: true,
+          due_date: true,
+          status: true,
+        },
+      });
+
+      if (!installment) {
+        throw new BadRequestException('Installment not found for this title');
+      }
+
+      if (installment.status === 'settled' || installment.status === 'canceled') {
+        throw new BadRequestException('This installment cannot be settled');
+      }
+
+      if (amountCents > installment.open_amount_cents) {
+        throw new BadRequestException('Settlement amount exceeds open amount');
+      }
+
+      const paymentMethodId = await this.resolvePaymentMethodId(
+        tx,
+        data.payment_channel,
+      );
+
+      const settlement = await tx.settlement.create({
+        data: {
+          person_id: title.person_id,
+          bank_account_id: data.bank_account_id || null,
+          payment_method_id: paymentMethodId,
+          settlement_type: titleType,
+          status: 'confirmed',
+          settled_at: settledAt,
+          amount_cents: amountCents,
+          description: data.description?.trim() || null,
+          created_by_user_id: userId,
+        },
+      });
+
+      await tx.settlement_allocation.create({
+        data: {
+          settlement_id: settlement.id,
+          installment_id: installment.id,
+          allocated_amount_cents: amountCents,
+          discount_cents: this.toCents(data.discount || 0),
+          interest_cents: this.toCents(data.interest || 0),
+          penalty_cents: this.toCents(data.penalty || 0),
+        },
+      });
+
+      const decrementResult = await tx.financial_installment.updateMany({
+        where: {
+          id: installment.id,
+          open_amount_cents: {
+            gte: amountCents,
+          },
+        },
+        data: {
+          open_amount_cents: {
+            decrement: amountCents,
+          },
+        },
+      });
+
+      if (decrementResult.count !== 1) {
+        throw new BadRequestException(
+          'Installment was updated concurrently, please try again',
+        );
+      }
+
+      const updatedInstallment = await tx.financial_installment.findUnique({
+        where: {
+          id: installment.id,
+        },
+        select: {
+          id: true,
+          amount_cents: true,
+          open_amount_cents: true,
+          due_date: true,
+          status: true,
+        },
+      });
+
+      if (!updatedInstallment) {
+        throw new NotFoundException('Installment not found');
+      }
+
+      const nextInstallmentStatus = this.resolveInstallmentStatus(
+        updatedInstallment.amount_cents,
+        updatedInstallment.open_amount_cents,
+        updatedInstallment.due_date,
+      );
+
+      if (updatedInstallment.status !== nextInstallmentStatus) {
+        await tx.financial_installment.update({
+          where: {
+            id: updatedInstallment.id,
+          },
+          data: {
+            status: nextInstallmentStatus,
+          },
+        });
+      }
+
+      const previousTitleStatus = title.status;
+      const nextTitleStatus = await this.recalculateTitleStatus(tx, title.id);
+
+      await this.createAuditLog(tx, {
+        action: 'SETTLE_INSTALLMENT',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Settled installment ${installment.id} of title ${title.id}`,
+        beforeData: JSON.stringify({
+          title_status: previousTitleStatus,
+          installment_open_amount_cents: installment.open_amount_cents,
+        }),
+        afterData: JSON.stringify({
+          title_status: nextTitleStatus,
+          installment_open_amount_cents: updatedInstallment.open_amount_cents,
+          settlement_id: settlement.id,
+        }),
+      });
+
+      const updatedTitle = await tx.financial_title.findFirst({
+        where: {
+          id: title.id,
+          title_type: titleType,
+        },
+        include: this.defaultTitleInclude(),
+      });
+
+      if (!updatedTitle) {
+        throw new NotFoundException('Financial title not found');
+      }
+
+      return {
+        title: updatedTitle,
+        settlementId: settlement.id,
+      };
+    });
+
+    return {
+      ...this.mapTitleToFront(result.title),
+      settlementId: String(result.settlementId),
+    };
+  }
+
+  private async reverseTitleSettlement(
+    titleId: number,
+    settlementId: number,
+    data: ReverseSettlementDto,
+    titleType: TitleType,
+    locale: string,
+    userId?: number,
+  ) {
+    const updatedTitle = await this.prisma.$transaction(async (tx) => {
+      const title = await tx.financial_title.findFirst({
+        where: {
+          id: titleId,
+          title_type: titleType,
+        },
+        select: {
+          id: true,
+          status: true,
+          competence_date: true,
+        },
+      });
+
+      if (!title) {
+        throw new NotFoundException(
+          getLocaleText(
+            'itemNotFound',
+            locale,
+            `Financial title with ID ${titleId} not found`,
+          ).replace('{{item}}', 'Financial title'),
+        );
+      }
+
+      await this.assertDateNotInClosedPeriod(
+        tx,
+        title.competence_date,
+        'reverse settlement',
+      );
+
+      const settlement = await tx.settlement.findFirst({
+        where: {
+          id: settlementId,
+          settlement_type: titleType,
+          settlement_allocation: {
+            some: {
+              financial_installment: {
+                title_id: title.id,
+              },
+            },
+          },
+        },
+        include: {
+          settlement_allocation: {
+            include: {
+              financial_installment: {
+                select: {
+                  id: true,
+                  amount_cents: true,
+                  open_amount_cents: true,
+                  due_date: true,
+                  status: true,
+                },
+              },
+            },
+          },
+        },
+      });
+
+      if (!settlement) {
+        throw new NotFoundException('Settlement not found for this title');
+      }
+
+      if (settlement.status === 'reversed') {
+        throw new BadRequestException('This settlement is already reversed');
+      }
+
+      for (const allocation of settlement.settlement_allocation) {
+        const installment = allocation.financial_installment;
+
+        if (!installment) {
+          continue;
+        }
+
+        const nextOpenAmountCents =
+          installment.open_amount_cents + allocation.allocated_amount_cents;
+
+        if (nextOpenAmountCents > installment.amount_cents) {
+          throw new BadRequestException(
+            `Reverse would exceed installment amount for installment ${installment.id}`,
+          );
+        }
+
+        const nextInstallmentStatus = this.resolveInstallmentStatus(
+          installment.amount_cents,
+          nextOpenAmountCents,
+          installment.due_date,
+        );
+
+        await tx.financial_installment.update({
+          where: {
+            id: installment.id,
+          },
+          data: {
+            open_amount_cents: nextOpenAmountCents,
+            status: nextInstallmentStatus,
+          },
+        });
+      }
+
+      await tx.settlement.update({
+        where: {
+          id: settlement.id,
+        },
+        data: {
+          status: 'reversed',
+          description: [
+            settlement.description,
+            data.reason ? `Reversed: ${data.reason.trim()}` : 'Reversed',
+          ]
+            .filter(Boolean)
+            .join(' | '),
+        },
+      });
+
+      const previousTitleStatus = title.status;
+      const nextTitleStatus = await this.recalculateTitleStatus(tx, title.id);
+
+      await this.createAuditLog(tx, {
+        action: 'REVERSE_SETTLEMENT',
+        entityTable: 'financial_title',
+        entityId: String(title.id),
+        actorUserId: userId,
+        summary: `Reversed settlement ${settlement.id} from title ${title.id}`,
+        beforeData: JSON.stringify({
+          title_status: previousTitleStatus,
+          settlement_status: settlement.status,
+        }),
+        afterData: JSON.stringify({
+          title_status: nextTitleStatus,
+          settlement_status: 'reversed',
+        }),
+      });
+
+      return tx.financial_title.findFirst({
+        where: {
+          id: title.id,
+          title_type: titleType,
+        },
+        include: this.defaultTitleInclude(),
+      });
+    });
+
+    if (!updatedTitle) {
+      throw new NotFoundException('Financial title not found');
+    }
+
+    return this.mapTitleToFront(updatedTitle);
+  }
+
+  private async updateTitleTags(
+    titleId: number,
+    titleType: TitleType,
+    tagIds: number[],
+    locale: string,
+  ) {
+    const title = await this.getTitleById(titleId, titleType, locale);
+
+    const installmentIds = (title.financial_installment || []).map(
+      (installment) => installment.id,
+    );
+
+    if (installmentIds.length === 0) {
+      throw new BadRequestException('Financial title has no installments');
+    }
+
+    const normalizedTagIds = [
+      ...new Set(
+        (tagIds || [])
+          .map((tagId) => Number(tagId))
+          .filter((tagId) => Number.isInteger(tagId) && tagId > 0),
+      ),
+    ];
+
+    if (normalizedTagIds.length > 0) {
+      const existingTags = await this.prisma.tag.findMany({
+        where: {
+          id: {
+            in: normalizedTagIds,
+          },
+        },
+        select: {
+          id: true,
+        },
+      });
+
+      const existingTagIds = new Set(existingTags.map((tag) => tag.id));
+      const invalidTagIds = normalizedTagIds.filter(
+        (tagId) => !existingTagIds.has(tagId),
+      );
+
+      if (invalidTagIds.length > 0) {
+        throw new BadRequestException(
+          `Invalid tag IDs: ${invalidTagIds.join(', ')}`,
+        );
+      }
+    }
+
+    await this.prisma.$transaction(async (tx) => {
+      if (normalizedTagIds.length === 0) {
+        await tx.financial_installment_tag.deleteMany({
+          where: {
+            installment_id: {
+              in: installmentIds,
+            },
+          },
+        });
+
+        return;
+      }
+
+      await tx.financial_installment_tag.deleteMany({
+        where: {
+          installment_id: {
+            in: installmentIds,
+          },
+          tag_id: {
+            notIn: normalizedTagIds,
+          },
+        },
+      });
+
+      const newRelations = installmentIds.flatMap((installmentId) =>
+        normalizedTagIds.map((tagId) => ({
+          installment_id: installmentId,
+          tag_id: tagId,
+        })),
+      );
+
+      await tx.financial_installment_tag.createMany({
+        data: newRelations,
+        skipDuplicates: true,
+      });
+    });
+
+    const updatedTitle = await this.getTitleById(titleId, titleType, locale);
+    return this.mapTitleToFront(updatedTitle);
+  }
+
+  private async loadTitles(type: TitleType) {
+    const titles = await this.prisma.financial_title.findMany({
+      where: { title_type: type },
+      include: this.defaultTitleInclude(),
+      orderBy: { created_at: 'desc' },
+    });
+
+    return titles.map((title) => this.mapTitleToFront(title));
+  }
+
+  private async loadPeople() {
+    const people = await this.prisma.person.findMany({
+      orderBy: { name: 'asc' },
+    });
+
+    return people.map((person) => ({
+      id: String(person.id),
+      nome: person.name,
+      tipo: 'ambos',
+      documento: '',
+    }));
+  }
+
+  private async loadCategories() {
+    const categories = await this.prisma.finance_category.findMany({
+      orderBy: [{ code: 'asc' }, { name: 'asc' }],
+    });
+
+    return categories.map((category) => ({
+      id: String(category.id),
+      codigo: category.code,
+      nome: category.name,
+      natureza:
+        category.kind === 'revenue'
+          ? 'receita'
+          : category.kind === 'expense'
+            ? 'despesa'
+            : category.kind,
+      status: category.status,
+    }));
+  }
+
+  private async loadCostCenters() {
+    const costCenters = await this.prisma.cost_center.findMany({
+      orderBy: [{ code: 'asc' }, { name: 'asc' }],
+    });
+
+    return costCenters.map((costCenter) => ({
+      id: String(costCenter.id),
+      codigo: costCenter.code,
+      nome: costCenter.name,
+      status: costCenter.status,
+    }));
+  }
+
+  private async loadBankAccounts() {
+    const bankAccounts = await this.prisma.bank_account.findMany({
+      include: {
+        bank_statement_line: {
+          select: {
+            amount_cents: true,
+            status: true,
+          },
+        },
+      },
+      orderBy: [{ code: 'asc' }, { name: 'asc' }],
+    });
+
+    return bankAccounts.map((bankAccount) => this.mapBankAccountToFront(bankAccount));
+  }
+
+  private async loadTags() {
+    const tags = await this.prisma.tag.findMany({
+      orderBy: { slug: 'asc' },
+    });
+
+    return tags.map((tag) => ({
+      id: String(tag.id),
+      nome: tag.slug,
+      cor: tag.color,
+    }));
+  }
+
+  private async loadAuditLogs() {
+    const logs = await this.prisma.audit_log.findMany({
+      orderBy: { created_at: 'desc' },
+      take: 500,
+    });
+
+    return logs.map((log) => ({
+      id: String(log.id),
+      entidade: log.entity_table === 'financial_title' ? 'TituloPagar' : log.entity_table,
       entidadeId: log.entity_id,
       usuarioId: log.actor_user_id ? String(log.actor_user_id) : null,
       acao: log.action,
@@ -1628,6 +2559,189 @@ export class FinanceService {
     }));
   }
 
+  private async resolvePaymentMethodId(tx: any, paymentChannel?: string) {
+    const paymentType = this.mapPaymentMethodFromPt(paymentChannel);
+
+    if (!paymentType) {
+      return null;
+    }
+
+    const paymentMethod = await tx.payment_method.findFirst({
+      where: {
+        type: paymentType,
+        status: 'active',
+      },
+      select: {
+        id: true,
+      },
+    });
+
+    return paymentMethod?.id || null;
+  }
+
+  private async assertDateNotInClosedPeriod(
+    tx: any,
+    competenceDate: Date | null | undefined,
+    operation: string,
+  ) {
+    if (!competenceDate) {
+      return;
+    }
+
+    const closedPeriod = await tx.period_close.findFirst({
+      where: {
+        status: 'closed',
+        period_start: {
+          lte: competenceDate,
+        },
+        period_end: {
+          gte: competenceDate,
+        },
+      },
+      select: {
+        id: true,
+      },
+    });
+
+    if (closedPeriod) {
+      throw new BadRequestException(
+        `Cannot ${operation}: competence is in a closed period`,
+      );
+    }
+  }
+
+  private resolveInstallmentStatus(
+    amountCents: number,
+    openAmountCents: number,
+    dueDate: Date,
+    currentStatus?: string,
+  ): InstallmentStatus {
+    if (currentStatus === 'canceled') {
+      return 'canceled';
+    }
+
+    if (openAmountCents <= 0) {
+      return 'settled';
+    }
+
+    if (openAmountCents < amountCents) {
+      return 'partial';
+    }
+
+    const today = new Date();
+    today.setHours(0, 0, 0, 0);
+    const dueDateOnly = new Date(dueDate);
+    dueDateOnly.setHours(0, 0, 0, 0);
+
+    if (dueDateOnly < today) {
+      return 'overdue';
+    }
+
+    return 'open';
+  }
+
+  private deriveTitleStatusFromInstallments(
+    installments: Array<{
+      amount_cents: number;
+      open_amount_cents: number;
+      due_date: Date;
+      status?: string;
+    }>,
+  ): TitleStatus {
+    if (installments.length === 0) {
+      return 'open';
+    }
+
+    const effectiveStatuses = installments.map((installment) =>
+      this.resolveInstallmentStatus(
+        installment.amount_cents,
+        installment.open_amount_cents,
+        installment.due_date,
+        installment.status,
+      ),
+    );
+
+    if (effectiveStatuses.every((status) => status === 'settled')) {
+      return 'settled';
+    }
+
+    const hasPayment = installments.some(
+      (installment) => installment.open_amount_cents < installment.amount_cents,
+    );
+
+    if (hasPayment) {
+      return 'partial';
+    }
+
+    return 'open';
+  }
+
+  private async recalculateTitleStatus(tx: any, titleId: number): Promise<TitleStatus> {
+    const title = await tx.financial_title.findUnique({
+      where: {
+        id: titleId,
+      },
+      select: {
+        id: true,
+        status: true,
+        financial_installment: {
+          select: {
+            amount_cents: true,
+            open_amount_cents: true,
+            due_date: true,
+            status: true,
+          },
+        },
+      },
+    });
+
+    if (!title) {
+      throw new NotFoundException('Financial title not found');
+    }
+
+    const nextStatus = this.deriveTitleStatusFromInstallments(
+      title.financial_installment,
+    );
+
+    if (title.status !== nextStatus) {
+      await tx.financial_title.update({
+        where: {
+          id: title.id,
+        },
+        data: {
+          status: nextStatus,
+        },
+      });
+    }
+
+    return nextStatus;
+  }
+
+  private async createAuditLog(
+    tx: any,
+    data: {
+      actorUserId?: number;
+      action: string;
+      entityTable: string;
+      entityId: string;
+      summary?: string;
+      beforeData?: string;
+      afterData?: string;
+    },
+  ) {
+    await tx.audit_log.create({
+      data: {
+        actor_user_id: data.actorUserId || null,
+        action: data.action,
+        entity_table: data.entityTable,
+        entity_id: data.entityId,
+        summary: data.summary || null,
+        before_data: data.beforeData || null,
+        after_data: data.afterData || null,
+      },
+    });
+  }
+
   private mapTitleToFront(title: any, paymentChannelOverride?: string) {
     const allocations = title.financial_installment.flatMap(
       (installment) => installment.installment_allocation,
@@ -1652,13 +2766,24 @@ export class FinanceService {
       numero: installment.installment_number,
       vencimento: installment.due_date.toISOString(),
       valor: this.fromCents(installment.amount_cents),
-      status: this.mapStatusToPt(installment.status),
+      valorAberto: this.fromCents(installment.open_amount_cents),
+      status: this.mapStatusToPt(
+        this.resolveInstallmentStatus(
+          installment.amount_cents,
+          installment.open_amount_cents,
+          installment.due_date,
+          installment.status,
+        ),
+      ),
       metodoPagamento:
         this.mapPaymentMethodToPt(
           installment.settlement_allocation[0]?.settlement?.payment_method?.type,
         ) || paymentChannelOverride || 'transferencia',
       liquidacoes: installment.settlement_allocation.map((allocation) => ({
         id: String(allocation.id),
+        settlementId: allocation.settlement?.id
+          ? String(allocation.settlement.id)
+          : null,
         data: allocation.settlement?.settled_at?.toISOString(),
         valor: this.fromCents(allocation.allocated_amount_cents),
         juros: this.fromCents(allocation.interest_cents || 0),
@@ -1667,6 +2792,7 @@ export class FinanceService {
         contaBancariaId: allocation.settlement?.bank_account_id
           ? String(allocation.settlement.bank_account_id)
           : null,
+        status: allocation.settlement?.status || null,
         metodo:
           this.mapPaymentMethodToPt(
             allocation.settlement?.payment_method?.type,
@@ -1674,6 +2800,11 @@ export class FinanceService {
       })),
     }));
 
+    const attachmentDetails = title.financial_title_attachment.map((attachment) => ({
+      id: String(attachment.file_id),
+      nome: attachment.file?.filename || attachment.file?.path,
+    }));
+
     return {
       id: String(title.id),
       documento: title.document_number || `TIT-${title.id}`,
@@ -1686,9 +2817,8 @@ export class FinanceService {
       criadoEm: title.created_at.toISOString(),
       categoriaId: title.finance_category_id ? String(title.finance_category_id) : null,
       centroCustoId: firstCostCenter ? String(firstCostCenter) : null,
-      anexos: title.financial_title_attachment.map(
-        (attachment) => attachment.file?.filename || attachment.file?.path,
-      ),
+      anexos: attachmentDetails.map((attachment) => attachment.nome),
+      anexosDetalhes: attachmentDetails,
       tags,
       parcelas: mappedInstallments,
       canal:
@@ -1744,6 +2874,20 @@ export class FinanceService {
     return statusMap[status] || 'aberto';
   }
 
+  private normalizeTagSlug(value?: string | null) {
+    if (!value) {
+      return '';
+    }
+
+    return value
+      .normalize('NFD')
+      .replace(/[\u0300-\u036f]/g, '')
+      .toLowerCase()
+      .trim()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/(^-|-$)+/g, '');
+  }
+
   private mapStatusFromPt(status?: string) {
     if (!status || status === 'all') {
       return undefined;
@@ -1763,7 +2907,7 @@ export class FinanceService {
   }
 
   private mapPaymentMethodToPt(paymentMethodType?: string | null) {
-    const paymentMethodMap = {
+    const paymentMethodMap: Record<string, string> = {
       boleto: 'boleto',
       pix: 'pix',
       ted: 'transferencia',
@@ -1776,6 +2920,30 @@ export class FinanceService {
     return paymentMethodMap[paymentMethodType] || undefined;
   }
 
+  private mapPaymentMethodFromPt(paymentMethodType?: string | null) {
+    if (!paymentMethodType) {
+      return undefined;
+    }
+
+    const paymentMethodMap = {
+      boleto: 'boleto',
+      pix: 'pix',
+      transferencia: 'ted',
+      transferência: 'ted',
+      ted: 'ted',
+      doc: 'doc',
+      cartao: 'card',
+      cartão: 'card',
+      dinheiro: 'cash',
+      cheque: 'other',
+      cash: 'cash',
+      card: 'card',
+      other: 'other',
+    };
+
+    return paymentMethodMap[(paymentMethodType || '').toLowerCase()];
+  }
+
   private mapAccountTypeToPt(accountType?: string | null) {
     const accountTypeMap = {
       checking: 'corrente',