Como concebi o Observatorio OGE

Concebi a POC como um observatorio operacional, e nao como um canal oficial de ouvidoria. O objetivo e demonstrar como uma equipe pode transformar manifestacoes em sinais de gestao sem delegar uma decisao administrativa final a um modelo de IA.

O sistema recebe manifestacoes manuais ou oriundas de fontes publicas previamente autorizadas. Em seguida, protege o texto, classifica quando houver condicoes para isso, encaminha casos incertos para pessoas e apresenta apenas dados agregados no observatorio.

A arquitetura separa experiencia, contrato HTTP, regra de negocio e integracoes externas. Essa divisao permite trocar uma fonte, o modelo de IA ou a interface sem reescrever a regra de triagem.

Navegador
    |
    | cookie HttpOnly + requisicoes relativas
    v
Next.js 16 (frontend e BFF /api/proxy)
    |
    | Authorization: Bearer JWT
    v
FastAPI (rotas, Pydantic, regras, RBAC)
    |                 |                    |
    v                 v                    v
PostgreSQL       Presidio + spaCy       Gemini
    ^
    |
Worker Python + Playwright <--- execucoes de coleta persistidas

Em producao, API e worker sao processos separados que compartilham o banco. A API cria uma execucao e responde rapidamente; o worker reivindica a pendencia com bloqueio transacional, executa a coleta e atualiza estado, contadores e logs.

O frontend e um monorepo npm com Next.js 16, React 19 e um pacote compartilhado de componentes shadcn/Base UI. Escolhi o App Router para combinar paginas publicas, layouts protegidos e rotas de servidor no mesmo projeto.

• Rotas: login e esta documentacao sao publicos; observatorio, triagem, manifestacoes, coletas e administracao usam o layout protegido.
• Estado remoto: TanStack Query busca, armazena em cache e invalida dados relacionados. Uma revisao invalida manifestacoes e indicadores; uma limpeza administrativa faz o mesmo.
• Formularios: React Hook Form coleta os valores e Zod valida no cliente antes da chamada. A API continua sendo a fonte final de validacao.
• Adaptacao de contrato: adaptManifestation, adaptCollection e adaptIndicators validam e normalizam a resposta para componentes tipados.
• Experiencia: ha estados de carregamento, vazio e erro, feedback de processamento longo, cancelamento apenas da espera e layouts de tabela/cartao para desktop e celular.

O backend usa Python 3.12+, FastAPI, Pydantic, SQLAlchemy 2 e Alembic. SQLite acelera a demonstracao local; PostgreSQL 16+ e a escolha de producao para concorrencia do worker, persistencia e operacao duravel. Todas as chaves sao UUID e os timestamps sao UTC.

Os schemas Pydantic aceitam aliases em ingles e portugues onde a integracao precisa deles. Por exemplo, a criacao aceita texto outext, e classificar_com_ia ou classify_with_ai; o frontend usa os nomes em portugues nesta operacao para tornar o payload legivel.

A referencia interativa do contrato esta em /docs e /scalar no backend quando DOCS_ENABLED=true. Para a POC, essa e a fonte de verdade para payloads, codigos HTTP e schemas atualizados.

1. O operador informa texto, origem e escolhe se deseja processar com IA.
2. O middleware limita corpo e taxa da rota de triagem e cria um ID de correlacao.
3. O servico normaliza o texto, calcula HMAC para deduplicar por origem e anonimiza CPF, e-mail, telefone e pessoas com Presidio, spaCy e reconhecedores brasileiros.
4. O registro e criado inicialmente em em_revisao; o texto original nao e persistido no estado atual da POC.
5. Se a IA estiver habilitada, somente o texto anonimizado e o catalogo ativo seguem para o Gemini, que deve responder JSON estruturado.
6. A API valida tipo, area, assunto, urgencia, confianca e a associacao area-assunto. So entao um resultado confiavel vira classificado.
7. Operador ou admin revisa um item em_revisao. O admin pode corrigir novamente um classificado; o operator recebe 403 para essa tentativa.

POST /api/manifestacoes/processar
{
  "texto": "Mensagem ficticia com CPF 123.456.789-00",
  "origem": "manual",
  "classificar_com_ia": false
}

Resultado esperado: texto anonimizado e status "em_revisao".

A coleta foi desenhada como fila persistida, e nao como uma requisicao HTTP longa. Fontes so ficam disponiveis quando estao ativas, aprovadas, com termos e robots.txt revisados. A POC nao tenta contornar login, CAPTCHA ou bloqueios tecnicos.

• A API cria execucao_coleta em pendente e devolve 202 Accepted.
• O worker seleciona uma pendencia com FOR UPDATE SKIP LOCKED, muda para em_execucao e controla tentativas, timeout e cancelamento.
• Os adaptadores atuais abrangem Dados Abertos MG, Fala.BR ZIP e Reclame Aqui via Playwright.
• Cada item coletado passa pelo mesmo servico de anonimização, deduplicacao e classificacao usado na triagem manual.
• Os estados finais sao concluida, falhou e cancelada; os logs guardam metadados sanitizados, nao o conteudo coletado.

O Playwright permite que o worker controle um navegador de forma programatica. Na fonte Reclame Aqui, ele abre uma sessao isolada, acessa somente a listagem previamente autorizada e aguarda os elementos necessarios antes de ler os dados disponiveis na pagina.

1. A API registra a solicitacao e o worker retira a execucao da fila, sem manter a requisicao HTTP do usuario aberta.
2. O worker inicia o navegador, navega para a fonte aprovada e usa seletores para identificar a listagem e seus itens.
3. Cada item encontrado e normalizado e enviado ao mesmo fluxo de anonimização, deduplicacao e classificacao da triagem manual.
4. Ao terminar, a execucao registra contadores e logs sanitizados, para que a equipe acompanhe o resultado na tela de coletas.

O endpoint GET /api/indicadores aceita origin, area_id,start e end. O frontend reaplica esses filtros na URL e na consulta para que a tela seja compartilhavel e a agregacao seja calculada pelo backend, onde os dados residem.

• Senhas usam Argon2; o backend emite JWT e protege as rotas com OAuth2 Bearer.
• O login do Next.js troca credenciais por JWT no servidor e grava cookie HttpOnly, sameSite=lax e secure em producao.
• O middleware do frontend bloqueia rotas protegidas sem cookie; o backend continua validando assinatura, usuario e papel em toda chamada.
• RBAC distingue admin e operator. Exclusoes, catalogos e coletas administrativas exigem admin.
• CORS e configuravel por ambiente; corpo da requisicao, rate limit e IDs de correlacao sao aplicados no backend.
• Segredos, URL do banco e chaves do Gemini ficam em variaveis de ambiente, nunca no repositorio ou no banco.

O frontend valida tipos, lint, build e testes Vitest. O backend possui testes Pytest para anonimização, seguranca, manifestacoes, catalogos, coletas, worker e requisitos funcionais. A API tambem expoe /health para disponibilidade e /ready para verificar a prontidao do banco.

Para evoluir esta POC para producao, eu priorizaria: retencao e criptografia formal para qualquer dado sensivel que venha a ser autorizado, auditoria persistente de acoes, rate limit distribuido, monitoramento centralizado, backups testados, SSO institucional, revisao juridica de cada fonte e testes de carga e seguranca.

Os dois repositorios podem ser executados separadamente durante a demonstracao.

Backend

cd D:\Projetos
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m spacy download pt_core_news_lg
Copy-Item .env.example .env
alembic upgrade head
python -m app.commands.bootstrap_admin
.\scripts\run-dev.ps1

Frontend

cd "D:\Sistemas\WebApp - Analitico\WebApp - OGE Entrevista"
npm install
Copy-Item apps\web\.env.example apps\web\.env.local
npm run dev

Configure API_URL=http://localhost:8000 no frontend. Depois, acesse http://localhost:3000/documentacao para esta pagina ouhttp://localhost:3000/login para a demonstracao autenticada.

Os GIFs abaixo foram gravados na interface local real, usando a sessao administrativa de demonstracao e os dados retornados pela API local. Senhas nunca aparecem na gravacao: o campo de senha e mascarado pelo navegador. A sequencia explica o papel de cada tela durante uma apresentacao de entrevista.