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.
PHP 8.4, MySQL, AdminLTE e APIs protegidas.
Flutter Android/iOS com entitlement, push e AdMob.
cPanel, CloudLinux, LiteSpeed, cron, backup e rollback.
Arquitetura e diretórios
| Diretório | Responsabilidade |
|---|---|
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/.
- Envie os arquivos para o document root.
- Crie o banco e o usuário MySQL com permissões mínimas.
- Acesse
/install.phpe informe banco, administrador e fuso horário. - Execute a migração em staging:
php scripts/migrate.php. - Remova ou bloqueie o instalador após concluir.
- Execute os diagnósticos e os testes antes de liberar o domínio.
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.
| Área | Configuração |
|---|---|
| SMTP | Host, porta, usuário, senha, remetente e nome do remetente. |
| Mercado Pago | Public Key, Access Token e segredo de webhook. |
| OneSignal | App ID, REST API Key e dispositivos de teste. |
| IA | Ativação, endpoint compatível, chave privada e modelo. |
| PWA | Manifesto, í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.
- Abra Configurações → Identidade visual.
- Informe o nome oficial e envie uma logo PNG, JPG ou WebP.
- Defina tema claro ou escuro e o fuso IANA.
- Para favicon, substitua os arquivos em
public/assets/pwa/pelos ícones quadrados aprovados e confirme o manifesto. - 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ódulo | Uso | Cuidados |
|---|---|---|
| Contas a pagar | Registrar fornecedor, vencimento, categoria, valor e baixa. | Confirme a baixa com SweetAlert2; não há alertas nativos. |
| Contas a receber | Acompanhar entradas previstas, recebidas e vencidas. | Concilie transações com o ID retornado pelo gateway. |
| Patrimônio | Cadastrar ativo, localização, responsável, valor e status. | Movimentações geram histórico e permanecem auditáveis. |
| Etiquetas | Selecionar 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.
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.
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.
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
- Publique a release no painel central.
- Execute
php scripts/auto-update.php --check. - Homologue a versão em staging.
- Execute
php scripts/auto-update.php --applyem janela aprovada. - 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.
Changelog
O histórico completo está no arquivo CHANGELOG.md, ordenado do mais novo para o mais antigo.
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.
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.
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.
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.
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.
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.
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.
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`.
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.
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`.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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`.
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.
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.
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.
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.
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.
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.
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.
