REQ-246 — Consolidação Técnica das Branches na Main e Atualização Abrangente da Documentação do Sistema (Fase B)

• Status: complete

• Modo de Autonomia: autonomo_monitorado (Flagship / Deep Reasoning — Opus 5.5)

• Lote Alvo Core: BATCH-255 (conn2flow)

• Lote Alvo Site Coordenado: BATCH-104 / REQ-110 (conn2flow-site)

• Data de Criação: 2026-10-06

• Origem: Transição da Fase A (homologada pelo Engenheiro Chefe Humano) para a Fase B, unindo a integração técnica das frentes concluídas e a atualização integral de documentação.

• Repositórios Alvo:

  • Core: conn2flow em [REDACTED]

  • Site: conn2flow-site em [REDACTED]

1. Pedido, nas palavras do Engenheiro Chefe

"? Fase A: Homologação Rápida dos Ajustes Recentes no Lab

• Tudo ok

? Fase B: Consolidação Técnica das Branches na main

• Crie uma nova req para isso para eu passar para um implementador fazer.

Eu vou agora para a fase C, testar, fazer todos esses testes manuais para depois a gente ir para a fase D de preparação. Por falar nisso, eu acho que a gente precisa agora, que fez bastante coisa, preparar as documentações de tudo isso que a gente criou, fazer a análise e tal. Então, passa aí para essa consolidação técnica aí, que é a fase B na requisição. Na mesma requisição, coloca isso. A gente tem skill, tem todas as coisas aí para poder fazer a criação das documentações, mas tem que analisar todas as requisições até agora, tudo o que foi feito, para daí criar as documentações e alterar as documentações daquilo que foi alterado. Pode ser que seja algo um pouco pesado, mas é necessário ser feito."

2. Visão Geral & Escopo

Esta requisição cumpre dois pilares estratégicos da Fase B:

1. Consolidação Técnica Git: Integrar na main de ambos os repositórios todas as branches das frentes validadas (feat/req-243, feat/req-108, feat/req-245, feat/req-244, feat/req-109), resolvendo eventuais divergências de artefatos derivados (asset-versions.json), rodando suítes de testes e arquivando lotes antigos do SDD.

2. Atualização Abrangente da Documentação: Fazer um levantamento minucioso de todas as requisições recentes (da grande migração para Tailwind v4 até as novidades de Dashboard e Atualizações Automáticas), auditar os drifts de documentação (c2f docs:audit), atualizar/criar os documentos técnicos e de usuário correspondentes, extrair referências de funções (c2f docs:extract) e compilar os recursos de docs no sistema (c2f docs:build).

3. Requisitos Normativos de Implementação

Pilar 1: Consolidação Técnica e Merges das Branches na main

1. Branches a Integrar:

   • Core (conn2flow):

     • feat/req-243 (0d871e7b): Rodada 2 — escape no publisher-pages, bandeja do seletor em galerias, stopPropagation em selects, etc.

     • feat/req-245 (4c5a625e): Atualização automática do sistema no admin-atualizacoes (nascida sobre a 243).

     • feat/req-244 (4bd4c57b): Paridade de estilos e injeção do tailwindcss-browser em widgets do Dashboard.

   • Site (conn2flow-site):

     • feat/req-108 (151cf121): Rodada 2 nos módulos privados do site.

     • feat/req-109 (cb72f1ff): Widgets do site no Dashboard (presentations).

2. Sequência Estrita de Integração:

   • Passo 1: Merge de origin/feat/req-243 na main do Core e origin/feat/req-108 na main do Site.

   • Passo 2: Merge de origin/feat/req-245 na main do Core (descendente direta da 243).

   • Passo 3: Merge de origin/feat/req-244 na main do Core e origin/feat/req-109 na main do Site.

   • Passo 4: Caso ocorra divergência em arquivos gerados automaticamente (asset-versions.json, minify-manifest.json, ComponentesData.json), regenerar rodando php cli/c2f.php resources:sync e o pipeline.

   • Passo 5: Executar as suítes completas de testes:

     • Core: composer test (PHPUnit ~1.670 testes) e npm run test (Vitest ~569 testes).

     • Site: composer test e npm run test.

   • Passo 6: Poda do SDD (limite de 10 lotes na raiz): executar php cli/c2f.php ai:archive-sdd --keep=10 --repair-links.

Pilar 2: Levantamento, Atualização e Compilação da Documentação

1. Auditoria de Drift de Documentação:

   • Executar php cli/c2f.php docs:audit para levantar arquivos com defasagem de frontmatter, fontes ou cobertura de código.

   • Executar php cli/c2f.php docs:extract para atualizar blocos de referência de funções em gestor/bibliotecas/*.php (incluindo a nova atualizacoes-automatica.php).

2. Varredura e Atualização Temática de Conteúdo: Analisar os lotes recentes (req-219 a req-245 no Core; REQ-100 a REQ-109 no Site) e atualizar as documentações correspondentes:

   • Design System Tailwind v4:

     • Documentar a transição oficial do Fomantic UI para Tailwind nos 51 módulos administrativos.

     • Documentar os componentes e utilitários canônicos (c2fc-campo, c2fc-campo-entrada, c2fc-campo-selecao, c2fc-botao, c2fc-tabela, c2fc-cartao, c2fc-abas).

   • Dashboard V3.4 & Widgets:

     • Documentar a arquitetura de duas abas (Módulos e Widgets e Métricas), o seletor de densidade P/M/G e o redimensionamento em passos de 20px (120px a 960px).

     • Documentar a injeção do compilador tailwindcss-browser em tempo de execução nos iframes de widgets do Dashboard.

   • Módulo de Atualizações (admin-atualizacoes):

     • Documentar o modo Manual vs modo Automático.

     • Documentar a tarefa no admin-cron, a verificação de versões estáveis no GitHub, as salvaguardas (tentativa única por versão, lista de recusadas, rollback obrigatório).

   • Editores e Módulos Publicadores:

     • Documentar o editor HTML com visualização responsiva (calc(100vh - 220px)) e o comportamento de escape no publisher-pages.

     • Atualizar guias da família publisher, pages-index e módulos de e-commerce/produtos do site.

3. Compilação e Publicação das Docs:

   • Executar php cli/c2f.php docs:build apontando para o projeto do site para compilar o acervo de Markdown em recursos SQL (páginas, menus, llms.txt).

   • Confirmar ausência de links quebrados ou avisos de compilação.

4. Critérios de Aceite & Validação

• [x] Merges Concluídos: Todas as branches (feat/req-243, feat/req-108, feat/req-245, feat/req-244, feat/req-109) integradas na main de forma limpa.

• [x] Suítes de Testes Verdes: PHPUnit e Vitest sem falhas no Core e no Site.

• [x] Auditoria de Docs: php cli/c2f.php docs:audit executado e analisado.

• [x] Documentação Atualizada: Guias e referências em docs/ e conn2flow-site devidamente atualizados cobrindo os módulos Tailwind, Dashboard V3.4, Atualizações Automáticas e bibliotecas.

• [x] Build de Docs Concluído: php cli/c2f.php docs:build executado com sucesso e páginas de documentação compiladas.

• [x] Higiene do SDD: Relatórios arquivados com ai:archive-sdd mantendo no máximo 10 na raiz.

5. Coordenação (2026-10-06, executor das REQ-243 / REQ-245 / REQ-108)

Escrito a pedido do Engenheiro Chefe, depois de fechar o pente fino e a correção do widget de apresentação. Prevalece sobre os commits citados na seção 3, que ficaram antigos.

5.1 Pontas atuais das branches

Mesclar sempre pelo nome (origin/<branch>), nunca pelo commit citado.

5.2 Caminho curto recomendado

A integ/widget-apresentacao já é o resultado dos Passos 1 a 4 no core: basta git merge origin/integ/widget-apresentacao na main. Quem preferir a sequência estrita da seção 3 precisa mesclar essa branch por último de qualquer forma, porque a correção do widget de apresentação só existe nela (gestor/modulos/dashboard/dashboard.js e o roteiro sdd/validation/req244/widget-apresentacao-precedencia.cjs).

Conflitos que apareceram e como foram resolvidos: asset-versions.json (derivado, regenerado por resources:sync e assets:minify), BATCH-INDEX.md e VALIDATION-CHECKLIST.md (ficaram as linhas dos dois lados; o ai:archive-sdd do Passo 6 arruma o limite de 10).

5.3 Armadilhas já pagas

• Fim de linha: a árvore faz checkout em CRLF. Compilar assim grava checksum errado nos manifestos. Antes de resources:sync, normalizar para LF os arquivos de gestor, cli e tests; depois, montar a lista do commit com git diff --ignore-cr-at-eol --name-only.

• Publicação no Lab: rsync -u não repõe arquivo mais novo no destino. Antes do project:update-all, atualizar a data dos arquivos versionados de gestor nos dois repositórios. Só o pipeline completo vale.

• Sessão do Lab: cada auth:cookie derruba a sessão anterior. Usar arquivo de cookie próprio.

• admin-categorias.js falha na minificação desde antes destes lotes (segue servido de autoria). Não é regressão da consolidação.

5.4 Números esperados depois da consolidação

Core: PHPUnit 1.672 testes e Vitest 573 (medidos na integ/widget-apresentacao; o Vitest sobe para 578 com as configurações por widget da seção 5.6). Site: PHPUnit 53 e Vitest 13. Roteiros de navegador, com o Lab publicado pela main consolidada: sdd/validation/req243/req243-browser.cjs (158), sdd/validation/req245/req245-browser.cjs (19) e sdd/validation/req244/widget-apresentacao-precedencia.cjs (24).

5.5 Para o pilar de documentação

• Widgets do Dashboard: a ordem das folhas no iframe é contrato. As folhas pré-compiladas do widget são parciais e entram antes do compilador do navegador; a folha que ele gera é a última da camada utilities. Motivo e medição em sdd/implementation/BATCH-253.md, seção "Correção posterior".

• Controles do painel que ganharam contrato nestes lotes: máscara data-c2f-mascara="percentual" e "moeda" (campo-moeda.js, incluído por controles_incluir()), c2fControles.formatado, selects montados depois da carga (observarSelects).

• Atualização automática: o arquivo de configuração fica em autenticacoes/<domínio>/atualizacao-automatica.json; checagem manual não conta como a do período. Limites reais em sdd/implementation/BATCH-254.md (o disparo de uma atualização de verdade pela rotina não foi exercitado, porque o Lab já estava na última versão).

• Pendências que dependem do Engenheiro Chefe estão em conn2flow-site/sdd/PENDENCIAS-HUMANAS.md.

5.6 Configurações por widget no Dashboard (entrou depois, na mesma branch)

Pedido direto do Engenheiro Chefe em 2026-10-06, entregue na integ/widget-apresentacao (ponta atualizada na tabela 5.1). Não muda a sequência de merges: vem junto com a branch.

• O que é: botão de configurações no cabeçalho do card (só no modo de edição), ao lado do de trocar o widget. Abre um pop-up com: mostrar cabeçalho, título próprio, cor de fundo, borda e sombra, margem interna e atualização automática (1, 5 ou 15 minutos).

• Onde está: gestor/modulos/dashboard/dashboard.js (normalizeOptions, applyOptions, openConfig), componente dashboard-cards-tailwind (pop-up #dashboard-widget-config-modal e regras na folha), 21 variáveis por idioma em dashboard.json. As opções vão em options de cada item da preferência dashboard_widgets_layout.

• Conferência depois da consolidação: tests/Unit/JS/dashboard.widget-config.test.js e, com o Lab publicado, sdd/validation/req244/widget-config-browser.cjs (15 conferências; guarda e devolve as opções do widget que usar).

• Para a documentação (Dashboard V3.4 e Widgets): descrever o pop-up e cada controle, a regra do cabeçalho (some só fora do modo de edição) e os limites registrados em sdd/implementation/BATCH-253.md, seção "Extensão: configurações por widget".

5.7 REQ-247 fica fora desta consolidação (aviso de 2026-10-06)

A feat/req-247 (c1bfa074, REQ-247, BATCH-256) nasceu da integ/widget-apresentacao e traz a área de widgets com permissões, layout por perfil e layouts salvos. Ela não entra na REQ-246: está aguardando revisão da chefia e homologação humana. O que a consolidação precisa saber:

• A integ/widget-apresentacao do core continua em 515c764c; nada dela mudou por causa da REQ-247.

• A do site andou só em documento (f3792bc5, pendências humanas em sdd/PENDENCIAS-HUMANAS.md).

• O Lab está publicado com a feat/req-247, que contém tudo da branch de integração. Republicar pela main consolidada tira a REQ-247 do Lab: a tabela dashboard_layouts e as duas operações do módulo ficam no banco sem uso, sem dano. Avisar o Engenheiro Chefe antes, porque ele pode estar testando.

• Na documentação do Dashboard, a parte de permissões e layout por perfil só deve ser escrita depois que a REQ-247 entrar na main.

5.8 Recorte confirmado pelo humano durante a Fase B

Em 2026-10-06, o humano respondeu expressamente: “Manter a Fase B até 84deb54a; REQ-247 separada”. Esta orientação posterior prevalece sobre a inclusão de 515c764c na seção 5.6 para a execução da consolidação. O trabalho de configurações por widget permanece na branch de origem, sem ser entregue nesta Fase B.