Guia Operacional

Introdução ao documento

Este guia operacional descreve os procedimentos para executar, implantar e recuperar o sistema Lean nas Emergências.

Versionamento

Versão do documento: 1.0.0
Última atualização: 2026-03-10
Responsável: Equipe HSL / Weef Interativa

Referencial teórico

Escopo

Ambiente local (Docker)
Deploy (backup/restore via All-in-One WP Migration)
Rollback
Troubleshooting

Fontes de verdade

docker-compose.yml — definição dos containers
Dockerfile — imagem WordPress customizada
wp-config.php — configuração do WordPress e KPI DB
mysql-init/init.sql — inicialização do banco KPI

Como rodar local

Pré-requisitos

Docker Desktop (ou Docker Engine + Docker Compose)
Backup .wpress fornecido pelo time
~~Node.js + npm~~ (build de assets não deve ser executado — ver seção Assets abaixo)

Comandos

# 1. Clonar repositório
git clone <repo-url>
cd hsl-lean-nas-emergencias

# 2. Subir containers
docker-compose up -d

# 3. Verificar status
docker-compose ps

# 4. Acessar WordPress
# http://localhost:8080

# 5. Instalar plugin All-in-One WP Migration
# Acesse http://localhost:8080/wp-admin > Plugins > Adicionar Novo

# 6. Importar backup .wpress
# All-in-One WP Migration > Importar > selecionar arquivo .wpress

# 7. Fix permissões
docker exec -it wp_app chown www-data:www-data /var/www/html/.htaccess

# 8. Logs
docker logs -f wp_app

# 9. Parar containers
docker-compose down

Evidência: docker-compose.yml:1-30, Readme.md

Assets frontend

ATENÇÃO: NÃO execute o build de assets (gulp, npm, bower). Os arquivos de distribuição (theme/assets/dist/project/js/project.js e theme/assets/dist/project/css/app.min.css) foram editados diretamente ao longo do tempo e já não correspondem aos fontes do build system original (Gulp/SCSS/Browserify). Executar gulp sobrescreveria essas alterações e quebraria o projeto. Alterações de CSS ou JS devem ser feitas diretamente nos arquivos dentro de theme/assets/dist/.

Evidência: theme/assets/dist/project/js/project.js, theme/assets/dist/project/css/app.min.css

Configuração do banco KPI

O banco KPI é criado automaticamente pelo mysql-init/init.sql. As credenciais estão em wp-config.php:

define( 'DB_KPI_HOST', 'db' );
define( 'DB_KPI_USER', 'root' );
define( 'DB_KPI_PASS', 'root' );
define( 'DB_KPI_DB_NAME', 'kpi' );

Evidência: wp-config.php:82-85, mysql-init/init.sql:1-3

Para popular dados de KPI no ambiente de desenvolvimento, restaurar dump fornecido pelo time:

docker exec -i wp_db mysql -u root -proot kpi < dump_kpi.sql

Deploy

Pipelines CI/CD (GitHub Actions)

O repositório possui 3 workflows configurados em .github/workflows/:

Workflow	Arquivo	Trigger	Descrição
Deploy HLG	`deploy_hlg.yml`	Push em `homolog` (paths: `theme/style.css`, `mu-plugins/**`)	Deploy automático do tema e mu-plugins para o servidor de homologação via SSH/SCP
Build & Release	`release.yml`	Push em `main`	Gera zip do tema, cria tag e release no GitHub com changelog
Docs Governance	`docs-governance.yml`	PR tocando `docs/**` ou `README.md`	Valida estrutura obrigatória de documentação e sintaxe do OpenAPI

Deploy HLG: Copia o tema para EC2 via appleboy/scp-action, cria release com symlink, roda composer install, mantém últimas 10 releases.
Release: Extrai versão de style.css, gera changelog de CHANGELOG.md ou commits, empacota zip e publica como GitHub Release.
Evidência: .github/workflows/deploy_hlg.yml, .github/workflows/release.yml, .github/workflows/docs-governance.yml

Procedimento manual (via backup/restore)

Gerar backup no ambiente de origem:
- WordPress Admin > All-in-One WP Migration > Exportar
Transferir arquivo .wpress para o ambiente de destino.
Importar no destino:
- WordPress Admin > All-in-One WP Migration > Importar
Verificar configurações de banco KPI no wp-config.php.
Verificar credenciais Canvas LMS em ACF Options.
Limpar cache (W3 Total Cache).

Deploy de tema (apenas código)

# Copiar tema atualizado para o container
docker cp theme/ wp_app:/var/www/html/wp-content/themes/lean-nas-emergencias/

# Ou montar via volume (já configurado em docker-compose.yml)
docker-compose restart wordpress

Evidência: docker-compose.yml:10 (volume mount de ./theme)

Rollback

Rollback via backup

# 1. Restaurar último backup .wpress via WordPress Admin
# All-in-One WP Migration > Backups > selecionar versão anterior

# 2. Ou restaurar via CLI (se disponível)
docker exec -it wp_app wp ai1wm restore <backup-file.wpress>

Rollback do banco KPI

# Restaurar dump anterior
docker exec -i wp_db mysql -u root -proot kpi < backup_kpi_anterior.sql

Rollback do tema (git)

# Voltar para commit anterior
git log --oneline
git checkout <commit-hash> -- theme/

# Reiniciar container para aplicar
docker-compose restart wordpress

Comandos úteis

Ação	Comando
Logs WordPress	`docker logs -f wp_app`
Logs MySQL	`docker logs -f wp_db`
Shell WordPress	`docker exec -it wp_app bash`
Shell MySQL	`docker exec -it wp_db mysql -u root -proot`
PHP error log	`docker exec -it wp_app tail -f /var/log/apache2/error.log`
Apache access log	`docker exec -it wp_app tail -f /var/log/apache2/access.log`
Cache clear (W3TC)	WordPress Admin > Performance > General > Empty All Caches
WP-CLI (se disponível)	`docker exec -it wp_app wp <command>`
Verificar memória PHP	`docker exec -it wp_app php -i \| grep memory_limit`
Status dos containers	`docker-compose ps`
Rebuild container	`docker-compose up -d --build wordpress`

Troubleshooting (Top 5)

1. Erro 413 Request Entity Too Large (upload de backup)

Sintoma: Falha ao importar backup .wpress, mensagem "413 Request Entity Too Large".
Causa provável: Limites de upload do PHP/Apache insuficientes.

Como diagnosticar:

docker exec -it wp_app php -i | grep -E "upload_max|post_max|memory"

Ação de correção:
- Verificar php.ini inclui upload_max_filesize=8G e post_max_size=8G.
- Verificar apache.conf inclui LimitRequestBody 0.
- Rebuild: docker-compose up -d --build wordpress
Evidência: php.ini, apache.conf

2. KPIs não carregam (erro de conexão ao banco KPI)

Sintoma: Gráficos de KPI em branco, erros no console, REST API retorna erro.
Causa provável: Banco kpi não criado ou credenciais incorretas.

Como diagnosticar:

docker exec -it wp_db mysql -u root -proot -e "SHOW DATABASES;"
docker exec -it wp_db mysql -u root -proot kpi -e "SHOW TABLES;"

Ação de correção:
- Verificar que mysql-init/init.sql rodou corretamente.
- Se banco não existe: docker exec -i wp_db mysql -u root -proot < mysql-init/init.sql
- Verificar constantes em wp-config.php: DB_KPI_HOST, DB_KPI_USER, DB_KPI_PASS, DB_KPI_DB_NAME.
Evidência: wp-config.php:82-85, theme/functions/kpis/forms.php:166-200

3. Falha no cadastro de usuário (registration)

Sintoma: Formulário de cadastro retorna erro genérico ou não responde.
Causa provável: Problemas de nonce, rate limit, validação de reCAPTCHA, ou BuddyPress não ativo.
Como diagnosticar:
- Verificar console do browser para resposta AJAX.
- Verificar logs PHP: docker exec -it wp_app tail -f /var/log/apache2/error.log
- Verificar se BuddyPress está ativo: WordPress Admin > Plugins.
Ação de correção:
- Verificar ACF Options > APIs > recaptcha_secret_key configurada.
- Rate limit: transient hsl_reg_rate_<IP> pode estar bloqueando (expira automaticamente).
- BuddyPress deve estar ativo para validação de hospital (grupo).
Evidência: theme/functions/registration/ajax.php:200-213

4. Canvas LMS — matrícula falha

Sintoma: Botão de matrícula retorna erro, usuário não matriculado no Canvas.
Causa provável: Credenciais Canvas expiradas, usuário já existe com ID diferente, API Canvas indisponível.
Como diagnosticar:
- Verificar ACF Options > APIs (canvas-api-url, canvas-token presentes).
- Verificar user meta canvas-id do usuário: get_user_meta($user_id, 'canvas-id', true).
- Testar connectivity com Canvas API manualmente.
Ação de correção:
- Atualizar canvas-token em ACF Options.
- Se canvas-id está incorreto, apagar meta e tentar novamente.
- Verificar se canvas-subaccount-id está correto.
Evidência: theme/functions/ead/ead.php:3-51

5. Permissões de arquivo / `.htaccess`

Sintoma: Erro 403, links permanentes quebrados, uploads falham.
Causa provável: Ownership/permissões incorretas nos volumes Docker.

Como diagnosticar:

docker exec -it wp_app ls -la /var/www/html/.htaccess
docker exec -it wp_app ls -la /var/www/html/wp-content/uploads/

Ação de correção:

docker exec -it wp_app chown -R www-data:www-data /var/www/html/.htaccess
docker exec -it wp_app chown -R www-data:www-data /var/www/html/wp-content/uploads/
docker exec -it wp_app chmod 644 /var/www/html/.htaccess

Evidência: Dockerfile (extends wordpress:php8.3-apache)

Pendências

Não há procedimento de backup automatizado (depende de export manual via plugin).
WP-CLI não instalado por padrão no container (precisa instalar se necessário).
Rotação de credenciais do Canvas LMS não documentada.
Monitoramento de saúde (healthcheck) não configurado no Docker.
Build system de assets (Gulp/SCSS/Browserify) obsoleto — atualizar arquivos para voltar a gerar builds.

Introdução ao documento​

Versionamento​

Referencial teórico​

Escopo​

Fontes de verdade​

Como rodar local​

Pré-requisitos​

Comandos​

Assets frontend​

Configuração do banco KPI​

Deploy​

Pipelines CI/CD (GitHub Actions)​

Procedimento manual (via backup/restore)​

Deploy de tema (apenas código)​

Rollback​

Rollback via backup​

Rollback do banco KPI​

Rollback do tema (git)​

Comandos úteis​

Troubleshooting (Top 5)​

1. Erro 413 Request Entity Too Large (upload de backup)​

2. KPIs não carregam (erro de conexão ao banco KPI)​

3. Falha no cadastro de usuário (registration)​

4. Canvas LMS — matrícula falha​

5. Permissões de arquivo / .htaccess​

Pendências​

Introdução ao documento

Versionamento

Referencial teórico

Escopo

Fontes de verdade

Como rodar local

Pré-requisitos

Comandos

Assets frontend

Configuração do banco KPI

Deploy

Pipelines CI/CD (GitHub Actions)

Procedimento manual (via backup/restore)

Deploy de tema (apenas código)

Rollback

Rollback via backup

Rollback do banco KPI

Rollback do tema (git)

Comandos úteis

Troubleshooting (Top 5)

1. Erro 413 Request Entity Too Large (upload de backup)

2. KPIs não carregam (erro de conexão ao banco KPI)

3. Falha no cadastro de usuário (registration)

4. Canvas LMS — matrícula falha

5. Permissões de arquivo / `.htaccess`

Pendências