@hed-hog/finance 0.0.366 → 0.0.370

package/hedhog/frontend/app/cash-and-banks/bank-reconciliation/page.tsx.ejs

@@ -348,7 +348,10 @@ function CriarAjusteSheet({
               <Button
                 type="button"
                 variant="outline"
-                onClick={() => setOpen(false)}
+                onClick={() => {
+                  clearDraft();
+                  setOpen(false);
+                }}
               >
                 {t('common.cancel')}
               </Button>

package/hedhog/frontend/app/cash-and-banks/statements/page.tsx.ejs

@@ -511,7 +511,10 @@ function NovaContaBancariaSheet({
               <Button
                 type="button"
                 variant="outline"
-                onClick={() => onOpenChange(false)}
+                onClick={() => {
+                  clearDraft();
+                  onOpenChange(false);
+                }}
               >
                 {tBank('common.cancel')}
               </Button>
@@ -764,7 +767,10 @@ function ImportarExtratoSheet({
               <Button
                 type="button"
                 variant="outline"
-                onClick={() => handleOpenChange(false)}
+                onClick={() => {
+                  clearDraft();
+                  handleOpenChange(false);
+                }}
               >
                 {t('common.cancel')}
               </Button>

package/hedhog/frontend/app/cash-and-banks/transfers/page.tsx.ejs

@@ -378,7 +378,10 @@ function NovaTransferenciaSheet({
                 <Button
                   type="button"
                   variant="outline"
-                  onClick={() => setOpen(false)}
+                  onClick={() => {
+                    clearDraft();
+                    setOpen(false);
+                  }}
                 >
                   {t('common.cancel')}
                 </Button>

package/hedhog/frontend/messages/en.json

@@ -162,7 +162,8 @@
       "cancel": "Cancel",
       "save": "Save",
       "createCategoryAria": "Create new category",
-      "createCostCenterAria": "Create new cost center"
+      "createCostCenterAria": "Create new cost center",
+      "createBankAccountAria": "Create new bank account"
     },
     "categorySheet": {
       "title": "New category",
@@ -255,6 +256,12 @@
         "quarterly": "Quarterly",
         "semiannual": "Semi-annual",
         "annual": "Annual"
+      },
+      "documentNumberModeLabel": "Document numbering",
+      "documentNumberModes": {
+        "same": "Same number on all",
+        "sequence": "Number in sequence (1/N)",
+        "none": "No number"
       }
     },
     "newTitle": {
@@ -767,6 +774,12 @@
         "quarterly": "Quarterly",
         "semiannual": "Semi-annual",
         "annual": "Annual"
+      },
+      "documentNumberModeLabel": "Document numbering",
+      "documentNumberModes": {
+        "same": "Same number on all",
+        "sequence": "Number in sequence (1/N)",
+        "none": "No number"
       }
     },
     "newTitle": {

package/hedhog/frontend/messages/pt.json

@@ -147,7 +147,8 @@
       "cancel": "Cancelar",
       "save": "Salvar",
       "createCategoryAria": "Criar nova categoria",
-      "createCostCenterAria": "Criar novo centro de custo"
+      "createCostCenterAria": "Criar novo centro de custo",
+      "createBankAccountAria": "Criar nova conta bancária"
     },
     "categorySheet": {
       "title": "Nova categoria",
@@ -240,6 +241,12 @@
         "quarterly": "Trimestral",
         "semiannual": "Semestral",
         "annual": "Anual"
+      },
+      "documentNumberModeLabel": "Numeração do documento",
+      "documentNumberModes": {
+        "same": "Mesmo número em todos",
+        "sequence": "Numerar em sequência (1/N)",
+        "none": "Sem número"
       }
     },
     "newTitle": {
@@ -752,6 +759,12 @@
         "quarterly": "Trimestral",
         "semiannual": "Semestral",
         "annual": "Anual"
+      },
+      "documentNumberModeLabel": "Numeração do documento",
+      "documentNumberModes": {
+        "same": "Mesmo número em todos",
+        "sequence": "Numerar em sequência (1/N)",
+        "none": "Sem número"
       }
     },
     "newTitle": {

package/hedhog/table/financial_title.yaml

@@ -38,6 +38,10 @@ columns:
   - name: recurrence_end_date
     type: date
     isNullable: true
+  - name: recurrence_group_id
+    type: varchar
+    length: 36
+    isNullable: true
   - name: finance_category_id
     type: fk
     isNullable: true
@@ -60,4 +64,5 @@ columns:
 indices:
   - columns: [title_type, status]
   - columns: [person_id]
-  - columns: [competence_date]
+  - columns: [competence_date]
+  - columns: [recurrence_group_id]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/finance",
-  "version": "0.0.366",
+  "version": "0.0.370",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
@@ -9,14 +9,14 @@
     "@nestjs/core": "^11",
     "@nestjs/jwt": "^11",
     "@nestjs/mapped-types": "*",
+    "@hed-hog/api-locale": "0.0.14",
     "@hed-hog/api": "0.0.8",
+    "@hed-hog/api-prisma": "0.0.6",
+    "@hed-hog/core": "0.0.370",
     "@hed-hog/api-pagination": "0.0.7",
+    "@hed-hog/tag": "0.0.370",
     "@hed-hog/api-types": "0.0.1",
-    "@hed-hog/api-prisma": "0.0.6",
-    "@hed-hog/crm": "0.0.366",
-    "@hed-hog/core": "0.0.366",
-    "@hed-hog/api-locale": "0.0.14",
-    "@hed-hog/tag": "0.0.366"
+    "@hed-hog/crm": "0.0.370"
   },
   "exports": {
     ".": {

package/src/dto/create-financial-title.dto.ts

@@ -28,6 +28,11 @@ export class CreateRecurrenceRuleDto {
   @Min(1)
   @Max(600)
   max_occurrences?: number;
+
+  @IsOptional()
+  @IsString()
+  @IsIn(['same', 'sequence', 'none'])
+  document_number_mode?: string;
 }
 
 export class CreateFinancialInstallmentDto {

package/src/finance.service.ts

@@ -16,7 +16,7 @@ import {
   Logger,
   NotFoundException,
 } from '@nestjs/common';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { CreateBankAccountDto } from './dto/create-bank-account.dto';
 import { CreateBankReconciliationDto } from './dto/create-bank-reconciliation.dto';
@@ -5138,18 +5138,59 @@ export class FinanceService {
       interest_cents?: number;
       penalty_cents?: number;
     };
-    const installments: NormalizedInstallment[] = isRecurring
-      ? this.buildRecurrenceInstallments(
-          data.due_date,
-          rule!.frequency,
-          this.toCents(data.total_amount),
-          rule!.end_date,
-          rule!.max_occurrences,
-        )
-      : this.normalizeAndValidateInstallments(data, locale);
+    type TitleSpec = {
+      documentNumber: string | null;
+      recurrenceGroupId: string | null;
+      totalAmountCents: number;
+      installments: NormalizedInstallment[];
+    };
+
+    // Recurring titles are NOT installment titles: each occurrence becomes an
+    // independent title (with a single installment), all linked by a shared
+    // recurrence_group_id. Installment titles remain a single title with many
+    // installments.
+    let titleSpecs: TitleSpec[];
+    if (isRecurring) {
+      const occurrences = this.buildRecurrenceInstallments(
+        data.due_date,
+        rule!.frequency,
+        this.toCents(data.total_amount),
+        rule!.end_date,
+        rule!.max_occurrences,
+      );
+      const recurrenceGroupId = randomUUID();
+      const baseDocument = data.document_number?.trim() || null;
+      const documentMode = rule!.document_number_mode || 'same';
+      titleSpecs = occurrences.map((occurrence, index) => ({
+        documentNumber: this.resolveRecurrenceDocumentNumber(
+          baseDocument,
+          documentMode,
+          index + 1,
+          occurrences.length,
+        ),
+        recurrenceGroupId,
+        totalAmountCents: occurrence.amount_cents,
+        installments: [
+          {
+            installment_number: 1,
+            due_date: occurrence.due_date,
+            amount_cents: occurrence.amount_cents,
+          },
+        ],
+      }));
+    } else {
+      titleSpecs = [
+        {
+          documentNumber: data.document_number?.trim() || null,
+          recurrenceGroupId: null,
+          totalAmountCents: this.toCents(data.total_amount),
+          installments: this.normalizeAndValidateInstallments(data, locale),
+        },
+      ];
+    }
 
-    const hasPaidInstallments = installments.some(
-      (installment) => installment.paid,
+    const hasPaidInstallments = titleSpecs.some((spec) =>
+      spec.installments.some((installment) => installment.paid),
     );
 
     const createResult = await this.prisma.$transaction(async (tx) => {
@@ -5233,158 +5274,157 @@ export class FinanceService {
         tx,
         data.competence_date
           ? this.parseLocalDate(data.competence_date)
-          : this.parseLocalDate(installments[0].due_date),
+          : this.parseLocalDate(titleSpecs[0].installments[0].due_date),
         'create title',
       );
 
-      const totalAmountCents = isRecurring
-        ? this.toCents(data.total_amount) * installments.length
-        : this.toCents(data.total_amount);
-
-      const title = await tx.financial_title.create({
-        data: {
-          person_id: data.person_id,
-          title_type: titleType,
-          status: 'draft',
-          document_number: data.document_number?.trim() || null,
-          description: data.description,
-          competence_date: data.competence_date
-            ? this.parseLocalDate(data.competence_date)
-            : null,
-          issue_date: data.issue_date ? this.parseLocalDate(data.issue_date) : null,
-          total_amount_cents: totalAmountCents,
-          is_recurring: isRecurring,
-          recurrence_frequency: rule?.frequency ?? null,
-          recurrence_end_date: rule?.end_date ? this.parseLocalDate(rule.end_date) : null,
-          finance_category_id: data.finance_category_id,
-          created_by_user_id: userId,
-        },
-      });
-
-      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,
-          })),
-        });
-      }
-
+      const createdTitleIds: number[] = [];
       const appliedSettlements: Array<{
         settlementId: number;
         installmentId: number;
         openAmountCentsBefore: number;
         openAmountCentsAfter: number;
+        titleId: number;
       }> = [];
 
-      for (let index = 0; index < installments.length; index++) {
-        const installment = installments[index];
-        const amountCents = installment.amount_cents;
-
-        const createdInstallment = await tx.financial_installment.create({
+      for (const spec of titleSpecs) {
+        const title = await tx.financial_title.create({
           data: {
-            title_id: title.id,
-            installment_number: installment.installment_number,
+            person_id: data.person_id,
+            title_type: titleType,
+            status: 'draft',
+            document_number: spec.documentNumber,
+            description: data.description,
             competence_date: data.competence_date
               ? this.parseLocalDate(data.competence_date)
-              : this.parseLocalDate(installment.due_date),
-            due_date: this.parseLocalDate(installment.due_date),
-            amount_cents: amountCents,
-            open_amount_cents: amountCents,
-            status: this.resolveInstallmentStatus(
-              amountCents,
-              amountCents,
-              this.parseLocalDate(installment.due_date),
-            ),
-            notes: data.description,
+              : null,
+            issue_date: data.issue_date ? this.parseLocalDate(data.issue_date) : null,
+            total_amount_cents: spec.totalAmountCents,
+            is_recurring: isRecurring,
+            recurrence_frequency: rule?.frequency ?? null,
+            recurrence_end_date: rule?.end_date ? this.parseLocalDate(rule.end_date) : null,
+            recurrence_group_id: spec.recurrenceGroupId,
+            finance_category_id: data.finance_category_id,
+            created_by_user_id: userId,
           },
         });
 
-        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,
-            },
+        createdTitleIds.push(title.id);
+
+        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,
+            })),
           });
         }
 
-        if (installment.paid) {
-          const appliedSettlement = await this.applyInstallmentSettlement(tx, {
-            title: { id: title.id, person_id: data.person_id },
-            titleType,
-            installmentId: createdInstallment.id,
-            amountCents: installment.paid_amount_cents ?? amountCents,
-            settledAt: this.parseLocalDate(
-              installment.paid_at || installment.due_date,
-            ),
-            bankAccountId: data.bank_account_id ?? null,
-            paymentChannel: data.payment_channel,
-            discountCents: installment.discount_cents,
-            interestCents: installment.interest_cents,
-            penaltyCents: installment.penalty_cents,
-            userId,
+        for (const installment of spec.installments) {
+          const amountCents = installment.amount_cents;
+
+          const createdInstallment = await tx.financial_installment.create({
+            data: {
+              title_id: title.id,
+              installment_number: installment.installment_number,
+              competence_date: data.competence_date
+                ? this.parseLocalDate(data.competence_date)
+                : this.parseLocalDate(installment.due_date),
+              due_date: this.parseLocalDate(installment.due_date),
+              amount_cents: amountCents,
+              open_amount_cents: amountCents,
+              status: this.resolveInstallmentStatus(
+                amountCents,
+                amountCents,
+                this.parseLocalDate(installment.due_date),
+              ),
+              notes: data.description,
+            },
           });
 
-          appliedSettlements.push(appliedSettlement);
-        }
-      }
+          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 finalStatus =
-        appliedSettlements.length > 0
-          ? await this.recalculateTitleStatus(tx, title.id)
-          : 'draft';
+          if (installment.paid) {
+            const appliedSettlement = await this.applyInstallmentSettlement(tx, {
+              title: { id: title.id, person_id: data.person_id },
+              titleType,
+              installmentId: createdInstallment.id,
+              amountCents: installment.paid_amount_cents ?? amountCents,
+              settledAt: this.parseLocalDate(
+                installment.paid_at || installment.due_date,
+              ),
+              bankAccountId: data.bank_account_id ?? null,
+              paymentChannel: data.payment_channel,
+              discountCents: installment.discount_cents,
+              interestCents: installment.interest_cents,
+              penaltyCents: installment.penalty_cents,
+              userId,
+            });
+
+            appliedSettlements.push({ ...appliedSettlement, titleId: title.id });
+          }
+        }
 
-      await this.createAuditLog(tx, {
-        action: 'CREATE_TITLE',
-        entityTable: 'financial_title',
-        entityId: String(title.id),
-        actorUserId: userId,
-        summary: `Created ${titleType} title ${title.id} in ${finalStatus}`,
-        afterData: JSON.stringify({
-          status: finalStatus,
-          total_amount_cents: this.toCents(data.total_amount),
-        }),
-      });
+        const titleSettlements = appliedSettlements.filter((s) => s.titleId === title.id);
+        const finalStatus =
+          titleSettlements.length > 0
+            ? await this.recalculateTitleStatus(tx, title.id)
+            : 'draft';
 
-      for (const appliedSettlement of appliedSettlements) {
         await this.createAuditLog(tx, {
-          action: 'SETTLE_INSTALLMENT',
+          action: 'CREATE_TITLE',
           entityTable: 'financial_title',
           entityId: String(title.id),
           actorUserId: userId,
-          summary: `Settled installment ${appliedSettlement.installmentId} of title ${title.id}`,
-          beforeData: JSON.stringify({
-            title_status: 'draft',
-            installment_open_amount_cents:
-              appliedSettlement.openAmountCentsBefore,
-          }),
+          summary: `Created ${titleType} title ${title.id} in ${finalStatus}`,
           afterData: JSON.stringify({
-            title_status: finalStatus,
-            installment_open_amount_cents:
-              appliedSettlement.openAmountCentsAfter,
-            settlement_id: appliedSettlement.settlementId,
-            bank_reconciliation_id: null,
+            status: finalStatus,
+            total_amount_cents: spec.totalAmountCents,
           }),
         });
+
+        for (const appliedSettlement of titleSettlements) {
+          await this.createAuditLog(tx, {
+            action: 'SETTLE_INSTALLMENT',
+            entityTable: 'financial_title',
+            entityId: String(title.id),
+            actorUserId: userId,
+            summary: `Settled installment ${appliedSettlement.installmentId} of title ${title.id}`,
+            beforeData: JSON.stringify({
+              title_status: 'draft',
+              installment_open_amount_cents: appliedSettlement.openAmountCentsBefore,
+            }),
+            afterData: JSON.stringify({
+              title_status: finalStatus,
+              installment_open_amount_cents: appliedSettlement.openAmountCentsAfter,
+              settlement_id: appliedSettlement.settlementId,
+              bank_reconciliation_id: null,
+            }),
+          });
+        }
       }
 
       return {
-        titleId: title.id,
-        settlementIds: appliedSettlements.map(
-          (appliedSettlement) => appliedSettlement.settlementId,
-        ),
+        titleIds: createdTitleIds,
+        settlementIds: appliedSettlements.map((s) => s.settlementId),
       };
     });
 
     const createdTitle = await this.getTitleById(
-      createResult.titleId,
+      createResult.titleIds[0],
       titleType,
       locale,
     );
-    this.financeRealtime.publish({ domain: 'installment', type: 'created', entityId: createResult.titleId });
+    this.financeRealtime.publish({ domain: 'installment', type: 'created', entityId: createResult.titleIds[0] });
     for (const settlementId of createResult.settlementIds) {
       this.financeRealtime.publish({ domain: 'settlement', type: 'settled', entityId: settlementId });
     }
@@ -5406,14 +5446,16 @@ export class FinanceService {
     }
 
     const isRecurring = Boolean(rule);
+    // When editing a recurring title we only update this single occurrence
+    // (one installment). Re-building the full series is out of scope for edits.
     const installments = isRecurring
-      ? this.buildRecurrenceInstallments(
-          data.due_date,
-          rule!.frequency,
-          this.toCents(data.total_amount),
-          rule!.end_date,
-          rule!.max_occurrences,
-        )
+      ? [
+          {
+            installment_number: 1,
+            due_date: data.due_date,
+            amount_cents: this.toCents(data.total_amount),
+          },
+        ]
       : this.normalizeAndValidateInstallments(data, locale);
 
     const updatedTitle = await this.prisma.$transaction(async (tx) => {
@@ -5537,9 +5579,7 @@ export class FinanceService {
         }
       }
 
-      const totalAmountCents = isRecurring
-        ? this.toCents(data.total_amount) * installments.length
-        : this.toCents(data.total_amount);
+      const totalAmountCents = this.toCents(data.total_amount);
 
       await tx.financial_title.update({
         where: { id: title.id },
@@ -5555,7 +5595,8 @@ export class FinanceService {
           is_recurring: isRecurring,
           recurrence_frequency: rule?.frequency ?? null,
           recurrence_end_date: rule?.end_date ? this.parseLocalDate(rule.end_date) : null,
-          finance_category_id: data.finance_category_id,
+          // Preserve recurrence_group_id — editing a single occurrence must not
+          // break the link to the rest of the series.
         },
       });
 
@@ -5703,6 +5744,17 @@ export class FinanceService {
     return installments;
   }
 
+  private resolveRecurrenceDocumentNumber(
+    base: string | null,
+    mode: string,
+    index: number,
+    total: number,
+  ): string | null {
+    if (mode === 'none') return null;
+    if (mode === 'sequence') return base ? `${base} ${index}/${total}` : `${index}/${total}`;
+    return base; // 'same'
+  }
+
   private normalizeAndValidateInstallments(
     data: CreateFinancialTitleDto,
     locale: string,
@@ -7251,6 +7303,7 @@ export class FinanceService {
       recurrenceEndDate: title.recurrence_end_date
         ? title.recurrence_end_date.toISOString().slice(0, 10)
         : null,
+      recurrenceGroupId: title.recurrence_group_id ?? null,
       ...(title.title_type === 'payable'
         ? {
             fornecedorId: String(title.person_id),

package/src/mcp-tools/finance-installments.mcp-tools.ts

@@ -90,7 +90,7 @@ export class FinanceInstallmentsMcpTools {
         },
         recurrence_rule: {
           type: 'object',
-          description: 'Recurrence rule. When provided, creates a recurring title (same amount each period) instead of a split installment title.',
+          description: 'Recurrence rule. When provided, each occurrence becomes an independent title (one installment each) linked by a recurrence_group_id.',
           properties: {
             frequency: {
               type: 'string',
@@ -99,6 +99,11 @@ export class FinanceInstallmentsMcpTools {
             },
             end_date: { type: 'string', description: 'End date (YYYY-MM-DD) — stop generating after this date' },
             max_occurrences: { type: 'number', description: 'Maximum number of repetitions' },
+            document_number_mode: {
+              type: 'string',
+              enum: ['same', 'sequence', 'none'],
+              description: 'How to set document_number on each title: same = copy as-is, sequence = append i/N suffix, none = leave blank (default: same)',
+            },
           },
           required: ['frequency'],
         },
@@ -358,7 +363,7 @@ export class FinanceInstallmentsMcpTools {
         },
         recurrence_rule: {
           type: 'object',
-          description: 'Recurrence rule. When provided, creates a recurring title (same amount each period) instead of a split installment title.',
+          description: 'Recurrence rule. When provided, each occurrence becomes an independent title (one installment each) linked by a recurrence_group_id.',
           properties: {
             frequency: {
               type: 'string',
@@ -367,6 +372,11 @@ export class FinanceInstallmentsMcpTools {
             },
             end_date: { type: 'string', description: 'End date (YYYY-MM-DD) — stop generating after this date' },
             max_occurrences: { type: 'number', description: 'Maximum number of repetitions' },
+            document_number_mode: {
+              type: 'string',
+              enum: ['same', 'sequence', 'none'],
+              description: 'How to set document_number on each title: same = copy as-is, sequence = append i/N suffix, none = leave blank (default: same)',
+            },
           },
           required: ['frequency'],
         },