File size: 5,326 Bytes
89b6a21
 
127bfda
 
89b6a21
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
127bfda
 
89b6a21
 
 
 
 
 
 
 
 
 
 
127bfda
 
 
 
 
 
89b6a21
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
# 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](INDEX.md)
- [Plano principal de paridade agente/dashboard](IMPLEMENTATION_PLAN_EXECUTAVEL_PARIDADE_AGENT_DASHBOARD.md)
- [Guia tecnico do produto](DOCUMENTATION.md)

## 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`.