Glossário do domínio¶

Fonte: o código (apps/api/app/models/ e apps/api/app/domain/) e o CLAUDE.md da raiz, seção "Domínio" — reproduzido aqui como página de produto porque é o texto mais consultado por quem chega novo, e porque o CLAUDE.md foca em quem vai mexer no código, não em quem quer entender o negócio. Entre parênteses, o nome no código quando ele difere do nome de tela.

Quem é quem¶

• Garantidora (Tenant) — cliente do SaaS. Contrata a plataforma e, no negócio, é a fiadora (fiança onerosa) — não é parte do contrato de locação em si.
• Imobiliária parceira (PartnerAgency) — o canal: capta o cliente, fecha o aluguel e, quando a parceria prevê, recolhe a mensalidade da garantia junto com o aluguel e a repassa à garantidora. É também um segundo eixo de escopo: inquilino, imóvel, análise, garantia e usuário pertencem a uma imobiliária ou à carteira própria da garantidora (sem imobiliária).
• Inquilino (Renter, PF ou PJ) — quem contrata a garantia. A garantia é dele com a garantidora, formalizada por contrato assinado e pagamento.
• Tomador — o locatário principal da análise de crédito. É o tipo dele (PF ou PJ) que escolhe a faixa da mensalidade (spec 0057). Corresponsáveis e locatários não principais não contam.
• Corresponsável (CO_RESPONSIBLE) — participante que responde junto com o locatário; sempre pessoa física.
• Proprietário (locador) — fora da relação com a garantidora: ela não o conhece nem o paga. No sinistro a garantidora paga a imobiliária, que repassa ao locador. Os dados dele vivem em campos do imóvel (owner_name, owner_document…), não num cadastro de pessoa. Não existe "conta de repasse do proprietário" do lado da garantidora.
• Responsável da imobiliária (AGENCY_MANAGER) — o usuário da imobiliária que, além de operar, administra quem tem acesso por ela e declara no acerto quem pagou (specs 0051 e 0055).

Fluxo do dinheiro¶

Entrada — taxa de adesão, e a 1ª mensalidade junto quando a garantidora cobra o primeiro mês à vista — cobrada sempre pela garantidora, por boleto ou PIX. Do 2º mês em diante, a mensalidade chega por um de dois caminhos, e qual deles é cláusula da parceria (spec 0054): inquilino → imobiliária → garantidora, quando a parceira recolhe (PartnerAgency.collects_monthly), ou inquilino → garantidora direto, quando não recolhe. A imobiliária repassa só a garantia, nunca o aluguel, e o repasse é conferido mês a mês no acerto (spec 0055). Do mesmo acerto sai, no sentido inverso, a comissão que a garantidora devolve à imobiliária sobre a taxa de adesão (spec 0056).

Sinistro (regra do contrato, ainda não modelada no produto — ver o roadmap): inquilino não paga → imobiliária comunica (≤ 60 dias do 1º vencimento) → garantidora valida e paga a imobiliária (que repassa ao locador) → garantidora sub-roga e regressa contra o inquilino.

Base de tudo: Pacote Locatício (aluguel + condomínio + IPTU); o limite de cobertura é um múltiplo do pacote.

Confirmado pelo contrato real em ../contratos/ — o mapeamento cláusula a cláusula está no roadmap. Ele é um retrato conferido contra o código em datas que ele mesmo declara; para status de implementação, a fonte viva é ../specifications/index.md.

Termos¶

Análise, parecer e preço¶

• Análise de Crédito (CreditAnalysis) — o pedido de garantia de um ou mais locatários para um imóvel, que percorre os estados do diagrama abaixo. Até a spec 0007 chamava-se Proposal no código.
• Parecer (Decision) — a decisão do analista dentro da análise: aprovar, reprovar ou devolver em pendência. Até a spec 0007 chamava-se Analysis.
• Pendência (PENDING, com um tipo de pendência, PendencyType) — a devolução da análise a quem a cadastrou para correção. O tipo diz do que se trata (spec 0037).
• Recomendação — sugestão automática pela razão renda declarada ÷ Pacote Locatício: aprovar a partir de 3×, análise manual entre 2× e 3×, reprovar abaixo de 2×. Não decide nada sozinha, e não usa o resultado das consultas de crédito.
• Consulta de crédito (CreditCheck) — uma consulta a bureau executada dentro de uma análise, sobre o locatário principal PF, a partir do catálogo da plataforma (specs 0050 e 0052). Perfil de consultas — NONE, ECONOMICO, COMPLETO ou PERSONALIZADO: a composição que a garantidora escolhe.
• Pacote Locatício — aluguel + condomínio + IPTU (spec 0006). É a base da mensalidade, da taxa de adesão percentual, do LMI e dos custos de saída.
• LMI — limite máximo de indenização: Pacote × múltiplo configurado (lmi_months_multiplier; 0 = ilimitado). Custos de saída — sub-limite próprio e menor, para reparos e multa (exit_costs_multiplier).
• Mensalidade — o valor mensal da garantia: Pacote Locatício × taxa da garantia ÷ 100. Na tela, o percentual também se chama "mensalidade"; no código é guarantee_rate_percent (garantia), approved_guarantee_rate_percent (parecer) e monthly_value (o valor em reais).
• Sugerida, mínima e máxima — a faixa da mensalidade, configurada pela garantidora por tipo de tomador, PF e PJ (spec 0057). O analista escolhe dentro da faixa ao aprovar; omitida, vale a sugerida.
• Taxa em vigor — a taxa que vale para uma análise: a da garantia, se já emitida; senão a aprovada no parecer; senão a sugerida do tipo atual do tomador (spec 0057, RN11 e RN16).
• Taxa de adesão (initial_fee; antes "taxa setup") — cobrada uma vez, na entrada: nenhuma, valor fixo, ou percentual sobre Pacote, contrato total ou LMI.
• Regra padrão, regra própria e regra em vigor (de adesão) — a regra da garantidora (TenantSettings), a regra que uma imobiliária pode ter (PartnerAgency), e a que vale para uma análise: a própria, quando a imobiliária tem, senão a padrão (spec 0056, RN3).

Garantia¶

• Garantia (Guarantee; até a spec 0027, Contract) — o contrato de fiança do inquilino com a garantidora, emitido de uma análise aprovada. Congela taxa, mensalidade, adesão, LMI e vigência no momento da emissão. A minuta (ContractTemplate) é outra coisa: o modelo de texto.
• Aguardando assinatura (PENDING_SIGNATURE), Vigente (ACTIVE), Encerrada (TERMINATED) — os três estados gravados. Vencida (EXPIRED) é derivada: vigente com end_date no passado (spec 0038).
• Dossiê — os documentos da garantia; depois de fechado, só se altera com permissões próprias (spec 0040).

Cobrança¶

• Cobrança (Billing) — uma parcela devida pelo inquilino à garantidora. Desde a spec 0048 o calendário inteiro nasce na assinatura da garantia (origin = CALENDAR); a avulsa é lançada à mão (origin = MANUAL).
• Tipo da cobrança (fee_type) — SETUP (só adesão), GUARANTEE (só a mensalidade), SETUP_AND_GUARANTEE (a entrada que junta as duas, com os dois valores discriminados) e MISC (avulsa). Na tela: Adesão, Fiança, Adesão + fiança, Avulsa (spec 0054).
• Canal da parcela (channel) — por onde o dinheiro daquela parcela entra: GUARANTOR_BOLETO (boleto da garantidora), GUARANTOR_PIX (PIX da garantidora) ou AGENCY_PIX (a imobiliária recolhe e repassa). Ninguém escolhe entre os três: o canal sai do meio de cobrança da garantidora (collection_method) combinado com a cláusula da parceira (collects_monthly), e é gravado quando a parcela nasce — mudar a parceria em março não reescreve janeiro. A entrada e a avulsa nunca caem na imobiliária.
• Canal do pagamento (payment_channel) — por onde o dinheiro de fato entrou na baixa; pode diferir do canal previsto (boleto pago por PIX). É registro, não classificação.
• Competência (reference_month, AAAA-MM) — o mês a que a cobrança pertence; obrigatória desde a spec 0054. É o recorte do resumo do mês, da Central de Operações e do acerto.
• Parcela n/N (installment_number/installment_total) — a posição da mensalidade no plano. Nula na avulsa e na entrada só de adesão.
• Situação (situation) — o que a tela mostra, derivado do status gravado: Pendente, Aguardando a imobiliária (AWAITING_AGENCY: venceu, é de canal da imobiliária e ainda não foi repassada — não é inadimplência), Em atraso, Paga, Cancelada (spec 0054, RN24).
• Encargo — multa mais juros de mora, calculados pela API sobre o principal, a partir de três parâmetros da garantidora: multa (%), juros ao mês (%, pro rata dia sobre 30 dias) e carência (dias). Dentro da carência, zero; passada, os juros correm desde o vencimento (spec 0054, RN12).
• Baixa — o registro do pagamento: data em que o dinheiro entrou (paid_on), canal do pagamento e a distribuição do valor entre adesão, fiança, avulsa e multa e juros.
• Abono — dispensar o encargo na baixa, sempre com motivo. Abatido (discount_amount) — o principal que a garantidora aceitou não receber.
• Comprovante — o documento do pagamento, anexado à cobrança.
• Remoção lógica — remover sem apagar: o registro some das listas, continua no banco e pode ser restaurado em até 60 dias (spec 0049).

Acerto com a imobiliária¶

• Acerto (AgencySettlement) — o par (imobiliária, competência) dentro de uma garantidora: o que a parceira recolheu e deve repassar naquele mês, e a comissão que a garantidora lhe deve (specs 0055 e 0056). Existe sem ser criado — basta haver membro ou comissão no mês. Na tela é a aba Repasses.
• Membro do acerto — a mensalidade de canal AGENCY_PIX da competência, de garantia daquela imobiliária, não removida e não cancelada.
• Declaração — o que se informa por membro: pagou (com data e multa cobrada) ou não pagou. Só produz efeito no fechamento.
• Transferência (AgencySettlementTransfer) — um movimento de dinheiro do acerto, em um de dois sentidos: da imobiliária para a garantidora (FROM_AGENCY, o repasse) ou da garantidora para a imobiliária (TO_AGENCY, o pagamento da comissão).
• Mensalidades e multas (devido no código), recebido, comissão, saldo (balance = mensalidades e multas − comissão) e falta (saldo − recebido + pago à imobiliária) — as contas do acerto. Falta positiva: a imobiliária deve; negativa: a garantidora deve.
• Pronto para fechar, Aberto, Fechado — a situação do acerto. Fechar dá baixa nos membros declarados pagos e marca em atraso os declarados não pagos; reabrir desfaz isso, com motivo.
• Membro tardio — cobrança que passou a pertencer a um acerto já fechado (emissão retroativa, restauração); pede reabertura.
• Comissão — a parte da taxa de adesão paga que volta à imobiliária: sobre o valor de adesão pago, descontam-se os impostos (commission_tax_percent) e aplica-se o percentual de comissão (commission_percent, da imobiliária ou o padrão). Congela na baixa da adesão e entra no acerto da primeira competência ainda não fechada (spec 0056, RN8 e RN9).

Modelo de entidades¶

erDiagram
    TENANT ||--|| TENANT_SETTINGS : configura
    TENANT ||--o{ USER : tem
    TENANT ||--o{ PARTNER_AGENCY : tem
    TENANT ||--o{ RENTER : tem
    TENANT ||--o{ PROPERTY : tem
    TENANT ||--o{ CREDIT_ANALYSIS : tem
    TENANT ||--o{ DOCUMENT_TYPE : define

    PARTNER_AGENCY ||--o{ USER : "tem (usuários do canal)"
    PARTNER_AGENCY ||--o{ PROPERTY : capta
    PARTNER_AGENCY ||--o{ AGENCY_SETTLEMENT : "acerta por competência"

    RENTER ||--o{ CREDIT_ANALYSIS_PARTICIPANT : participa
    PROPERTY ||--o{ CREDIT_ANALYSIS : referenciado_por

    CREDIT_ANALYSIS ||--o{ CREDIT_ANALYSIS_PARTICIPANT : tem
    CREDIT_ANALYSIS ||--o{ CREDIT_ANALYSIS_STATUS_HISTORY : registra
    CREDIT_ANALYSIS ||--o{ CREDIT_CHECK : consulta
    CREDIT_ANALYSIS ||--o| DECISION : recebe
    CREDIT_ANALYSIS ||--o| GUARANTEE : origina

    GUARANTEE ||--o{ BILLING : gera
    AGENCY_SETTLEMENT ||--o{ AGENCY_SETTLEMENT_TRANSFER : registra
    AGENCY_SETTLEMENT ||--o{ BILLING : "baixa ao fechar"

    DOCUMENT_TYPE ||--o{ DOCUMENT : tipifica

    CREDIT_ANALYSIS {
        uuid partner_agency_id
        enum status
        decimal informed_initial_fee
    }
    DECISION {
        enum status
        decimal approved_guarantee_rate_percent
        decimal approved_initial_fee_value
    }
    GUARANTEE {
        uuid partner_agency_id
        enum status
        decimal guarantee_rate_percent
        decimal monthly_value
        decimal initial_fee
        decimal lmi_value
    }
    BILLING {
        string reference_month
        enum fee_type
        enum channel
        enum status
        decimal amount
        decimal commission_amount
    }
    AGENCY_SETTLEMENT {
        uuid partner_agency_id
        string reference_month
        enum status
        string invoice_number
    }

Documento pertence a uma entidade só. As seis FKs do Document — inquilino, imóvel, análise de crédito, garantia, cobrança (o comprovante, spec 0054) e acerto (a nota fiscal, spec 0055) — são mutuamente exclusivas. É isso que permite saber de quem é um documento.

Multi-tenant lógico: toda entidade de negócio tem tenant_id, filtrado automaticamente no BaseRepository. Só ADMIN_GLOBAL ignora o filtro, e só em dado de plataforma — ver ../architecture/data-model.md para o detalhe técnico, e as regras de papéis e escopo.

Papéis¶

São sete papéis de sistema (apps/api/app/db/rbac_seed.py):

Os dois últimos são os papéis de parceiro, escopados ao partner_agency_id do usuário. Além dos papéis de sistema, a garantidora pode montar perfis personalizados com as permissões que escolher. O modelo-alvo de negócio tem 10 papéis area-scoped (Crédito/Financeiro/Imobiliário × Gestor/Analista + Gestor Geral + Estagiário + parceiro) — detalhado em ../navigation-brief.md; ele ainda não está no código.

Status da Análise de Crédito¶

stateDiagram-v2
    [*] --> DRAFT
    DRAFT --> SUBMITTED: submeter
    DRAFT --> CANCELLED
    SUBMITTED --> IN_ANALYSIS: iniciar análise
    SUBMITTED --> CANCELLED
    IN_ANALYSIS --> APPROVED
    IN_ANALYSIS --> PENDING: devolver
    IN_ANALYSIS --> REJECTED
    IN_ANALYSIS --> CANCELLED
    PENDING --> IN_ANALYSIS: retomar
    PENDING --> APPROVED
    PENDING --> REJECTED
    PENDING --> CANCELLED
    APPROVED --> [*]: Garantia emitida
    REJECTED --> [*]
    CANCELLED --> [*]

A tabela que governa isso é ALLOWED_TRANSITIONS (apps/api/app/services/credit_analysis_service.py). CANCELLED chega por dois caminhos: o cancelamento pela garantidora e a desistência pela imobiliária, esta só em DRAFT, SUBMITTED ou PENDING — enquanto ninguém começou a trabalhar na análise (spec 0037).

PENDING chamava-se PENDING_DOCS até a spec 0037: desde a spec 0036 a devolução deixou de ser só documental (renda que não fecha, documento ilegível também devolvem) — quem diz do que se trata é o tipo da pendência, não mais o nome do estado.