# Gestor Church KDK

> Plataforma modular de gestão e comunicação para igrejas, com backend PHP puro, aplicativo Flutter Android/iOS e operação preparada para cPanel, CloudLinux e LiteSpeed.

**Documentação interativa:** `public/docs.php`  
**Changelog:** `CHANGELOG.md`  
**Prototipagem consolidada:** `/home/ubuntu/prototipagem`  
**Aplicativo Flutter:** `/home/ubuntu/gestor-church-kdk-flutter`

## Apresentação

O Gestor Church KDK centraliza cadastros, membros, visitantes, equipes, cargos, permissões, eventos, ações de caridade, doações, comunicação, notificações, PWA, licenciamento multi-igreja e integração com aplicativo móvel. A arquitetura é modular e granular, com PHP 8.4 puro e MySQL no backend, AdminLTE 3.2, Bootstrap 4.6, DataTables, FullCalendar, Toastr e SweetAlert2 na interface.

O aplicativo Flutter compartilha a identidade da igreja e integra ativação por chave, entitlement seguro, AdMob com consentimento UMP, compras para remoção de anúncios, OneSignal e validação de compras no servidor.

## Funcionalidades

| Módulo | Recursos principais |
|---|---|
| Membros e visitantes | Cadastro, contatos, tags, metadados, status e permissões |
| Equipes e cargos | Equipes por evento, participantes membros ou externos e funções eclesiásticas |
| Eventos | Eventos únicos, recorrentes, FullCalendar, caridade, GPS e mídia |
| Comunicação | Push OneSignal, e-mail SMTP/PHPMailer, templates, biblioteca KJV e cron |
| Disparo bíblico | Mensagem KJV diferente para cada membro no mesmo lote, com auditoria e IA opcional |
| Financeiro | Doações, PIX/cartão via Mercado Pago, retorno automático e webhook |
| Aplicativo | Flutter Android/iOS, ativação, entitlement, AdMob e remoção de anúncios |
| PWA | Manifesto, service worker, ícones, nome, cores e instalação offline |
| Administração | Permissões granulares, auditoria, relatórios, configurações e licenciamento |
| Operações | Instalador, migração, backup, restauração, rollback, diagnósticos e staging |

## Estrutura do projeto

```text
app/                 Serviços de negócio e integrações
config/              Configuração protegida e lock de instalação
database/            Schema e seeds idempotentes
docs/                Documentação técnica e relatórios
includes/            Helpers e layout administrativo
modules/             Módulos protegidos do painel
public/              Login, APIs, webhooks, PWA e documentação HTML
scripts/             Instalação, cron, backup, migração e release
tests/               Testes automatizados
prototipagem/        Mockups, branding, assets, Flutter e documentação consolidada
```

## Requisitos

Use PHP 8.4 ou superior, MySQL/MariaDB compatível, PDO MySQL, cURL, Fileinfo, JSON e ZIP. Para produção, use HTTPS, domínio com document root correto e permissões de escrita somente em `config/`, `uploads/` e `backups/`. O aplicativo Flutter requer Flutter SDK compatível com o projeto, Android SDK, Xcode para iOS, certificados e credenciais das lojas.

## Instalação no cPanel, CloudLinux e LiteSpeed

Envie o projeto para o document root configurado no domínio. Crie um banco MySQL e um usuário com permissões mínimas. Confirme as extensões PHP, habilite HTTPS e verifique as permissões de `config/`, `uploads/` e `backups/`.

Acesse `/install.php`, informe banco, usuário administrador, senha, nome da igreja e fuso horário. Depois execute a migração controlada, sempre após backup:

```bash
php scripts/check-environment.php
php scripts/migrate.php
php tests/smoke.php
```

Após a instalação, remova ou bloqueie `install.php`, confirme que `config/installed.lock` foi criado e verifique o log de erros do LiteSpeed. Não mantenha credenciais no Git nem disponibilize arquivos de configuração pelo navegador.

## Configuração inicial

No painel, acesse **Configurações** e preencha o nome da igreja, logo, tema, fuso horário, SMTP, Mercado Pago, OneSignal, PWA e IA opcional. As chaves ficam no backend e não devem ser expostas no frontend.

Para instalações antigas, execute `php scripts/migrate.php` após criar um backup. O seed da biblioteca KJV pode ser aplicado com `php scripts/seed-content.php`; a operação é idempotente e não duplica a mesma referência na mesma tradução.

## Logo, cores, favicon e PWA

Abra **Configurações → Identidade visual**. Informe o nome oficial e envie uma logo PNG, JPG ou WebP. Escolha o tema e o fuso horário. O `BrandingService` utiliza esses dados no login, recuperação de senha, e-mails, sidebar, PWA e Flutter.

Os ícones do PWA ficam em `public/assets/pwa/`. Mantenha versões aprovadas na pasta `prototipagem/branding/`, substitua os arquivos 192×192 e 512×512, confirme o manifesto e limpe o cache do navegador. O favicon pode ser atualizado junto dos ícones públicos, preservando nomes e formatos definidos no manifesto.

## SMTP e mensagens

Configure host, porta, usuário, senha, remetente e nome do remetente. Teste recuperação de senha e uma mensagem programada antes da produção. O editor de templates aceita placeholders documentados e sanitiza scripts, eventos inline e links perigosos.

## IA e mensagens KJV

A IA é opcional. Em **Configurações → IA para mensagens bíblicas**, ative o recurso e informe endpoint compatível com OpenAI Chat Completions, chave privada e modelo. A IA cria somente uma introdução curta; o texto KJV e a referência são inseridos pelo servidor e não são alterados.

Em **Disparo bíblico individual**, o sistema seleciona mensagens KJV ativas, embaralha mensagens e membros e envia individualmente pelo OneSignal. Dentro do mesmo lote não há repetição. Quando faltam mensagens, os excedentes são registrados como ignorados. O cron usa a chave `biblical_individual_dispatch`.

## Cron no servidor

No cPanel, configure uma tarefa a cada cinco minutos:

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

O cron processa mensagens agendadas, tarefas bíblicas e demais rotinas permitidas. A tarefa `biblical_individual_dispatch` é criada por padrão para executar diariamente às 08:00, usando o fuso configurado da igreja. Para que o sistema verifique a agenda e dispare a rotina no horário correto, mantenha o executor do cron rodando a cada cinco minutos. Configure backups separados:

```text
0 2 * * * /usr/local/bin/php /home/USUARIO/public_html/scripts/backup.php >/dev/null 2>&1
15 2 * * * /usr/local/bin/php /home/USUARIO/public_html/scripts/verify-backup.php >/dev/null 2>&1
```

## Mercado Pago e OneSignal

Configure as credenciais de staging primeiro. Valide PIX/cartão, assinatura do webhook, retorno automático e idempotência. No OneSignal, registre um dispositivo de teste, confirme o consentimento e valide o histórico antes de usar a audiência de produção.

## Flutter Android/iOS

Entre em `/home/ubuntu/gestor-church-kdk-flutter`, instale dependências com `flutter pub get`, configure a URL da API, IDs de teste do AdMob, OneSignal, certificados, assinatura e produtos das lojas. Execute testes em dispositivos reais de staging. O app deve validar entitlement no servidor e usar cache seguro com expiração curta.

## Testes e release

Execute o lint e os testes antes de cada release:

```bash
find app modules scripts tests -name '*.php' -print0 | xargs -0 -n1 php -l
php tests/content.php
php tests/cron.php
php tests/biblical-dispatch.php
php tests/ai-settings.php
php tests/member-tags.php
php tests/smoke.php
php scripts/release-check.php
```

Use `scripts/backup.php` antes de migrações, `scripts/verify-backup.php` para validar arquivos e `scripts/rollback.php` somente após confirmar o snapshot correto. Faça o primeiro simulado de restauração em staging.

## Prototipagem

A pasta `/home/ubuntu/prototipagem` reúne as telas de alta fidelidade do backend, telas Android/iOS do Flutter, branding, logos, ícones, PWA, documentação e cópias sincronizadas dos arquivos principais. Consulte `prototipagem/README.md` para o índice visual e operacional.

## Documentação complementar

- `public/docs.php`: central HTML interativa integrada ao projeto.
- `CHANGELOG.md`: histórico cronológico, com novidades mais recentes primeiro.
- `docs/BIBLICAL-DISPATCH-IA.md`: IA e distribuição individual KJV.
- `docs/CRON-EDITOR.md`: editor e execução do cron.
- `docs/RELATORIO-DISPARO-BIBLICO-IA.md`: relatório técnico consolidado.
- `CHECKLIST-HOMOLOGACAO-STAGING.md`: checklist de staging, quando disponível.

## Segurança

Use HTTPS, CSRF, prepared statements, permissões granulares, validação MIME, limites de upload, logs de auditoria, webhooks assinados e backups fora do servidor. Nunca reutilize chaves de produção em testes. A validação local não substitui a homologação real de banco, SMTP, Mercado Pago, OneSignal, IA e lojas móveis.
