Regras de negócio centrais¶

Esta página é o mapa das regras do produto, bloco a bloco, com a spec de origem de cada uma — "spec 0057, RN7" quer dizer a regra RN7 da seção 9 de ../specifications/0057-taxa-da-mensalidade/. O detalhe (códigos de erro, ordem das recusas, casos de borda) fica na spec. Para os termos, ver o glossário.

Quando a spec e o código divergem, vale o código, e a seção Registro de cada spec diz o que mudou na implementação. Tudo aqui foi conferido contra apps/api/app/ em 2026-10-15; o que não pôde ser confirmado está marcado a confirmar.

Base de cálculo — Pacote Locatício¶

Tudo incide sobre o Pacote Locatício = aluguel + condomínio + IPTU, com condomínio e IPTU contando zero quando ausentes (spec 0006; services/pricing.py). Sobre ele:

• mensalidade = Pacote × taxa da garantia ÷ 100;
• LMI = Pacote × lmi_months_multiplier (0 = ilimitado);
• custos de saída = Pacote × exit_costs_multiplier, sub-limite próprio e menor (0 = sem cobertura);
• taxa de adesão percentual = percentual sobre o Pacote, o Pacote × meses da vigência ou o LMI, conforme a base escolhida.

Arredondamento a centavo, meio para cima, em toda conta de dinheiro.

Parâmetros da garantidora (TenantSettings)¶

Editados em PATCH /api/v1/settings, só pelo ADMIN_TENANT (tela Parâmetros). Os principais:

A taxa padrão única e a faixa única de mensalidade (guarantee_rate_percent, min_/max_guarantee_rate_percent) deixaram de existir com a spec 0057. A imobiliária lê os parâmetros (para saber cobrar o inquilino), mas recebe commission_percent nulo — o padrão das outras parceiras é informação de negociação (spec 0056, RN1).

Análise de crédito e estados¶

• Os estados e as transições estão no glossário e em ALLOWED_TRANSITIONS (services/credit_analysis_service.py). APPROVED, REJECTED e CANCELLED são terminais.
• Quem cadastra: OPERATOR, AGENCY_USER/AGENCY_MANAGER e ADMIN_TENANT. A imobiliária da análise vem do imóvel e não muda depois de criada (spec 0056, RN5).
• Devolver em pendência exige um tipo de pendência, vocabulário que o ADMIN_TENANT mantém (spec 0037). Quem cadastrou corrige e retoma (PENDING → IN_ANALYSIS); o analista pode corrigir erro evidente sem devolver (spec 0036, RN13).
• Desistir é da imobiliária, com motivo, e só em DRAFT, SUBMITTED ou PENDING; cancelar é da garantidora — são permissões distintas (spec 0037).
• Recomendação automática pela razão renda declarada ÷ Pacote: aprovar a partir de 3×, análise manual entre 2× e 3×, reprovar abaixo de 2× (services/credit.py). É sugestão; quem decide é o analista.
• Taxa de adesão informada na análise: quando a regra em vigor permite editar, quem preenche a análise pode informar outro valor de adesão; quem informou fica gravado, e o valor sobrevive a mudança posterior da regra (spec 0056, RN4–RN6).

Consultas de crédito¶

Specs 0050 (a primeira, Boa Vista) e 0052 (o catálogo, que a substituiu):

• Catálogo da plataforma, mantido pelo ADMIN_GLOBAL, com itens de um provedor só, a API Full: Boa Vista Essencial, QUOD PF, Dados Financeiros, CADIN, Protesto Nacional e SCR Premium. QUOD e Boa Vista são mutuamente exclusivos numa composição (spec 0052, RN1–RN2).
• Cada garantidora escolhe a composição — NONE, ECONOMICO, COMPLETO ou PERSONALIZADO — e tem preço por item com vigência; preço novo é linha nova, nunca sobrescrita (spec 0052, RN3–RN5).
• Disparo na submissão da análise (DRAFT → SUBMITTED), em background no worker; a falha da consulta nunca desfaz a transição. Só para locatário principal pessoa física com CPF (spec 0050, RN5 e RN7; spec 0052, RN8a).
• Reexecutar ou acrescentar consulta tem custo confirmado antes. Uma consulta recente do mesmo locatário dentro da janela (padrão 30 dias, desligável) é reaproveitada em vez de paga de novo (spec 0052, RN9–RN10).
• Imutável depois de concluída; o retorno bruto do provedor é purgado após 12 meses pelo job diário das 6h (spec 0052, RN12–RN13).
• O resultado é só informativo — não entra na recomendação nem em cálculo nenhum (spec 0050, RN8; spec 0052, RN14).
• Quem vê: o resultado, quem tem credit_checks:read — ADMIN_TENANT, ANALYST, OPERATOR, VIEWER; o retorno bruto, só ADMIN_TENANT e ANALYST. Nem a imobiliária nem o ADMIN_GLOBAL veem consulta de cliente (spec 0052, RN22–RN24).
• Visão financeira: o extrato do provedor é sincronizado e conciliado com as consultas, com relatório de divergências e proposta de ajuste de preço — nunca automática (spec 0052, RN15–RN18).

Parecer — a mensalidade e a taxa de adesão¶

A mensalidade (spec 0057):

• O tipo do tomador decide a faixa: o tipo atual do locatário principal, lido no momento do uso; sem principal, o primeiro locatário; sem locatário, PF (RN6).
• Toda aprovação grava uma taxa: informada, precisa estar na faixa do tipo (senão 422 RATE_OUT_OF_RANGE); omitida, grava-se a sugerida. Garantidora sem parâmetros não aprova (422 SETTINGS_NOT_FOUND). Fica gravado quem fixou a taxa e quando (RN7–RN8).
• Alterar entre aprovar e emitir tem endpoint próprio (PATCH /credit-analyses/{id}/decision/guarantee-rate), com as mesmas permissões de aprovar (ADMIN_TENANT, ANALYST), auditado. Emitida a garantia, 409; o ADMIN_GLOBAL nunca altera (403). Alteração e emissão não se atravessam — as duas travam o parecer (RN9–RN10).
• A emissão usa a taxa em vigor e não a revalida: mudar a faixa depois não invalida o que foi decidido. Garantia emitida não muda de taxa — mudar o preço é encerrar e emitir outra (RN11, RN12, RN14).

A taxa de adesão (spec 0056):

• Regra em vigor: a própria da imobiliária, quando ela tem; senão a padrão da garantidora (inclusive na carteira própria). A comissão segue à parte: o percentual da imobiliária, ou o padrão (RN3).
• Precedência do valor na emissão: o valor que o analista tocou no parecer (approved_initial_fee_value); senão o informado na análise; senão o da regra em vigor na emissão (RN7).

Emissão e assinatura da garantia¶

• Só análise APPROVED emite, e só uma garantia por análise. Emitem ADMIN_TENANT, ANALYST e OPERATOR; o ADMIN_GLOBAL e a imobiliária, não (spec 0039, RN12–RN13; spec 0038).
• O valor garantido é o Pacote da análise, e a vigência não passa do prazo aprovado, contada em meses de calendário (mês parcial arredonda para cima); mínimo de um mês; início livre, passado ou futuro (spec 0039, RN1–RN8).
• O dia de vencimento é escolhido na emissão entre os allowed_due_days da garantidora (omitido, o primeiro da lista) (spec 0048, RN1).
• Toda garantia nasce Aguardando assinatura. Só o registro do contrato assinado — documento desta garantia mais a data, não futura — a leva a Vigente; garantia cuja vigência já acabou não se ativa, encerra-se. Registram ADMIN_TENANT e OPERATOR (spec 0038, RN2, RN6–RN8a). A assinatura em si é fora do sistema: não há integração de assinatura eletrônica.
• Vencida é derivada: vigente com end_date passada, no fuso de São Paulo (spec 0038, RN4–RN4d).
• Encerrar exige motivo, é só do ADMIN_TENANT e é irreversível. Cancela as cobranças do calendário ainda pendentes com vencimento futuro; as avulsas e as já vencidas ficam (spec 0038, RN14–RN15; spec 0048, RN4).

Cobrança¶

O calendário (spec 0048, RN2; spec 0054, RN6): ao registrar a assinatura, nasce na mesma transação o plano inteiro — a entrada (adesão, mais a 1ª mensalidade se a garantidora cobra o primeiro mês à vista) e as mensalidades do prazo. Cobrança nova só se cria em garantia vigente; dar baixa em cobrança já emitida vale em qualquer estado da garantia (spec 0038, RN12–RN13). A avulsa é lançada à mão, sempre no canal da garantidora (spec 0054, RN7).

Tipo e canal (spec 0054):

• Toda cobrança tem tipo (SETUP, GUARANTEE, SETUP_AND_GUARANTEE, MISC), e a entrada guarda adesão e fiança discriminadas — a soma das duas é sempre o valor (RN1–RN2).
• Toda cobrança tem canal, gravado quando nasce e nunca recalculado: a mensalidade é AGENCY_PIX se a parceira recolhe (collects_monthly), senão o meio da garantidora; a entrada e a avulsa são sempre da garantidora (RN3, RN9). Só a garantidora decide se a parceira recolhe — o ADMIN_GLOBAL não (RN11a).
• Toda cobrança tem competência obrigatória (RN5).

Encargo (spec 0054, RN12–RN14): multa e juros são calculados pela API, sobre o principal: multa percentual fixa; juros ao mês pro rata dia sobre 30 dias; nada dentro da carência; passada a carência, os juros correm desde o vencimento. Cobrança paga ou cancelada não acumula encargo. Isto revoga a multa sugerida e editável calculada na tela (spec 0048, RN5).

Baixa (spec 0054, RN15–RN22): informa a data em que o dinheiro entrou (não futura), o canal do pagamento e a distribuição entre adesão, fiança, avulsa e multa e juros. A distribuição fecha com o valor recebido, nenhum balde é negativo nem passa do devido naquele item, e o total não passa de principal + encargo da data — não há crédito a favor do inquilino. Principal recebido a menos fica como abatido. Abonar o encargo exige motivo. O comprovante é um documento da cobrança. Só o ADMIN_TENANT dá baixa, e mensalidade de canal da imobiliária não tem baixa avulsa — ela se baixa no acerto (spec 0055, RN15).

Atraso e situação (spec 0054, RN23–RN25; spec 0055, RN16): o job diário das 7h marca em atraso a cobrança pendente vencida de canal da garantidora; a de canal da imobiliária fica Aguardando a imobiliária — não é inadimplência — até o fechamento do acerto dizer se o inquilino pagou. A fila de atrasados recorta pelo fato (venceu e não foi paga), não pelo status.

Agregados do mês (spec 0054, RN26–RN29): o resumo por tipo × canal e os indicadores fecham uma identidade — previsto = recebido + abatido + a receber da garantidora + a repassar pela imobiliária —, com encargo por fora. Resumo e exportação exigem tenant: o ADMIN_GLOBAL lê a lista de cobranças, mas não agrega nem exporta a carteira de um cliente.

Remoção lógica (spec 0049): imobiliária, inquilino, imóvel, análise, garantia e cobrança se removem sem apagar e se restauram em até 60 dias. Remover é de baixo para cima — a garantia com cobrança não removida não sai, e assim por diante (RN6); restaurar não depende do pai. Nada disso mexe no status de negócio. Remover e restaurar análise, garantia e cobrança é só do ADMIN_TENANT. Cobrança que um acerto fechado gravou não se altera, remove nem restaura (spec 0055, RN14; spec 0056, RN10).

Acerto com a imobiliária e comissão¶

O acerto (spec 0055) é o par (imobiliária, competência), e seus membros são as mensalidades AGENCY_PIX daquele mês de garantias daquela imobiliária, não removidas nem canceladas (RN1). Não é criado por agendamento: existe quando há membro ou comissão, e o registro nasce na primeira escrita (RN2–RN3).

• Declaração por membro: pagou (data não futura, multa cobrada até o teto do encargo daquela data; o valor é sempre o da mensalidade) ou não pagou (só o que já venceu). Uma declaração substitui a anterior; há declaração em lote para "todos pagaram no vencimento" (RN5–RN8a). Declaram o AGENCY_MANAGER (do lado da imobiliária) e o ADMIN_TENANT.
• Transferências do repasse registradas pela garantidora, até o que a imobiliária deve (RN10; spec 0056, RN13).
• Fechar exige todo membro declarado e a conta zerada; numa transação, dá baixa nos declarados pagos pelo mesmo caminho da baixa avulsa e marca em atraso os declarados não pagos, revalidando cada declaração no momento. Reabrir exige motivo e desfaz as baixas, mantendo declarações, transferências e nota (RN11–RN13). O acerto fechado é imutável; cobrança que entra nele depois (emissão retroativa, restauração) é membro tardio e pede reabertura (RN14–RN14a).
• Nota fiscal do acerto fechado: número e arquivo, como documento do acerto (RN17).

A comissão (spec 0056):

• Na baixa da adesão de garantia com imobiliária, congela-se a comissão: impostos = adesão paga × commission_tax_percent; comissão = (adesão paga − impostos) × percentual de comissão em vigor. Depois de gravada não muda mais (RN8).
• Entra no acerto da primeira competência ainda não fechada a partir do mês do pagamento (RN9).
• As contas do acerto: mensalidades e multas − comissão = saldo; falta = saldo − recebido + pago à imobiliária. Positiva, a imobiliária deve; negativa, a garantidora deve, e paga registrando uma transferência no sentido inverso (TO_AGENCY). Recebido acima das mensalidades e multas, ou pago à imobiliária acima da comissão, impede o fechamento (RN11–RN13).

Quem faz o quê: ler, todos os papéis do tenant e a imobiliária (só a própria); declarar, ADMIN_TENANT e AGENCY_MANAGER; transferir, fechar, reabrir e anexar nota, só o ADMIN_TENANT; o ADMIN_GLOBAL não lê nem escreve acerto (spec 0055, 10.1–10.2 e RN23).

Papéis e escopo¶

Sete papéis de sistema (db/rbac_seed.py) — a tabela com o resumo de cada um está no glossário. Três regras atravessam todos:

• Isolamento por garantidora. Toda entidade de negócio carrega tenant_id, filtrado automaticamente pelo BaseRepository — nunca contornado, sempre passado pela camada de serviço. Recurso de outro tenant responde 404, indistinguível de inexistente (spec 0034).
• O segundo eixo: a imobiliária. AGENCY_USER e AGENCY_MANAGER só alcançam o que é da própria imobiliária — inquilinos, imóveis, análises, garantias, cobranças e acertos com o partner_agency_id dela (services/scoping.py). O vínculo vem do perfil de quem grava, nunca do corpo da requisição. Usuário de parceiro sem imobiliária não alcança nada (spec 0051, RN8a); remover a imobiliária suspende os usuários dela, e restaurá-la os devolve (spec 0051, RN9). A imobiliária não vê a tela agregada de Cobranças, as consultas de crédito nem o parecer.
• Plataforma × cliente. O ADMIN_GLOBAL não tem filtro de tenant, mas administra a plataforma — garantidoras, convites, catálogo de consultas —, não o negócio dos clientes. Guardas de código o recusam em: emitir garantia, alterar a mensalidade, dar baixa, remover análise, garantia ou cobrança, agregar ou exportar cobranças, ler ou escrever acerto, ver consultas de crédito, e definir se a parceira recolhe (specs 0039, 0048, 0049, 0052, 0054, 0055, 0057).

Quem administra os usuários da imobiliária: o AGENCY_MANAGER (convidar, reenviar, cancelar convite, remover acesso, tornar responsável), e o ADMIN_TENANT. A imobiliária não fica sem responsável enquanto tiver outro usuário ativo, e ninguém tira o próprio acesso (spec 0051, RN6–RN7b).

Além dos papéis de sistema, a garantidora pode criar perfis personalizados. O detalhe de quem pode cada endpoint está na seção 10 (Autorização e isolamento) de cada spec, e o mecanismo técnico em ../architecture/data-model.md.

Sinistro — o que existe e o que não existe¶

Não existe processo de sinistro no produto. Não há entidade, tela nem endpoint para comunicar inadimplência, validar, pagar a imobiliária ou registrar regresso.

O que existe:

• os parâmetros claim_grace_period_days e claim_trigger_days em TenantSettings, congelados em cada garantia na emissão — nada os consome;
• o LMI e os custos de saída, calculados e congelados na garantia;
• a inadimplência registrada na cobrança (status Em atraso, pelo job das 7h ou pelo fechamento do acerto) — é o dado de que um processo de sinistro partiria;
• o item Sinistros no menu, sem rota.

A regra que o contrato define (comunicado da imobiliária em até 60 dias do 1º vencimento, validação, pagamento à imobiliária, sub-rogação e regresso) e o plano para construí-la estão no roadmap. Uma consequência em aberto já registrada: o resumo do mês continua contando como "a repassar" a mensalidade que o acerto declarou não paga, porque classifica pelo canal — tratá-la como inadimplência em toda leitura é decisão que fica para quando o sinistro existir (spec 0055, Registro) — a confirmar.

Paginação — sempre com ORDER BY¶

Toda lista paginada ordena por created_at desc, id desc como desempate, salvo quando a spec da tela define outra ordem (a fila de atrasados, por vencimento; o acerto, por inquilino). Sem desempate, o PostgreSQL não garante ordem entre páginas — um registro editado pode aparecer duas vezes ou nunca. Regra de implementação, mas afeta o negócio: listas de centenas de análises e cobranças precisam ser confiáveis para quem trabalha nelas.