Relatório de Maturidade do Core — CIBA¶
Data: 2026-02-13 Objetivo: Avaliar se o core do produto está pronto para lançamento no mercado. Escopo: Apenas funcionalidades core. Não inclui: landing page, pricing, planos, cadastro SSO, sistema de apresentação.
Veredicto Geral¶
O core está maduro o suficiente para um lançamento controlado (beta fechado / early adopters). Não está cru — pelo contrário, tem sofisticação acima da média para este estágio. Porém, há gaps específicos que representam risco se o lançamento for aberto e em escala.
Score final: 7.5/10 para beta fechado, 5.5/10 para lançamento público aberto.
Inventário do Sistema¶
Números Gerais¶
| Métrica | Valor |
|---|---|
| Entidades de domínio | 22 |
| Enums | 13 |
| Endpoints REST | 100+ |
| Pipelines de webhook | 4 (50+ steps composáveis) |
| Páginas frontend | 18 (rotas) + 30+ dialogs |
| Componentes globais | 25 |
| Services frontend | 9 |
| Arquivos no Shared layer | 207+ |
| Migrations EF Core | 27 |
| Features areas (API) | 12 |
O Que Está Bom (Pontos Fortes Reais)¶
1. Arquitetura de IA — Excelente¶
- Prompt em 7 camadas semânticas com cache Anthropic (economia de ~30-35% em tokens):
- Block 1 (STABLE, CACHE): System Rules + Agent Prompt + Behavior Rules + Attachments + Response Format
- Block 2 (SEMI-VOLATILE, CACHE): Service Steps
- Block 3 (DYNAMIC, NO CACHE): Knowledge Base (RAG)
- RAG com pgvector + chunking inteligente via LLM (Haiku normaliza, remove ruído, converte prosa em listas — não é chunking ingênuo por caracteres)
- Suporte multi-modal: áudio (Whisper), imagens (Claude Vision), documentos
- Parsing de resposta JSON com 3 níveis de fallback (JSON direto → bloco markdown → busca por chaves)
- Steps dinâmicos onde a IA navega o fluxo da conversa autonomamente
- Follow-up automatizado com TickerQ para reengajamento
- Resposta diferida fora do horário de atendimento (reagenda para próximo horário útil via TickerQ)
- Suporte a múltiplos modelos: Claude Sonnet 4.5 (default), Haiku, GPT-4.1, GPT-4o-mini, GPT-5
- Override de modelo por instância WhatsApp
2. Pipeline de Mensagens — Production-Grade¶
- 16 steps no pipeline de processamento (MessageAggregationPipeline):
- ValidateAggregation
- SendTypingIndicator
- ProcessMedia (download, R2, OCR/transcrição)
- ConsolidateMessages (merge batch)
- LoadMessageHistory (últimas 20 msgs)
- GenerateAiResponse (sub-pipeline com 4 steps internos)
- ApplySignature
- ApplyResponseDelay (0-10s artificial)
- StopTypingIndicator
- SendWhatsAppResponse
- SendAttachments
- MarkMessagesAsRead
- PersistMessages (com token counts)
- ScheduleFollowUp
- NotifySignalR
- CleanupAggregation
- Agregação de mensagens com debounce + max wait (PostgreSQL ACID)
- Idempotência via Redis (previne duplicatas do WhatsApp, TTL 24h)
FOR UPDATE SKIP LOCKEDno PostgreSQL para coordenação distribuída- Dead-letter queue para mensagens que falharam 3x
- Resposta ao webhook em <100ms (processamento assíncrono via Redis Streams)
- Retry policy: Polly 2 retries com exponential backoff, timeout 30s
3. Modelo de Domínio — Maduro¶
- 22 entidades bem encapsuladas (factory methods, private setters, aggregate roots):
- Core: Tenant, User, Agent, AgentStep, Conversation, Message
- Knowledge: AgentKnowledge, AgentKnowledgeChunk, AgentFaq
- WhatsApp: WhatsAppInstance, InstanceWhitelist, InstanceBlacklist
- Automação: EscalationRule, Escalation, FollowUpConfig, ConversationFollowUp
- Workflow: StepTransition, PendingAggregation
- Mídia: AgentAttachment, Reaction
- Analytics: LlmUsage, SystemSettings
- Multi-tenancy baked-in com query filters globais no EF Core
- Pre-computed columns para dashboard (
ResolutionTimeMinutes,StartedHour,StartedDayOfWeek) - Tracking granular de custos LLM por tenant/agent/conversa/operação (com cache tokens separados)
- Ciclo de vida completo de conversa: Active → Escalated → Resolved
- Soft delete via
IsActive(nãodeleted_at) - Value Object
ScheduleDaypara horários de disponibilidade
4. Segurança e Guardrails da IA — Forte¶
- Regras de sistema imutáveis (Layer 1 — nunca sobrescritas):
- Nunca revelar dados de outros clientes
- Nunca fabricar informações
- Nunca divulgar dados pessoais de terceiros
- Sem promessas sobre prazos/preços/garantias não documentadas
- Sem decisões que exigem autorização humana (cancelamentos, reembolsos)
- Conformidade LGPD explícita nos prompts (não coletar CPF, senhas, dados bancários)
- Limites de input em múltiplas camadas:
- PlaygroundValidator: 20 msgs, 5k chars/msg
- MaxHistoryMessages: 20 msgs
- ChatHistoryTrimmer: 5k chars/msg, 30k total
- MaxMediaExtractionsPerBatch: 5 itens
- MaxAudioBytesForTranscription: 2 MB (~5 min)
- Attachment size: 16 MB/arquivo, 500 MB/agente
- Rate limiting por política:
- API: 100 req/min (sliding window)
- Login: 10 req/5min por IP
- LLM (playground): 10 req/min
- Send-message: 25 req/min
- Escalação automática por keywords, contagem de mensagens e duração
- Temperatura 0.6 + max 1024 tokens de output
- Retry com Polly: 2 retries, exponential backoff
5. Frontend — Funcional e Completo¶
- 18 páginas com rotas:
/— Dashboard/login— Autenticação/profile— Perfil do usuário/agents— Lista de agentes/agents/{id}— Detalhe do agente (8 tabs)/instances— Lista de instâncias WhatsApp/instances/{id}— Detalhe da instância (4 tabs)/conversations— Chat em tempo real/admin/users— Gestão de usuários/admin/tenants— Gestão de tenants (SuperAdmin)/admin/llm-usage— Monitoramento de custos LLM/admin/settings— Configurações do sistema- 30+ dialogs modais para CRUD e operações
- Dashboard com 5 visualizações analíticas:
- KPI Cards (Total, Ativos, Resolvidos por IA, Escalados, Tempo médio, Taxa IA)
- Conversations Over Time (ApexCharts area chart, granularidade hora/dia/mês)
- Step Funnel (horizontal bar chart)
- Peak Hours Heatmap (7 dias × 24 horas)
- Follow-Up Effectiveness (4 cards de métricas)
- Chat real-time via SignalR com bolhas de mensagem, status de entrega, reações emoji
- Playground para testar agentes (texto, imagem, áudio) com persistência em LocalStorage
- Controle de acesso 3 níveis:
- User (Atendente): Dashboard R, Conversas RW, Agentes R
- Admin: + CRUD agentes, instâncias, usuários
- SuperAdmin: + Tenants, LLM Usage, System Settings
- Monitoramento de custos LLM por modelo/operação/tenant
- Componentes reutilizáveis: StateView, FluentForm, MudModalForm, StatusChip, ConnectionStatusIndicator, etc.
6. Deploy e CI/CD — Operacional¶
- GitHub Actions com pipeline:
create-tag → build-api (GHCR) → deploy-frontend (Cloudflare) → deploy-api (SSH/VPS) - Rollback automático se health check falhar
- Backup de banco antes de cada deploy (
pg_dump) - Docker Compose com resource limits definidos:
- PostgreSQL: 1.5 CPU / 2GB
- Redis: 0.5 CPU / 256MB
- Ciba.Api: 1.0 CPU / 1GB
- Evolution: 1.0 CPU / 512MB
- Nginx Proxy: 0.25 CPU / 128MB
- Seq: 0.5 CPU / 512MB
- Cloudflare Pages para frontend (CDN global, SSL automático)
- Seq para logs estruturados (Serilog + correlação de requests)
- Health checks: PostgreSQL + Redis + Docker HEALTHCHECK (30s interval, 3 retries)
- Migrations automáticas no startup
- Credenciais em
.envno VPS (fora do git)
7. Integrações Externas — Maduras¶
| Integração | Maturidade | Detalhe |
|---|---|---|
| Evolution API (WhatsApp) | ⭐⭐⭐⭐ | v2.3.7, webhook com 4 pipelines, QR code, retry Polly |
| Anthropic Claude | ⭐⭐⭐⭐⭐ | Prompt caching, vision, multi-model, cost tracking |
| OpenAI GPT | ⭐⭐⭐ | Funcional mas sem caching |
| OpenAI Whisper | ⭐⭐⭐⭐ | Transcrição com retry policy |
| OpenAI Embeddings | ⭐⭐⭐⭐ | pgvector HNSW, top-5, threshold 0.3 |
| Cloudflare R2 | ⭐⭐⭐⭐ | Lifecycle policies (90d conversas, 30d playground, permanente agentes) |
| Redis | ⭐⭐⭐⭐ | Cache, rate limiting, idempotência, streams |
| TickerQ | ⭐⭐⭐ | Follow-ups, deferred responses, cleanup |
O Que Não Está Tão Bom (Gaps Reais)¶
1. Zero Testes Automatizados — RISCO ALTO¶
Não existe nenhum projeto de testes no repositório. Significa que: - Qualquer refactor pode quebrar silenciosamente - Não há como validar regressões antes de deploy - Confiança no sistema depende 100% de teste manual - Cada bug em produção vai exigir debugging manual sem rede de segurança
Projetos necessários:
src/
├── Ciba.Domain.Tests/ (comportamento de entidades, validações)
├── Ciba.Api.Features.Tests/ (handlers, pipelines, endpoints)
└── Ciba.Integration.Tests/ (fluxos completos com Testcontainers)
2. Sem Métricas/APM em Produção — RISCO MÉDIO¶
- Tem Seq para logs, mas não tem Prometheus/Grafana para métricas
- Não tem OpenTelemetry para tracing distribuído
- Não tem alertas automáticos (se a API cair às 3h da manhã, ninguém sabe até cliente reclamar)
- Performance thresholds estão configurados nos logs, mas sem dashboards visuais
Impacto: Operar "às cegas" sobre performance e saúde do sistema.
3. Whisper Rate Limit — RISCO para Escala¶
- OpenAI Whisper tem limite de 50 RPM
- Com 10% de mensagens sendo áudio, basta ~500 conversas/dia com áudio para saturar
- Solução documentada (Whisper.cpp local) mas não implementada
- Economia estimada: ~$9.000/mês com Whisper local em volume alto
4. Single Point of Failure na Evolution API¶
- Uma única instância Evolution API
- Se cair, todo atendimento WhatsApp para
- Sharding documentado em
docs/planning/scalability-evolution-llm.mdmas não implementado - Sem redundância, sem failover
5. Sem Audit Trail / Versionamento¶
- Não há log de quem alterou o quê (prompts, knowledge, configurações)
- Não há versionamento de prompts de agente — se alguém estragar o prompt, não tem como reverter
SystemSettingstemUpdatedAtmas não registra quem mudou- Escalações e resoluções registram o fato, mas não há audit trail abrangente
6. Sem Domain Events¶
- Mudanças de estado importantes (escalação, resolução, troca de modo) não emitem eventos de domínio
- Dificulta futuras integrações (webhooks para clientes, notificações externas, audit log)
- Padrão atual é procedural (handler chama serviço diretamente)
7. Features de Operação Ausentes¶
- Sem notificações para o tenant (instância desconectou, conversa escalou — ninguém é notificado fora do painel)
- Sem export de dados (CSV/Excel de conversas e analytics)
- Sem limites por tenant (um tenant pode consumir todo o budget LLM)
- Sem filas de atendimento (conversas manuais vão para todos os operadores igualmente)
- Sem templates de resposta rápida (operadores humanos digitam tudo manualmente)
- Sem tags/labels em conversas (sem categorização)
- Sem pesquisa de satisfação (CSAT)
- Sem webhooks para clientes (API apenas interna)
Comparação com Mercado¶
| Funcionalidade | CIBA | Mercado (Zenvia, Blip, etc) | Impacto |
|---|---|---|---|
| IA conversacional com RAG | ✅ Avançado | ✅ (geralmente menos sofisticado) | Diferencial |
| Steps/fluxos guiados | ✅ Dinâmico (IA decide) | ✅ (geralmente estático/flowchart) | Diferencial |
| Prompt caching (economia) | ✅ Implementado | ❌ Raro | Diferencial |
| Follow-up automatizado | ✅ Com scheduling | ✅ (básico) | Paridade |
| Escalação para humano | ✅ Regras + IA | ✅ | Paridade |
| Dashboard analítico | ✅ 5 visualizações | ✅ (geralmente mais extenso) | Paridade |
| Multi-tenancy | ✅ Completo | ✅ | Paridade |
| Tracking de custos LLM | ✅ Granular | ❌ Raro | Diferencial |
| Multi-canal | ❌ Só WhatsApp | ✅ (WhatsApp, Instagram, Telegram, etc) | Gap |
| CRM integrado | ❌ Não tem | ✅ (geralmente básico) | Gap menor |
| Webhooks para cliente | ❌ Não tem | ✅ | Gap |
| Pesquisa de satisfação | ❌ Não tem | ✅ | Gap |
| Filas de atendimento | ❌ Não tem | ✅ | Gap |
| Tags/labels | ❌ Não tem | ✅ | Gap menor |
| Templates de resposta rápida | ❌ Não tem | ✅ | Gap |
| API pública documentada | ❌ Interna apenas | ✅ | Gap |
| Testes automatizados | ❌ Zero | ✅ (variável) | Risco |
Vantagem competitiva real: A sofisticação da IA (7 camadas, RAG inteligente, steps dinâmicos, caching) é superior à maioria dos concorrentes que usam flows estáticos. Isso é o principal diferencial.
Principal fraqueza: Features de operação do dia-a-dia (tags, templates, filas, notificações) que concorrentes já oferecem.
O Que Fazer Antes do Lançamento¶
ESSENCIAL — Fazer antes de colocar cliente real¶
| # | Item | Justificativa | Esforço |
|---|---|---|---|
| 1 | Testes nos handlers críticos | Webhook pipeline, escalação, follow-up — fluxos que mais impactam o cliente | Médio |
| 2 | Alertas básicos | Health check com notificação (Telegram/email/Discord) quando API ou Evolution cair | Baixo |
| 3 | Versionamento de prompt | Cliente vai iterar no prompt. Sem histórico = risco de perder trabalho | Baixo-Médio |
| 4 | Onboarding flow simplificado | Wizard guiado: criar tenant → criar agente → conectar WhatsApp → testar | Médio |
| 5 | Documentação de uso para o admin | O admin do tenant precisa saber usar sem você explicar pessoalmente | Médio |
| 6 | Limites básicos por tenant | Conversas/dia, tokens/mês — proteção contra uso abusivo no beta | Médio |
IMPORTANTE — Fazer nas primeiras semanas pós-lançamento¶
| # | Item | Justificativa | Esforço |
|---|---|---|---|
| 7 | Audit log | "Quem mudou meu agente?" — pergunta inevitável de qualquer cliente | Médio |
| 8 | Métricas Prometheus + Grafana | Visibilidade operacional para operar o SaaS | Médio |
| 9 | Notificações para o tenant | Email/webhook quando conversa escala, quando instância desconecta | Médio |
| 10 | Export de dados | CSV/Excel de conversas e analytics — clientes vão pedir | Baixo |
| 11 | Templates de resposta rápida | Operadores humanos precisam de respostas padronizadas | Baixo |
| 12 | Tags/labels em conversas | Organização e busca por categorias | Baixo |
NICE TO HAVE — Backlog pós-validação¶
| # | Item | Justificativa | Esforço |
|---|---|---|---|
| 13 | Whisper local | Só necessário se volume de áudio for alto | Alto |
| 14 | Multi-server Evolution | Só necessário com muitas instâncias WhatsApp | Alto |
| 15 | Circuit breakers | Polly retry existe, mas falta circuit breaker real | Baixo |
| 16 | CSAT / pesquisa de satisfação | Medir qualidade do atendimento percebida | Médio |
| 17 | Webhooks para clientes | Permitir integrações externas (CRM, ERP) | Médio |
| 18 | Filas de atendimento | Distribuição inteligente de conversas manuais | Médio |
| 19 | API pública | Clientes que querem integrar programaticamente | Alto |
| 20 | Multi-canal (Instagram, Telegram) | Expandir além do WhatsApp | Alto |
Scores por Categoria¶
| Categoria | Score | Status |
|---|---|---|
| Arquitetura | 9/10 | Excelente — Clean Architecture + CQRS + Vertical Slices |
| IA / LLM | 9/10 | Excelente — 7 camadas, RAG, cache, multi-modal |
| Segurança da IA | 9/10 | Excelente — regras imutáveis, LGPD, limites em camadas |
| Frontend | 8/10 | Bom — completo, real-time, dashboard rico |
| Deploy / CI-CD | 8/10 | Bom — GitHub Actions, rollback, health check |
| Documentação técnica | 9/10 | Excelente — docs completos por feature |
| Backup / Recovery | 8/10 | Bom — pg_dump automatizado, volumes nomeados |
| Segurança geral | 8/10 | Bom — JWT, rate limiting, multi-tenancy, CORS |
| Resiliência | 7/10 | Razoável — retry policies, mas sem circuit breakers |
| Monitoring | 6/10 | Básico — Seq/logs ok, sem métricas/APM/alertas |
| Escalabilidade | 6/10 | Documentada mas não implementada |
| Testing | 2/10 | Crítico — zero testes automatizados |
| Features de operação | 5/10 | Gaps em notificações, export, tags, templates |
| MÉDIA GERAL | 7.2/10 | Pronto para beta fechado, gaps para público |
Recomendação Final¶
Lançar em beta fechado com 3-5 clientes selecionados, com os seguintes pré-requisitos mínimos:
- Testes automatizados nos fluxos críticos (webhook pipeline, escalação, follow-up) — mesmo que seja 30% de coverage, cobre o que mais quebra
- Alerta quando Evolution desconectar — o cliente não pode ficar sem atendimento sem ninguém saber
- Uma página de "como usar" para o admin do tenant — não precisa ser sofisticada, pode ser inline no próprio painel
- Limites básicos por tenant (conversas/dia, tokens/mês) — proteção contra uso abusivo no beta
- Versionamento de prompt — cliente vai iterar e precisa poder voltar atrás
O core de IA está acima da média do mercado — a abordagem de prompt em camadas com cache, RAG com chunking inteligente, e steps dinâmicos é um diferencial real. O que falta são features de operação e produtização, não de core.
Referência de Arquivos-Chave¶
| Área | Arquivo |
|---|---|
| Arquitetura geral | docs/architecture.md |
| Modelo de dados | docs/data-model.md |
| Escalabilidade | docs/planning/scalability-evolution-llm.md |
| Pipeline de mensagens | docs/flows/message-processing.md |
| Fluxo de escalação | docs/flows/escalation.md |
| Fluxo de conexão | docs/flows/connection.md |
| Integração LLM | docs/integrations/llm-api.md |
| Integração Evolution | docs/integrations/evolution-api.md |
| Knowledge/RAG | docs/integrations/knowledge-retrieval.md |
| Prompt optimization | docs/integrations/prompt-optimization.md |
| Safety LLM | docs/patterns/llm-safety.md |
| Rate limiting | docs/patterns/rate-limiting.md |
| Performance | docs/patterns/performance-monitoring.md |
| Pipeline pattern | docs/patterns/pipeline.md |
| Dashboard API | docs/api/dashboard.md |
| LLM Usage API | docs/api/llm-usage.md |
| Deploy guide | deploy/DEPLOY.md |
| CI/CD | .github/workflows/deploy.yml |
| Prompts da IA | src/Ciba.Infrastructure/Prompts/*.md |
| AI Service | src/Ciba.Infrastructure/Services/Conversation/AiResponseService.cs |
| Rotas centralizadas | src/Ciba.Shared/Routes/ApiRoutes.cs |