REQ-245 — Atualização automática do sistema, com abas Manual e Automático no `admin-atualizacoes`

Tela: [REDACTED]. Módulo de agendamento: [REDACTED].

Status: in-progress
Modo de Autonomia: autonomo_monitorado
Lote Alvo Core: BATCH-254 (conn2flow)
Data de Criação: 2026-10-06
Origem: pedido direto do Engenheiro Chefe ao executor da REQ-243, ao fim daquela requisição. Redigida e implementada pelo mesmo executor.
Absorve: REQ-241 (BATCH-250), que descrevia o mesmo recurso e não foi implementada. A REQ-241 fica como referência de ciclo e salvaguardas; o que diverge está na seção 3.
Repositório: conn2flow em [REDACTED]
Base da branch: feat/req-243 (a tela usa os controles corrigidos naquele lote, ainda não integrados à main).

1. Pedido, nas palavras do Engenheiro Chefe

"Para esse módulo aí que eu te passei, o admin-atualizacao, criar uma opção de ele poder atualizar automaticamente. Crie um hook para disparar no rotinas-automatico, o outro módulo (admin-cron). Analisa esse, você vai ver que tem uma estrutura que você consegue criar via sistema, declarando uma rotina automática por esse módulo. E aí você podia criar um controle de ativar, desativar e definir o período. Pode dar umas três opções de período, eu acho que para ver se tem atualização do sistema, não precisa ser sempre não. No atualização automática, ele faz sozinho tudo. E aí, se der algum problema, ele tem que dar rollback automático, alguma coisa do gênero para ter um controle de melhor qualidade. Mas você pode me dar sugestões do que você acha interessante."

"Logo abaixo [do resumo] tem atualização do sistema, nessa primeira linha aí que tem três boxes, eu acho que podia criar uma aba modo manual e automático. O modo manual é literalmente essas três opções, as três caixas a seguir, e o modo automático é esse novo que você vai criar. Tenta manter a mesma estrutura visual do que está na atualização do sistema, que está bem legalzinho."

Tela: [REDACTED]. Módulo de agendamento: [REDACTED].

2. O que já existe e é reaproveitado

Peça	Onde
Atualizador com trava, snapshot, verificação e volta automática	`controladores/atualizacoes/atualizacoes-sistema.php` (req-197, req-198)
Disparo em segundo plano e leitura do estado da execução	`bibliotecas/atualizacoes-execucao.php` (req-201)
Trava de deploy	`bibliotecas/deploy-lock.php`
Choques pendentes	tabela `atualizacoes_choques`
Tarefas agendadas declaradas por módulo	chave `cron` do manifesto + `<modulo>.cron.php`; tabela `cron_tarefas`; painel `admin-cron`

3. Decisões desta requisição (fecham a seção 6 da REQ-241)

Ponto	Decisão
Onde mora a configuração	Arquivo `atualizacao-automatica.json` na pasta do host (`autenticacoes/<domínio>/`), ao lado do `.env`: fora da área pública, fora do pacote da atualização e por instalação.
Agendamento	Tarefa declarada pelo módulo (`admin-atualizacoes-automatica`), frequência `horario`. A tarefa é barata: só consulta a rede quando a checagem está vencida.
Período da checagem	Três opções na tela: diária, semanal (padrão) e mensal.
Hora preferida	Uma hora do dia (padrão 03h). Substitui a "janela por dias da semana" da REQ-241, que fica como evolução.
Fonte das versões	API pública de releases do GitHub, a mesma do atualizador, com verificação de certificado.
Canal	Só versões estáveis (tags `gestor-v…` não marcadas como pré-lançamento).
Backup completo antes	Opção na tela, ligada por padrão.
Interruptor	Desligado por padrão. O estado do interruptor também liga e desliga a tarefa no `admin-cron`.

4. Comportamento

4.1 Tela

Abaixo do resumo, abas Manual e Automático.
Manual: os três blocos atuais (modo, opções, execução), sem mudança de comportamento.
Automático, no mesmo desenho de blocos numerados:
1. Interruptor e período (três cartões de escolha, como os de modo).
2. Opções: hora preferida e backup completo antes.
3. Estado: última checagem, versão encontrada, próxima checagem, última tentativa e resultado, versões recusadas (com "tentar de novo") e o botão Verificar agora (só confere, não atualiza).
A aba aberta é lembrada no navegador.

4.2 Ciclo (tarefa agendada)

Desligado: não faz nada.
Há execução automática pendente: lê o resultado. Sucesso encerra; volta automática ou falha põe a versão na lista de recusadas.
Fora da hora preferida ou checagem ainda não vencida: não faz nada.
Consulta a versão estável mais recente e registra a checagem.
Atualiza quando: a versão é mais nova que a instalada, não está recusada, não há choque pendente e a trava de deploy está livre. Caso contrário registra o motivo.
A atualização é disparada em segundo plano pelo mesmo caminho da API (atualizacoes-execucao.php), modo completo.

4.3 Salvaguardas

A automação nunca usa wipe, no_verify, no_health, no_rollback, dry_run nem modos parciais, ainda que o arquivo de configuração seja editado à mão: as opções saem de uma lista fechada no código.
Uma tentativa por versão. A versão recusada só volta a ser tentada se o administrador liberar, ou quando sair uma mais nova.
Choque pendente é decisão humana: a automação não atualiza.
Tudo o que a automação faz fica no estado da tela e no log da tarefa no admin-cron.

5. Fora de escopo

Rollback manual pela tela (segue por CLI e API).
Plugins e projetos; orquestração de vários sites (é do host-manager do conn2flow-site).
Aviso por e-mail, janela por dias da semana e canal de pré-lançamento (sugestões da seção 7).

6. Critérios de aceite

CA-1: interruptor desligado, nenhuma checagem dispara atualização.
CA-2: ligado, na hora preferida, checagem vencida e versão nova: a atualização é disparada em modo completo, com verificação e volta automática.
CA-3: versão que termina em volta automática ou falha entra nas recusadas e não é tentada de novo; uma mais nova é tentada; "tentar de novo" libera.
CA-4: fora da hora, checagem em dia, trava ocupada ou choque pendente: nada é atualizado e o motivo fica registrado.
CA-5: opções proibidas não passam, nem por arquivo de configuração alterado à mão.
CA-6: testes de unidade para a decisão do ciclo, a comparação de versões, o vencimento por período e a leitura da configuração.
CA-7: abas Manual e Automático; o modo manual segue funcionando; textos por variáveis em pt-br e en; sem rolagem lateral a 390 px.
CA-8: a tarefa aparece no admin-cron como rotina do módulo e acompanha o interruptor.

7. Sugestões do executor para depois (não implementadas aqui)

Aviso por e-mail a cada tentativa (sucesso, volta automática, falha) e quando houver versão nova mas a automação estiver travada por choque.
Janela por dias da semana (por exemplo, só de terça a quinta), para não atualizar em véspera de fim de semana.
Espera de segurança: só instalar uma versão publicada há mais de N dias, deixando outros sites encontrarem os problemas primeiro.
Só avisar: um modo intermediário que confere e avisa que há versão nova, sem instalar.
Validação ponta a ponta no tenant isolado [REDACTED] com uma versão que quebra de propósito, para provar a volta automática disparada pela tarefa (a volta em si já foi validada na req-198 e na req-201).

8. Live Todo List

[ ] Biblioteca: configuração, comparação de versões, vencimento e decisão do ciclo, com testes.
[ ] Tarefa agendada declarada pelo módulo e callback.
[ ] Ações do painel: salvar, verificar agora, liberar versão recusada.
[ ] Tela com abas Manual e Automático.
[ ] resources:sync, suítes, Lab e roteiro de navegador.
[ ] Relatório em BATCH-254.md.

# REQ-245 — Atualização automática do sistema, com abas Manual e Automático no `admin-atualizacoes`
- **Status:** `in-progress`
- **Modo de Autonomia:** `autonomo_monitorado`
- **Lote Alvo Core:** `BATCH-254` (`conn2flow`)
- **Data de Criação:** 2026-10-06
- **Origem:** pedido direto do Engenheiro Chefe ao executor da REQ-243, ao fim daquela requisição. Redigida e implementada pelo mesmo executor.
- **Absorve:** [REQ-241](req-241.md) (BATCH-250), que descrevia o mesmo recurso e não foi implementada. A REQ-241 fica como referência de ciclo e salvaguardas; o que diverge está na seção 3.
- **Repositório:** `conn2flow` em `[REDACTED]`
- **Base da branch:** `feat/req-243` (a tela usa os controles corrigidos naquele lote, ainda não integrados à `main`).
---
## 1. Pedido, nas palavras do Engenheiro Chefe
> "Para esse módulo aí que eu te passei, o admin-atualizacao, criar uma opção de ele poder atualizar automaticamente. Crie um hook para disparar no rotinas-automatico, o outro módulo (`admin-cron`). Analisa esse, você vai ver que tem uma estrutura que você consegue criar via sistema, declarando uma rotina automática por esse módulo. E aí você podia criar um controle de ativar, desativar e definir o período. Pode dar umas três opções de período, eu acho que para ver se tem atualização do sistema, não precisa ser sempre não. No atualização automática, ele faz sozinho tudo. E aí, se der algum problema, ele tem que dar rollback automático, alguma coisa do gênero para ter um controle de melhor qualidade. Mas você pode me dar sugestões do que você acha interessante."
> "Logo abaixo [do resumo] tem atualização do sistema, nessa primeira linha aí que tem três boxes, eu acho que podia criar uma aba modo manual e automático. O modo manual é literalmente essas três opções, as três caixas a seguir, e o modo automático é esse novo que você vai criar. Tenta manter a mesma estrutura visual do que está na atualização do sistema, que está bem legalzinho."
Tela: `[REDACTED]`. Módulo de agendamento: `[REDACTED]`.
## 2. O que já existe e é reaproveitado
| Peça | Onde |
| --- | --- |
| Atualizador com trava, snapshot, verificação e volta automática | `controladores/atualizacoes/atualizacoes-sistema.php` (req-197, req-198) |
| Disparo em segundo plano e leitura do estado da execução | `bibliotecas/atualizacoes-execucao.php` (req-201) |
| Trava de deploy | `bibliotecas/deploy-lock.php` |
| Choques pendentes | tabela `atualizacoes_choques` |
| Tarefas agendadas declaradas por módulo | chave `cron` do manifesto + `<modulo>.cron.php`; tabela `cron_tarefas`; painel `admin-cron` |
## 3. Decisões desta requisição (fecham a seção 6 da REQ-241)
| Ponto | Decisão |
| --- | --- |
| Onde mora a configuração | Arquivo `atualizacao-automatica.json` na pasta do host (`autenticacoes/<domínio>/`), ao lado do `.env`: fora da área pública, fora do pacote da atualização e por instalação. |
| Agendamento | Tarefa declarada pelo módulo (`admin-atualizacoes-automatica`), frequência `horario`. A tarefa é barata: só consulta a rede quando a checagem está vencida. |
| Período da checagem | Três opções na tela: **diária**, **semanal** (padrão) e **mensal**. |
| Hora preferida | Uma hora do dia (padrão 03h). Substitui a "janela por dias da semana" da REQ-241, que fica como evolução. |
| Fonte das versões | API pública de releases do GitHub, a mesma do atualizador, com verificação de certificado. |
| Canal | Só versões estáveis (tags `gestor-v…` não marcadas como pré-lançamento). |
| Backup completo antes | Opção na tela, ligada por padrão. |
| Interruptor | Desligado por padrão. O estado do interruptor também liga e desliga a tarefa no `admin-cron`. |
## 4. Comportamento
### 4.1 Tela
- Abaixo do resumo, abas **Manual** e **Automático**.
- **Manual**: os três blocos atuais (modo, opções, execução), sem mudança de comportamento.
- **Automático**, no mesmo desenho de blocos numerados:
  1. Interruptor e período (três cartões de escolha, como os de modo).
  2. Opções: hora preferida e backup completo antes.
  3. Estado: última checagem, versão encontrada, próxima checagem, última tentativa e resultado, versões recusadas (com "tentar de novo") e o botão **Verificar agora** (só confere, não atualiza).
- A aba aberta é lembrada no navegador.
### 4.2 Ciclo (tarefa agendada)
1. Desligado: não faz nada.
2. Há execução automática pendente: lê o resultado. Sucesso encerra; volta automática ou falha põe a versão na lista de recusadas.
3. Fora da hora preferida ou checagem ainda não vencida: não faz nada.
4. Consulta a versão estável mais recente e registra a checagem.
5. Atualiza quando: a versão é mais nova que a instalada, não está recusada, não há choque pendente e a trava de deploy está livre. Caso contrário registra o motivo.
6. A atualização é disparada em segundo plano pelo mesmo caminho da API (`atualizacoes-execucao.php`), modo completo.
### 4.3 Salvaguardas
- A automação nunca usa `wipe`, `no_verify`, `no_health`, `no_rollback`, `dry_run` nem modos parciais, ainda que o arquivo de configuração seja editado à mão: as opções saem de uma lista fechada no código.
- Uma tentativa por versão. A versão recusada só volta a ser tentada se o administrador liberar, ou quando sair uma mais nova.
- Choque pendente é decisão humana: a automação não atualiza.
- Tudo o que a automação faz fica no estado da tela e no log da tarefa no `admin-cron`.
## 5. Fora de escopo
- Rollback manual pela tela (segue por CLI e API).
- Plugins e projetos; orquestração de vários sites (é do `host-manager` do `conn2flow-site`).
- Aviso por e-mail, janela por dias da semana e canal de pré-lançamento (sugestões da seção 7).
## 6. Critérios de aceite
- **CA-1**: interruptor desligado, nenhuma checagem dispara atualização.
- **CA-2**: ligado, na hora preferida, checagem vencida e versão nova: a atualização é disparada em modo completo, com verificação e volta automática.
- **CA-3**: versão que termina em volta automática ou falha entra nas recusadas e não é tentada de novo; uma mais nova é tentada; "tentar de novo" libera.
- **CA-4**: fora da hora, checagem em dia, trava ocupada ou choque pendente: nada é atualizado e o motivo fica registrado.
- **CA-5**: opções proibidas não passam, nem por arquivo de configuração alterado à mão.
- **CA-6**: testes de unidade para a decisão do ciclo, a comparação de versões, o vencimento por período e a leitura da configuração.
- **CA-7**: abas Manual e Automático; o modo manual segue funcionando; textos por variáveis em pt-br e en; sem rolagem lateral a 390 px.
- **CA-8**: a tarefa aparece no `admin-cron` como rotina do módulo e acompanha o interruptor.
## 7. Sugestões do executor para depois (não implementadas aqui)
1. **Aviso por e-mail** a cada tentativa (sucesso, volta automática, falha) e quando houver versão nova mas a automação estiver travada por choque.
2. **Janela por dias da semana** (por exemplo, só de terça a quinta), para não atualizar em véspera de fim de semana.
3. **Espera de segurança**: só instalar uma versão publicada há mais de N dias, deixando outros sites encontrarem os problemas primeiro.
4. **Só avisar**: um modo intermediário que confere e avisa que há versão nova, sem instalar.
5. **Validação ponta a ponta no tenant isolado** `[REDACTED]` com uma versão que quebra de propósito, para provar a volta automática disparada pela tarefa (a volta em si já foi validada na req-198 e na req-201).
## 8. Live Todo List
- [ ] Biblioteca: configuração, comparação de versões, vencimento e decisão do ciclo, com testes.
- [ ] Tarefa agendada declarada pelo módulo e callback.
- [ ] Ações do painel: salvar, verificar agora, liberar versão recusada.
- [ ] Tela com abas Manual e Automático.
- [ ] `resources:sync`, suítes, Lab e roteiro de navegador.
- [ ] Relatório em `BATCH-254.md`.