Pular para conteúdo

ADR 0006: Deliberações Comparativas Nativas A/B, Painéis HTML de Alta Densidade e Padrão Cloudflare Pages

Status

Aceito (2026-08-30)

Contexto

Durante a auditoria de sizing e benchmarking arquitetural (ex: Databricks Enterprise AWS vs Nossa Arquitetura de Dados em VMs Dedicadas com IaC), constatou-se que deliberações puramente isoladas ou relatórios textuais simplificados em PDF não forneciam a granularidade comparativa necessária para decisões executivas de comitês de investimento. Identificou-se a necessidade de: 1. Deliberações Comparativas Nativas (A/B e Multi-Cenário): Capacidade de confrontar duas ou mais propostas arquiteturais ou modelos de negócio diretamente no core do Conselho (deliberate_comparative). 2. Discriminação Explícita de Furos Fatais e Diretrizes: Eliminar contagens vagas (ex: "1 furos apontados") em favor de listas completas e detalhadas de furos reais e ações mandatórias de mitigação. 3. Painéis Interativos HTML de Alta Densidade (KPIs por Persona): Renderização executiva em Dark Mode com medidores semânticos (0-100) para cada persona (RED, CFO, COO, CMO, DATA, SRE), tabela side-by-side e árvore de decisão estratégica. 4. Padrão de Publicação Cloudflare Pages para Validação: Padronizar a publicação contínua da documentação e painéis interativos no Cloudflare Pages via GitHub Actions, seguindo o padrão canônico estabelecido no workspace (projeto-salao e projeto-rh).

Decisão

  1. Core Engine: Implementar deliberate_comparative(...) e modelos Pydantic ComparativeDossier e ComparativeDimension em src/core/models.py e src/council/engine.py.
  2. Exportador HTML Autônomo: Implementar src/exporters/html_exporter.py (export_comparative_dossier_to_html e export_dossier_to_html) estilizado com TailwindCSS, sem dependências externas de runtime.
  3. Exportador PDF Corporativo: Implementar export_comparative_dossier_to_pdf em src/exporters/pdf_exporter.py com ReportLab.
  4. API Endpoints: Adicionar endpoints REST (POST /api/v1/deliberations/comparative, GET /deliberations/comparative/{id}/html, GET /deliberations/comparative/{id}/pdf).
  5. Hospedagem Cloudflare Pages: Configurar .github/workflows/docs.yml com mkdocs-material para deploy automático no Cloudflare Pages (conselho-ia-docs).

Consequências

  • Positivas:
  • Decisões de arquitetura e infraestrutura (ex: TCO de $41k/ano vs R$ 4,8k/ano) tornam-se visualmente incontestáveis com dados e furos explícitos.
  • O Conselho de IA opera como a plataforma central de governança e validação de todo o workspace.
  • Hospedagem gratuita, rápida e global no Cloudflare Pages sem limitações de repositório privado.
  • Negativas / Mitigações:
  • Requer a configuração do secret CLOUDFLARE_API_TOKEN no repositório GitHub para publicação do pipeline de CI/CD. Conforme o cânone de segurança do workspace (_framework/seguranca/), deve ser emitido um token Cloudflare nomeado e dedicado para este repositório (ex: conselho-ia-pages-token), garantindo rastreabilidade no audit log, isolamento de ciclo de vida e rotação/revogação sem impacto nos demais projetos do Hub.