docs/IMPLEMENTATION_PLAN_DASHBOARD_OPERACIONAL_CACHE_SHORTCUTS_COMPACT.md

Plano Executavel - Dashboard Operacional (Cache + Shortcuts + Compact Mode)

Data: 2026-02-21 Status: pronto para execucao Escopo: melhorias de velocidade operacional sem alterar contratos principais do agente.

Links rapidos:

• Indice de documentacao
• Plano principal de paridade agente/dashboard
• Guia tecnico do produto

1) Objetivo

• Reduzir latencia percebida da dashboard em acessos repetidos.
• Acelerar operacao ao vivo com atalhos de teclado.
• Criar visualizacao "second screen" com menor ruido e foco no essencial.

2) Escopo fechado (3 features)

F1. Cache seletivo de assets estaticos com ETag + Cache-Control. F2. Atalhos de teclado operacionais (r refresh, g run tick). F3. Modo compacto para monitoramento continuo.

3) Baseline AS-IS (confirmado no codigo)

• bot/dashboard_server.py aplica Cache-Control: no-store para toda resposta, inclusive assets estaticos.
• Dashboard ja tem botoes para Re-Sync, Refresh Queue e Run 1 Tick, mas sem atalhos de teclado globais.
• Nao existe estado de "compact mode" em dashboard/index.html, dashboard/main.js e CSS.
• Rotas e autenticacao estao corretas (challenge Basic em /dashboard, token para /api/*).

4) Requisitos obrigatorios

R1. API e HTML continuam sem cache (no-store). R2. Apenas CSS/JS/static recebem cache curto com revalidacao por ETag. R3. r dispara refresh operacional sem quebrar foco de campos de input. R4. g dispara POST /api/autonomy/tick com feedback visual. R5. Compact mode preserva controles criticos no topo e oculta blocos densos. R6. Estado do compact mode persiste em localStorage. R7. Nenhum arquivo novo/alterado passa de 300 linhas.

5) Contrato tecnico alvo

5.1 Cache seletivo de assets

Backend (bot/dashboard_server.py):

• Adicionar branch de resposta para assets estaticos:
• index.html: Cache-Control: no-store.
• .css/.js: Cache-Control: public, max-age=120, must-revalidate.
• Gerar ETag forte por hash de bytes do arquivo.
• Aceitar If-None-Match e retornar 304 sem body quando bater.
• Manter auth exatamente igual (sem bypass por cache).

5.2 Shortcuts operacionais

Frontend:

• Novo modulo dashboard/features/shortcuts/controller.js.
• r: executa sequencia rapida:
• refresh observability;
• refresh action queue;
• channel-control list (re-sync de canais).
• g: dispara o mesmo handler de Run 1 Tick.
• Ignorar atalhos quando foco estiver em input, textarea, select ou elemento contenteditable.
• Adicionar throttle de 1.2s para evitar spam por key repeat.

5.3 Compact mode

Frontend:

• Toggle visual no topo (Compact: on/off) em dashboard/index.html.
• Persistencia em localStorage com chave byte.dashboard.compact_mode.
• Classe body.compact-mode para alterar layout.
• Em compact mode:
• manter visiveis: topbar, channel manager, KPIs, autonomy runtime, risk queue.
• recolher/ocultar: tabelas longas de analytics, context internals e listas extensas.
• reduzir paddings e fontes secundarias para caber em second screen.

6) Plano por fases

Fase 0 - Safety baseline (pre-condicao)

• Criar testes de contrato atuais em bot/tests/scientific/suite_http.py:
• dashboard asset retorna 200 com body;
• API continua Cache-Control: no-store.
• Aceite: baseline travada antes de mudar cache.

Fase 1 - Cache seletivo de assets

• Implementar helpers de cache em bot/dashboard_server.py:
• calculo de ETag;
• resposta 304;
• headers por tipo de recurso.
• Nao alterar handle_get/handle_post da API.
• Testes:
• suite_http: cobertura de ETag, If-None-Match, 304, e no-store para API.
• Aceite:
• assets repetidos respondem 304;
• endpoints API continuam sem cache.

Fase 2 - Shortcuts de teclado

• Criar dashboard/features/shortcuts/controller.js.
• Integrar no bootstrap em dashboard/main.js.
• Exibir feedback curto no topo ao executar atalho (ex.: Shortcut: refresh).
• Testes/smoke:
• validar que r e g funcionam com foco fora de input;
• validar que nada dispara digitando em campos.
• Aceite:
• operacao principal fica acionavel sem mouse, sem regressao de UX.

Fase 3 - Compact mode

• Adicionar botao/estado no index.html.
• Implementar controlador de estado compacto em dashboard/main.js ou modulo proprio.
• Adicionar regras CSS em dashboard/styles/layout.css e dashboard/styles/components.css.
• Testes/smoke:
• persistencia apos reload;
• layout legivel em 1366x768 e em mobile sem quebrar fluxo atual.
• Aceite:
• visual compacto reduz ruido e mantem controles de operacao ao vivo.

Fase 4 - Validacao final e deploy

• Rodar testes rapidos:
• pytest bot/tests/test_scientific.py -v -x
• pytest bot/tests/test_observability.py -v -x
• Smoke manual:
• /dashboard auth;
• refresh via teclado;
• tick manual via teclado;
• modo compacto persistente.
• Deploy com rollback simples (reverter revisao Cloud Run anterior).

7) Definition of Done

• Cache seletivo ativo apenas para assets estaticos, com ETag funcional.
• Shortcuts r e g operando de forma segura e previsivel.
• Compact mode funcionando e persistente, sem perda de controle critico.
• Sem regressao de auth/dashboard API.
• Documentacao indexada em docs/INDEX.md.