Design Brief — Navegação e Menu da Garantora¶

Produzido com o skill /shape em 2026-07-25. Guia a reorganização da navegação e serve de referência para as specs de RBAC, menu e telas do pipeline. Não é código — é o pensamento que precede o código.

0. Modelo de domínio (corrigido 2026-07-26 pelo contrato real)¶

A navegação reflete o fluxo real do negócio, confirmado pelo contrato da TXC Garantia (docs/contratos/: Termo de Condições Gerais + Quadro Resumo). Corrige descrições anteriores que tratavam o proprietário como parte — ou que faziam a garantidora pagá-lo direto.

Parceria:  Garantidora ⇄ Imobiliária (PARCEIRO) — que gere a locação do Proprietário (LOCADOR)
Garantia:  Inquilino (LOCATÁRIO) ── contrato de fiança onerosa ──▶ Garantidora (fiadora)
Dinheiro:  Inquilino ──aluguel + garantia──▶ Imobiliária ──repassa só a garantia──▶ Garantidora
           (mês 1 = boleto direto ao inquilino; mês 2+ = repasse, agregado por imobiliária)
Sinistro:  Inquilino não paga → Imobiliária COMUNICA (≤60 dias do 1º venc.)
           → Garantidora valida e PAGA a Imobiliária → Imobiliária repassa ao LOCADOR
           → Garantidora sub-roga e REGRESSA contra o Inquilino

Entidades e papéis:

• Garantidora — cliente do SaaS (o tenant). É a fiadora (fiança onerosa), não parte do contrato de locação.
• Imobiliária (PARCEIRO) — parceira. É o canal: fecha o aluguel, cobra a garantia junto com o aluguel e repassa só a garantia à garantidora. No sinistro, é ela quem comunica a inadimplência e quem recebe o pagamento (repassando ao locador).
• Inquilino (LOCATÁRIO) — quem contrata a garantia. O contrato é dele com a garantidora, ativado por assinatura digital (Autentique + biometria) + pagamento.
• Proprietário (LOCADOR) — fora da relação com a garantidora: ela não o conhece nem o paga. Não é uma "Pessoa" da garantidora nem uma conta de repasse dela — quem cuida do locador é a imobiliária.

Fluxo do dinheiro: setup + 1ª Taxa TXC no 1º vencimento (boleto); do 2º mês em diante inquilino → imobiliária → garantidora (repasse mensal, só a garantia, agregado por imobiliária). Base de tudo: Pacote Locatício = aluguel + condomínio + IPTU.

Sinistro: 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. Limite = múltiplo do Pacote (ex.: 36×).

Terminologia: o que hoje o código chama de Proposal é, no negócio, Análise de Crédito. A tela e o menu usam "Análise de Crédito". O rename da entidade no código é um refactor transversal à parte (ver §11).

1. Resumo¶

Reorganizar a navegação para seguir o pipeline da garantia, não o modelo de dados. Cada papel enxerga a lente do seu trabalho; a imobiliária parceira tem um portal próprio. É a arquitetura de navegação definitiva — inclui etapas ainda a construir (Cobranças, Sinistros), sinalizadas como tal.

2. Ação primária¶

Fazer o usuário encontrar seu próximo trabalho em um clique: o crédito vê a fila de análise, o financeiro vê o que cobrar, o imobiliário vê as parcerias e a originação. Hoje todos garimpam dentro de telas-entidade.

3. Direção de design¶

Do impeccable.md: B2B profissional, "densidade com organização", "identidade como suporte, não distração". A navegação é estrutural e silenciosa — azul #005577 como cor de estrutura/navegação, teal só na marca, âmbar reservado para ação. Sem decoração: o menu é ferramenta, não vitrine. Os section labels estáticos que o custom-sider já suporta (OPERAÇÃO/CADASTROS/ADMINISTRAÇÃO) são o esqueleto.

4. Estrutura de navegação (a espinha do fluxo)¶

Eixo trocado de entidade → pipeline. Estrutura interna completa (Gestor Geral):

Painel                    visão do pipeline (atalhos para cada etapa)

OPERAÇÃO                  o dia a dia, na ordem do fluxo
  Análise de Crédito      pedido de garantia + análise (era "Propostas")
  Contratos               garantias ativas (inquilino ↔ garantidora)
  Cobranças               repasse mensal via imobiliária          ⟵ existe na API, falta no menu
  Sinistros               paga a imobiliária, regressa ao inquilino ⟵ "Em breve" (a construir)

CADASTROS                 insumos do pipeline
  Inquilinos              (hoje "Pessoas"; proprietário NÃO entra — garantidora nem o conhece)
  Imóveis
  Imobiliárias            parceiras

ADMINISTRAÇÃO
  Minha Garantidora · Equipe · Perfis de Acesso · Parâmetros · Tipos de Documento · Auditoria

A "fila do analista" não é item de menu — é uma visão filtrada (pendentes) dentro de Análise de Crédito. Os papéis de crédito abrem já nessa visão.

5. Modelo de papéis (alvo — 10)¶

Matriz área × nível dentro da garantidora, mais transversais e o parceiro:

• Transversais: Gestor Geral (todas as áreas) · Estagiário (leitura)
• Parceiro: Gestor Parceiro Imobiliário · Analista Parceiro Imobiliário

6. Lentes de navegação por papel¶

A espinha é constante (é um sistema só); cada papel recebe uma visão filtrada, com landing e seção-foco próprios. O Gestor de uma área vê a fila do Analista mais a gestão daquela área (equipe + parâmetros pertinentes). ADMINISTRAÇÃO é escopada por área — só o Gestor Geral vê a completa.

Portal do parceiro (navegação própria, enxuta — não é o menu interno podado):

7. Estados-chave¶

• Padrão: menu expandido, item ativo em azul de estrutura, seção do item em destaque.
• Colapsado: só ícones (o sider já faz); section labels viram divisores. O ícone de cada módulo é o mesmo do PageHeader (regra existente).
• Badges de fila (o sider já tem useNavBadges): Análise de Crédito = nº pendentes, Cobranças = nº vencidas, Sinistros = nº abertos. Maior ganho operacional — a fila aparece sem abrir a tela.
• Etapa "Em breve": Sinistros aparece desabilitado, rótulo discreto + tooltip. Sinaliza o modelo mental completo sem prometer o que não existe.
• Por papel: seções sem itens para aquele papel não renderizam (não "cinza bloqueado").

8. Modelo de interação¶

• Clique navega; item ativo reflete a rota (basename="/app" já cuida).
• Landing por papel: o redirecionamento pós-login leva cada papel ao ponto de partida (crédito → Análise de Crédito filtrada em pendentes; financeiro → Cobranças; imobiliário → Imobiliárias).
• Badges atualizam com o contexto (contadores por tenant, já suportado).

9. Conteúdo / copy¶

• Section labels: OPERAÇÃO · CADASTROS · ADMINISTRAÇÃO (caixa-alta curta).
• Itens: Análise de Crédito (era "Propostas"), Contratos, Cobranças, Sinistros, Inquilinos (era "Pessoas"), Imóveis, Imobiliárias.
• "Em breve": rótulo sóbrio, não badge chamativo.
• Portal do parceiro: linguagem possessiva (Minhas Análises, Meus Contratos).
• Tudo via i18n (nav.*), pt_BR/en_US.

10. Referências recomendadas (na implementação)¶

• spatial-design.md — hierarquia do sider, seções, densidade.
• interaction-design.md — estados de nav, menu adaptativo por papel, badges.
• ux-writing.md — labels de seção, copy do "Em breve", tom do portal do parceiro.

11. Notas de implementação e sequenciamento¶

Esta navegação depende de duas mudanças anteriores. Sugestão de ordem em specs:

1. RBAC — 10 papéis area-scoped. O RBAC atual tem 6 papéis fixos; o modelo-alvo tem 10 (área × nível + transversais + parceiro). A navegação se apoia neles. Spec própria, primeiro.
2. Rename Proposal → Análise de Crédito. Refactor transversal (api → web → e2e); a entidade proposal está em todo lugar. Spec própria, pesada. Pode rodar em paralelo ao RBAC.
3. Reorganização do menu (esta) — depende de (1); o rename (2) só troca rótulos.
4. Etapas do pipeline ainda ausentes: Cobranças (existe na API, falta menu/tela), Sinistros (a construir — ver ROADMAP). Entram como specs próprias; o menu já reserva o lugar.

12. Questões em aberto¶

1. Parâmetros por área. Hoje é uma tela só; tende a se dividir (regras de crédito para Crédito; taxas/LMI/vencimentos para Financeiro). Resolver quando Parâmetros for redesenhado.
2. Proprietário fora do escopo. Confirmado pelo contrato: a garantidora não conhece nem paga o proprietário — paga a imobiliária, que repassa ao locador. Não há dado de proprietário a modelar do lado da garantidora.
3. "Inquilinos" vs "Pessoas". Se além do inquilino houver outros tipos de pessoa relevantes (contatos, avalistas), o rótulo do cadastro pode precisar ser mais amplo. Confirmar ao modelar Cadastros.
4. Portal do parceiro: mesma casca visual (sider) com menu próprio, ou layout distinto? Assumido: mesma casca, menu próprio.