REQ-241 — Atualização automatizada do sistema, ativável pelo painel

Poder ligar, pelo painel, a atualização automática do sistema: o próprio site confere se há versão nova e se atualiza sozinho. Como a atualização já tem verificação…

Status: ready-for-intake
Modo de Autonomia: a definir pelo Engenheiro Chefe na promoção
Lote Alvo Core: BATCH-250 (conn2flow)
Data de Criação: 2026-10-06
Origem: pedido do Engenheiro Chefe durante a REQ-240, ao revisar a tela nova do admin-atualizacoes. Redigida pelo agente da REQ-240 a pedido dele; não foi implementada.
Repositório: conn2flow em [REDACTED]

1. Pedido

Poder ligar, pelo painel, a atualização automática do sistema: o próprio site confere se há versão nova e se atualiza sozinho. Como a atualização já tem verificação pós-atualização e volta automática (req-198, req-201), uma versão que quebra é desfeita sem intervenção; quando sair uma versão mais nova, o site tenta de novo.

O rollback disparado manualmente pela tela não faz parte desta requisição: fica pelo sistema (CLI e API), por decisão do Engenheiro Chefe.

2. O que já existe e deve ser reaproveitado

Peça	Onde	Observação
Execução em segundo plano	`/_api/system/update`, `action=run`, `run-status`, `runs` (req-201)	É o caminho que a automação deve chamar; não criar um segundo executor.
Trava de deploy	`gestor/bibliotecas/deploy-lock.php` (req-197)	Impede duas atualizações ao mesmo tempo.
Snapshot, verificação e volta automática	`atualizacoes-sistema.php`: `--no-health`, `--no-rollback`, `--health-url`, `--health-ip`	A automação roda sempre com verificação e com volta automática.
Versão instalada e versões publicadas	`action=version` (req-204) e a consulta de releases do atualizador	Fonte da comparação.
Histórico	tabela `atualizacoes_execucoes`	Onde a tentativa automática fica registrada.
Tarefas agendadas	módulo `admin-cron` e a biblioteca de cron	Onde a checagem periódica mora.
Tela	`admin-atualizacoes` (req-240)	Onde entram o interruptor e o estado.

3. Comportamento esperado

3.1 Configuração (tela `admin-atualizacoes`)

Interruptor Atualização automática, desligado por padrão.
Janela: dias da semana e faixa de horário em que a atualização pode rodar.
Canal: só versões estáveis (padrão) ou também pré-lançamentos.
Backup completo antes (equivalente a --backup), ligado por padrão.
Aviso por e-mail ao administrador a cada tentativa: sucesso, volta automática ou falha.
Bloco de estado: última checagem, versão encontrada, próxima janela, última tentativa automática e o resultado dela.

3.2 Ciclo

Uma tarefa agendada confere a versão publicada mais recente do canal escolhido.
Se é mais nova que a instalada, não está na lista de versões recusadas e o momento está dentro da janela, dispara a atualização pelo mesmo caminho do action=run, modo completo, com verificação e volta automática.
Sucesso: registra, avisa e encerra.
Volta automática ou falha: a versão entra na lista de recusadas e não é tentada de novo. A próxima tentativa só acontece quando houver uma versão mais nova que ela.
Sem versão nova, fora da janela ou com a trava ocupada: não faz nada e registra a checagem.

3.3 Salvaguardas

Nunca roda com --wipe, --no-verify, --no-health ou --no-rollback.
Há choque pendente de decisão (atualizacoes_choques sem resolução): a automação não atualiza e avisa. Decisão de choque é humana.
Uma tentativa por versão; no máximo uma atualização automática por janela.
A versão recusada pode ser liberada à mão na tela ("tentar de novo").
Tudo o que a automação faz aparece no histórico, marcado como automático.

4. Fora de escopo

Rollback manual pela tela.
Atualização automática de plugins e de projetos (só o sistema).
Orquestração em massa de vários sites: isso é do host-manager do conn2flow-site.

5. Critérios de aceite

CA-1: com o interruptor desligado, nenhuma checagem dispara atualização.
CA-2: ligado, dentro da janela e com versão nova, a atualização roda sozinha e fica no histórico como automática.
CA-3: uma versão que termina em volta automática entra na lista de recusadas e não é tentada de novo; uma versão mais nova é tentada.
CA-4: fora da janela, com a trava ocupada ou com choque pendente, nada é atualizado e o motivo fica registrado.
CA-5: as opções proibidas da seção 3.3 não podem ser ativadas pela automação, nem por configuração gravada à mão.
CA-6: testes de unidade para a decisão do ciclo (comparação de versões, janela, lista de recusadas, choque pendente, trava) e validação ponta a ponta no tenant isolado [REDACTED] do Lab, com sucesso e com volta automática.
CA-7: textos da tela por variáveis, em pt-br e en; tela sem overflow a 390 px.

6. Pontos para decidir na promoção

Onde guardar a configuração: .env do host (como as demais chaves de ambiente) ou tabela própria.
Se a checagem usa a API pública de releases do GitHub diretamente ou um endpoint do Central.
Frequência padrão da checagem (sugestão: a cada 6 horas).
Se o padrão do backup completo deve ser ligado mesmo em instalações com pouco disco.

7. Live Todo List

[ ] Decisão do ciclo como função pura, com testes.
[ ] Tarefa agendada de checagem e disparo.
[ ] Lista de versões recusadas e liberação manual.
[ ] Configuração e bloco de estado na tela admin-atualizacoes.
[ ] Aviso por e-mail.
[ ] Validação no tenant [REDACTED] (sucesso e volta automática).
[ ] Relatório em BATCH-250.md.

# REQ-241 — Atualização automatizada do sistema, ativável pelo painel
- **Status:** `ready-for-intake`
- **Modo de Autonomia:** a definir pelo Engenheiro Chefe na promoção
- **Lote Alvo Core:** `BATCH-250` (`conn2flow`)
- **Data de Criação:** 2026-10-06
- **Origem:** pedido do Engenheiro Chefe durante a REQ-240, ao revisar a tela nova do `admin-atualizacoes`. Redigida pelo agente da REQ-240 a pedido dele; não foi implementada.
- **Repositório:** `conn2flow` em `[REDACTED]`
---
## 1. Pedido
Poder ligar, pelo painel, a atualização automática do sistema: o próprio site confere se há versão nova e se atualiza sozinho. Como a atualização já tem verificação pós-atualização e volta automática (req-198, req-201), uma versão que quebra é desfeita sem intervenção; quando sair uma versão mais nova, o site tenta de novo.
O rollback disparado manualmente pela tela **não** faz parte desta requisição: fica pelo sistema (CLI e API), por decisão do Engenheiro Chefe.
## 2. O que já existe e deve ser reaproveitado
| Peça | Onde | Observação |
| --- | --- | --- |
| Execução em segundo plano | `/_api/system/update`, `action=run`, `run-status`, `runs` (req-201) | É o caminho que a automação deve chamar; não criar um segundo executor. |
| Trava de deploy | `gestor/bibliotecas/deploy-lock.php` (req-197) | Impede duas atualizações ao mesmo tempo. |
| Snapshot, verificação e volta automática | `atualizacoes-sistema.php`: `--no-health`, `--no-rollback`, `--health-url`, `--health-ip` | A automação roda sempre **com** verificação e **com** volta automática. |
| Versão instalada e versões publicadas | `action=version` (req-204) e a consulta de releases do atualizador | Fonte da comparação. |
| Histórico | tabela `atualizacoes_execucoes` | Onde a tentativa automática fica registrada. |
| Tarefas agendadas | módulo `admin-cron` e a biblioteca de cron | Onde a checagem periódica mora. |
| Tela | `admin-atualizacoes` (req-240) | Onde entram o interruptor e o estado. |
## 3. Comportamento esperado
### 3.1 Configuração (tela `admin-atualizacoes`)
- Interruptor **Atualização automática**, desligado por padrão.
- **Janela**: dias da semana e faixa de horário em que a atualização pode rodar.
- **Canal**: só versões estáveis (padrão) ou também pré-lançamentos.
- **Backup completo antes** (equivalente a `--backup`), ligado por padrão.
- **Aviso por e-mail** ao administrador a cada tentativa: sucesso, volta automática ou falha.
- Bloco de estado: última checagem, versão encontrada, próxima janela, última tentativa automática e o resultado dela.
### 3.2 Ciclo
1. Uma tarefa agendada confere a versão publicada mais recente do canal escolhido.
2. Se é mais nova que a instalada, não está na lista de versões recusadas e o momento está dentro da janela, dispara a atualização pelo mesmo caminho do `action=run`, modo completo, com verificação e volta automática.
3. **Sucesso**: registra, avisa e encerra.
4. **Volta automática ou falha**: a versão entra na lista de recusadas e **não é tentada de novo**. A próxima tentativa só acontece quando houver uma versão mais nova que ela.
5. Sem versão nova, fora da janela ou com a trava ocupada: não faz nada e registra a checagem.
### 3.3 Salvaguardas
- Nunca roda com `--wipe`, `--no-verify`, `--no-health` ou `--no-rollback`.
- Há choque pendente de decisão (`atualizacoes_choques` sem resolução): a automação **não** atualiza e avisa. Decisão de choque é humana.
- Uma tentativa por versão; no máximo uma atualização automática por janela.
- A versão recusada pode ser liberada à mão na tela ("tentar de novo").
- Tudo o que a automação faz aparece no histórico, marcado como automático.
## 4. Fora de escopo
- Rollback manual pela tela.
- Atualização automática de plugins e de projetos (só o sistema).
- Orquestração em massa de vários sites: isso é do `host-manager` do `conn2flow-site`.
## 5. Critérios de aceite
- **CA-1**: com o interruptor desligado, nenhuma checagem dispara atualização.
- **CA-2**: ligado, dentro da janela e com versão nova, a atualização roda sozinha e fica no histórico como automática.
- **CA-3**: uma versão que termina em volta automática entra na lista de recusadas e não é tentada de novo; uma versão mais nova é tentada.
- **CA-4**: fora da janela, com a trava ocupada ou com choque pendente, nada é atualizado e o motivo fica registrado.
- **CA-5**: as opções proibidas da seção 3.3 não podem ser ativadas pela automação, nem por configuração gravada à mão.
- **CA-6**: testes de unidade para a decisão do ciclo (comparação de versões, janela, lista de recusadas, choque pendente, trava) e validação ponta a ponta no tenant isolado `[REDACTED]` do Lab, com sucesso e com volta automática.
- **CA-7**: textos da tela por variáveis, em pt-br e en; tela sem overflow a 390 px.
## 6. Pontos para decidir na promoção
- Onde guardar a configuração: `.env` do host (como as demais chaves de ambiente) ou tabela própria.
- Se a checagem usa a API pública de releases do GitHub diretamente ou um endpoint do Central.
- Frequência padrão da checagem (sugestão: a cada 6 horas).
- Se o padrão do backup completo deve ser ligado mesmo em instalações com pouco disco.
## 7. Live Todo List
- [ ] Decisão do ciclo como função pura, com testes.
- [ ] Tarefa agendada de checagem e disparo.
- [ ] Lista de versões recusadas e liberação manual.
- [ ] Configuração e bloco de estado na tela `admin-atualizacoes`.
- [ ] Aviso por e-mail.
- [ ] Validação no tenant `[REDACTED]` (sucesso e volta automática).
- [ ] Relatório em `BATCH-250.md`.