orbit-platform

# ORBIT Platform — Skill Operacional ## Contexto do Projeto ORBIT é uma plataforma agentiva de inteligência aplicada. Recebe comandos via Telegram ou Dashboard Web, aciona agentes especializados e entrega dossiês analíticos + apresentações HTML premium. **Credenciais e stack:** Ver `/workspace/projeto/backend/.env` e `/workspace/projeto/decisoes/2026-03-24-credenciais-finais.md` --- ## Stack Técnica | Camada | Tecnologia | |--------|-----------| | Backend | Node.js + TypeScript + Fastify | | Agentes | OpenAI Agents SDK (JS/TS) + GPT-4o | | Banco | Supabase (projeto `umwqxkggzrpwknptwwju`) | | Frontend | React + Vite + TypeScript + Tailwind CSS | | Entrada | Telegram Bot API (webhook) | | Filas | pgmq via RPCs do Supabase | --- ## Arquitetura em Camadas ``` Telegram / Dashboard → Webhook Handler (Fastify) → Command + Job criados no Supabase → Worker faz pop da fila (pop_intent_job_from_queue) → Orquestrador interpreta e distribui → Pesquisa Web + Social + Acadêmica (paralelo) → Análise → Dossiê → Apresentação HTML → Quality Review → Resultado persistido no Supabase → Notificação ao usuário (Telegram) → Dashboard atualizado (Realtime) ``` --- ## Agentes — Referência Rápida | Agente | Missão | Output | |--------|--------|--------| | Orquestrador | Interpreta intenção, distribui handoffs | orchestration_result | | Pesquisa Web | Busca + evidências de fontes web | research_result | | Pesquisa Social | Discussões Reddit e fóruns | social_research_result | | Pesquisa Acadêmica | Papers, DOI, OpenAlex | scholarly_research_result | | Análise | Cruza evidências, gera SWOT | analysis_result | | Dossiê | Documento estruturado analítico | dossier_result | | Apresentação | HTML premium autocontido | presentation_result | | Qualidade | Valida todos os outputs (score ≥ 7/10) | quality_review_result | Para contratos de dados completos: ver `references/contratos-dados.md` Para perfis detalhados dos agentes: ver `references/perfis-agentes.md` --- ## Schema Supabase — Tabelas Principais O banco (`umwqxkggzrpwknptwwju`) já tem 26 tabelas criadas e limpas. Não criar novas — usar as existentes. | Grupo | Tabelas | |-------|---------| | Core | `commands`, `jobs`, `job_events` | | Pesquisa | `research_reports`, `research_sources`, `research_branches`, `research_conflicts`, `evidence_store` | | Dossiês | `dossiers`, `dossier_sources` | | Apresentações | `presentations`, `studio_outputs` | | Rastreabilidade | `execution_traces`, `execution_checkpoints`, `handoff_log` | | Qualidade | `quality_gates`, `quality_evaluations` | | Inteligência | `conversation_memory`, `knowledge_base`, `semantic_entities` | | Usuários | `user_profiles`, `user_preferences` | | Config | `directives`, `intent_patterns`, `pipeline_configs` | | Utilitários | `notifications`, `calendar_events`, `tasks` | RPCs prontos: `pop_intent_job_from_queue`, `push_intent_job`, `log_trace`, `log_quality_eval`, `evaluate_quality_gates`, `get_conversation_context`, `match_intent_pattern`, `get_dashboard_stats`, etc. Para schema completo com campos: ver `references/schema-supabase.md` --- ## Plano de Implementação | Fase | Objetivo | Status | |------|---------|--------| | A | Backend + Telegram webhook + criação de jobs | Próxima | | B | Orquestrador + Pesquisa + Análise + Dossiê + Qualidade | Aguardando A | | C | Pesquisa Social + Acadêmica | Aguardando B | | D | Apresentações HTML | Aguardando B | | E | Dashboard + Studio React | Paralelo com B/C | | F | Robustez: retry, dead letter, tracing, testes | Após B | | G | Refinamento visual e UX | Por último | --- ## Padrões de Código ### Supabase Client (backend) ```typescript import { createClient } from '@supabase/supabase-js' const supabase = createClient( process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_KEY! ) ``` ### Criar job no Supabase ```typescript const { data: job } = await supabase .from('jobs') .insert({ command_id: cmdId, chat_id: chatId, status: 'pending' }) .select().single() ``` ### Pop da fila ```typescript const { data } = await supabase.rpc('pop_intent_job_from_queue') ``` ### Log de trace ```typescript await supabase.rpc('log_trace', { p_job_id: jobId, p_agent: 'orchestrator', p_version: '1.0.0', p_step: 'intent_parsed', p_input: input, p_output: output, p_duration: durationMs, p_tokens: tokensUsed, p_status: 'ok' }) ``` ### Agente OpenAI SDK ```typescript import { Agent, run } from '@openai/agents' const agent = new Agent({ name: 'Orquestrador', model: 'gpt-4o', instructions: '...', tools: [...], handoffs: [researchAgent, analysisAgent] }) const result = await run(agent, input) ``` Para exemplos completos de cada agente: ver `references/exemplos-agentes.md` --- ## Regras de Execução 1. **Nunca codifique sem entender o fluxo** — verifique os contratos e o schema 2. **Use sempre a service_role key** do projeto `umwqxkggzrpwknptwwju` 3. **Respeite as foreign keys** ao deletar dados (filhos antes dos pais) 4. **Quality gate obrigatório** antes de qualquer entrega — score mínimo 7/10 5. **Logs estruturados** via `log_trace` RPC — nunca console.log em produção 6. **HTML das apresentações deve ser autocontido** — sem CDN externo 7. **Idioma padrão:** Português do Brasil em toda comunicação com o usuário 8. **Nunca expor credenciais** no código — sempre via variáveis de ambiente --- ## Quality Gates | Tipo | Critério Mínimo | |------|----------------| | research_result | ≥ 5 fontes, ≥ 3 ângulos do tema | | analysis_result | Convergências + Divergências + Gaps + SWOT + Implicações | | dossier_result | ≥ 800 palavras, todas as seções obrigatórias | | presentation_result | HTML autocontido, SWOT visual, responsivo | | quality_review_result | Score geral ≥ 7/10 | --- ## Referências Adicionais - Contratos de dados JSON: `references/contratos-dados.md` - Perfis completos dos agentes: `references/perfis-agentes.md` - Schema Supabase completo: `references/schema-supabase.md` - Exemplos de código por agente: `references/exemplos-agentes.md` - Metodologia de trabalho: `/workspace/projeto/metodologia/METODOLOGIA.md` - Workflows reutilizáveis: `/workspace/projeto/workflows/WORKFLOWS.md` - Plano mestre: `/workspace/projeto/PLANO-MESTRE.md`