AXM Processos — Especificação Completa do Sistema

Documento para replicar o sistema em outra plataforma (ex.: Lovable/Supabase). Contém: visão do produto, papéis, modelo de dados, regras de negócio, telas, automações, integrações e critérios de aceite.

1. Visão geral

Nome: AXM Processos Objetivo: controlar o ciclo de vida de processos societários/burocráticos (abertura, alteração e baixa de empresas) de um escritório de serviços, com total rastreabilidade de quem está com a bola (escritório, cliente ou governo), controle de SLA por etapa e por responsável, cobrança automática de documentos e um portal público onde o cliente acompanha o andamento.

Conceito central — "a bola": todo processo, em qualquer momento, está numa etapa e com uma posse (escritorio, cliente ou governo). O tempo é contabilizado separadamente por posse, então é possível provar que o atraso é do cliente ou do órgão público, e não do escritório.

Público:

Equipe interna (admin, gestor, operacional) — app autenticado.
Cliente final — portal público sem login, acesso por código de rastreio ou e-mail.

Idioma: Português (BR). O portal do cliente é multilíngue (PT/EN/ES).

Identidade visual:

Amarelo da marca #ffdf00 (ações e destaques), preto #0b0b0c (texto/base), cinza #a5a5a5, azul #116bef (secundário).
Cores de status: verde (emerald) = em dia, âmbar = perto de estourar, vermelho = SLA estourado, cinza = sem SLA.
Layout: topbar fixa com busca global e notificações, sidebar lateral no desktop, barra inferior de 5 ícones no mobile.

2. Papéis e permissões

Três papéis, gravados no usuário (campo app_role) e espelhados no registro de membro da equipe:

| Ação | admin | gestor | operacional | |---|---|---|---| | Ver tudo (dashboard, kanban, processos, clientes) | ✅ | ✅ | ✅ | | Criar/editar cliente | ✅ | ✅ | ❌ | | Criar processo | ✅ | ✅ | ❌ | | Atualizar processo (etapa, posse, notas) | ✅ | ✅ | só os atribuídos a ele | | Enviar mensagens / anexar documentos / marcar checklist | ✅ | ✅ | ✅ | | Templates de processo e etapas | ✅ | ❌ | ❌ | | Equipe (cadastrar, mudar papel) | ✅ | ✅ (visualizar) | ❌ | | Relatórios | ✅ | ✅ | ❌ | | Configurações, WhatsApp, notificações | ✅ | ❌ | ❌ | | Excluir qualquer registro | ✅ | ❌ | ❌ | | Exportar base completa | somente o super-usuário (e-mail fixo) | ❌ | ❌ |

Regras importantes de segurança:

A autoridade de permissão é o papel no usuário; o papel no cadastro de equipe é apenas espelho para exibição. Gravar sempre os dois juntos.
Leitura de todas as entidades é liberada para qualquer usuário autenticado (é um escritório único / multi-tenant por campo tenant_id), mas escrita é restrita por papel.
Toda entidade carrega tenant_id para isolamento multi-escritório futuro.
Webhooks externos validam assinatura; funções de notificação exigem chamador autenticado (nunca anônimo).
O app não pode ser embutido em iframe (proteção contra clickjacking).

3. Modelo de dados

Todas as entidades têm: id, created_at, updated_at, created_by (id do usuário) e tenant_id.

3.1 Tenant (escritório)

name, slug (único), logo_url, primary_color, contact_email, contact_phone, address, is_active, e configurações: notify_client_on_change, notify_team_on_sla_warning, sla_warning_threshold_hours, default_timezone.

3.2 TeamMember (membro da equipe)

user_email, full_name, role (admin|gestor|operacional), avatar_url, phone, is_active, notification_preferences { email, whatsapp, in_app }.

3.3 Client (cliente)

name, document_type (cpf|cnpj), document_number, email (obrigatório), phone, whatsapp, address, contact_person, notes, notification_preferences { email, whatsapp }.

3.4 ProcessTemplate (tipo de processo)

name (único por tenant), description, category (abertura|alteracao|baixa|outros), estimated_days, is_active, color, icon.

3.5 ProcessStage (etapa do template)

template_id, name, description, order (único por template), default_owner (escritorio|cliente|governo), sla_hours { escritorio, cliente, governo }, requires_protocol (bool — exige nº de protocolo para avançar), is_final (bool), color, notification_rules { notify_client_on_enter, notify_team_on_enter, notify_on_sla_warning }, auto_request_document (bool) e document_request_config { document_name, document_category, description, auto_advance_on_upload }.

3.6 ChecklistItem (item do checklist do template)

3.7 Process (processo real) — entidade central

Identificação: template_id, client_ids[], tracking_code (único por tenant, usado no portal público), internal_number, title.
Posição: current_stage_id, current_stage_name (cache), current_stage_started_at, current_ball_owner, ball_owner_since.
Responsável: assigned_to (e-mail), assigned_to_name.
Status: status (active|paused|completed|cancelled), paused_at, paused_duration (minutos acumulados em pausa).
SLA: sla_status (ok|warning|critical), sla_violations[] com { stage_id, stage_name, owner, sla_hours, actual_hours, violation_hours, detected_at }.
Governo: protocol_number, protocol_date, protocol_history (texto consolidado, editável).
Datas: started_at, completed_at, estimated_completion.
Métricas: time_accumulated { escritorio, cliente, governo } em minutos.
Outros: priority (low|normal|high|urgent), notes, tags[], idempotency_key (único por tenant, evita duplicidade em operações críticas).
Índices recomendados: (tenant, tracking_code) único; (tenant, status, sla_status); (tenant, current_ball_owner, status); (tenant, assigned_to, status); (tenant, client_ids, status).

3.8 ProcessChecklist (checklist materializado do processo)

process_id, checklist_item_id, stage_id, name (cache), is_completed, completed_at, completed_by, completed_by_name, evidence_type, evidence_value, is_required, notes.

3.9 Document

3.10 DocumentRequest (solicitação de documento ao cliente)

process_id, stage_id, document_name, document_category, description (instruções), requested_by, requested_by_name, status (pending|completed|cancelled), completed_at, document_id, auto_advance_on_upload.

3.11 Message (mensagens processo ↔ cliente)

process_id, sender_type (team_member|client|system), sender_id, sender_name, content, channel (portal|whatsapp), attachments[{name,url}], is_read, read_at, is_internal (não visível ao cliente).

3.12 EventLog (trilha de auditoria — imutável)

process_id, event_type, timestamp, actor_type (system|team_member|client), actor_id, actor_name, from_stage_id/name, to_stage_id/name, from_ball_owner, to_ball_owner, duration_minutes (duração da posse anterior), details (json), message (texto legível), is_visible_to_client, is_archived, archived_at.

event_type possíveis: process_created, stage_changed, ball_transferred, checklist_completed, document_uploaded, document_requested, protocol_added, note_added, message_sent, sla_warning, sla_breached, process_completed, process_cancelled, process_paused, process_resumed, assignment_changed.

3.13 NotificationSettings (um registro por tenant)

Switches: notify_client_on_ball_transfer, notify_client_on_stage_change, notify_client_on_document_request, notify_client_on_message, notify_client_on_completion. E-mail: email_from_name, email_template_color. Relatório periódico: weekly_report_enabled, weekly_report_frequency (daily|weekly|biweekly|monthly), weekly_report_day (0=domingo), weekly_report_hour (HH:MM). Lembretes: document_reminder_enabled, document_reminder_days, document_reminder_after_hours, client_ball_reminder_enabled, client_ball_reminder_days, client_ball_reminder_after_hours.

3.14 WhatsAppTemplate

4. Regras de negócio

4.1 Criação de processo (wizard de 3 passos)

Escolher o tipo de processo (template).
Escolher cliente(s) (com busca) — um processo pode ter mais de um cliente.
Título, número interno, prioridade, responsável e data estimada.

Ao salvar:

Gera tracking_code único (usado no portal público).
Posiciona na primeira etapa (order menor): grava current_stage_id, current_stage_name, current_stage_started_at = agora, current_ball_owner = default_owner da etapa, ball_owner_since = agora, started_at = agora, status = active.
Materializa os itens de checklist da etapa.
Cria EventLog do tipo process_created.
Se a etapa tem auto_request_document, cria a DocumentRequest e notifica o cliente.
Dispara e-mail + WhatsApp de boas-vindas/abertura (se habilitado).

4.2 Avançar / retroceder etapa

Validações antes de avançar:

Todos os itens de checklist obrigatórios da etapa atual concluídos.
Se a etapa exige protocolo (requires_protocol), o número do protocolo deve estar informado.

Efeitos do avanço:

Calcula minutos na posse atual e soma em time_accumulated[posse]; registra duration_minutes no evento.
Atualiza current_stage_*, define a nova posse pelo default_owner da nova etapa, reinicia ball_owner_since e current_stage_started_at.
Recalcula sla_status para a nova etapa.
Materializa o checklist da nova etapa.
Cria EventLog stage_changed (+ ball_transferred se a posse mudou).
Se a nova etapa tem auto_request_document, cria a solicitação e notifica.
Se a nova etapa é is_final: status = completed, completed_at = agora, evento process_completed e notificação de conclusão.
Notifica cliente por e-mail e WhatsApp conforme as configurações.

Retroceder: mesma mecânica em sentido inverso, sempre gerando evento (nunca apagar histórico).

4.3 Transferência de posse (sem mudar de etapa)

Fecha o tempo da posse anterior somando em time_accumulated, grava nova posse e ball_owner_since, cria evento ball_transferred, recalcula SLA e notifica o cliente quando a bola passa para ele.

4.4 Pausar / retomar

Pausar: status = paused, paused_at = agora, evento process_paused. Retomar: soma os minutos pausados em paused_duration, volta para active, evento process_resumed. Tempo pausado não conta para SLA.

4.5 Cálculo de SLA (regra mais importante)

O SLA é por etapa e por posse: o limite é stage.sla_hours[current_ball_owner].

horas_decorridas = (agora − ball_owner_since) em horas, descontando o tempo pausado
limite           = etapa.sla_hours[posse_atual]
uso              = horas_decorridas / limite

se não há limite configurado → status = "no_sla" (não monitorado)
uso >= 1.0  → "critical"  (estourado)
uso >= 0.8  → "warning"   (perto de estourar)
senão       → "ok"

O status é calculado em tempo real no front para exibição (não depender só do campo gravado).
Um job horário recalcula e grava sla_status, e registra sla_violations + eventos sla_warning / sla_breached quando o limite é cruzado (uma vez por violação, sem duplicar).
Processos paused, completed e cancelled não geram violação.

4.6 Documentos e avanço automático

A equipe (ou a automação da etapa) cria uma DocumentRequest com instruções.
O cliente recebe e-mail + WhatsApp com link do portal.
Ao subir o arquivo no portal: cria Document, marca a solicitação como completed, gera evento document_uploaded, notifica a equipe e — se auto_advance_on_upload — avança a etapa automaticamente aplicando todas as regras de 4.2.
Lembretes automáticos são enviados enquanto a solicitação estiver pendente.

4.7 Mensagens

Conversa por processo, nos canais portal e WhatsApp. Mensagens da equipe podem ser marcadas como internas (invisíveis ao cliente). Mensagens recebidas do WhatsApp entram na mesma thread via webhook. Mensagens não lidas do cliente geram notificação no topbar e badge na navegação.

4.8 Prazo estimado

estimated_completion é recalculada considerando as etapas restantes, os SLAs de cada posse e o histórico de atrasos, sinalizando quando o processo já não cabe no prazo prometido.

5. Telas (app interno)

5.1 Dashboard

KPIs (ativos, com o escritório, críticos, concluídos no mês), processos que precisam de ação, alertas de SLA e atalho para novo processo.

5.2 Kanban

Colunas = etapas do template selecionado; cartões = processos, com arrastar-e-soltar para mudar de etapa (aplicando as validações de 4.2). Cartão mostra cliente, código, posse, tempo na posse e cor de SLA.

5.3 Processos (lista)

Tabela/cards com busca e filtros avançados (status, posse, SLA, responsável, template, cliente, prioridade, período). Indicadores visuais de SLA e de pendências.

5.4 Detalhe do processo (tela mais densa do sistema)

Cabeçalho com título, cliente, código de rastreio, etapa atual, posse, prioridade, responsável e badges de SLA. Ações: avançar/retroceder etapa, transferir posse, pausar/retomar, editar, concluir, solicitar documento, cancelar. Abas:

Status: timeline de etapas, barra de progresso de SLA, tempo acumulado por posse, análise de prazo, alertas de violação, histórico de protocolos.
Checklist: itens da etapa com evidência (arquivo/texto/número/data), obrigatórios destacados.
Documentos: upload, categorias, visibilidade ao cliente, download, exclusão.
Mensagens: chat com o cliente (portal e WhatsApp), mensagens internas.
Histórico: EventLog completo, legível, com autor e duração de cada posse.

5.5 Clientes

CRUD, documentos (CPF/CNPJ), contatos, preferências de notificação, processos vinculados.

5.6 Templates

CRUD de tipos de processo, etapas (ordem, posse padrão, SLA por posse, exige protocolo, etapa final, automação de documento) e itens de checklist. Painel resumo de SLA do template.

5.7 Equipe

Lista de membros, papel, status ativo, convite de novos usuários por e-mail (o papel é gravado no usuário e espelhado no membro).

5.8 Relatórios (três abas, por pergunta de negócio)

O que precisa de ação: painel de problemas (críticos, perto de estourar, parados, sem SLA) + visão “Corrida dos Processos”.
Como está o fluxo: onde os processos estão travando (tempo médio de permanência por etapa), comparativo por tipo de processo (ativos, críticos, idade média, média para concluir), tabela de avanço e gráficos.
Quem está produzindo: desempenho por membro da equipe. Topo fixo: KPIs, faixas de alerta (críticos / perto de estourar / sem SLA), botão de envio manual do relatório periódico e botão de recarregar.

Visão "Corrida dos Processos" (diferencial visual)

Uma pista de corrida: colunas = etapas (nomes escritos na vertical para caber compactamente, com contador de processos e nº de críticos), 3 raias horizontais = posse (Escritório / Cliente / Governo), e cada processo é uma bolinha posicionada na célula (etapa × posse).

Cor da bolinha = status de SLA (verde/âmbar/vermelho/cinza); crítico pulsa.
Tamanho da bolinha = prioridade.
Texto dentro da bolinha = tempo total do processo em dias.
Tooltip: título, cliente, código, etapa, tempo na posse vs. SLA, status, % da pista percorrida, prioridade.
Clique abre o processo.
Máximo de 8 bolinhas por célula; excedente vira “+N” (o contador do cabeçalho mostra o total real).
Filtros: tipo de processo, posse e SLA. Última coluna com bandeira e padrão quadriculado de linha de chegada.

5.9 Configurações (admin)

Dados do escritório, notificações (todos os switches de 3.13), WhatsApp (número, templates aprovados e mapeamento de variáveis), e página restrita de exportação da base em JSON (visível apenas para o e-mail super-usuário).

5.10 Portal público do cliente (sem login)

Busca por código de rastreio ou e-mail (se houver mais de um processo, o cliente escolhe).
Mostra: etapa atual, progresso, timeline de etapas, status/prazo, documentos visíveis, solicitações pendentes com upload, chat com a equipe, histórico de eventos visíveis ao cliente.
Ações do cliente: enviar mensagem, subir documento, atender solicitação, excluir arquivo que ele mesmo enviou.
Cada ação gera EventLog, notifica a equipe (portal + WhatsApp) e pode avançar a etapa automaticamente.
Seletor de idioma PT/EN/ES.

6. Automações (jobs e gatilhos)

| Automação | Disparo | O que faz | |---|---|---| | Recalcular SLA | a cada hora | Recalcula sla_status, grava violações, cria eventos sla_warning/sla_breached | | Lembrete de documentos pendentes | diário às 09:00 | E-mail + WhatsApp ao cliente com solicitações pendentes, respeitando document_reminder_days e after_hours | | Lembrete de bola com o cliente | diário | Cobra o cliente enquanto a posse for dele, conforme client_ball_reminder_* | | Relatório periódico | conforme weekly_report_* | Envia resumo do andamento ao cliente/gestão | | Verificar prazos do governo | diário | Sinaliza processos parados com o órgão além do SLA | | Documento solicitado | ao criar DocumentRequest | Orquestra e-mail + WhatsApp | | Upload de documento | ao criar Document do cliente | Marca solicitação, notifica equipe, avança etapa se configurado | | Notificação de processo | mudança de etapa/posse/conclusão | Envia WhatsApp pelo template correspondente | | Webhook WhatsApp de entrada | mensagem recebida | Valida assinatura e grava Message na thread do processo |

Observação de mapeamento: eventos de conclusão reaproveitam o template de mudança de etapa quando não há template próprio.

7. Integrações

E-mail transacional (Resend ou equivalente): notificações ao cliente e à equipe, com nome do remetente e cor configuráveis, e links para o portal.
WhatsApp (Twilio): envio por templates aprovados (content SID) com mapeamento de variáveis, envio de mensagem livre dentro da janela de conversa, listagem dos templates disponíveis e webhook de entrada com validação de assinatura X-Twilio-Signature.
IA (assistente): dois assistentes — interno (consulta processos, resume situação, sugere próximos passos para a equipe) e do cliente (responde sobre o andamento do processo dele).
Segredos necessários: chave do e-mail, credenciais do WhatsApp (SID, token, número) e domínio do portal usado nos links.

8. Serviços de backend a implementar

Funções (endpoints/edge functions), todas exigindo chamador autenticado — exceto o webhook, que valida assinatura:

calculateProcessSLAStatus — calcula o SLA de um processo.
updateSLAStatus — job horário que recalcula todos.
resetProcessSLAStatus — zera/recalibra após correção manual.
transferBallOwner — transfere posse com contabilização de tempo e evento.
calculateUpdatedDeadline — recalcula prazo estimado.
checkGovernmentDeadlines — varredura de prazos com o governo.
consolidatedDocumentRequestTrigger — orquestra notificação de documento solicitado.
handleDocumentUpload — pós-upload: conclui solicitação, notifica, avança etapa.
sendDocumentReminder — lembretes diários (documentos e bola com o cliente).
sendEmailNotification — envio de e-mail padronizado.
sendWhatsAppNotification / notifyProcessWhatsApp — envio por template de evento.
sendWhatsAppMessage — mensagem livre.
getTwilioTemplates / getWhatsAppNumber — apoio à tela de configuração.
twilioWhatsAppWebhook — recepção de mensagens com validação de assinatura.
sendWeeklyReport — relatório periódico.
exportProcessData — exportação da base (restrita).

Módulo compartilhado de autenticação do chamador (validação de sessão e de assinatura) usado por todas as funções — sem duplicar código.

9. Critérios de aceite

Criar processo posiciona na 1ª etapa, define posse padrão, gera checklist e evento, e notifica o cliente.
Não é possível avançar com checklist obrigatório pendente nem sem protocolo quando a etapa exige.
Cada mudança de etapa/posse soma corretamente o tempo na posse anterior em time_accumulated e gera evento com duração.
Tempo pausado não conta para SLA.
SLA aparece como verde/âmbar/vermelho/cinza conforme 80% e 100% do limite da posse atual; violações ficam registradas.
Solicitação de documento chega ao cliente por e-mail e WhatsApp; o upload no portal conclui a solicitação e, se configurado, avança a etapa.
O portal público encontra o processo por código de rastreio e por e-mail, mostra só o que é visível ao cliente e permite mensagem e upload.
Mensagem enviada pelo cliente aparece nas notificações do topbar e na thread do processo.
Um operacional não consegue criar cliente/processo nem editar processo que não é dele; um gestor não acessa Templates/Configurações.
Relatórios: a Corrida posiciona cada processo ativo na célula etapa × posse correta, com cor de SLA e tempo total em dias na bolinha.
Nenhuma ação apaga histórico — tudo gera EventLog.
Todos os jobs rodam nos horários definidos e respeitam os switches de configuração.

10. Sugestões de evolução (não implementadas)

Tendência nos KPIs comparando com o período anterior.
Cache/atualização em segundo plano nos relatórios (hoje carrega até 500 processos por abertura).
Tempo médio histórico por etapa a partir do EventLog (hoje usa a permanência atual).
Paleta única de status compartilhada por todas as visões.

Especificação do Sistema