# Casos de Uso — Mud Sentinel **Documento:** `produto/02-casos-de-uso.md` **Versão:** 1.0.0 **Status:** Vigente --- ## 1. Atores | Ator | Descrição | |------|-----------| | Visitante | Usuário não autenticado (marketing / pricing) | | Usuário autenticado | Membro de um tenant | | Analista | Executa buscas, monta dossiês, usa IA | | Auditor | Acesso somente leitura ampliado + exportação de evidências | | Administrador do tenant | Gestores de usuários, papéis, políticas e billing local | | Administrador da plataforma | Operação Mud Sentinel (suporte L2/L3, feature flags) | | Sistema de ingestão | Jobs e workers que atualizam bases | | Sistema externo (API client) | Integração M2M do cliente | | Modelo de IA | Capacidade interna/externa sob orquestração controlada | --- ## 2. Convenções - **UC-XXX** = identificador estável. - **Prioridade:** P0 (MVP), P1 (pós-MVP curto), P2 (horizonte). - Casos descrevem intenção de negócio; contratos de API serão definidos em fase de especificação técnica (OpenAPI), não nesta etapa. --- ## 3. Casos de uso prioritários ### UC-001 — Onboarding de tenant (P0) **Ator principal:** Administrador do tenant / fluxo self-serve **Objetivo:** Criar organização, plano, usuário root e configuração inicial. **Fluxo principal:** 1. Cadastro da organização e aceite de termos. 2. Verificação de e-mail / domínio (conforme plano). 3. Criação do workspace e papéis padrão. 4. Convite do primeiro time. 5. Ativação de trial ou assinatura. **Regras:** Isolamento multi-tenant desde o primeiro registro; trilha de auditoria do aceite legal. --- ### UC-002 — Autenticação e sessão segura (P0) **Ator:** Usuário autenticado **Objetivo:** Acessar a plataforma com MFA quando exigido. **Requisitos:** SSO (OIDC/SAML) em planos enterprise (P1); MFA TOTP no P0 para admins. --- ### UC-003 — Busca de entidades (P0) **Ator:** Analista **Objetivo:** Localizar pessoa, empresa ou órgão por identificadores e atributos. **Exemplos de entrada:** razão social, nome, documento (quando licitamente disponível), UF, CNAE. **Saída:** Lista ranqueada com snippets e sinais de risco preliminares. **Justificativa arquitetural:** Índice de busca dedicado; não consultar apenas o OLTP para free-text. --- ### UC-004 — Visualizar ficha de entidade (P0) **Ator:** Analista / Auditor **Objetivo:** Ver atributos normalizados, fontes, timestamps de validade e avisos de qualidade de dado. **Regra:** Toda afirmação exibida deve poder ser rastreada à fonte e à versão do registro. --- ### UC-005 — Explorar relacionamentos (grafo) (P0) **Ator:** Analista **Objetivo:** Navegar redes (sócios, administradores, parentesco declarado em fonte pública, vínculos contratuais públicos quando aplicável). **Capacidades:** expandir nó, filtrar por tipo de aresta, limitar profundidade, salvar vista. **Restrição:** Profundidade e fan-out limitados por quota para proteção de custo/DoS analítico. --- ### UC-006 — Encontrar caminho entre entidades (P1) **Ator:** Analista **Objetivo:** Descobrir se existe caminho de relacionamento entre A e B sob restrições (tipos de aresta, profundidade máxima). **Nota:** Caminhos são hipóteses estruturais; a UI deve evitar linguagem de “prova”. --- ### UC-007 — Criar e manter dossiê / caso (P0) **Ator:** Analista **Objetivo:** Agrupar entidades, notas, anexos lógicos (referências), prints de grafo e conclusões. **Estados típicos:** Rascunho → Em revisão → Finalizado → Arquivado. **Auditoria:** Mudanças de estado e exports são eventos obrigatórios. --- ### UC-008 — Análise assistida por IA sobre dossiê ou entidade (P0) **Ator:** Analista **Objetivo:** Obter resumo, riscos destacados e perguntas de follow-up. **Regras:** - Resposta deve citar evidências/fonte IDs disponíveis no contexto. - Prompt e modelo versionados; saída armazenada com hash do contexto quando política exigir. - Modo “somente fatos indexados” vs. “hipóteses explícitas” claramente separado na UX. --- ### UC-009 — Configurar regras de risco do tenant (P1) **Ator:** Administrador do tenant / Head de Integridade **Objetivo:** Ativar/desativar regras, pesos e limiares. **Saída:** Score explicável (fatores contribuidores). --- ### UC-010 — Monitoramento contínuo e alertas (P1) **Ator:** Analista / Sistema **Objetivo:** Observar entidades/watchlists e notificar mudanças relevantes (ex.: alteração societária refletida em fonte). **Canal:** in-app, e-mail, webhook (P1/P2). --- ### UC-011 — Exportação auditável (P0) **Ator:** Analista / Auditor **Objetivo:** Exportar dossiê (PDF/JSON) com manifesto de evidências e metadados de geração. **Regra:** Export gera evento de auditoria imutável (append-only). --- ### UC-012 — Gestão de usuários e papéis (P0) **Ator:** Administrador do tenant **Objetivo:** Convidar, revogar, atribuir papéis, aplicar least privilege. --- ### UC-013 — Ingestão e reprocessamento de fonte (P0 interno) **Ator:** Sistema de ingestão / ops **Objetivo:** Coletar, validar, normalizar, versionar e publicar dados de um conector. **Requisitos:** Idempotência, dead-letter, métricas de lag, lineage até registro publicado. --- ### UC-014 — API de consulta para cliente enterprise (P1) **Ator:** Sistema externo **Objetivo:** Consultar entidades, relacionamentos e status de jobs via API versionada. **Segurança:** Credenciais M2M, escopos OAuth2, rate limit por tenant. --- ### UC-015 — Atendimento a direitos do titular (LGPD) (P0 política / P1 automação) **Ator:** Administrador plataforma / DPO workflow **Objetivo:** Localizar e tratar dados pessoais sob base legal adequada; registrar cumprimento. **Nota:** Priorizar minimização — preferir dados públicos não sensíveis e pseudonimização quando possível. --- ### UC-016 — Billing, quotas e feature flags (P0 básico) **Ator:** Admin tenant / plataforma **Objetivo:** Controlar seats, volume de consultas, jobs de IA e features por plano. --- ## 4. Matriz ator × caso (P0) | Caso | Analista | Auditor | Admin tenant | Plataforma | Sistema | |------|----------|---------|--------------|------------|---------| | UC-001 | | | ● | ● | | | UC-002 | ● | ● | ● | ● | | | UC-003 | ● | ● | ○ | | | | UC-004 | ● | ● | ○ | | | | UC-005 | ● | ● | ○ | | | | UC-007 | ● | ○ | | | | | UC-008 | ● | ○ | | | ● | | UC-011 | ● | ● | | | | | UC-012 | | | ● | ○ | | | UC-013 | | | | ● | ● | | UC-016 | | | ● | ● | ● | ● primário ○ secundário/leitura --- ## 5. Critérios de aceite transversais Todo caso de uso P0 que leia ou escreva dados sensíveis ou de negócio deve satisfazer: 1. Autorização verificada no boundary da aplicação (não só na UI). 2. Evento de auditoria quando aplicável (ver política de auditoria). 3. Logs estruturados com `tenant_id`, `actor_id`, `request_id` (sem PII desnecessária). 4. Comportamento definido para erro, timeout e partial failure. 5. Testes automatizados de domínio e de autorização. --- ## 6. Fora dos casos de uso iniciais - Match biométrico. - Vigilância em tempo real de indivíduos sem base legal. - Marketplace aberto de plugins de terceiros (avaliar em P2+ com sandbox).