Decision Log

Índice de Decisões Arquivadas

| DEC-061 | 2026-06-22 | accepted | Refatoração dinâmica do módulo Forms com html-editor (req-049 / BATCH-049).... → archive | | DEC-062 | 2026-06-22 | accepted | Correções do visual editor, colisão de abas e novos templates para Forms (req... → archive | | DEC-063 | 2026-06-22 | accepted | Escape HTML global no editor e separador de valor/rótulo nos selects do Forms... → archive | | DEC-064 | 2026-06-23 | accepted | Sincronização Declarativa de Recursos, Deleção e Atualização Forçada — Módulo... → archive | | DEC-065 | 2026-06-24 | accepted | Correção de Tipagem e Validação de Perfil Anônimo em Menus Condicionais (req-... → archive | | DEC-066 | 2026-06-25 | accepted | Sistema de Recuperação e Engenharia Reversa de Recursos (Pull System) (req-05... → archive | | DEC-067 | 2026-06-25 | accepted | Atualização de Versões dos Componentes do GitHub Actions (req-064 / BATCH-064... → archive | | DEC-068 | 2026-06-29 | accepted | Registro Dinâmico de Widgets do Sistema e Carregamento sob Demanda no Editor ... → archive | | DEC-069 | 2026-06-29 | accepted | Correção de Exceção de CodeMirror Indefinido no Módulo de Formulários (req-06... → archive | | DEC-070 | 2026-06-29 | accepted | Correção de Causa-Raiz das Abas Travadas e Widget Vazio no Módulo de Formulár... → archive | | DEC-071 | 2026-06-29 | accepted | Alinhamento Visual do CRUD e Painel de Conteúdo de Formulários com Menus (req... → archive | | DEC-072 | 2026-06-29 | accepted | Integração do Módulo de Formulários com o Controlador de Submissão da Bibliot... → archive | | DEC-073 | 2026-06-30 | accepted | Parametrização de Scripts de Widget no Editor HTML e Dinamização do Mapeament... → archive | | DEC-074 | 2026-06-30 | accepted | Novos Tipos de Campos, Limites via Campo "Opções" e Melhoria Progressiva no M... → archive | | DEC-075 | 2026-06-30 | accepted | Remoção do Campo e Metadado "hosting_plan" no Módulo de Planos de Assinatura ... → archive | | DEC-076 | 2026-06-30 | accepted | Parametrização Dinâmica de E-mails e Integração de Estágios de Serviço em Pla... → archive | | DEC-077 | 2026-06-30 | accepted | Dinamização Completa de Planos e Saneamento de Hardcodes no Módulo Subscripti... → archive | | DEC-078 | 2026-07-09 | accepted | Dashboard Site Toolbar, Agendamento de Páginas e Extensões do Editor HTML (re... → archive | | DEC-079 | 2026-07-10 | accepted | Desacoplamento de Scripts do Iframe e Mapeamento Inteligente de Variáveis no ... → archive | | DEC-080 | 2026-07-10 | accepted | Correções no Live Editor: Trava de Widgets, Submenu do Painel "+" e Isolament... → archive | | DEC-081 | 2026-07-10 | accepted | Mapeamento no Pai de Widgets Múltiplos, Image Picker, Filtro/Agrupamento de M... → archive | | DEC-082 | 2026-07-10 | accepted | Integração de Modelos de Sessão e Assistente IA no Live Editor (req-080 / BAT... → archive | | DEC-083 | 2026-07-11 | accepted | CodeMirror no Assistente IA, Correção do Save Intermitente, Dropdowns da Tool... → archive | | DEC-084 | 2026-07-13 | accepted | Carregamento de Widgets, Seleção de Modelos, Restauração de Backups e Isolame... → archive | | DEC-085 | 2026-07-13 | accepted | Correções de Homologação do Live Editor (BATCH-083). Três correções pós-BATCH... → archive | | DEC-086 | 2026-07-13 | accepted | Restauração de Backup Server-Side e Preview de Dispositivo com JS do Site (BA... → archive | | DEC-089 | 2026-07-15 | accepted | Criação dos Módulos/Widgets forms-search (Formulários de Busca) e pages-in... → [archive](file:///[REDACTED]) | | DEC-090 | 2026-07-17 | accepted | Transição do Gerenciador de Arquivos para Árvore Física no Disco e CRUD Compl... → [archive](file:///[REDACTED]) | | DEC-091 | 2026-07-20 | accepted | Renderização de Variáveis/Widgets no Editor HTML Clássico e Preview, igual à ... → [archive](file:///[REDACTED]) | | DEC-092 | 2026-07-29 | accepted | Mapeamento visual de mídia/documento embutido, proteção de eventos, suporte h... → [archive](file:///[REDACTED]) | | DEC-093 | 2026-07-30 | accepted | Correções de homologação do BATCH-096, separação da edição avançada e embeds ... → [archive](file:///[REDACTED]) | | DEC-094 | 2026-07-30 | accepted | Área de transferência persistente do Editor Visual (demanda direta do Engenhe... → [archive](file:///[REDACTED]) | | DEC-095 | 2026-07-30 | accepted | Upload e gestão de pastas liberados no modo picker doadmin-arquivos(deman... → [archive](file:///[REDACTED]) | | DEC-096 | 2026-07-30 | accepted | Mídia embutida: 403 em arquivos com espaço, streaming por HTTP Range e dimens... → [archive](file:///[REDACTED]) | | DEC-097 | 2026-07-30 | accepted | Embed sem arquivo escolhido não emite atributo de fonte vazio (homologação / ... → [archive](file:///[REDACTED]) | | DEC-098 | 2026-07-30 | accepted | Memória da última pasta no modo picker doadmin-arquivos(demanda direta do... → [archive](file:///[REDACTED]) | | DEC-099 | 2026-07-30 | accepted | Filtro de módulos no menu principal do gestor (demanda direta do Engenheiro C... → [archive](file:///[REDACTED]) | | DEC-100 | 2026-07-31 | accepted | Extensão da biblioteca PayPal (PHP) e asset JS para Checkout Transparente e T... → [archive](file:///[REDACTED]) | | DEC-101 | 2026-08-03 | accepted | Navegacao por foco real nos resultados visiveis dos dois filtros de modulos (BATCH-105). → [archive](file:///[REDACTED]) | | DEC-103 | 2026-08-06 | accepted | Painéis fixos opcionais do editor visual (Sidebar de CSS e Barra de Navegação), expansão do styler e ação Substituir (BATCH-106). → [archive](file:///[REDACTED]) | | DEC-104 | 2026-08-13 | accepted | Isenção de crawlers, verificação silenciosa de cookie, OpenGraph no core e auditoria de CSRF em formulários submetidos por código (BATCH-109). → [archive](file:///[REDACTED]) | | DEC-105 | 2026-08-13 | accepted | Metadados de compartilhamento por página, aba de SEO no Editor HTML, painel de Configurações na Editbar e sitemap.xml incremental (BATCH-110). → [archive](file:///[REDACTED]) | | DEC-106 | 2026-08-13 | accepted | Reversão do bloqueio de analytics e fim do laço de verificação de cookie; tokens de robô em duas camadas (CR-001 / BATCH-111). Reverte DEC-104 §4. → [archive](file:///[REDACTED]) | | DEC-107 | 2026-08-14 | accepted | Sitemap em assets, correção do 301, aba SEO no publisher-pages, isolamento do painel da Editbar e meta tags de SEO (BATCH-112). → [archive](file:///[REDACTED]) | | DEC-108 | 2026-08-14 | accepted | Extração incremental dos bridges privados e preservação temporária da cobertura de[REDACTED]-system(BATCH-115). → [archive](file:///[REDACTED]) | | DEC-109 | 2026-08-14 | accepted | Bundle Tailwind canônico e opt-in por página para impedir colisão entre sidecars independentes (BATCH-115). → [archive](file:///[REDACTED]) | | DEC-110 | 2026-08-14 | accepted | Governança de bundles Tailwind por recurso e compilação incremental (BATCH-114). → [archive](file:///[REDACTED]) | | DEC-111 | 2026-08-17 | accepted | Política de captura de CSS compilado na Editbar e delta contra cascata real (BATCH-117). → [archive](file:///[REDACTED]) | | DEC-112 | 2026-08-17 | accepted | Resolução de conflitos de display em layouts Tailwind e filtro fino de theme (BATCH-118). → [archive](file:///[REDACTED]) | | DEC-113 | 2026-08-18 | accepted | Arquitetura híbrida de layouts Tailwind e coexistência de componentes de interface (BATCH-119). → [archive](file:///[REDACTED]) | | DEC-114 | 2026-08-19 | accepted | Migração estruturada de telas públicas de identidade para Tailwind puro (BATCH-121). → [archive](file:///[REDACTED]) | | DEC-115 | 2026-08-20 | accepted | Customização de rótulos e ordenação de módulos administrativos em modulos-grupos (BATCH-125). | | DEC-116 | 2026-08-21 | accepted | Atualização Global da Documentação, Readmes, Changelogs e Workflows de Release (Gestor v2.9.39 e Instalador v1.5.6) (BATCH-127). | | DEC-117 | 2026-08-21 | accepted | Correção de Reload em Erro de CSRF/Sessão, Mapeamento de Ícones de Projetos, Alternância de Botões de Menu e Saneamento do Lucide (BATCH-127). | | DEC-118 | 2026-08-24 | accepted | Extrator semântico de tokens do Tailwind para o Assistente de IA no Editor HTML (BATCH-129). | | DEC-119 | 2026-08-28 | accepted | Correspondência por nome sanitizado no controlador estático e desempate de colisão sem espaço (BATCH-143). | | DEC-120 | 2026-08-29 | accepted | Aparência de estado resolvida por CADEIA DE RECURSOS no galleries, com o CSS acompanhando as classes (BATCH-147). | | DEC-121 | 2026-08-29 | accepted | A telavariablesnão oferece ações sobre a tabelamodulos; tipo de campo passa a sereditor-texto(BATCH-147). | | DEC-122 | 2026-08-29 | accepted | Assets de terceiros versionados emgestor/assets/vendor/, com verificação de certificado inegociável no download (BATCH-146). | | DEC-123 | 2026-08-29 | accepted | Uma biblioteca local inclui também o que ela própria pede: chavearquivosno registro (BATCH-148). | | DEC-124 | 2026-08-29 | accepted | Fontes hospedadas pelo projeto, com filtro de subset eunicode-rangepreservado (BATCH-148). | | DEC-125 | 2026-08-29 | accepted | Minificar é build; escolher o arquivo é resolução — nunca transformar o corpo na entrega (BATCH-148). | | DEC-126 | 2026-08-29 | accepted | Ocss:rebuildregenera apenas recursos editados online (user_modified=1`) (BATCH-149). | | DEC-127 | 2026-08-29 | accepted | Assets locais também no layout administrativo Tailwind, com guarda de versão (BATCH-149). | | DEC-128 | 2026-08-30 | accepted | Dependências Tailwind de sistema: declarada falha alto, automática degrada em silêncio (BATCH-150). | | DEC-132 | 2026-10-04 | accepted | Painel em Tailwind por variantes que guardam os ganchos do JS e ponte vanilla para a API do Fomantic (BATCH-227). |

DEC-116 a DEC-122 arquivadas em decisions-114-122.md.

DEC-123 - 2026-08-29 - accepted

Uma biblioteca local inclui também o que ela própria pede (BATCH-148).

O BATCH-146 migrou o CSS do Fomantic para o disco e os ícones do layout administrativo sumiram. O semantic.min.css pede as fontes por caminho RELATIVO a ele próprio; servido do CDN isso resolvia contra o domínio do CDN, servido do disco passou a resolver contra vendor/fomantic-ui/2.9.4/ — onde os arquivos não existiam.

Decisões:

1. O registro ganha a chave arquivos: dependências que a biblioteca pede sozinha (fontes, sprites) e que NÃO viram tag. Migrar apenas o que aparece em <link>/<script> deixa a metade invisível para trás, e a falha é visível para o usuário e silenciosa para o servidor.

2. A régua é "tudo que ela pede está local", não "os arquivos que eu listei estão local". Foram 22 arquivos no caso do Fomantic — e o Lato veio junto, eliminando mais uma busca externa.

DEC-124 - 2026-08-29 - accepted

Fontes hospedadas pelo próprio projeto, com filtro de subset (BATCH-148).

Um <link> para [REDACTED] faz o navegador de cada visitante entregar ao Google IP, Referer e User-Agent antes de qualquer consentimento. Precedente: Landgericht München I, 2022 (Az. 3 O 17493/20). Licença não é obstáculo: OFL e Apache 2.0 permitem hospedar.

Decisões:

1. O comando descobre as URLs nos recursos em vez de exigir uma lista: acrescentar uma família ao layout e rodar o comando basta, e a declaração não pode divergir do que os layouts realmente pedem.

2. User-Agent moderno é requisito, não detalhe: o Google decide o formato por ele. Sem um moderno, devolve ttf — várias vezes maior, sem a compressão que justifica o formato web.

3. Filtra subsets, preserva unicode-range: das 78 faces devolvidas, 50 eram cirílico, grego e vietnamita. Mas o unicode-range das 28 restantes é preservado — é ele que faz o navegador baixar só o subset necessário. Removê-lo transformaria a economia em desperdício de banda do visitante.

4. Escreve na FONTE do projeto, não no espelho: resolve() prefere path_tests, mas o pipeline lê e o deploy publica path. Gravar no espelho faria o trabalho sumir no próximo sync, sem erro.

5. O @import era o pior caso: no CSS de destaques, além de vazar dados, ele BLOQUEAVA a renderização até a resposta do Google chegar.

DEC-125 - 2026-08-29 - accepted

Minificar é build; escolher o arquivo é resolução — nunca transformar o corpo na entrega (BATCH-148).

A sugestão original era minificar no arquivo-estatico.php. O controlador ganhou no BATCH-100 Content-Length, Accept-Ranges, ETag e 304, e os quatro dependem de o corpo entregue ser exatamente o arquivo em disco.

Decisões:

1. As duas responsabilidades ficam separadas: c2f assets:minify produz o derivado no build; arquivo_estatico_preferir_minificado() apenas ESCOLHE qual arquivo enviar. O envio continua sendo um envio de arquivo, e as quatro garantias seguem corretas — medido: Content-Length 17305 batendo byte a byte, 304 no If-None-Match, 206 com 100 bytes no Range.

2. O minificado é derivado, irmão de css_precompiled (CR-002): gerado por build, nunca editado à mão, sempre recalculável, com procedência (sha1 do fonte) registrada em manifesto.

3. A escolha acontece DEPOIS da autorização: o containment continua decidido num lugar só.

4. Em desenvolvimento serve o fonte: depurar com nomes destruídos pelo --mangle é pior que baixar alguns KB a mais — e isso torna inofensivo o derivado envelhecer enquanto alguém edita, porque quem edita está em dev.

5. node --check obrigatório antes de gravar: sintaxe inválida quebraria a tela sem sinal no servidor, e o arquivo de autoria — maior, porém correto — é sempre a alternativa preferível. O limite fica declarado: isso valida sintaxe, não semântica.

6. A etapa entra no pipeline, não fatal: fora dele viraria "alguém precisa lembrar", e derivado velho serviria código antigo com cara de novo. Máquina sem Node continua rodando o pipeline.

DEC-126 - 2026-08-29 - accepted

O css:rebuild regenera apenas o que foi editado ONLINE (BATCH-149).

A tela /perfil-usuario/ apareceu sem estilo depois do BATCH-148. Dois defeitos somados, ambos meus:

1. regenerarFontesDeclaradas() só lia <id>.json (metadado por recurso). O perfil-usuario não tem esse arquivo: as 15 páginas dele declaram tailwind_sources no MANIFESTO DO MÓDULO. A função devolvia lista vazia e a regeneração descartava as utilities montadas em PHP/JS.

2. Mesmo com as fontes lidas, o resultado (13.429 bytes) continuava menor que o do build offline (25.276), porque o resources:sync compila com o contexto completo do projeto.

Decisões:

1. O escopo do css:rebuild é user_modified = 1: o problema que o req-141 descreve existe SÓ quando o HTML do banco divergiu do HTML do disco. Para user_modified = 0, o build offline já compilou do MESMO HTML, com mais contexto. Regenerar ali não corrige nada e troca um CSS completo por um mais pobre. Medido: 17 de 1.446 recursos precisavam de regeneração; os outros 1.429 eram dano puro.

2. --todos continua alcançando o acervo, para auditoria e recuperação.

3. As fontes declaradas são lidas também do manifesto do módulo, mantendo o containment (realpath preso à raiz do gestor): a origem da declaração muda, a guarda não.

4. A lição registrada: uma etapa de pipeline que REESCREVE derivados precisa de escopo mínimo demonstrável. A minha reescrevia 1.446 registros para consertar 17, e o excesso era invisível — o comando reportava sucesso.

DEC-127 - 2026-08-29 - accepted

Assets locais também no layout administrativo Tailwind, com guarda de versão (BATCH-149).

O inventário do BATCH-146 procurou dist/semantic.min.css e não viu dist/components/icon.min.css — outro caminho do mesmo pacote, usado pelo layout Tailwind do gestor. O lucide estava ao lado, também por CDN.

Decisões:

1. fomantic-icon é entrada própria no registro: o layout precisa só do componente de ícones, e carregar os 2,1 MB do Fomantic inteiro para desenhar ícone seria pior que o CDN. As fontes vão junto (DEC-123), com o relativo correto para dist/components/ (../themes/...).

2. Recurso HTML não chama PHP, então o layout escreve o caminho com a versão dentro. O risco é a versão do registro e a do layout divergirem, produzindo 404 silencioso — exatamente a falha dos ícones. Por isso existe teste que compara as duas.

3. Teste que exige o arquivo no disco para cada entrada do registro: assets_externos_url() cai no CDN em silêncio quando o local falta; a suíte transforma esse silêncio em falha.

DEC-128 - 2026-08-30 - accepted

Dependências Tailwind de sistema: declarada falha alto, automática degrada em silêncio (BATCH-150).

O modal de alerta (interface_alerta()) aparecia sem estilo na tela de login do Photon (/photon/signin/): botão com texto branco sobre fundo transparente, sem sombra e sem limite de largura (7 de 12 classes sem regra). O CSS do modal existia compilado em banco e disco (4.694 B), mas não pertencia à compilação daquela página. O modal é injetado dinamicamente em runtime, e a compilação por recurso dependia de declaração manual em tailwind_dependencies em cada página — uma lista de exceções que bastou falhar em acessar-sistema para quebrar a interface.

Ao transformar os três modais de sistema injetados em runtime (interface-alerta-modal-tailwind, interface-carregamento-dimmer-tailwind, interface-confirmacao-exclusao-modal-tailwind) em dependências automáticas de toda página Tailwind no compilador (tailwind_recursos_dependencies()), a compilação estrita abortou todo o build do Photon com erro fatal, pois o projeto local traz os componentes em pt-br e não em en.

Decisões:

1. Modais de sistema injetados em runtime são dependência automática de toda página Tailwind: nenhuma página precisa declarar manualmente os componentes que o próprio core pode injetar por função global (interface_alerta(), dimmers ou confirmações).

2. Distinção de severidade entre dependência declarada e automática:

   • Dependência declarada pelo desenvolvedor continua falhando alto com erro fatal: a ausência indica erro de digitação, dependência quebrada ou caminho incorreto no manifesto/metadado.

   • Dependência automática injetada pelo framework é marcada como opcional: true e degrada em silêncio: quem a inseriu foi o sistema e não o autor da página. Em ambientes/idiomas onde o componente ainda não existe ou não foi sincronizado (ex: ausência de variantes en), a compilação segue sem abortar a esteira.

3. Guarda de sincronia na suíte de testes: teste unitário compara o mapa de injeção em runtime de interface_componentes_incluir() com a lista de modais automáticos do compilador, impedindo que um novo modal de sistema nasça sem estilo no Tailwind.

DEC-129 - 2026-10-03 - accepted

• Contexto: req-215 (parte do core da REQ-096 do conn2flow-site). Na arquitetura "painel no Central, execução no cliente", o painel precisa de efeitos que só existem no site do cliente.

• Decisão: o canal assinado ganha a ação rotina. O Central pede uma rotina por nome; o cliente só executa o que o manifesto da cópia de execução declarou em routines. Tabelas do core continuam fora do canal de banco: o painel do Central as usa para se desenhar.

• Decisão: cópia de execução (scope: distributed-execution) só age quando o módulo (ou um de active_with) está contratado no .env da instalação.

• Consequência: regra de negócio de cada efeito fica no projeto (no conn2flow-site, a biblioteca site-local); o core só transporta e confere.

DEC-130 - 2026-10-03 - accepted

• Contexto: req-216 (parte do core da REQ-097 do conn2flow-site). O Engenheiro Chefe definiu que o acesso aos módulos distribuídos vem do perfil do usuário no Central, sem lista por cliente, e que a inadimplência tem quatro estados.

• Decisão: o cliente lê o catálogo do próprio pacote (project/distributed-modules.json); a lista do .env fica opcional.

• Decisão: o canal ganha a ação estado. O projeto fornece o estado (account-provider); o core transporta, assina, guarda no cliente e aplica: carência com aviso, suspenso só de visualização (garantido no canal), encerrado fora do painel.

• Decisão: módulo que já executou no cliente continua executando, para não derrubar pós-venda.

• Consequência: a regra de cobrança fica no projeto; o core não conhece assinatura nem plano.

DEC-131 - 2026-10-03 - accepted

• Contexto: req-217, pedido do Engenheiro Chefe: mesmo com a chave do canal vazada, o [REDACTED] ser identificado.

• Decisão: o segredo da instalação só abre sessão (abrir). Quem recebe confirma a origem ligando para o endereço que ele tem cadastrado (confirmar) e só então entrega uma chave de sessão aleatória de 15 minutos; requisições comuns são assinadas com ela (X-C2F-Session).

• Decisão: o endereço de retorno nunca vem da requisição: central-url no cliente, url do cadastro no Central.

• Consequência: Central e sites precisam ser publicados juntos; MODULO_DISTRIBUIDO_ORIGIN_CHECK=false volta ao canal anterior durante a transição. Próximo passo proposto: chaves assimétricas (Ed25519).

DEC-132 - 2026-10-04 - accepted

• Contexto: req-219. O editor HTML tem cerca de 10 mil linhas de JavaScript sobre a API do Fomantic (dropdown, modal, tab…) e o Engenheiro Chefe pediu o painel em Tailwind, sem jQuery onde der.

• Decisão: a troca é por variante de componente (<id>-tailwind, escolhida por interface_componente_variante()), que guarda marcadores, ids, nomes, data-tab e as classes-gancho do JS. As classes ui … restantes são só ganchos, sem CSS na página. Um teste compara cada variante com a original.

• Decisão: onde o Fomantic não está, a biblioteca de controles (controles.js, sem framework) responde pela API do Fomantic usada no core (ponte). O JS legado passa a vanilla aos poucos, sem quebrar as duas variantes no meio do caminho.

• Decisão: estilo de elemento gerado por PHP ou JS vai em classe c2fc-* própria (controles.css); utilities do Tailwind só no HTML dos recursos, que é o que o compilador enxerga.

• Decisão: página Tailwind com o editor usa bundle (tailwind_bundle + $_GESTOR['tailwind-page-bundle'] = true); sem o flag, os sidecars dos componentes invertem as responsivas.

• Consequência: cada módulo migra trocando layout e páginas e ganhando as variantes que faltam; a fatia 6 segue esse caminho por grupo de módulos.