@baruk/core 0.3.1 → 0.5.0

package/dist/billing/ar-repository.js

@@ -0,0 +1,783 @@
+import { ConflictError, NotFoundError, ValidationError, uuidv7 } from '@baruk/shared';
+import { availableMeansOf } from './payment-means-catalog.js';
+/**
+ * Accounts Receivable — M1 do Merchant Billing Core
+ * (RFC-CAPABILITY-MERCHANT-BILLING-CORE-001 §4/§20). O M0 entregou schema e
+ * contratos; aqui entram a geração por competência, a máquina de estados e as
+ * consultas financeiras.
+ *
+ * A separação do M0 continua valendo e não pode ser colapsada: `Receivable` é a
+ * DÍVIDA do cliente com o escritório; `Charge` é o INSTRUMENTO (boleto/pix) que
+ * tenta recebê-la; `Payment` é o dinheiro que chegou. Um mesmo Receivable pode
+ * ter vários Charges (reemissão) e vários Payments (parcial).
+ *
+ * Tenant-scoped por RLS: nenhuma query aqui filtra `tenant_id` na mão — quem
+ * garante o recorte é a policy, e o contexto vem de `withContext`.
+ */
+// ── Vencido é uma DERIVAÇÃO, não um estado que alguém precisa lembrar de gravar ──
+//
+// Um recebível `open` cuja data passou já está vencido — mesmo que nenhum job
+// tenha rodado. Gravar 'overdue' numa coluna faria o número do dashboard depender
+// de um cron ter executado; quando o cron falha, o escritório vê inadimplência
+// menor do que a real, que é o pior erro possível neste domínio.
+//
+// Então o status efetivo é calculado na leitura. `markOverdueReceivables` existe
+// para MATERIALIZAR a transição — não para descobri-la — porque a régua de
+// cobrança precisa de um instante definido para disparar RECEIVABLE_OVERDUE.
+// `partially_paid` entra junto de `open`: um recebível pago pela metade cujo
+// vencimento passou TEM saldo em atraso. Considerar só `open` fazia o resumo
+// dizer "vencido: R$ 0" enquanto o aging listava o mesmo saldo na faixa de 1-7
+// dias — dois números verdadeiros contando coisas diferentes, e o mais visível
+// deles subestimando a inadimplência.
+const EFFECTIVE_STATUS_SQL = `
+  CASE WHEN r.status IN ('open','partially_paid')
+        AND r.due_date IS NOT NULL AND r.due_date < CURRENT_DATE
+       THEN 'overdue' ELSE r.status END`;
+/** Status que ainda representam dinheiro a receber. */
+const OPEN_STATUSES = ['open', 'partially_paid', 'overdue'];
+const iso = (d) => (d ? d.toISOString().slice(0, 10) : null);
+/** Texto de `metadata`, ou null. Ignora número/objeto: metadata é livre. */
+function metaText(metadata, key) {
+    const v = metadata?.[key];
+    return typeof v === 'string' && v.trim() ? v.trim() : null;
+}
+function mapReceivable(r) {
+    const amount = Number(r.amount);
+    const amountPaid = Number(r.amount_paid);
+    return {
+        id: r.id,
+        clientId: r.client_id,
+        clientName: r.client_name,
+        feeAgreementId: r.fee_agreement_id,
+        competence: r.competence,
+        amount,
+        status: r.status,
+        effectiveStatus: r.effective_status,
+        dueDate: iso(r.due_date),
+        issuedAt: r.issued_at.toISOString(),
+        renegotiatedFromId: r.renegotiated_from_id,
+        createdAt: r.created_at.toISOString(),
+        amountPaid,
+        outstandingAmount: Math.max(0, Number((amount - amountPaid).toFixed(2))),
+        daysOverdue: r.days_overdue,
+        // A origem é o `fee_agreement_id` e nada mais. Derivar da competência —
+        // tentador, porque quase todo recorrente tem uma — classificaria como
+        // recorrente todo avulso que o operador competenciou, que é justamente o
+        // caso em que a distinção importa.
+        origin: r.fee_agreement_id ? 'recurring' : 'one_off',
+        generatedBy: r.generated_by,
+        description: r.description,
+        notes: metaText(r.metadata, 'notes'),
+        serviceCategory: metaText(r.metadata, 'serviceCategory'),
+        activeCharge: r.charge_id
+            ? {
+                id: r.charge_id,
+                status: r.charge_status,
+                means: availableMeansOf(r.charge_metadata),
+            }
+            : null,
+    };
+}
+/**
+ * Descrição do recebível a partir dos seus itens.
+ *
+ * Hoje tanto a geração por competência quanto o avulso criam exatamente UM
+ * item, mas o schema permite vários (RFC §4) — então junta em vez de pegar o
+ * primeiro: com dois itens, "Honorários" sozinho esconderia metade da dívida.
+ */
+const DESCRIPTION_SQL = `
+  (SELECT string_agg(i.description, ' · ' ORDER BY i.created_at, i.id)
+     FROM receivable_item i WHERE i.receivable_id = r.id)`;
+const SELECT_RECEIVABLE = `
+  SELECT r.id, r.client_id, c.display_name AS client_name, r.fee_agreement_id, r.competence,
+         r.amount, r.status, ${EFFECTIVE_STATUS_SQL} AS effective_status, r.generated_by,
+         r.due_date, r.issued_at, r.renegotiated_from_id, r.created_at, r.metadata,
+         ${DESCRIPTION_SQL} AS description,
+         ac.id AS charge_id, ac.status AS charge_status, ac.metadata AS charge_metadata,
+         COALESCE((SELECT sum(p.amount) FROM payment p
+                    WHERE p.receivable_id = r.id AND p.status = 'confirmed'), 0) AS amount_paid,
+         GREATEST(0, COALESCE(CURRENT_DATE - r.due_date, 0))::int AS days_overdue
+    FROM receivable r
+    LEFT JOIN client c ON c.id = r.client_id AND c.deleted_at IS NULL
+    -- LATERAL, e não uma subquery por coluna: as três colunas da cobrança
+    -- precisam vir da MESMA linha. Três subqueries independentes poderiam, com
+    -- mais de uma cobrança viva, montar um Frankenstein com o id de uma e os
+    -- meios de outra.
+    LEFT JOIN LATERAL (
+      SELECT ch.id, ch.status, ch.metadata
+        FROM charge ch
+       WHERE ch.receivable_id = r.id
+         AND ch.deleted_at IS NULL
+         AND ch.status NOT IN ('canceled', 'refunded')
+       ORDER BY ch.created_at DESC
+       LIMIT 1
+    ) ac ON true`;
+// ── Competência ──────────────────────────────────────────────────────────────
+const COMPETENCE_RE = /^\d{4}-(0[1-9]|1[0-2])$/;
+export function assertCompetence(competence) {
+    if (!COMPETENCE_RE.test(competence)) {
+        throw new ValidationError('Competência deve estar no formato YYYY-MM, com mês entre 01 e 12');
+    }
+}
+/**
+ * Data de vencimento de uma competência, respeitando o `due_day` do honorário.
+ *
+ * `due_day` é limitado a 28 no schema justamente para não existir "dia 31 de
+ * fevereiro"; ainda assim clampamos ao último dia do mês, porque a regra de
+ * negócio não pode depender de uma constraint continuar existindo.
+ */
+export function dueDateFor(competence, dueDay) {
+    assertCompetence(competence);
+    const [year, month] = competence.split('-').map(Number);
+    const lastDay = new Date(Date.UTC(year, month, 0)).getUTCDate();
+    const day = Math.min(Math.max(dueDay ?? lastDay, 1), lastDay);
+    return `${competence}-${String(day).padStart(2, '0')}`;
+}
+const DUE_DATE_RE = /^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/;
+/**
+ * Janela tolerada entre a competência e o vencimento de um lançamento avulso.
+ *
+ * No fluxo por competência não existe folga: `dueDateFor` devolve sempre uma data
+ * DENTRO do mês da competência. O avulso relaxa isso de propósito — competência e
+ * vencimento são campos independentes do payload — e é justamente aí que um erro
+ * de digitação vira "honorários de março/2027 vencendo em agosto/2026" no e-mail
+ * que o cliente lê.
+ *
+ * A folga é assimétrica porque a prática comercial é assimétrica: faturar um mês
+ * adiantado acontece; dar três meses de prazo acontece; sete meses de distância,
+ * em qualquer direção, não é arranjo comercial — é dedo trocado.
+ */
+const DUE_MONTHS_BEFORE_COMPETENCE = 1;
+const DUE_MONTHS_AFTER_COMPETENCE = 3;
+/**
+ * A competência e o vencimento informados fazem sentido juntos?
+ *
+ * Aritmética de mês em inteiros, não em `Date`: o que importa é a distância entre
+ * dois meses do calendário, e converter para instante só introduziria fuso onde
+ * não há hora nenhuma envolvida.
+ */
+export function checkCompetenceDueDate(competence, dueDate) {
+    assertCompetence(competence);
+    if (!DUE_DATE_RE.test(dueDate)) {
+        throw new ValidationError('Vencimento deve estar no formato YYYY-MM-DD');
+    }
+    const monthIndex = (year, month) => year * 12 + (month - 1);
+    const [cy, cm] = competence.split('-').map(Number);
+    const [dy, dm] = dueDate.split('-').map(Number);
+    const monthsFromCompetence = monthIndex(dy, dm) - monthIndex(cy, cm);
+    const coherent = monthsFromCompetence >= -DUE_MONTHS_BEFORE_COMPETENCE &&
+        monthsFromCompetence <= DUE_MONTHS_AFTER_COMPETENCE;
+    return { coherent, monthsFromCompetence };
+}
+/**
+ * Mensagem do 422. Diz o que veio, qual é a distância e como confirmar — quem lê
+ * precisa conseguir decidir entre "corrigi o dedo trocado" e "é isso mesmo".
+ */
+function competenceMismatchMessage(competence, dueDate, monthsFromCompetence) {
+    const distance = Math.abs(monthsFromCompetence);
+    const direction = monthsFromCompetence < 0 ? 'antes' : 'depois';
+    const plural = distance === 1 ? 'mês' : 'meses';
+    return (`Competência ${competence} com vencimento em ${dueDate}: o vencimento está ` +
+        `${distance} ${plural} ${direction} do mês da competência. O esperado é entre ` +
+        `${DUE_MONTHS_BEFORE_COMPETENCE} mês antes e ${DUE_MONTHS_AFTER_COMPETENCE} meses ` +
+        `depois. Se a combinação está correta, reenvie confirmando explicitamente ` +
+        `(competenceMismatchAck).`);
+}
+/** Ver `FeeCompetenceVerdict`. Pura: nenhum I/O, nenhum relógio. */
+export function classifyFeeForCompetence(fee, competence) {
+    if (fee.status === 'suspended')
+        return 'suspended';
+    if (fee.status !== 'active')
+        return 'canceled';
+    const first = `${competence}-01`;
+    const [year, month] = competence.split('-').map(Number);
+    const last = `${competence}-${String(new Date(Date.UTC(year, month, 0)).getUTCDate()).padStart(2, '0')}`;
+    // Vigência: o honorário precisa estar valendo em ALGUM dia da competência.
+    if (fee.startsOn && fee.startsOn > last)
+        return 'before_term';
+    if (fee.endsOn && fee.endsOn < first)
+        return 'after_term';
+    switch (fee.periodicity) {
+        case 'monthly':
+            return 'eligible';
+        // Trimestral/anual ancoram no mês de início da vigência — sem `startsOn` não
+        // há âncora, e gerar todo mês seria cobrar a mais. Fail-safe: não gera.
+        case 'quarterly': {
+            if (!fee.startsOn)
+                return 'no_anchor';
+            const anchor = Number(fee.startsOn.slice(5, 7));
+            return (month - anchor) % 3 === 0 ? 'eligible' : 'off_cycle';
+        }
+        case 'yearly': {
+            if (!fee.startsOn)
+                return 'no_anchor';
+            return Number(fee.startsOn.slice(5, 7)) === month ? 'eligible' : 'off_cycle';
+        }
+        // Avulso nunca é gerado em lote: nasce por lançamento manual.
+        case 'one_time':
+            return 'one_time';
+        default:
+            return 'off_cycle';
+    }
+}
+/** Um honorário vale para a competência? Considera vigência e periodicidade. */
+export function feeAppliesTo(fee, competence) {
+    return classifyFeeForCompetence(fee, competence) === 'eligible';
+}
+/**
+ * Gera os recebíveis de uma competência a partir dos honorários ativos.
+ *
+ * Idempotente por construção: o índice único `(tenant_id, fee_agreement_id,
+ * competence)` do M0 é a garantia real, e o `ON CONFLICT DO NOTHING` a
+ * transforma em "pular" em vez de "explodir". Rodar duas vezes no mesmo mês não
+ * duplica cobrança — o que aqui não é detalhe técnico: cobrar o cliente duas
+ * vezes é o erro que destrói a confiança no sistema.
+ */
+export async function generateReceivablesForCompetence(tx, input) {
+    assertCompetence(input.competence);
+    const source = input.source ?? 'manual';
+    const fees = await tx `
+    SELECT id, client_id, description, amount, periodicity, due_day, discount, status, starts_on, ends_on
+      FROM fee_agreement
+     WHERE deleted_at IS NULL
+       ${input.feeAgreementIds?.length ? tx `AND id IN ${tx(input.feeAgreementIds)}` : tx ``}
+  `;
+    const created = [];
+    let skipped = 0;
+    let notApplicable = 0;
+    for (const fee of fees) {
+        // A decisão de gerar vem de UM lugar só.
+        //
+        // Até a fase 2.3 havia duas: um `AND status = 'active'` no SELECT acima e a
+        // checagem de status dentro de `feeAppliesTo`. As duas concordavam, e por
+        // isso o arranjo parecia inofensivo — mas um teste de mutação mostrou o
+        // custo: com a regra do status quebrada dentro da função, o SELECT continuava
+        // segurando, e nenhum teste de "suspenso não gera" reprovava. A garantia
+        // estava numa cláusula SQL que ninguém estava testando, enquanto o dry-run
+        // — que decide se o scheduler pode ser ligado — usava a OUTRA cópia.
+        //
+        // Duas cópias de uma regra financeira só precisam divergir uma vez.
+        const verdict = classifyFeeForCompetence({
+            periodicity: fee.periodicity,
+            startsOn: iso(fee.starts_on),
+            endsOn: iso(fee.ends_on),
+            status: fee.status,
+        }, input.competence);
+        if (verdict !== 'eligible') {
+            // Suspenso e encerrado ficam FORA da contagem, e não é descuido: quem lê
+            // "3 fora de vigência" na tela está perguntando quantos acordos vigentes o
+            // calendário deixou de fora nesta competência. Um acordo cancelado no ano
+            // passado não é resposta a essa pergunta, e somá-lo aqui inflaria o número
+            // todo mês, para sempre, com o acervo morto do escritório.
+            if (verdict !== 'suspended' && verdict !== 'canceled')
+                notApplicable += 1;
+            continue;
+        }
+        // O desconto acordado entra no valor do recebível: a dívida é o líquido, e
+        // guardar o bruto obrigaria toda leitura a lembrar de subtrair.
+        const amount = Math.max(0, Number(fee.amount) - Number(fee.discount));
+        const dueDate = dueDateFor(input.competence, fee.due_day);
+        const receivableId = uuidv7();
+        const rows = await tx `
+      INSERT INTO receivable (id, tenant_id, client_id, fee_agreement_id, competence,
+                              amount, status, due_date, created_by, generated_by)
+      VALUES (${receivableId},
+              (NULLIF(current_setting('app.current_tenant', true), ''))::uuid,
+              ${fee.client_id}, ${fee.id}, ${input.competence},
+              ${amount}, 'open', ${dueDate}, ${input.createdBy ?? null}, ${source})
+      -- O predicado precisa casar EXATAMENTE com o do índice parcial do M0,
+      -- senão o Postgres não reconhece o índice e o INSERT volta a estourar.
+      ON CONFLICT (tenant_id, fee_agreement_id, competence)
+        WHERE fee_agreement_id IS NOT NULL AND competence IS NOT NULL AND deleted_at IS NULL
+      DO NOTHING
+      RETURNING id
+    `;
+        if (!rows[0]) {
+            skipped += 1;
+            continue;
+        }
+        await tx `
+      INSERT INTO receivable_item (id, tenant_id, receivable_id, description, amount)
+      VALUES (${uuidv7()},
+              (NULLIF(current_setting('app.current_tenant', true), ''))::uuid,
+              ${receivableId}, ${fee.description}, ${amount})
+    `;
+        const full = await getReceivable(tx, receivableId);
+        created.push(full);
+    }
+    return { competence: input.competence, created, skipped, notApplicable };
+}
+/**
+ * Lançamento avulso — serviço extra que não vem de honorário recorrente.
+ *
+ * A guarda de coerência mora AQUI, e não na rota, porque quem chama o domínio
+ * direto (script de importação, backfill, outro serviço) precisa da mesma
+ * proteção que o operador tem pela tela. Uma validação só na borda HTTP protege
+ * a borda HTTP.
+ */
+export async function createOneOffReceivable(tx, input) {
+    if (input.amount <= 0)
+        throw new ValidationError('Valor deve ser maior que zero');
+    if (input.competence) {
+        const check = checkCompetenceDueDate(input.competence, input.dueDate);
+        if (!check.coherent && !input.competenceMismatchAck) {
+            throw new ValidationError(competenceMismatchMessage(input.competence, input.dueDate, check.monthsFromCompetence));
+        }
+    }
+    const id = uuidv7();
+    const notes = input.notes?.trim() || null;
+    const serviceCategory = input.serviceCategory?.trim() || null;
+    const metadata = {};
+    if (notes)
+        metadata.notes = notes;
+    if (serviceCategory)
+        metadata.serviceCategory = serviceCategory;
+    // `ON CONFLICT DO NOTHING` sobre a chave da tentativa: quem chega primeiro
+    // grava, quem repete não insere e é devolvido ao recebível existente. A
+    // alternativa — consultar antes e inserir depois — deixa uma janela entre as
+    // duas operações, e duplo clique acontece exatamente dentro dela.
+    const inserted = await tx `
+    INSERT INTO receivable (id, tenant_id, client_id, fee_agreement_id, competence,
+                            amount, status, due_date, created_by, idempotency_key, metadata)
+    VALUES (${id},
+            (NULLIF(current_setting('app.current_tenant', true), ''))::uuid,
+            ${input.clientId}, NULL, ${input.competence ?? null},
+            ${input.amount}, 'open', ${input.dueDate}, ${input.createdBy ?? null},
+            ${input.idempotencyKey ?? null}, ${tx.json(metadata)})
+    ON CONFLICT (tenant_id, idempotency_key) WHERE idempotency_key IS NOT NULL
+      DO NOTHING
+    RETURNING id
+  `;
+    if (!inserted[0]) {
+        // Tentativa repetida. Devolve o que a primeira criou — nunca um erro: para
+        // quem clicou duas vezes, o lançamento deu certo, e um 409 mandaria a pessoa
+        // tentar de novo.
+        const existing = await tx `
+      SELECT id FROM receivable
+       WHERE idempotency_key = ${input.idempotencyKey ?? null} AND deleted_at IS NULL
+    `;
+        if (!existing[0])
+            throw new ConflictError('Lançamento avulso em conflito');
+        return getReceivable(tx, existing[0].id);
+    }
+    await tx `
+    INSERT INTO receivable_item (id, tenant_id, receivable_id, description, amount)
+    VALUES (${uuidv7()},
+            (NULLIF(current_setting('app.current_tenant', true), ''))::uuid,
+            ${id}, ${input.description}, ${input.amount})
+  `;
+    return getReceivable(tx, id);
+}
+/**
+ * O WHERE compartilhado entre a página e a contagem.
+ *
+ * Escrito uma vez de propósito: quando a lista e o total repetiam os mesmos
+ * predicados lado a lado, bastava acrescentar um filtro num deles para a tela
+ * dizer "mostrando 12 de 47" com os dois números medindo carteiras diferentes.
+ */
+function receivableWhere(tx, filter) {
+    const search = filter.search?.trim();
+    return tx `
+    r.deleted_at IS NULL
+      ${filter.clientId ? tx `AND r.client_id = ${filter.clientId}` : tx ``}
+      ${filter.competence ? tx `AND r.competence = ${filter.competence}` : tx ``}
+      ${filter.status ? tx `AND ${tx.unsafe(EFFECTIVE_STATUS_SQL)} = ${filter.status}` : tx ``}
+      ${filter.openOnly ? tx `AND r.status IN ('open','partially_paid','overdue')` : tx ``}
+      ${filter.overdueOnly ? tx `AND ${tx.unsafe(EFFECTIVE_STATUS_SQL)} = 'overdue'` : tx ``}
+      ${filter.origin
+        ? filter.origin === 'recurring'
+            ? tx `AND r.fee_agreement_id IS NOT NULL`
+            : tx `AND r.fee_agreement_id IS NULL`
+        : tx ``}
+      ${filter.dueFrom ? tx `AND r.due_date >= ${filter.dueFrom}::date` : tx ``}
+      ${filter.dueTo ? tx `AND r.due_date <= ${filter.dueTo}::date` : tx ``}
+      ${search
+        ? tx `AND (c.display_name ILIKE ${'%' + search + '%'}
+                    OR EXISTS (SELECT 1 FROM receivable_item i
+                                WHERE i.receivable_id = r.id
+                                  AND i.description ILIKE ${'%' + search + '%'}))`
+        : tx ``}
+  `;
+}
+export async function listReceivables(tx, filter = {}) {
+    const limit = Math.min(Math.max(filter.limit ?? 50, 1), 200);
+    const offset = Math.max(filter.offset ?? 0, 0);
+    const where = receivableWhere(tx, filter);
+    const rows = await tx `
+    ${tx.unsafe(SELECT_RECEIVABLE)}
+     WHERE ${where}
+     ORDER BY r.due_date NULLS LAST, r.created_at
+     LIMIT ${limit} OFFSET ${offset}
+  `;
+    // O `LEFT JOIN client` acompanha a contagem porque a busca textual alcança o
+    // nome do cliente: sem ele, filtrar por nome quebraria o total.
+    const totals = await tx `
+    SELECT count(*) AS n FROM receivable r
+     LEFT JOIN client c ON c.id = r.client_id AND c.deleted_at IS NULL
+     WHERE ${where}
+  `;
+    return { items: rows.map(mapReceivable), total: Number(totals[0]?.n ?? 0) };
+}
+export async function getReceivable(tx, id) {
+    const rows = await tx `
+    ${tx.unsafe(SELECT_RECEIVABLE)} WHERE r.id = ${id} AND r.deleted_at IS NULL
+  `;
+    const row = rows[0];
+    if (!row)
+        throw new NotFoundError('Recebível não encontrado');
+    return mapReceivable(row);
+}
+export async function listReceivableItems(tx, receivableId) {
+    const rows = await tx `
+    SELECT id, receivable_id, description, amount, service_item_ref, created_at
+      FROM receivable_item WHERE receivable_id = ${receivableId} ORDER BY created_at
+  `;
+    return rows.map((r) => ({
+        id: r.id,
+        receivableId: r.receivable_id,
+        description: r.description,
+        amount: Number(r.amount),
+        serviceItemRef: r.service_item_ref,
+        createdAt: r.created_at.toISOString(),
+    }));
+}
+export async function listPayments(tx, receivableId) {
+    const rows = await tx `
+    SELECT id, receivable_id, charge_id, amount, method, status, paid_at, created_at
+      FROM payment WHERE receivable_id = ${receivableId} ORDER BY paid_at
+  `;
+    return rows.map((r) => ({
+        id: r.id,
+        receivableId: r.receivable_id,
+        chargeId: r.charge_id,
+        amount: Number(r.amount),
+        method: r.method,
+        status: r.status,
+        paidAt: r.paid_at.toISOString(),
+        createdAt: r.created_at.toISOString(),
+    }));
+}
+/**
+ * Registra dinheiro recebido e reavalia o status do recebível.
+ *
+ * A soma dos pagamentos confirmados é a fonte da verdade do que foi pago — o
+ * status é consequência dela, nunca o contrário. Por isso o recálculo lê a soma
+ * do banco em vez de somar em memória: dois lançamentos concorrentes não podem
+ * produzir um `paid` com saldo em aberto.
+ */
+export async function registerPayment(tx, input) {
+    if (input.amount <= 0)
+        throw new ValidationError('Valor do pagamento deve ser maior que zero');
+    const current = await getReceivable(tx, input.receivableId);
+    if (current.status === 'canceled') {
+        throw new ConflictError('Recebível cancelado não aceita baixa');
+    }
+    if (input.amount > current.outstandingAmount + 0.001) {
+        throw new ValidationError(`Valor excede o saldo em aberto (${current.outstandingAmount.toFixed(2)})`);
+    }
+    await tx `
+    INSERT INTO payment (id, tenant_id, receivable_id, charge_id, amount, method, status, paid_at, metadata)
+    VALUES (${uuidv7()},
+            (NULLIF(current_setting('app.current_tenant', true), ''))::uuid,
+            ${input.receivableId}, ${input.chargeId ?? null}, ${input.amount},
+            ${input.method ?? 'manual'}, 'confirmed',
+            ${input.paidAt ?? new Date().toISOString()},
+            ${tx.json({ note: input.note ?? null })})
+  `;
+    const [totals] = await tx `
+    SELECT COALESCE((SELECT sum(p.amount) FROM payment p
+                      WHERE p.receivable_id = r.id AND p.status = 'confirmed'), 0) AS paid,
+           r.amount
+      FROM receivable r WHERE r.id = ${input.receivableId}
+  `;
+    const paid = Number(totals.paid);
+    const total = Number(totals.amount);
+    // Tolerância de um centavo: `numeric(14,2)` não sofre erro de ponto flutuante,
+    // mas o valor chega da borda HTTP como number — e 0.1+0.2 continua sendo
+    // 0.30000000000000004 em JavaScript.
+    const nextStatus = paid + 0.001 >= total ? 'paid' : 'partially_paid';
+    await tx `
+    UPDATE receivable
+       SET status = ${nextStatus},
+           updated_at = now(),
+           version = version + 1
+     WHERE id = ${input.receivableId}
+  `;
+    return getReceivable(tx, input.receivableId);
+}
+/**
+ * Anula a liquidação registrada para uma cobrança — o dinheiro nunca entrou.
+ *
+ * Não confundir com estorno. No estorno o dinheiro **entrou e saiu**: são dois
+ * fatos de caixa, a dívida foi quitada, e reabri-la seria cobrar de novo algo
+ * que foi pago. Aqui não há fato novo — há um fato anterior que deixou de valer,
+ * e manter o recebível quitado seria o sistema afirmando um recebimento que a
+ * própria origem já negou.
+ *
+ * **Nada é apagado.** A linha de `payment` permanece com valor, método e data em
+ * que se acreditou ter recebido; ela sai do saldo e passa a dizer quando e por
+ * que foi anulada. `charge.paid_at` também permanece — é o registro de quando a
+ * cobrança esteve liquidada.
+ *
+ * **Idempotente por construção:** o `UPDATE` só alcança pagamentos ainda
+ * `confirmed`. Uma segunda reversão do mesmo evento encontra zero linhas, não
+ * mexe em nada e devolve `reversedPayments: 0`. Não há contador a decrementar
+ * duas vezes.
+ *
+ * Só toca pagamentos **desta cobrança**. Uma baixa manual que o escritório deu
+ * por fora (`charge_id IS NULL`) é outro fato, de outra origem, e o gateway não
+ * tem autoridade sobre ela.
+ */
+export async function reverseSettlementForCharge(tx, chargeId, reason) {
+    const reversed = await tx `
+    UPDATE payment
+       SET status = 'reversed', reversed_at = now(), reversal_reason = ${reason}
+     WHERE charge_id = ${chargeId} AND status = 'confirmed'
+    RETURNING receivable_id, amount
+  `;
+    // A cobrança sai de `paid` mesmo quando não havia pagamento a anular: o evento
+    // é da origem, e o estado tem de refletir o que ela diz. `reversed` não entra
+    // na lista de cobranças mortas — o boleto ou o PIX continuam pagáveis, e esta
+    // segue sendo a cobrança viva do recebível.
+    await tx `
+    UPDATE charge
+       SET status = 'reversed', reversed_at = now(), updated_at = now()
+     WHERE id = ${chargeId} AND status IN ('paid', 'sent', 'pending', 'overdue')
+  `;
+    const receivableId = reversed[0]?.receivable_id ?? null;
+    const reversedAmount = reversed.reduce((sum, r) => sum + Number(r.amount), 0);
+    if (!receivableId) {
+        return {
+            reversedPayments: reversed.length,
+            reversedAmount,
+            receivableId: null,
+            receivable: null,
+        };
+    }
+    // O status do recebível é recalculado a partir do que SOBROU de confirmado —
+    // nunca assumido como `open`. Uma baixa parcial anterior, ou uma baixa manual
+    // do escritório, continua valendo e o recebível continua parcialmente pago.
+    const [totals] = await tx `
+    SELECT COALESCE((SELECT sum(p.amount) FROM payment p
+                      WHERE p.receivable_id = r.id AND p.status = 'confirmed'), 0) AS paid,
+           r.amount
+      FROM receivable r WHERE r.id = ${receivableId}
+  `;
+    const paid = Number(totals.paid);
+    const total = Number(totals.amount);
+    const nextStatus = paid + 0.001 >= total ? 'paid' : paid > 0 ? 'partially_paid' : 'open';
+    // `canceled`, `renegotiated` e `written_off` são decisões do escritório sobre
+    // a dívida, e um evento de gateway não as revoga.
+    await tx `
+    UPDATE receivable
+       SET status = ${nextStatus}, updated_at = now(), version = version + 1
+     WHERE id = ${receivableId}
+       AND status IN ('open', 'partially_paid', 'paid', 'overdue')
+  `;
+    return {
+        reversedPayments: reversed.length,
+        reversedAmount,
+        receivableId,
+        receivable: await getReceivable(tx, receivableId),
+    };
+}
+/**
+ * Cancela a obrigação, preservando o que já foi pago.
+ *
+ * ## Cancelar não é pagar, e não é estornar
+ *
+ * O que morre aqui é o **saldo em aberto**. O dinheiro que já entrou continua
+ * tendo entrado: os pagamentos não são tocados, e seguem somando em "Recebido".
+ * Transformar o saldo cancelado em recebimento inventaria receita; apagar o
+ * pagamento anterior apagaria dinheiro que existe na conta do escritório.
+ *
+ * ## Por que aceita pagamento parcial agora
+ *
+ * A versão anterior recusava qualquer recebível com pagamento — o que deixava
+ * sem saída exatamente o caso mais comum de cancelamento legítimo: cliente pagou
+ * parte, o serviço foi cancelado, e o resto não é mais devido. Sem esta operação,
+ * a única forma de tirar o saldo do painel seria fingir um pagamento ou apagar a
+ * linha no banco. As duas são piores.
+ *
+ * Recebível **totalmente pago** continua recusado: ali não há obrigação a
+ * cancelar, e desfazer dinheiro recebido é estorno — outra operação, com outras
+ * consequências contábeis.
+ */
+export async function cancelReceivable(tx, id, input) {
+    const motivo = input.reason?.trim() ?? '';
+    if (motivo.length < 3) {
+        throw new ValidationError('Informe o motivo do cancelamento — ele fica na trilha de auditoria e é o que explica, depois, por que esta cobrança deixou de existir.');
+    }
+    const current = await getReceivable(tx, id);
+    if (current.status === 'canceled') {
+        throw new ConflictError('Este recebível já está cancelado.');
+    }
+    if (current.outstandingAmount <= 0) {
+        // Sem saldo, não há obrigação a cancelar. Se houve pagamento, o caminho é
+        // estorno; se o valor era zero, não havia o que cobrar.
+        throw new ConflictError('Não há saldo em aberto para cancelar. Um recebível quitado se desfaz por estorno do pagamento, não por cancelamento.');
+    }
+    // Fail-closed: cobrança viva no gateway não pode ficar órfã de obrigação.
+    //
+    // Cancelar só do lado de cá deixaria no provedor um boleto que o cliente ainda
+    // consegue pagar — e o escritório achando que cancelou. É o mesmo defeito que
+    // a auditoria encontrou no cancelamento de cobrança, com o dinheiro indo na
+    // direção contrária.
+    const [viva] = await tx `
+    SELECT count(*)::int AS n FROM charge
+     WHERE receivable_id = ${id}
+       AND deleted_at IS NULL
+       AND provider <> 'manual'
+       AND status NOT IN ('canceled', 'refunded')
+  `;
+    if ((viva?.n ?? 0) > 0) {
+        throw new ConflictError('Este recebível tem cobrança emitida no provedor de pagamento. Cancele a cobrança primeiro — cancelar só aqui deixaria um boleto que o cliente ainda consegue pagar.', { code: 'RECEIVABLE_HAS_ACTIVE_EXTERNAL_CHARGE' });
+    }
+    const canceledOutstanding = current.outstandingAmount;
+    const preservedPayments = current.amountPaid;
+    await tx `
+    UPDATE receivable
+       SET status = 'canceled',
+           metadata = coalesce(metadata, '{}'::jsonb) || ${tx.json({
+        canceledReason: motivo,
+        canceledAt: new Date().toISOString(),
+        canceledBy: input.actorId ?? null,
+        canceledFromStatus: current.effectiveStatus,
+        canceledOutstanding,
+        preservedPayments,
+    })},
+           updated_at = now(),
+           version = version + 1
+     WHERE id = ${id} AND deleted_at IS NULL
+  `;
+    const atual = await getReceivable(tx, id);
+    return { ...atual, canceledOutstanding, preservedPayments };
+}
+/**
+ * Materializa a transição para `overdue`.
+ *
+ * A leitura já deriva o vencido (ver nota no topo) — esta função existe para dar
+ * um INSTANTE à transição, que é o que a régua de cobrança precisa para disparar
+ * `RECEIVABLE_OVERDUE` uma única vez. Retorna os ids afetados justamente para
+ * quem for emitir os eventos na próxima onda.
+ */
+export async function markOverdueReceivables(tx) {
+    const rows = await tx `
+    UPDATE receivable
+       SET status = 'overdue', updated_at = now(), version = version + 1
+     WHERE deleted_at IS NULL
+       AND status = 'open'
+       AND due_date IS NOT NULL
+       AND due_date < CURRENT_DATE
+    RETURNING id
+  `;
+    return rows.map((r) => r.id);
+}
+export async function financialSummary(tx) {
+    const [r] = await tx `
+    -- Cancelado sai da base de OBRIGAÇÃO, e o dinheiro já recebido fica.
+    --
+    -- A base exclui cancelados porque eles não são mais exigíveis: não entram em
+    -- "A receber", "Vencido" nem "A vencer". Mas o pagamento que já entrou
+    -- ENTROU — cancelar a obrigação não devolve dinheiro ao cliente, e tirá-lo
+    -- de "Recebido" faria o total do escritório encolher sozinho no dia em que
+    -- alguém cancelasse um recebível parcialmente pago.
+    --
+    -- Por isso "Recebido" é somado à parte, sobre todos os recebíveis vivos.
+    WITH base AS (
+      SELECT r.*, ${tx.unsafe(EFFECTIVE_STATUS_SQL)} AS eff,
+             COALESCE((SELECT sum(p.amount) FROM payment p
+                        WHERE p.receivable_id = r.id AND p.status = 'confirmed'), 0) AS paid
+        FROM receivable r WHERE r.deleted_at IS NULL AND r.status <> 'canceled'
+    ),
+    recebido AS (
+      SELECT COALESCE(sum(p.amount), 0) AS total
+        FROM payment p
+        JOIN receivable r ON r.id = p.receivable_id AND r.deleted_at IS NULL
+       WHERE p.status = 'confirmed'
+    )
+    SELECT
+      COALESCE(sum(amount), 0) AS total_receivable,
+      COALESCE(sum(amount - paid) FILTER (WHERE eff IN ('open','partially_paid','overdue')), 0) AS total_open,
+      COALESCE(sum(amount - paid) FILTER (WHERE eff = 'overdue'), 0) AS total_overdue,
+      (SELECT total FROM recebido) AS total_paid,
+      COALESCE(sum(amount - paid) FILTER (
+        WHERE eff IN ('open','partially_paid')
+          AND due_date BETWEEN CURRENT_DATE AND CURRENT_DATE + 7), 0) AS total_due_soon,
+      COALESCE(count(DISTINCT client_id) FILTER (WHERE eff = 'overdue'), 0)::int AS overdue_client_count,
+      COALESCE(count(*) FILTER (WHERE eff IN ('open','partially_paid','overdue')), 0)::int AS open_count,
+      COALESCE(count(*) FILTER (WHERE eff = 'overdue'), 0)::int AS overdue_count
+      FROM base
+  `;
+    return {
+        totalReceivable: Number(r.total_receivable),
+        totalOpen: Number(r.total_open),
+        totalOverdue: Number(r.total_overdue),
+        totalPaid: Number(r.total_paid),
+        totalDueSoon: Number(r.total_due_soon),
+        overdueClientCount: r.overdue_client_count,
+        openCount: r.open_count,
+        overdueCount: r.overdue_count,
+    };
+}
+/**
+ * Faixas de aging. Padrão do produto, **não** política imutável: as faixas são
+ * parâmetro justamente para que um escritório possa usar as suas sem alteração
+ * de código.
+ */
+export const DEFAULT_AGING_BUCKETS = [
+    { label: '1-7', from: 1, to: 7 },
+    { label: '8-15', from: 8, to: 15 },
+    { label: '16-30', from: 16, to: 30 },
+    { label: '31-60', from: 31, to: 60 },
+    { label: '61-90', from: 61, to: 90 },
+    { label: '90+', from: 91, to: null },
+];
+export async function agingBuckets(tx, buckets = DEFAULT_AGING_BUCKETS) {
+    const rows = await tx `
+    SELECT (CURRENT_DATE - r.due_date)::int AS days_overdue,
+           (r.amount - COALESCE((SELECT sum(p.amount) FROM payment p
+                                  WHERE p.receivable_id = r.id AND p.status = 'confirmed'), 0)) AS outstanding,
+           r.client_id
+      FROM receivable r
+     WHERE r.deleted_at IS NULL
+       AND r.status IN ('open','partially_paid','overdue')
+       AND r.due_date IS NOT NULL
+       AND r.due_date < CURRENT_DATE
+  `;
+    return buckets.map((b) => {
+        const inBucket = rows.filter((r) => r.days_overdue >= b.from && (b.to === null || r.days_overdue <= b.to));
+        return {
+            ...b,
+            amount: Number(inBucket.reduce((s, r) => s + Number(r.outstanding), 0).toFixed(2)),
+            count: inBucket.length,
+            clientCount: new Set(inBucket.map((r) => r.client_id)).size,
+        };
+    });
+}
+/** Situação financeira de um cliente — usada no console e no portal. */
+export async function clientFinancialSummary(tx, clientId) {
+    const [r] = await tx `
+    WITH base AS (
+      SELECT r.*, ${tx.unsafe(EFFECTIVE_STATUS_SQL)} AS eff,
+             COALESCE((SELECT sum(p.amount) FROM payment p
+                        WHERE p.receivable_id = r.id AND p.status = 'confirmed'), 0) AS paid
+        FROM receivable r
+       WHERE r.deleted_at IS NULL AND r.client_id = ${clientId} AND r.status <> 'canceled'
+    )
+    SELECT
+      COALESCE(sum(amount - paid) FILTER (WHERE eff IN ('open','partially_paid','overdue')), 0) AS open,
+      COALESCE(sum(amount - paid) FILTER (WHERE eff = 'overdue'), 0) AS overdue,
+      COALESCE(sum(paid), 0) AS paid,
+      min(due_date) FILTER (WHERE eff IN ('open','partially_paid')) AS next_due
+      FROM base
+  `;
+    return {
+        open: Number(r.open),
+        overdue: Number(r.overdue),
+        paid: Number(r.paid),
+        nextDueDate: iso(r.next_due),
+    };
+}
+export { OPEN_STATUSES };
+//# sourceMappingURL=ar-repository.js.map