Roadmap¶

Distância entre o negócio e o que está implementado.

Origem: anotações de negócio sobre o fluxo TXC Garantia (parceria com a imobiliária Solar), levantadas em 2026-07-24. É um retrato de um momento — ao mexer numa área, atualize a linha correspondente.

Revisto em 2026-09-27, conferido contra o código linha a linha; atualizado em 2026-10-01 com o fix 0021, que tirou da dívida técnica o seletor que só buscava. Este arquivo tinha ficado dois meses parado enquanto as specs 0005 a 0054 eram entregues, e descrevia o produto de julho: dava a cobrança recorrente como ausente (as specs 0048 e 0054 a entregaram), dizia que a taxa setup faltava (existe), que bureaus estavam fora de escopo (as specs 0050 e 0052 integraram dois), e listava como dívida técnica coisas já resolvidas — a produção no ar, o e2e destravado. Cada afirmação daqui em diante tem arquivo:linha para quem quiser abrir e conferir.

Modelo de domínio (alinhado em 2026-07-26, revisto na spec 0054)¶

Confirmado pelo contrato real da TXC Garantia (docs/contratos/: Termo de Condições Gerais + Quadro Resumo). Corrige leituras anteriores que tratavam o proprietário como parte — ou que faziam a garantidora pagá-lo direto:

• Garantidora contrata o SaaS; tem contrato de parceria com a Imobiliária. No negócio ela é a fiadora (fiança onerosa), não parte do contrato de locação.
• A Imobiliária (PARCEIRO) é o canal: fecha o aluguel e, quando a parceria prevê isso, cobra a garantia junto com o aluguel e repassa à garantidora (repasse mensal — só a Taxa TXC, nunca o aluguel).
• O contrato de garantia é do Inquilino (LOCATÁRIO) com a Garantidora, formalizado por assinatura digital (Autentique + biometria facial) + pagamento (Cl. 1ª).
• O Proprietário (LOCADOR) não tem relação com a garantidora: ela não o conhece nem o paga. No sinistro ela paga o PARCEIRO, que repassa ao LOCADOR (Cl. 3ª/15ª). Não existe "conta de repasse do proprietário" do lado da garantidora.
• Sinistro: inquilino não paga → imobiliária comunica (até 60 dias do 1º vencimento) → garantidora valida e paga a imobiliária → imobiliária repassa ao locador → garantidora sub-roga e regressa contra o inquilino/corresponsável.

Quem recolhe do 2º mês em diante é cláusula da parceria, não regra do domínio (spec 0054). O texto anterior dizia "do 2º mês em diante quem recolhe é a imobiliária", sem exceção — era descrição do piloto tratada como lei. O que decide são dois campos: PartnerAgency.collects_monthly (apps/api/app/models/partner_agency.py:48) e TenantSettings.collection_method (tenant_settings.py:74, BOLETO ou PIX). Juntos produzem o canal de cada parcela — GUARANTOR_BOLETO, GUARANTOR_PIX ou AGENCY_PIX (models/billing.py:115-117, derivados em domain/canal_de_cobranca.py:39-52). Consequência prática: "quanto entrou na minha conta" e "quanto está com a imobiliária para repassar" são perguntas diferentes.

Base de cálculo: tudo incide sobre o Pacote Locatício = aluguel + condomínio + IPTU + encargos. O limite (LMI) é um múltiplo do Pacote (ex.: 36×), com um sub-limite próprio e menor para Custos de Saída (reparos/multa, ex.: 5×).

Código e negócio falam a mesma língua desde a spec 0007. A entidade é CreditAnalysis (Análise de Crédito) e o parecer do analista dentro dela é Decision — o "rename pendente" que este arquivo anunciava foi feito. A entidade Contract também não existe mais: virou Guarantee (models/guarantee.py:77, spec 0027); ContractTemplate sobreviveu, mas é a minuta, não a garantia. Arquitetura de navegação-alvo em docs/navigation-brief.md.

Situação por processo¶

✅ Implementado¶

A precificação e a cobrança são as áreas mais maduras: a primeira cobre taxa fixa ou percentual, base aluguel ou contrato total, parcelamento e antecipação do primeiro mês; a segunda sabe de que é feita cada parcela e por onde ela entra.

⚠️ Parcial¶

Bureau de crédito — integrado, mas não alimenta a recomendação¶

A decisão de 2026-07-26 dizia que os bureaus ficavam fora do escopo. Ela foi revertida: as specs 0050 e 0052 construíram a consulta de verdade — catálogo por provedor, seleção por garantidora, execução assíncrona no worker e tela própria (Consultas de Crédito).

O que ainda é parcial: a regra 3× aluguel sobre renda declarada segue sendo a única fonte da recomendação (services/credit.py:95-148 — APPROVE ≥3×, MANUAL_ANALYSIS 2–3×, REJECT <2×). O resultado do bureau fica disponível ao analista, mas não entra no cálculo. As duas coisas coexistem sem se falarem.

Registro de e-mail de cobrança¶

email_service envia código de verificação e convite de usuário. ChannelIntegration (EMAIL / WHATSAPP) existe como configuração, sem nada que dispare ou registre comunicação de cobrança.

Cláusula Obrigatória — implementada e depois revogada¶

A spec 0003 a implementou como checkpoint de validade (RN2: aprovar exigia confirmá-la), e o fix 0009 a retirou do produto — o teste que a cobria está marcado como revogado (apps/api/tests/test_analise_completa.py:305) e o e2e afirma a ausência do controle (apps/e2e/tests/e2e/credit-analyses.spec.ts:127-128). Se o negócio ainda a quiser, ela volta como decisão nova, não como pendência antiga.

❌ Ausente¶

Em ordem sugerida de ataque.

1. Sinistro — processo inteiro¶

Não existe modelo Claim/Sinistro em apps/api/app/models/. Existem só os parâmetros de prazo (tenant_settings.py:85-86, com snapshot em guarantee.py:163-164) e o item Sinistros no menu, marcado comingSoon e sem rota. O contrato define as regras (ver Modelo de domínio). Falta modelar:

• Comunicado de Inadimplência pela imobiliária, no prazo de até 60 dias corridos do 1º vencimento (passou, a garantidora fica desobrigada — Cl. 15ª)
• Validação pela garantidora antes de pagar + workflow de status do sinistro
• Pagamento à imobiliária (que repassa ao locador) — não à conta do proprietário; janela configurável, padrão 5 dias após a validação
• Controle do LMI (múltiplo do Pacote) e do sub-limite de Custos de Saída
• Sub-rogação e regresso contra inquilino/corresponsável (cartão cadastrado ou meios legais — Cl. 15ª P4)
• Término da fiança por chaves / certidão de despejo / desocupação (Cl. 15ª P6)

É o maior buraco e é o que justifica o produto. Dos três processos do negócio, é o único sem nenhuma linha de código.

2. Emissão de boleto¶

"Boleto" existe hoje só como rótulo de canal (BillingChannel.GUARANTOR_BOLETO, CollectionMethod.BOLETO). Não há linha digitável, nosso-número, gateway nem dependência de pagamento no pyproject.toml. Billing é registro contábil e a baixa é manual (billing_service.py:210).

3. Assinatura eletrônica — Autentique + biometria facial¶

O contrato confirma: Autentique é o fornecedor (Cl. 21ª), com biometria facial, e a fiança só se formaliza após assinatura + pagamento (Cl. 1ª P1) — é o gate de ativação da garantia. Não há uma única ocorrência de "autentique" em apps/api/: hoje a assinatura é registrada à mão por quem já a colheu fora do sistema. Falta gerar o documento, enviá-lo para assinatura e tratar o callback que ativa a garantia.

Decisões de negócio (resolvidas em 2026-07-26)¶

Levantadas com o negócio e resolvidas — pelo contrato real, pelo relatório de cobrança (docs/) e pelo dono da garantidora. Base para as specs; nenhuma é técnica.

• [x] TXC Garantia / Solar são só ilustrativos — não viram seed real (o exemplo nos docs já está anonimizado).
• [x] ~~Bureaus (Rede Busca / Caixa Aqui / LOFT) — fora do escopo~~ — revertida em 2026-09: as specs 0050 e 0052 integraram API Full / SCPC Boa Vista e Quod. O que continua valendo é que o bureau não decide: a recomendação segue na regra 3×.

Jornadas Garantidora × Imobiliária — sinistro/regresso¶

Levantado em 2026-07-26 e cravado pelo contrato real (docs/contratos/: Termo de Condições Gerais + Quadro Resumo da TXC Garantia).

Fluxo confirmado:

• Originação tem duas portas (mesma análise): a imobiliária cadastra inquilino + imóvel e pede a análise no próprio portal, ou a garantidora cadastra em nome dela.
• O cobrador pode trocar no meio: setup + 1ª Taxa TXC saem juntos no 1º vencimento; do 2º mês em diante o recolhimento segue a cláusula da parceria — a imobiliária cobra junto do aluguel e repassa só a Taxa TXC (Cl. 5ª), ou o inquilino paga a garantidora direto. É o collects_monthly da spec 0054.
• Fechamento é por imobiliária: o sistema gera a fatura de repasse (automática, com revisão opcional), envia à imobiliária, ela paga, a garantidora dá baixa e emite nota fiscal. Relatórios por garantia por baixo.
• Sinistro: a imobiliária comunica a inadimplência (≤ 60 dias do 1º vencimento); a garantidora valida e paga a imobiliária (não o locador direto); a imobiliária repassa ao locador; a garantidora sub-roga e regressa contra o inquilino/ corresponsável. A fiança segue até chaves/despejo/desocupação.

Respondido pelo contrato:

• [x] Prazo para abrir — até 60 dias corridos do 1º vencimento (Cl. 15ª); passou, garantidora desobrigada.
• [x] Abertura é obrigação do parceiro (Cl. 4ª), não opcional.
• [x] O que a garantidora paga — Pacote Locatício (aluguel+condomínio+encargos+IPTU), água/luz/gás do locador, multa ≤10% da parcela, Custos de Saída, honorários de despejo, Taxa TXC inadimplida (Cl. 8ª).
• [x] Limite (LMI) — múltiplo do Pacote (ex.: 36×); Custos de Saída em múltiplo próprio (ex.: 5×) (Cl. 7ª + Quadro).
• [x] Quem recebe — a imobiliária (repassa ao locador); a garantidora não toca no proprietário (Cl. 15ª P2/P3).
• [x] Regresso — sub-rogação; cobra inquilino/corresponsável por cartão cadastrado ou meios legais, com encargos + multa 2% e juros 1%/mês (Cl. 15ª P4, Cl. 11ª).
• [x] Taxa continua durante o sinistro, até o término da fiança (Cl. 15ª P7).
• [x] Término da fiança — chaves / certidão de despejo / desocupação, o 1º que ocorrer (Cl. 15ª P6).
• [x] Imobiliária não repassa — fiança suspensa; após 60 dias, encerra — mesmo com inquilino em dia (Cl. 5ª P4, Cl. 13ª).
• [x] Ativação — só após assinatura digital (Autentique + biometria) + pagamento (Cl. 1ª P1).
• [x] Proprietário — não é parte, não assina, não recebe direto: sem relação com a plataforma.

Decidido com o dono (2026-07-26):

• [x] Janela para pagar o locador — configurável, padrão 5 dias após a validação (mapeia sobre claim_*_days).
• [x] Documentos do Comunicado de Inadimplência — checklist configurável na configuração do sistema, com valores padrão editáveis no SaaS Admin.
• [x] Fechamento — considerar só o caminho feliz (recebe e concilia); atraso da imobiliária no repasse não é tratado neste momento.
• [x] Corresponsável — sem obrigatoriedade agora (modelar como opcional). Entregue.
• [x] Taxa Setup — arbitrada pelo analista na aprovação. Entregue.

Plano de entregas — validar a jornada por incrementos¶

Cada entrega fecha uma etapa da jornada e é testável ponta a ponta. Constrói primeiro a lógica de domínio (E1→E3) e deixa as integrações externas (assinatura + boleto) por último (E4).

Trilha da jornada (sequencial)¶

A ativação real (assinatura Autentique + boleto) foi empurrada para o fim (E4) — são as integrações externas mais pesadas. E1–E3 constroem a lógica sobre uma garantia ativada por um caminho simplificado; E4 pluga o gate real no lugar.

E1 · Análise completa — etapa Análise / Contrato — ✅ IMPLEMENTADA (spec 0003, mesclada na main em 2026-07-27)

• ✅ Taxa setup arbitrada pelo analista na aprovação
• ⚠️ Cláusula Obrigatória — entregue e depois retirada pelo fix 0009 (ver Parcial)
• ✅ Corresponsável opcional (PF, analisado)

Entregue junto: menu por pipeline (Painel/OPERAÇÃO/CADASTROS/ADMINISTRAÇÃO) e o rename transversal Person → Renter (proprietário virou dado do imóvel; papel LANDLORD removido) — parte da trilha de base Linguagem & menu.

E2 · Cobrança recorrente & Fechamento — etapa Cobrança/Fechamento — ✅ ENTREGUE (specs 0048, 0054 e 0055)

• ✅ Billing mensal do 2º mês em diante — o calendário nasce com a garantia
• ✅ Cada parcela diz de que é feita (tipo) e por onde entra (canal); a competência fecha em si mesma, com resumo por tipo × canal
• ✅ Acerto por imobiliária (spec 0055): Previsão × Pagamentos × Acerto por parceira e competência; a imobiliária declara quem pagou, a garantidora registra as transferências e fecha o mês, que dá baixa nas pagas e carimba atraso nas não pagas
• ✅ Recebimento e baixa do repasse (spec 0055); a nota fiscal entra como registro (número e arquivo) — a emissão integrada a emissor ficou fora, e quem emite contra quem segue em aberto

E3 · Sinistro & Regresso — etapa Sinistro — ❌ não começou

• Modelo Claim + workflow de status
• Comunicado de Inadimplência (≤60 dias do 1º venc. + checklist configurável)
• Validação → pagamento à imobiliária (janela 5 dias), dentro do LMI + Custos de Saída
• Sub-rogação e regresso contra o inquilino; término (chaves/despejo/desocupação)

E4 · Ativação real (integrações) — etapa Contrato & Ativação · por último — ❌ não começou

• Geração do documento (Termo + Quadro Resumo) + assinatura Autentique/biometria
• Boleto inicial — setup + 1ª parcela
• Garantia ativa só após assinar + pagar — troca o registro manual pelo gate real

Trilha de base (habilitadores — antes ou em paralelo)¶

• Mobile & PWA — ✅ IMPLEMENTADA (spec 0004): casca mobile (top app bar + bottom tab bar + drawer do pipeline), PWA instalável, cadastros em cards abaixo do breakpoint e auth/onboarding em coluna única.
• Linguagem & menu — ✅ IMPLEMENTADA (spec 0007): Proposal → CreditAnalysis, Analysis → Decision, menu por pipeline.
• Portal da imobiliária — ⚠️ parcial: AGENCY_USER escopado por partner_agency_id origina e acompanha; a spec 0051 deu a tela Minha Imobiliária e a gestão dos próprios usuários; a spec 0055, a aba Repasses, onde o responsável declara quem pagou. Falta a abertura de sinistro (E3), que depende do que ainda não existe.
• RBAC — 10 papéis area-scoped + landings por papel — ❌ pendente. O código tem sete (ADMIN_GLOBAL > ADMIN_TENANT > ANALYST > OPERATOR > VIEWER, mais AGENCY_USER e AGENCY_MANAGER, este acrescentado pela spec 0051) — app/db/rbac_seed.py:193; o modelo-alvo está em docs/navigation-brief.md.

Ordem sugerida: E3 → E4. RBAC entra quando a validação exigir o recorte por papel.

Dívida técnica¶

A dívida técnica e o que falta construir em cada parte da arquitetura estão em Implementação.