Flaubert CMS — Content Manager AI

1 Visão geral

Duas aplicações independentes no mesmo repositório, comunicando por HTTP através de um proxy.

Como front e back conversam

O PHP não envia cabeçalhos CORS, então o navegador não chama a API diretamente. O front expõe uma rota-proxy server-side (src/routes/api/proxy/$.ts) que roda no mesmo domínio e repassa tudo para o PHP:

O cliente HTTP central do front (src/lib/api.ts) sempre aponta para /api/proxy, anexa o JWT do localStorage e trata refresh automático em 401. Cabeçalhos de proxy/CDN (X-Forwarded-For, CF-*) são removidos no repasse.

2 Stack tecnológica

3 Estrutura de pastas

Projeto CMS/
├── README.md                     Monorepo (instruções de deploy)
├── Plano-de-Acao-SaaS.md         Plano de virar SaaS multi-tenant
├── Alexa-Integracao-Guia.md
├── Google-Search-Console-Guia.md
│
├── frontend/                     SPA React (Vite + TanStack)
│   ├── src/
│   │   ├── routes/               1 arquivo = 1 tela (dashboard, editor, sites…)
│   │   │   └── api/proxy/$.ts    Proxy server-side → PHP
│   │   ├── components/           AdminShell, AppSidebar, Topbar, AuthGuard…
│   │   │   └── ui/               46 componentes shadcn/ui
│   │   ├── lib/                  api.ts, auth.ts, api-types.ts, utils.ts
│   │   └── hooks/
│   ├── package.json  vite.config.ts  .env (API_BASE_URL)
│
└── backend/                      API + CMS em PHP 8.2
    ├── .htaccess                 Roteamento (SPA + API + /aprovacao)
    ├── .env.example              Modelo de configuração
    ├── cron.php                  Worker da fila (CLI) + limpezas
    ├── api/v1/                   19 endpoints REST
    ├── core/
    │   ├── bootstrap.php         Carrega .env, autoload, handlers de erro
    │   ├── Database.php  ContentService.php
    │   ├── auth/                 AuthManager, RoleManager
    │   ├── middleware/           Auth, Permission, MiddlewareStack
    │   ├── models/               ORM (Model, QueryBuilder) + 20 models
    │   ├── providers/adapters/   Claude, Gemini, OpenAI, Pexels, Unsplash
    │   ├── queue/                Queue, Job + 5 jobs
    │   └── services/             ~18 serviços (regra de negócio)
    ├── database/                 schema.sql + migrations
    ├── admin/                    Sobras (dicas-conteudo.html, esta doc, css/js)
    ├── mcp-server/               Servidor MCP (Node/Express)
    ├── wordpress-mu-plugin/      cms-faq-rest-bridge.php (instalar no WP)
    ├── install/                  Instalador web (wizard)
    └── storage/  uploads/        Logs, cache, mídia temporária

4 Núcleo do backend (bootstrap e ORM)

bootstrap.php

Ponto de entrada de todo endpoint (require_once core/bootstrap.php). Responsável por:

• Sessão: só inicia se ainda não houver sessão ativa (evita warning em inclusão aninhada).
• Parser de .env manual: não usa parse_ini_file() (falhava com #, ;, =, aspas em senhas/chaves). Faz parse linha a linha e remove aspas envolventes.
• Controle de erros: display_errors fica OFF por padrão (um warning no corpo quebra o JSON do front). Erros vão para storage/logs/php-errors.log. APP_DEBUG=1 liga a exibição só em dev.
• Handlers globais: set_exception_handler devolve JSON de erro genérico em vez de resposta vazia.
• Autoload de classes do core/ e carga explícita do Validator.php (funções globais soltas não disparam o autoload).

ORM próprio

Sem Eloquent/Doctrine. core/models/Model.php + QueryBuilder.php implementam um mini-ORM sobre PDO:

• fill() respeita $fillable (proteção contra mass-assignment na entrada de usuário).
• hydrate() reconstrói objetos a partir de linhas reais do banco aceitando todas as colunas (inclusive id, created_at) — sem abrir brecha via API.
• Dirty tracking: update() só grava os campos realmente alterados.
• Helpers where(), whereNull(), whereNotNull(), first(), get().
• Database.php normaliza booleanos para 1/0 (com EMULATE_PREPARES=false, true/false viravam string vazia).

Roteamento

Cada arquivo em api/v1/ é um roteador simples: lê REQUEST_METHOD + REQUEST_URI e casa a rota com preg_match/strpos, respondendo com json_response(). Autenticação via getAuthenticatedUser(); erros centralizados em handleApiException() (loga o real, devolve mensagem genérica).

5 Autenticação e papéis

JWT próprio com access token + refresh token, 2FA opcional (TOTP) e blacklist de tokens revogados.

• Login devolve token + refresh_token; o front guarda no localStorage e renova em 401 via auth/refresh.
• Logout adiciona o token à token_blacklist; o cron.php limpa tokens expirados diariamente.
• Recuperação de senha: auth/password/forgot e auth/password/reset.

Papéis (RoleManager)

Verificação por RoleManager::can($role, $permission). Endpoints sensíveis (usuários, publicação) também revalidam papel. Recursos são checados por dono (helpers findContentForUser / findSiteForUser) para evitar IDOR.

6 Endpoints da API (/api/v1)

19 arquivos de rota. Abaixo, o mapa completo por recurso.

Autenticação — auth.php

Posts / conteúdo — posts.php

Sites — sites.php

Publicação, mídia e fila

IA, imagens e limites

Configurações, relatórios e observabilidade

Google Search Console — google.php

Aprovação pública — approval-public.php

7 Serviços (regra de negócio)

A lógica vive em core/services/; os endpoints são finos e delegam para cá.

8 Provedores de IA e imagem

Padrão adapter em core/providers/adapters/, orquestrados por ProviderManager com ordem de fallback configurável.

Todos verificam erro de conexão cURL explicitamente (evita o confuso "HTTP 0"). Consumo é registrado em token_usage / ai_image_usage com custo estimado. O provider padrão de texto e de imagem é definido em /settings/ai-defaults.

9 Fila de jobs e cron

Trabalho pesado (gerar conteúdo, imagem, publicar, validar SEO) roda de forma assíncrona na tabela jobs.

Jobs disponíveis

Worker (cron.php)

• Só roda via CLI (bloqueia acesso por navegador). Configurar * * * * * a cada minuto.
• Processa até 10 jobs por execução; lock atômico (UPDATE ... WHERE status='pending') evita processamento duplicado.
• Recupera jobs travados em "processing" por 3+ minutos (recoverStalled()).
• Publica agendados vencidos via PublishService — mas se há aprovação pendente, marca o post como expired e avisa o redator (segurança: não publica sem aprovação).
• Limpezas periódicas: remove tokens expirados da blacklist.
• Ambientes sem cron: existe um worker inline como fallback.

10 Modelo de dados

MySQL/MariaDB, utf8mb4. Schema completo em backend/database/schema.sql; alterações incrementais em migrate_*.sql.

11 Integração WordPress

Publicação remota via REST API + Application Passwords. O plugin no site é opcional (só necessário para FAQ Schema e para contornar bloqueios de segurança).

• Publicação: PublishService cria/atualiza o post via /wp-json/wp/v2/posts, enviando categorias, autor e a imagem destacada.
• Categorias/autores: buscados via REST com cache de 1h, reutilizando as credenciais já salvas do site.
• Mídia: imagem enviada para a biblioteca do WP; metadados (alt/title/caption) sincronizados.

mu-plugin: cms-faq-rest-bridge.php

Instalar em wp-content/mu-plugins/ no site gerenciado. Faz duas coisas, de forma puramente aditiva (não edita plugins existentes):

• Expõe as 9 metas _mseo_faq_* do plugin "FAQ Schema" na REST API (com auth_callback exigindo edit_post e a mesma sanitização do plugin), gerando FAQPage Schema.org.
• Cria a rota /wp-json/cms-faq/v1/authors, contornando bloqueios do Wordfence/iThemes Security ao endpoint padrão /wp/v2/users. Também expõe /status para a plataforma detectar o plugin.

12 Fluxo de aprovação do cliente

O cliente aprova o conteúdo por um link sem login, recebido por e-mail ou WhatsApp.

• A rota /aprovacao/ é PHP renderizado no servidor, fora do SPA (o .htaccess a exclui do React) — por isso funciona sem login.
• Cada envio gera um token único; envios antigos ficam superseded. O IP e o comentário do cliente são registrados para auditoria.
• Se um post agendado tem aprovação pendente na hora de publicar, o cron o marca expired e avisa o redator — nunca publica sem aprovação.
• Canais dependem do que o site tem cadastrado (e-mail e/ou WhatsApp).

13 Google Search Console

Ao publicar/aprovar, o CMS avisa o Google. Conexão OAuth é por site (o cliente é o dono da propriedade).

• Reenvio de sitemap via Search Console API — funciona e ajuda o Google a descobrir URLs novas mais rápido.
• Pedido de indexação via Indexing API — a API é oficialmente só para JobPosting/BroadcastEvent; para blog comum o Google ignora. Conte com o reenvio de sitemap como ganho real.
• Botão manual "Reindexar no Google" e consulta de desempenho da URL (/google/performance).
• Credenciais OAuth criadas uma vez para a plataforma; cada cliente conecta a própria conta. Detecção automática de sitemap disponível.

Detalhes de configuração em Google-Search-Console-Guia.md.

14 Integração Alexa

Notificações proativas na Alexa usando a API oficial de Proactive Events da Amazon — sem AWS Lambda, tudo roda no servidor.

• Eventos cobertos: cliente aprovou, pediu ajustes, rejeitou uma publicação.
• Serviço dedicado AlexaNotificationService (isConfigured(), sendProactiveEvent(), notifyApproval()). Arquitetura modular: novo evento = novo método.
• Endpoint de teste: POST /api/v1/alexa-test.

Passo a passo em Alexa-Integracao-Guia.md.

15 MCP Server

Servidor Node/Express (backend/mcp-server/) que expõe a plataforma como ferramentas para o Claude Desktop.

• Configuração por ambiente: PLATFORM_API_URL, PLATFORM_API_KEY, MCP_PORT (padrão 3000).
• Ferramentas expostas incluem generate-content (gera post por site/tópico/keyword, com opção de auto-publicar) e search-and-process-image, entre outras.
• Chama a mesma API /api/v1 — é um cliente, não um caminho paralelo.

16 Frontend (SPA React)

TanStack Router com roteamento por arquivo: cada src/routes/*.tsx é uma tela. Layout comum em AdminShell (sidebar + topbar), proteção por AuthGuard.

Camada de dados

• lib/api.ts — cliente HTTP único (proxy + JWT + refresh + HttpError).
• lib/auth.ts — sessão/token no localStorage.
• lib/api-types.ts — tipos TypeScript espelhando as respostas do PHP.
• TanStack Query para cache/estado de servidor; react-hook-form + zod nos formulários; sonner para toasts.

17 Configuração (.env)

Segredos só no .env do backend (fora do git). Modelo em backend/.env.example.

No frontend, frontend/.env define API_BASE_URL (destino do proxy; padrão https://cms.flaubert.dev.br).

18 Deploy

1. cd frontend && bun install && bun run build
2. Enviar backend/ + o build do frontend (index.html + assets/) para a raiz do servidor.
3. Configurar backend/.env a partir de backend/.env.example.
4. Banco: manter o existente; aplicar migrations de backend/database/ na ordem indicada.
5. Cron: agendar php /caminho/cron.php a cada minuto.

Servidor de produção: cPanel + LiteSpeed (lsphp ea-php82) em cms.flaubert.dev.br. O .htaccess cuida do roteamento: arquivo real → arquivo; /api/ → PHP; /aprovacao/ → PHP público; resto → index.html do SPA. Também bloqueia acesso web direto a .env, core/, database/, storage/.

19 Segurança (correções consolidadas)

Endurecimentos aplicados ao longo das versões (ver backend/CHANGELOG.md e ALTERACOES.md).

• IDOR: posts, mídia e publicação verificam o dono antes de operar.
• Mass-assignment: PUT não pode reatribuir user_id/site_id; só campos editáveis explícitos.
• Vazamento de senha WP: wp_password oculto nas respostas da API.
• Erros 500: tratador central loga o real e devolve mensagem genérica (não expõe MySQL/paths).
• Rate limiter à prova de spoofing: só confia em cabeçalho de proxy com TRUSTED_PROXY=1.
• Instalador: bloqueado após instalado (.installed); cron.php e setup.php protegidos.
• Cabeçalhos: X-Content-Type-Options, X-Frame-Options, X-XSS-Protection; storage/.htaccess bloqueia acesso direto.
• Fila: lock atômico evita processamento duplicado; recuperação de jobs travados.

20 Roadmap SaaS

Direção definida em Plano-de-Acao-SaaS.md: transformar em SaaS multi-tenant escalável sem afetar clientes atuais.

Os 4 desacoplamentos

1. Cloudflare na frente de tudo (troca de origem invisível ao cliente).
2. Mídia em object storage (Cloudflare R2 / Backblaze B2) — a mídia nunca se move.
3. Banco portátil (dump/import; depois banco gerenciado).
4. App stateless (JWT + config em .env) — já em grande parte atendido.

Multi-tenant (principal item da Fase 0)

• Tabela organizations; organization_id em users, sites, contents, media, settings, uso/limites.
• Toda query filtrada pela organização (escopo global); settings por organização.
• Papel admin vira admin da organização; acima, um super-admin.
• BYOK (cada cliente com sua chave de IA) + limites por tenant.

Fases seguintes: cobrança recorrente (Asaas/Mercado Pago/Iugu/Vindi com Pix/boleto), travar recursos por plano, e por fim migração para VPS/infra dedicada quando o volume justificar.