Atualizado em 27/08/2026

Documentação do Minha Igreja

Guia central para instalar, configurar, personalizar e operar a plataforma de gestão eclesiástica.

Apresentação

O Minha Igreja é um sistema modular para membros, visitantes, equipes, eventos, doações, comunicação, permissões, licenciamento e aplicativo móvel. O backend utiliza PHP puro e MySQL, com painel AdminLTE 3.2, Bootstrap 4.6, DataTables, FullCalendar, PWA e integrações externas.

Backend

PHP 8.4, MySQL, AdminLTE e APIs protegidas.

Mobile

Flutter Android/iOS com entitlement, push e AdMob.

Operação

cPanel, CloudLinux, LiteSpeed, cron, backup e rollback.

Arquitetura e diretórios

DiretórioResponsabilidade
app/Serviços de negócio, branding, cron, conteúdo, licenciamento e integrações.
modules/Telas protegidas do painel administrativo.
public/Login, APIs, webhooks, PWA, assets e documentação pública.
database/Schema e seeds idempotentes.
scripts/Instalação, migração, cron, backup, rollback e diagnósticos.
tests/Testes de conteúdo, cron, smoke, tags, IA e distribuição individual.
prototipagem/Mockups, branding, Flutter e cópia consolidada da documentação.

Instalação

Antes de instalar, confirme PHP 8.4 ou superior, MySQL, PDO MySQL, cURL, Fileinfo, JSON e ZIP. No cPanel, aponte o domínio para a pasta pública do projeto, habilite HTTPS e assegure escrita controlada em config/, uploads/ e backups/.

  1. Envie os arquivos para o document root.
  2. Crie o banco e o usuário MySQL com permissões mínimas.
  3. Acesse /install.php e informe banco, administrador e fuso horário.
  4. Execute a migração em staging: php scripts/migrate.php.
  5. Remova ou bloqueie o instalador após concluir.
  6. Execute os diagnósticos e os testes antes de liberar o domínio.
php scripts/check-environment.php php scripts/migrate.php php tests/smoke.php

Configuração inicial

Use Configurações no painel para definir identidade da igreja, fuso horário, tema, SMTP/PHPMailer, Mercado Pago, OneSignal, PWA e IA opcional. As credenciais devem permanecer no servidor, nunca no frontend ou no repositório.

ÁreaConfiguração
SMTPHost, porta, usuário, senha, remetente e nome do remetente.
Mercado PagoPublic Key, Access Token e segredo de webhook.
OneSignalApp ID, REST API Key e dispositivos de teste.
IAAtivação, endpoint compatível, chave privada e modelo.
PWAManifesto, ícones, nome e cores de instalação.

Logo, cores, favicon e identidade visual

O BrandingService centraliza nome, logo e cores. A troca de identidade pelo painel deve refletir login, recuperação de senha, e-mails, sidebar, PWA e telas do aplicativo.

  1. Abra Configurações → Identidade visual.
  2. Informe o nome oficial e envie uma logo PNG, JPG ou WebP.
  3. Defina tema claro ou escuro e o fuso IANA.
  4. Para favicon, substitua os arquivos em public/assets/pwa/ pelos ícones quadrados aprovados e confirme o manifesto.
  5. Limpe cache do navegador e reinstale o PWA para verificar a nova identidade.

Use a pasta prototipagem/branding/ para manter versões aprovadas dos logos, ícones, splash screens e referências visuais.

Integrações e gateways

Comunicação

PHPMailer/SMTP para e-mails e OneSignal para push. O consentimento e o registro de dispositivo precisam ser validados antes dos testes.

Mercado Pago

PIX e cartão usam o checkout transparente. Cada cobrança gera um token aleatório exclusivo, armazenado somente como hash e vinculado ao ID do pagamento; o callback aceita reenvios idempotentes e valida a assinatura quando não há token dinâmico.

Banco Cora

Configure no painel o Client ID, Client Secret, certificado e chave mTLS, além da URL base e do endpoint de cobrança homologado. O gateway só aparece na doação quando a configuração está completa. A Cora deve enviar o retorno ao endpoint definido pelo contrato da conta e o processamento precisa ser homologado com payload real antes da produção.

Dados

ViaCEP para preenchimento de endereços, com edição manual para comunidades e endereços especiais.

Mídia

Uploads com arrastar e soltar, barra de progresso, validação MIME e limite de tamanho.

Operação segura

Credenciais ficam no cofre criptografado do sistema, nunca em .env, frontend ou Git. Use HTTPS e mantenha certificados mTLS fora do document root.

Contas e patrimônio

O menu Financeiro e patrimônio reúne visão financeira, contas a pagar, contas a receber, doações, ativos da igreja e etiquetas patrimoniais. Todas as operações são protegidas por CSRF, permissão granular, escopo de igreja/tenant e registro de auditoria.

MóduloUsoCuidados
Contas a pagarRegistrar fornecedor, vencimento, categoria, valor e baixa.Confirme a baixa com SweetAlert2; não há alertas nativos.
Contas a receberAcompanhar entradas previstas, recebidas e vencidas.Concilie transações com o ID retornado pelo gateway.
PatrimônioCadastrar ativo, localização, responsável, valor e status.Movimentações geram histórico e permanecem auditáveis.
EtiquetasSelecionar ativos e abrir a impressão física.Folha A4 em grade de 5 colunas × 7 linhas; cada etiqueta mede 2 cm × 1,5 cm e comporta até 7 linhas.

Para imprimir, abra Etiquetas patrimoniais, selecione os ativos, gere a prévia e use a caixa de impressão do navegador em escala 100%, sem ajustar à página.

Cron, biblioteca bíblica e IA opcional

Configure o cron do servidor para processar mensagens programadas e verificar a tarefa diária biblical_individual_dispatch, criada por padrão para as 08:00 no fuso configurado da igreja. Cada membro recebe uma mensagem KJV diferente no mesmo lote; excedentes são ignorados quando não há mensagens suficientes.

*/5 * * * * /usr/local/bin/php /home/USUARIO/public_html/scripts/cron.php >/dev/null 2>&1

A IA gera apenas uma introdução curta. O texto KJV e a referência são preservados no servidor. Consulte docs/BIBLICAL-DISPATCH-IA.md e docs/CRON-EDITOR.md para detalhes.

Aplicativo Flutter

O projeto mobile está em /home/ubuntu/gestor-church-kdk-flutter. A integração inclui ativação por chave, cache seguro de entitlement, compras para remoção de anúncios, UMP Consent, branding e sincronização com a API do backend.

Antes do build, configure a URL da API, IDs de teste do AdMob, OneSignal, assinatura das lojas e certificados Android/iOS. Nunca use credenciais de produção durante a homologação.

Prototipagem do projeto

A prototipagem consolidada está em /home/ubuntu/prototipagem. Ela reúne mockups de backend e Flutter Android/iOS, logos, ícones, assets PWA, documentação de branding e cópias sincronizadas dos arquivos principais.

Índice da prototipagem

Segurança e produção

Use HTTPS, CSRF em formulários, permissões granulares, prepared statements, validação MIME, limites de upload, webhooks assinados e logs de auditoria. Faça backup antes de migrações e teste restauração fora da base de produção.

A validação local confirma sintaxe, lógica e regressão. SMTP, Mercado Pago, OneSignal, MySQL remoto e endpoint de IA ainda precisam ser homologados com credenciais de staging.

Auto-update e chaves Ed25519

O fluxo completo está descrito em docs/AUTO-UPDATE-RUNBOOK.md. A instalação consulta o manifesto assinado, verifica a chave pública local, solicita o artefato por POST protegido, valida licença e instalação, confere o SHA-256, cria snapshot, aplica a release e executa rollback quando necessário.

Fluxo operacional
  1. Publique a release no painel central.
  2. Execute php scripts/auto-update.php --check.
  3. Homologue a versão em staging.
  4. Execute php scripts/auto-update.php --apply em janela aprovada.
  5. Valide health check, login e módulos críticos.
Chaves

A central usa licensing-central/config/license-private.key. Cada cliente usa config/license-public.key. O projeto não exige ED25519_PRIVATE_KEY, ED25519_PUBLIC_KEY ou qualquer variável de ambiente para transportar chaves.

Nunca coloque a chave privada em Git, .env, banco, logs ou diretório público.
php scripts/auto-update.php --check

Abrir o runbook completo

Changelog

O histórico completo está no arquivo CHANGELOG.md, ordenado do mais novo para o mais antigo.

26/08/2026 — Health check e histórico de alertas

Foram adicionados testes do `KDK_REVOCATION_THRESHOLD_ALERT`, histórico de entregas Webhook/Telegram, gráfico temporal de alertas disparados e a rota administrativa `notification-health.php` para verificar conectividade mediante ação explícita.

26/08/2026 — Alerta por limite de revogações JWT

Foi adicionado um limite configurável de revogações nas últimas 24 horas. Ao atingir o valor definido, a central dispara `KDK_REVOCATION_THRESHOLD_ALERT` pelo Webhook HTTPS ou Telegram configurado, com deduplicação de uma notificação por janela de 24 horas.

26/08/2026 — Relatórios e métricas de tokens JWT

A auditoria passou a oferecer exportação filtrada em CSV/PDF e métricas consolidadas de tokens ativos, revogados, expirados e revogados nas últimas 24 horas. Foram adicionados gráficos de revogações por dia e de ativos versus revogados por escopo.

26/08/2026 — Auditoria de tokens JWT revogados

Foi criada `security-revoked-tokens.php` para listar tokens revogados por período, administrador e escopo, com paginação e sem exibir JWT, JTI ou hashes completos. O teste `tests/revoked-token-audit.php` valida a rota, os filtros e os controles de privacidade.

26/08/2026 — Checklist de homologação JWT

Foi criado `docs/STAGING-JWT-HOMOLOGACAO.md`, com pré-condições, migração, emissão de dois tokens, teste de acesso, revogação individual, cenários negativos, critérios de aprovação e encerramento seguro sem tocar em produção.

26/08/2026 — Testes de integração JWT em staging

Foi criado `tests/staging-jwt.php` para validar acesso autenticado ao dashboard e às exportações com Bearer JWT, além da rejeição de um token revogado quando informado separadamente. O teste é opt-in e não aplica alterações.

26/08/2026 — Testes do fluxo de revogação JWT

Foi criada a suíte `tests/jwt-revocation-flow.php`, cobrindo revogação condicional de tokens ativos, rejeição de tokens expirados ou já revogados, JTI hash, CSRF, auditoria e ausência do token completo na interface administrativa.

26/08/2026 — Autenticação JWT do dashboard de segurança

O dashboard e as exportações passaram a aceitar sessão administrativa ou Bearer JWT Ed25519 com escopo `security:read`, audiência específica, validade de 15 minutos e JTI revogável. Foi criada a página `security-token.php` e a tabela `central_access_tokens`.

26/08/2026 — Gráficos estatísticos de segurança

O dashboard de eventos passou a exibir gráficos consolidados por dia, tipo de evento, severidade e alertas `KDK_LICENSE_ALERT`, utilizando consultas agregadas reais da tabela `central_security_events`. As visualizações possuem período configurável e indicam a fonte dos dados. O teste `tests/security-dashboard.php` foi ampliado para validar as agregações e os três gráficos Chart.js.

26/08/2026 — Exportação e notificações de segurança

O dashboard de eventos passou a permitir exportação filtrada em CSV e PDF, limitada a 10.000 registros e com hashes parciais. Foi adicionada a configuração administrativa de Webhook HTTPS ou Telegram, com credenciais cifradas por Sodium e disparo automático quando o limiar `KDK_LICENSE_ALERT` é atingido. Também foram criados os endpoints `security-export.php` e `security-settings.php`, além do teste `tests/security-exports.php`.

26/08/2026 — Dashboard de eventos de segurança

Foi criada a interface administrativa `licensing-central/public/security-events.php`, protegida por sessão de administrador, com métricas das últimas 24 horas, filtros por período, tipo e severidade, paginação e identificação visual de ocorrências que atingiram o limiar `KDK_LICENSE_ALERT`. A interface exibe somente hashes parciais e códigos operacionais. Também foi adicionado o teste `tests/security-dashboard.php` para verificar autenticação, consultas, filtros, marcador de alerta e sanitização da apresentação.

26/08/2026 — Rollback automático e monitoramento de licenças

O updater passou a controlar explicitamente o estado do snapshot e executar rollback automático em falhas ocorridas após o download, incluindo checksum, validação do pacote, extração e cópia. Também foi criado o `CentralSecurityMonitor`, com eventos JSON sanitizados, persistência em `central_security_events` e alerta `KDK_LICENSE_ALERT` após repetição anormal de falhas por IP. Foi adicionado o teste `tests/auto-update.php` para verificar o rastreamento do snapshot, o rollback pós-download, o schema de eventos, a sanitização e o alerta operacional.

26/08/2026 — Runbook do auto-update e chaves Ed25519

Foi criado `docs/AUTO-UPDATE-RUNBOOK.md`, documentando a preparação e publicação de releases, manifesto assinado, download protegido, verificação de licença e instalação, SHA-256, snapshot, aplicação, rollback, cron no cPanel/LiteSpeed, troubleshooting e checklist de staging. A documentação esclarece que as chaves Ed25519 não usam variáveis de ambiente: a chave privada permanece em `licensing-central/config/license-private.key` e a chave pública é distribuída em `config/license-public.key` nas instalações clientes. Também foram documentados geração, permissões, backup e rotação das chaves. A documentação HTML `public/docs.php` recebeu a seção navegável “Auto-update e chaves Ed25519”, com comandos copiáveis e acesso ao runbook completo.

26/08/2026 — Páginas de erro padronizadas

Foram adicionadas páginas branded para erros 403, 404 e 500, integradas ao Apache/LiteSpeed por `ErrorDocument`. As respostas não exibem stack traces, credenciais ou caminhos internos. Testes de regressão verificam a existência das páginas e das diretivas de roteamento.

26/08/2026 — Correções de segurança em autenticação e push

A redefinição de senha passou a validar CSRF e renderizar o campo correspondente. O consentimento de notificações push deixou de usar `innerHTML` para mensagens dinâmicas e passou a usar `textContent`, reduzindo risco de interpretação de conteúdo como HTML. Foi criado um teste de regressão e incluído no CI/CD.

26/08/2026 — Hardening de backup e rollback

Os scripts de backup, verificação, snapshot e rollback foram reforçados. Agora o verificador retorna falha quando não há backup, valida ZIP/SQL e rejeita caminhos perigosos; backups preservam subdiretórios de uploads e exibem SHA-256; snapshots usam arquivo temporário e retenção dos cinco mais recentes; rollback valida o conteúdo do tar antes da extração e preserva o checksum do estado anterior.

26/08/2026 — Preflight de staging

Foi executada a bateria local de release check, security check, lint PHP, smoke tests, tags, biblioteca, cron, integrações e anti-reverse engineering. A release foi aprovada estruturalmente, mas o sandbox não atende PHP 8.4, não possui ZipArchive nem banco configurado; a homologação funcional permanece condicionada a um staging cPanel/LiteSpeed isolado. # Changelog — Gestor Church KDK Todas as alterações relevantes do projeto são registradas abaixo, com o item mais recente primeiro. As entradas de 26/08/2026 consolidam as entregas realizadas nesta fase de pré-produção.

26/08/2026 — Cron diário do disparo KJV

A tarefa padrão de cron foi configurada como `biblical_individual_dispatch`, com execução diária às 08:00 no fuso da igreja. A migração renomeia a antiga tarefa `daily_verse` sem criar uma rotina duplicada. O executor continua sendo verificado a cada cinco minutos pelo cPanel/LiteSpeed.

26/08/2026 — Documentação HTML interativa

Foi criada a central pública `public/docs.php`, integrada ao branding dinâmico do sistema e ao estilo visual AdminLTE/KDK. A página possui busca por conteúdo, navegação por seções, modo claro/escuro, botões para copiar comandos, novidades, arquitetura, instalação, configuração, personalização visual, integrações, cron, Flutter, prototipagem, segurança e changelog. Foi adicionado acesso à documentação pela tela de login e pelo painel administrativo. O README principal foi reorganizado para servir como apresentação técnica e guia de implantação.

26/08/2026 — Disparo bíblico KJV com IA opcional

Foi implementado o `BiblicalDispatchService`, com seleção aleatória de mensagens KJV e atribuição única por membro dentro de cada lote. O sistema envia individualmente pelo OneSignal e ignora excedentes quando não existem mensagens suficientes, sem reutilização. Foi adicionada integração opcional com endpoint compatível com OpenAI Chat Completions. A IA cria somente uma introdução curta; o servidor preserva o texto KJV e a referência. Falhas da IA acionam fallback para o conteúdo original. Foram criadas as tabelas de lotes e itens individuais, o painel `biblical-dispatch`, a tarefa cron `biblical_individual_dispatch`, o lock contra execução concorrente e a auditoria por destinatário.

26/08/2026 — Segurança e persistência da IA

Foram adicionados os campos `ai_enabled`, `ai_endpoint`, `ai_api_key` e `ai_model` ao schema e à tela de configurações SuperAdmin. Foi corrigida a ordem de persistência dos campos de identidade visual e a quantidade de placeholders SQL. Foi criado o teste `tests/ai-settings.php` para confirmar campos, rota e compatibilidade entre colunas e valores SQL.

26/08/2026 — Auditoria do disparo e estados de falha

Foi separado o contador de destinatários ignorados do contador de falhas de entrega. O painel passou a mostrar `enviados`, `ignorados` e `falhas` em colunas distintas. A migração existente recebeu a nova coluna `failed_count`.

26/08/2026 — Biblioteca bíblica e editor de conteúdo

A biblioteca KJV foi ampliada com seed idempotente e categorias pastorais. O editor ganhou inserção rápida de placeholders e validação de conteúdo HTML. Scripts, eventos inline, esquemas perigosos e tags não autorizadas são removidos.

26/08/2026 — Editor visual de cron

O painel de cron recebeu presets de frequência, execução manual protegida, validação de expressões, lock no executor CLI e cálculo correto da próxima ocorrência. Foi criada documentação operacional para cPanel e LiteSpeed.

26/08/2026 — Branding dinâmico e PWA

O `BrandingService` passou a centralizar nome, logo, cores e fallback visual em login, recuperação de senha, e-mails, sidebar, PWA e aplicativo Flutter. Foram sincronizados logos, ícones e manifestos na prototipagem consolidada.

26/08/2026 — Flutter e monetização

Foi consolidado o scaffold Flutter para Android/iOS, com ativação por chave, cache seguro de entitlement, UMP Consent, integração AdMob e serviço de compras para remoção de anúncios com validação no servidor.

26/08/2026 — Licenciamento multi-igreja

Foi estruturado o licenciamento por igreja, incluindo assinatura, ativação do aplicativo, regras de anúncios por igreja e remoção individual de anúncios conforme entitlement validado no servidor.

26/08/2026 — Operações e recuperação

Foram consolidados scripts de instalação, diagnóstico, migração, backup, verificação de backup, snapshot, rollback, release check e documentação de disaster recovery/staging.

Histórico consolidado — funcionalidades do produto

O projeto reúne gestão de membros, visitantes, equipes, cargos e permissões; eventos únicos, recorrentes e de caridade; GPS e mídia; doações e Mercado Pago; SMTP/PHPMailer; OneSignal; PWA; DataTables; FullCalendar; temas dark/light; upload global; Toastr; SweetAlert2; auditoria; relatórios; API mobile e integração Flutter Android/iOS.