--- id: 20260918-182214-2148 created: '2026-09-18T18:22:14Z' --- # Projeto: Mood System (V5)- **Contexto:** Plataforma completa de tecnologia, automação e orquestração para projetos de branding e identidade visual da Mood Hunter. Substitui a antiga automação legada dispersa em múltiplos workflows de n8n por um backend centralizado e robusto em Python (FastAPI), controlando pagamentos, criação de projetos, machine state de 19 etapas, orquestração de IA generativa multimodal, kanban e aprovações do cliente.- **Stack & Ferramentas:** - **Backend:** Python 3.12+, FastAPI, Uvicorn, Pydantic Settings, Supabase-py, Pillow, Requests/HTTPX. - **Frontend Interno:** React 18, Vite, Tailwind CSS, Framer Motion, Lucide React (tema Cyber-Noir). - **Banco de Dados:** Supabase / PostgreSQL (Schema isolado `mood_system_5`, 14+ tabelas relacionais). - **Armazenamento de Arquivos:** Dropbox API (OAuth2 com Refresh Token automático para pastas estruturadas de projetos e entregáveis finais). - **Servidor de Mídia Pública:** Chevereto API (upload via base64 para URLs públicas permanentes usadas pelas IAs e visualização de interfaces). - **Kanban & Task Tracking:** Planka API (criação automática de cards e movimentação física entre listas a cada avanço de etapa). - **Mensageria & E-mails:** n8n Webhooks (e-mails transacionais de boas-vindas, links mágicos e entregas; notificações com DM no Slack por nível de criticidade). - **Pagamentos:** Stripe Webhooks (primário) e Mercado Pago (secundário), suportando compra de novos pacotes e compra avulsa de créditos de refação/ajuste. - **Inteligência Artificial:** Google Gemini (1.5 / 2.0 Flash / Pro) e OpenRouter para raciocínio, análise de briefing e refinamento iterativo de prompts; fal.ai (GPT-Image, Flux, Recraft, Muse) para geração e renderização de logotipos e produtos. - **Infraestrutura & Deploy:** Docker, Docker Compose, Coolify, GitHub Actions.- **Papéis e Atores:** - **Cliente:** Acessa via Magic Link sem senha, responde briefing, avalia logotipos, solicita correções ou refações e aprova entregáveis finais. - **Designer:** Avalia as 24 opções de logo geradas por IA, define o pódio (Top 3), faz ajustes manuais/textuais em artes, gera e organiza produtos extras. - **Coordenador:** Valida as entregas dos designers, aprova ou solicita revisões internas antes que o material chegue ao cliente. - **Admin / Sistema:** Orquestra transições atômicas, monitora execuções e roda serviços pontuais de IA.- **Foco & Objetivos Atuais:** - Operação 100% autônoma e resiliente do ciclo de branding de ponta a ponta (onboarding → briefing → 24 logos → podio → ajustes → produtos → Brand Guide PDF → entrega Dropbox). - Ecossistema de **Serviços Modulares e Studio de IA** desacoplados para apoio à criação (moodboards dinâmicos, upscale, patterns, desmonte de camadas, pareamento de fontes). - Controle rígido de custos e prazos através de créditos de refação e filas assíncronas de execução.---## 1. Arquitetura de Alto Nível e Integrações``` [ Stripe / Mercado Pago ] │ (Webhook de compra) ▼ [ Cliente ] ◄──Magic Link── [ FastAPI Backend (v5) ] ──Webhook──► [ n8n ] ──► [ Slack / E-mail ] │ │ ▼ ├─► [ Supabase DB (mood_system_5) ] [ Client Web ] ├─► [ Dropbox API ] (Pastas MS{codigo}/...) │ ├─► [ Planka API ] (Cards Kanban automatizados) ▼ ├─► [ Chevereto API ] (Hospedagem de imagens públicas) [ Briefing & Feedbacks ] ├─► [ Google Gemini / OpenRouter ] (LLMs e Visão) └─► [ fal.ai ] (Modelos de Difusão e Renderização) ▲ [ Designers & Coordenadores ] ──────────────┘ [ Painel Front Interno (React) ]```---## 2. Máquina de Estados do Projeto (As 19 Etapas)O ciclo de vida completo do projeto é governado linearmente no banco (`projetos.etapa`):| # | Slug da Etapa | Descrição e Comportamento ||---|---|---|| 1 | `cliente_aguardando_briefing` | Pagamento aprovado. Criação de pastas Dropbox, card no Planka e envio de Magic Link para o formulário. || 2 | `designer_referencias` | Briefing respondido e analisado pelo Gemini. Designer sobe referências visuais (3 pastas no Dropbox). || 3 | `gerar_estilos_logos` | Orquestração de IA gera 6 estilos conceituais e 24 opções de logos via Gemini + fal.ai. || 4 | `designer_avaliar_logos` | Designers votam e dão notas às 24 opções; o sistema calcula e elege o Pódio Top 3. || 5 | `designer_ajustar_logos` | Designer refina tipografia, paletas e ajusta eventuais textos do Top 3. || 6 | `coord_validar_logos` | Coordenador revisa o Top 3 ajustado e libera para o cliente ou retorna ao designer. || 7 | `cliente_avaliacao_logos` | Cliente avalia os 3 logotipos (pode escolher 1 para ajuste ou solicitar refação total). || 8 | `designer_feedback_ajustar_logo` | Designer realiza as alterações pontuais solicitadas pelo cliente no logo escolhido. || 9 | `coord_feedback_validar_logo` | Coordenador valida se o ajuste no logo atendeu às exigências do cliente. || 10 | `cliente_aprovacao_logo` | Cliente aprova definitivamente o logotipo final (Pack 1 pula para etapa 18; Packs 2 e 3 vão para 11). || 11 | `gerar_produtos` | Fila assíncrona (`product_queue_worker`) gera os entregáveis adicionais por IA (cartão, flyer, etc.). || 12 | `designer_ajustar_produtos` | Designer revisa, faz correções nas artes e ajusta formatos dos produtos gerados. || 13 | `coord_validar_produtos` | Coordenador valida as peças dos produtos antes do envio ao cliente. || 14 | `cliente_avaliacao_produtos` | Cliente recebe e avalia todos os produtos em lote. || 15 | `designer_feedback_ajustar_produtos` | Designer realiza correções nos produtos que o cliente reprovou. || 16 | `coord_feedback_validar_produtos` | Coordenador valida os ajustes do lote de produtos. || 17 | `cliente_aprovacao_produtos` | Cliente dá aprovação formal de todo o pacote de produtos. || 18 | `gerar_entrega` | Backend compila o Brand Guide PDF, consolida arquivos finais e cria link compartilhado. || 19 | `finalizado` | Envio de e-mail ao cliente com link para download no Dropbox e notificação de conclusão no Slack. |---## 3. Catálogo de Pacotes e Regras de Créditos- **Pacotes de Venda:** - **Pack 1 (Essencial):** Focado exclusivamente na identidade visual (Logo, tipografia, paleta e Brand Guide simples). Após aprovar o logo (`etapa 10`), pula direto para `gerar_entrega` (`etapa 18`). - **Pack 2 (Completo) e Pack 3 (Profissional):** Incluem múltiplos produtos e desdobramentos de marca (Cartão de Visita, Flyer, Fundo de Telechamada, Mídias Sociais, Papel Timbrado, Envelopes etc.). Percorrem o ciclo completo de produtos (`etapas 11 a 17`).- **Política de Créditos e Monetização:** - **Ajuste de Logo:** 1 crédito incluso. Ajustes adicionais exigem compra de crédito avulso via Stripe. - **Refação Total de Logos:** 1 refação inclusa (reinicia o ciclo a partir de `designer_referencias` em versão V+1). Refações extras são pagas. - **Ajuste de Produtos:** 1 lote de correções incluso. Lotes extras exigem novo checkout.---## 4. Pipeline Criativo de Inteligência Artificial1. **Loop Iterativo de 24 Logos (6 Estilos × 4 Imagens):** - **Geração Conceitual:** O Gemini analisa o briefing da empresa e formula 6 estilos com nome, narrativa, sensações, paleta hex e diretrizes visuais. - **Rodada 1 (fal.ai):** Gera as imagens `A1` e `B1` para o estilo. - **Refinamento Multimodal:** O Gemini recebe as imagens geradas, audita aderência e legibilidade e reescreve os prompts refinados. - **Rodada 2 (fal.ai):** Gera as versões refinadas `A2` e `B2`. - **Armazenamento:** Imagens salvas no Supabase, Chevereto e Dropbox.2. **Geração de Produtos:** - **Fila Sequencial (`product_queue_worker.py`):** Processamento resiliente de entregáveis pendentes com bloqueio atômico. - **Transparência de Logo (`remove_white_background`):** Limpeza algorítmica de pixels brancos do logo para composições e mockups sem caixas brancas. - **Prompts Estruturados por Tipo de Peça:** Regras rígidas de proporção, safe area e aplicação de marca.---## 5. Ecossistema de Serviços Modulares e Studio de IALocalizado em `backend/app/modular_services/`, permite a execução de microserviços pontuais e desacoplados:- **Filosofia Arquitetural:** - **Zero Código no Frontend:** Schemas Pydantic são convertidos em JSON Schema OpenAPI, renderizando o formulário dinamicamente no React. - **Modelos Fixados pelo Desenvolvedor:** O usuário não escolhe o modelo de IA no front; o desenvolvedor define o melhor motor (Gemini, Flux, Recraft, etc.) no `runner.py`. - **Execução Assíncrona:** Gerenciado via background tasks com polling em `mood_system_5.execucoes_servicos`.- **Catálogo de Serviços Implementados:** 1. `moodboard_por_referencias`: Recebe até 5 imagens e gera moodboard conceitual estruturado com paleta e elementos visuais. 2. `moodboard_empresa`: Gera moodboard completo baseado no nicho e respostas de briefing. 3. `moodboard_ms_codigo`: Constrói o moodboard utilizando os dados e referências reais de um projeto `MSxxxxx`. 4. `moodboard_para_design_md`: Converte um moodboard visual em documentação técnica e estruturada `DESIGN.md`. 5. `posts_redes_sociais`: Gera conceitos e artes para redes sociais (1:1, 4:5, 9:16). 6. `upscale_imagem`: Ampliação de resolução com IA preservando nitidez de marcas. 7. `desmontar_camadas`: Separação de elementos e planos de fundo de artes compostas. 8. `gerador_pattern_grafismos`: Criação de estampas vetoriais e patterns contínuos de marca. 9. `pareamento_tipografico_googlefonts`: Curadoria inteligente e pareamento harmônico de fontes disponíveis no Google Fonts.---## 6. Estrutura de Diretórios no DropboxConvenção padronizada criada automaticamente na inicialização do projeto (`MS{codigo}`):```MS{codigo}/├── BDG/ # Brand Guide final em PDF compilado├── TP/ # Arquivos tipográficos (.ttf/.otf) do projeto├── LG/ # Logotipos do projeto│ └── V{versao}/│ ├── APROVACAO/ # Versões finais de aprovação enviadas ao cliente│ ├── APROVADO/ # Logotipo escolhido em alta resolução│ ├── PARA EDITAR/ # Arquivos abertos de trabalho do designer│ └── ESTILO_{1..6}/ # Pastas dos 6 estilos criados pela IA│ └── REFS/ # Referências visuais enviadas pelo designer└── PRODUTOS/ # Pastas de desdobramentos (Packs 2 e 3) ├── CRV/ # Cartão de Visita ├── FL/ # Flyer ├── FTC/ # Fundo de Tele-chamada ├── PSM_{1X1, 4X5, 9X16}/ # Posts para Mídias Sociais ├── PT/ # Papel Timbrado └── EN_{1, 2}/ # Envelopes```---## 7. Banco de Dados (Supabase / PostgreSQL)- **Schema:** `mood_system_5`.- **Filosofia V5:** Migração completa da inteligência de negócio do banco para o backend Python. Eliminação das 65 RPCs legadas do V3 em favor de ORM/queries controladas via client `service_role`.- **Única RPC Atômica Residual:** `fn_deduplicar_webhook` (garante idempotência estrita no recebimento de eventos de pagamentos).- **Tabelas Centrais:** - `clientes`, `projetos`, `compras_pacotes`, `pacotes`, `produtos`, `entregaveis`. - `briefings`, `estilos_gerados`, `imagens_logos`, `votos_designers`, `feedbacks`. - `staff_sessions` (tokens de Magic Link interno), `execucoes_servicos` (fila do Studio de IA). - `logs_execucao` (rastreamento centralizado via `tracker_svc`).---## 8. Frontend Interno (`front_interno`)- **Tecnologia:** React 18, Vite, Tailwind CSS (estilo Cyber-Noir).- **Rotas e Visões por Perfil:** - `/interno/dashboard`: Visão geral dos projetos ativos agrupados por etapa e responsável. - `/interno/projeto/:ms_codigo`: Sala de trabalho contextual à etapa atual do projeto. - `TelaVotarLogos.jsx`: Avaliação das 24 opções de logo com pódio e notas exclusivas. - `TelaUploads.jsx`: Ajustes de paleta, tipografia e upload paralelo para os 3 logos do pódio. - `TelaFeedbackCoord.jsx`: Painel de aprovação ou retorno de ajustes com zoom e checklist. - `/servicos` e `/coord/servicos`: Studio de Serviços Modulares com geração de formulários dinâmicos via JSON Schema e monitoramento em tempo real.---## 9. Resiliência Operacional e Concorrência- **Prevenção de Duplo Clique:** Janela de tolerância de 15 segundos em todas as submissões de cliente para descartar requisições repetidas sem gerar erros 400/500.- **CORS Dinâmico:** Expressão regular flexível no backend para aceitar domínios de produção `moodsystem.com.br` e branch previews efêmeros do Coolify.- **Roteador Genérico de Feedback:** `POST /feedback/projeto/` suporta endpoints unificados do front identificando automaticamente se a intenção é busca de dados ou execução de ação.- **Observabilidade Total (`tracker_svc`):** Todo o tráfego crítico (login, briefing, votos, geração de produtos, webhooks) gera registros estruturados na tabela `logs_execucao`.---## 10. Execução Local e Comandos Rápidos```bash# 1. Iniciar o Backend FastAPIcd backendpython -m uvicorn app.main:app --port 8001 --reload# 2. Iniciar o Frontend Internocd front_internonpm run dev # Roda na porta 3001 (ou 3002 caso 3001 esteja ocupada)# 3. Scripts de Teste e Validação Rápida (scratch)python backend/scratch/simulate_webhook.py # Simula compra no Stripepython backend/scratch/test_briefing_submit.py # Simula envio e análise de briefingpython backend/scratch/test_posts_service.py # Testa serviço modular de posts```