Decaelo — Roadmap

Visão do Produto

Sistema SaaS de gestão para igrejas com multi-tenancy (banco de dados isolado por subdomínio). Modelo freemium com planos escalonados por número de membros e funcionalidades premium.

Stack

• Backend: Laravel 13, PHP 8.4, MariaDB, Redis (predis)
• Frontend: Vue 3, Inertia.js, PrimeVue 4 (unstyled + PT preset), Tailwind CSS v4
• Multi-tenancy: stancl/tenancy (multi-database, subdomínios)
• Pacotes: Spatie Permission, Spatie MediaLibrary, Spatie PDF, Laravel Auditing, Laravel Fortify, Laravel Reverb, Laravel Scout, Laravel Socialite, Laravel AI SDK
• IA/WhatsApp: Meta Cloud API (WhatsApp Business), Laravel AI SDK (OpenAI gpt-4o-mini + fallback)
• Pagamentos: Asaas API v3 (assinaturas SaaS, doações/dízimos com split)
• Mobile (futuro): NativePHP / Capacitor para Android/iOS
• Infra: Docker, Nginx, WSL2

---

Fases Concluídas

Fase 0 — Fundação Arquitetural ✅

• Estrutura DDD (Domain/Church, Domain/User, Domain/Shared, Domain/Member)
• Multi-tenancy com stancl/tenancy (multi-database, subdomínios)
• PrimeVue 4 unstyled + Tailwind CSS v4
• ULID como identificador público (nunca expõe IDs)
• L5-Swagger configurado
• Models unguarded globalmente, validação via Form Requests

Fase 1 — Autenticação, Usuários e Permissões ✅

• User model no banco do tenant (isolamento total)
• Fortify (login, registro, 2FA, reset password, email verification)
• Spatie Permission (7 roles, 19 permissions)
• CRUD de Usuários e Roles com policies
• Middleware EnsureProfileCompleted
• Auditoria via laravel-auditing

Fase 2 — Estrutura Eclesiástica ✅

• ChurchProfile, Congregation, ChurchOfficial, Address (polimórfico)
• Tabelas de referência: IgrejaFuncao, IgrejaCargo, IgrejaSituacao, IgrejaModoAdmissao
• Dados compartilhados: Profissao, Escolaridade, TelefoneTipo, Pais, Uf
• CRUD completo com Actions, Events, Policies
• Frontend: 7 páginas + 4 componentes reutilizáveis

Fase 2.5 — Design System & UI Polish ✅

• Paleta: navy sidebar (#1a1f36), gold accent (#c9942e), slate content (#f8fafc)
• Tipografia: Plus Jakarta Sans (app), Bricolage Grotesque + Figtree (landing)
• PrimeVue PT preset global (primevue-pt.ts)
• Locale pt-BR configurado globalmente
• Landing page SaaS na central (igreja.test)
• Tenant welcome page com identidade da igreja
• Auth pages com split layout (navy + formulário)
• SESSION_DRIVER=cookie, predis para Redis
• Border radius 12px, DataTable com paginação centralizada

Fase 3 — Gestão de Membros ✅

• Member model separado do User (abordagem hybrid)
• Dados eclesiásticos inline (situação, função, cargo, modo admissão, congregação)
• MemberPhone (hasMany com TelefoneTipo)
• Address polimórfico reutilizado
• Cônjuge (self-referência), responsável para menores
• 5 Actions, 4 Events, MemberPolicy
• CRUD completo com filtros server-side
• 4 páginas Vue (Index DataTable, Create/Edit forms, Show profile)
• MemberSeeder com 25 membros fake
• 290 testes passando

---

Fases Concluídas (cont.)

Fase 4 — Planos, Limites e Feature Flags ✅

• Plan model no banco central (Semente/Crescimento/Expansão)
• Tenant helpers: hasFeature(), memberLimit(), isAtMemberLimit()
• Limit checks, CheckFeature middleware, UpgradeModal
• Admin panel central em /admin/tenants

Fase 5A — Fundação Financeira ✅

• Transaction model com status workflow (pendente→efetivada/cancelada)
• TransactionCategory, BankAccount, formas de pagamento
• 4 Actions, TransactionPolicy, 3 Controllers, 8 páginas Vue
• Sidebar agrupada: Secretaria, Igreja, Financeiro

Fase 6A — Grupos e Células ✅

• GroupType, Group, GroupMember, GroupActivity models
• 8 events, 8 actions, GroupPolicy com lider ownership
• CRUD completo + sidebar "Grupos"

Fase 6B — Escalas de Voluntários ✅

• GroupPosition, Schedule, ScheduleItem models
• Detecção de conflitos entre grupos
• Calendário mensal grid + schedule dialog
• Dashboard "Minhas Escalas"

Fase 7A — Eventos e Inscrições ✅

• EventType, Event, EventRegistration models + 3 enums
• Público-alvo por evento (membros, usuários, público)
• Aprovação opcional, lista de espera automática
• Integração financeira por plano (finance_integration feature flag)
• Página pública de inscrição para visitantes
• 108 testes específicos

Fase 8 — Patrimônio ✅

• AssetType, Asset, AssetMovement models + 3 enums
• Movimentações: transferência, manutenção, baixa
• Foto via Spatie Media + UuidFileNamer
• Rota /media multi-tenant para servir arquivos
• 84 testes específicos

Fase 10 — Secretaria Digital ✅

• Certificado de Batismo + Cartas (recomendação, transferência, desligamento)
• PDFs via Spatie Laravel PDF + Gotenberg
• DocumentLog com download permanente
• Templates Blade formais com logo da igreja
• 35 testes específicos

---

Fase 7B — Check-in Kids ✅

• Checkin model com QR code (chillerlan/php-qrcode)
• Check-out com validação de responsáveis autorizados
• Etiqueta PDF via Gotenberg (planos pagos — kids_print_label)
• Dual-mode: membro + visitante
• Nova role: voluntario-kids
• Feature flags: kids_checkin, kids_print_label

Fase 12A — Scout + Typesense (Busca Full-Text) ✅

• TenantSearchable trait com collections isoladas por tenant
• Member, Transaction, Event com toSearchableArray e schemas Typesense
• Controllers com busca Scout + fallback Eloquent
• Typesense como servico Docker
• Artisan command app:reindex-search
• Feature flag: full_text_search (Crescimento, Expansao)

Fase 9 — Comunicação e Notificações ✅

• Domain/Communication com 6 models, 5 enums, 15+ actions
• Notificações in-app (database + mail) com preferências por membro/canal/categoria
• Sino de notificação no header com contagem em tempo real (Echo + Reverb)
• Mural de pedidos de oração com moderação, "Estou orando", broadcasting real-time
• Aniversariantes: widget no dashboard (semana), job diário para líderes
• E-mail em massa: 5 templates, wizard 4 steps, filtros de audiência, batch via Bus::batch()
• Feature trial: extra_features com expiração, painel admin central, job de limpeza
• 8 novas permissions, 4 feature flags (notifications, prayer_wall, birthday_alerts, mass_email)
• ~104 novos testes

Fase 12B — Importação de Membros (CSV/Excel) ✅

• Upload CSV/XLSX com mapeamento de colunas e preview
• Deduplicação por CPF (prioritário) ou nome+sobrenome (fallback)
• Resolução de referências por nome (situação, congregação, cargo, etc.)
• Template de planilha modelo para download
• Importações grandes via queue (>50 linhas)
• Permissão: member.import (admin-igreja, secretário)

Fase 14 — WhatsApp + IA Conversacional ✅

Integração WhatsApp Business (Meta Cloud API) com chatbot de IA por igreja.

14A — Infraestrutura ✅

• Domain/WhatsApp: 6 models (WhatsAppAccount, WhatsAppConversation, WhatsAppMessage, WhatsAppTemplate, WhatsAppCreditUsage, AiPromptConfiguration)
• MetaCloudApiService (única Service — integração externa)
• WhatsApp account no banco central (roteamento de webhook); conversas/mensagens/templates/config/créditos no tenant
• Webhook controller (verificação HMAC), jobs inbound/outbound
• 7 enums (ConversationStatus, MessageDirection, MessageDeliveryStatus, AiAccessLevel, TemplateApprovalStatus, TemplateCategory, etc.)

14B — IA Conversacional ✅

• WhatsAppAgent (Laravel AI SDK nativo), OpenAI gpt-4o-mini primário + fallback
• 14 tools: consultar horários/info igreja/avisos/eventos próximos/meus dados/minhas contribuições/meus eventos/minhas células, inscrever em evento, confirmar presença, registrar pedido de oração, solicitar atestado, escalar para humano
• 4 middleware: PersonalizeByTemplate (formal/acolhedor/jovem), EnforceTokenBudget, RestrictSensitiveTopics, LogAiUsage
• ProcessInboundMessageJob completo

14C — Funcionalidades Avançadas ✅

• Fluxo de escalação para atendente humano + resposta humana (SendHumanReplyAction)
• Timeout/expiração de conversa (CheckEscalationTimeoutJob)
• Transcrição de áudio
• Broadcasting real-time via Reverb

14D — Frontend Admin ✅

• 8 páginas Vue: Conversations (Index lazy + Show chat real-time), Templates (Index/Form), Configuration (Edit), Credits (Index), Admin/WhatsApp (Index/Form de contas)
• ~210 testes específicos
• Docs: architecture/whatsapp-ai.md, architecture/whatsapp-costs.md, modules/whatsapp.md (+ tabela troubleshooting de deploy: CSRF 419, HMAC 403, central connection, Horizon env, Meta dev mode)

Fase 15A — Núcleo de Cobrança + Inscrição de Evento Paga ✅

Recebimento online genérico via Asaas, reutilizável (eventos agora; avulsa/recorrência/carnê depois).

• ChurchPaymentSettings — sub-conta Asaas a nível igreja, desacoplada de DonationSettings; doações migradas para ler dela via ResolvePaymentAccount.
• Charge genérico (morph chargeable) + ChargeStatus, split reaproveitando services.asaas.split_percentage.
• CreateChargeAction (PIX/cartão + split), webhook ramo charge:, HandleChargeConfirmed/Refunded (cria Transaction no Finance, idempotente, atômico).
• ExpireUnpaidChargesJob (a cada 15min) — expira cobrança vencida, cancela no Asaas, libera vaga e promove lista de espera.
• Evento pago: payment_flow configurável por evento (pay_first / approve_first), status aguardando_pagamento (segura vaga), prazo de pagamento, página de cobrança /charges/{ulid} (membro) e /inscricao/pagamento/{ulid} (visitante público).
• Anti-duplicação de Transaction (charge é a fonte única quando presente). 25 testes específicos.
• Spec/plano: docs/superpowers/specs/2026-06-10-cobranca-asaas-evento-design.md, docs/superpowers/plans/2026-06-10-cobranca-asaas-evento.md.

Pendências técnicas (15A) — resolvidas:

• ✅ Config Asaas em produção: BuildChargeSplit valida ASAAS_WALLET_ID e lança erro claro (fail-fast antes de criar cliente/pagamento no Asaas). Usado por CreateChargeAction e SwitchChargeMethodAction.

• ✅ UX: "ver cobrança" em Events/Show.vue agora usa <Link> do Inertia (navegação client-side).

• ✅ Form do evento: payment_flow/prazo_pagamento_horas anulados via form.transform() quando valor_inscricao <= 0 (Create/Edit).

• ✅ DeleteEventAction: cancela inscrições aguardando_pagamento e suas cobranças via CancelChargeAction (remove pagamento no Asaas + status canceled) antes de excluir o evento.

• ✅ Webhook multi-tenant: o webhook do Asaas chega no contexto central, mas charges/donation_payments vivem no banco do tenant. O tenant agora é codificado no externalReference (charge:{tenantId}:{ulid}) e resolvido via PaymentReference; o WebhookAsaasController despacha ProcessAsaasWebhookJob, que entra no tenant (Tenant::run) e roteia para os handlers (espelha o webhook do WhatsApp). Doação tinha o mesmo bug e também foi corrigida. Documentação completa: docs/modules/asaas-webhook.md.

• ✅ Auto-registrar webhook na sub-conta: SetupDonationAccountAction agora chama RegisterSubAccountWebhookAction após criar a sub-conta — registra o webhook nela (POST /v3/webhooks com a apiKey da sub-conta, authToken = ASAAS_WEBHOOK_TOKEN, URL de ASAAS_WEBHOOK_URL/route('webhooks.asaas')). Idempotente e resiliente. Produção funciona sem cadastro manual por igreja.

Nota de config (dev): o compose real é docker-compose.yml na raiz do repo (env_file: ./html/.env); deploy/ é só documentação. Esse Compose interpola $ no env_file → a ASAAS_API_KEY (que contém $) precisa de escape $$ em html/.env. Mudanças no .env exigem recriar os containers + config:clear. Ver docs/modules/asaas-webhook.md.

Nota de teste: ~265 falhas HTTP 419 (CSRF) são pré-existentes (testes não desabilitam o middleware CSRF), não regressões. Ao validar mudanças, filtrar pela própria suíte (--filter=Payment). Novos testes que fazem POST devem incluir PreventRequestForgery::class em withoutMiddleware([...]).

Próximos sub-projetos (reusam o núcleo Charge):

• E — Cobrança avulsa a membro: UI na secretaria para emitir cobrança pontual (taxa, material, aluguel de espaço); Charge sem chargeable ou com chargeable próprio.
• F — Mensalidade/recorrência interna: subscription Asaas sobre Charge (curso, contribuição associativa), fora de dízimo.
• G — Carnê/parcelamento: cobrança em N parcelas (boleto/PIX) sobre qualquer fluxo.
• Cartão direto na inscrição: hoje ChargeForEventRegistrationAction cria a cobrança como PIX; o cartão entra via troca de método na tela de cobrança (SwitchChargeMethodAction). Suficiente para o MVP. Para cartão direto na inscrição é preciso: tokenização Asaas no front (PublicRegister.vue/fluxo autenticado), campo de método/token no request de inscrição e branch de payment_method no ChargeForEventRegistrationAction. Decisão (2026-06-12): adiado — fica como sub-projeto futuro.
• Boleto como método de pagamento (hoje só PIX + cartão).
• Preço SaaS diferenciado por feature premium: add-on sobre o plano no Domain/Billing (hoje extra_features são trial grátis, não alteram o preço).

---

Próximas Fases

Fase 11 — App White Label

Objetivo: App personalizado para cada igreja.

• NativePHP / Capacitor para Android e iOS
• Identidade visual da igreja (logo, cores)
• Taxa de setup + mensalidade extra
• Build automatizado via CI/CD

Fase 12 — Integrações e Ecossistema

Objetivo: Expandir o ecossistema.

• Socialite (login social Google/Facebook) ✅ Implementado (Google + Facebook, callback centralizado, auto-link por e-mail)
• API pública para integrações de terceiros
• Conciliação bancária

Fase 13A — Painel Central SaaS ✅

• Autenticação admin com guard dedicado (AdminUser model)
• Dashboard central com KPIs (tenants, membros, atividade)
• CRUD de Tenants com onboarding completo (banco + seeds + admin user)
• CRUD de Planos com gestão de features
• Suspensão/reativação de tenants
• Impersonação para suporte (signed URLs + banner)
• Middleware de tracking de atividade
• Gestão de features inline na página do tenant (grant/revoke/trial)

Fase 13B-1 — Assinatura SaaS (Asaas) ✅

• Integração Asaas API v3 (AsaasService com Http macro, retry, logging)
• Subscription + Invoice models no banco central
• Webhook controller para eventos de pagamento (PAYMENT_CONFIRMED, PAYMENT_OVERDUE)
• Pipeline de inadimplência automático (banner 4d → read-only 8d → suspensão 16d)
• Middleware EnsureNotReadOnly + billing status no Inertia shared props
• Painel de assinatura no tenant (troca de plano, cancelamento, histórico faturas)
• Dashboard billing no admin central (MRR, assinantes, inadimplência)
• Formas de pagamento: PIX + Cartão de Crédito

13B-2 — Doações/Dízimos Online ✅

• Sub-contas Asaas por igreja com split automático (3% Decaelo)
• Doação via membro logado + link público (/doar)
• PIX (QR code) + Cartão de crédito
• Dízimo recorrente mensal via Asaas subscription
• Recibo PDF automático via Gotenberg + envio por e-mail
• Webhook routing por externalReference (donation: prefix)
• Integração com módulo Finance (cria Transaction automaticamente)

13B-3 — Painel Central Financeiro ✅

• KPIs no dashboard central: MRR, receita de split, receita total
• Volume de doações cross-tenant, contagem mensal, recorrências ativas
• Variação % vs mês anterior

13C — Auditoria e Operações (parcial) ✅

• Logs de atividade centralizados — visualização cross-tenant no admin + dentro do tenant
• Filtros: período, modelo, evento, usuário, busca texto
• 30 models auditados via laravel-auditing, permissão audit.view (admin-igreja)

13C pendente (futuro):

• Suporte a convenções/denominações (painel consolidado multi-igreja)
• Marketplace de conteúdo (livros, artigos)

---

Backlog — Melhorias e Pendências

Itens identificados durante o desenvolvimento que ficaram para implementação futura.

Comunicação & Notificações

• Notificar autor ao aprovar pedido de oração ✅ Implementado
• E-mail automático de boas-vindas ✅ Implementado (MemberCreated → SendWelcomeEmailListener)
• Barra de busca global (Spotlight/Cmd+K) ✅ Implementado (Scout + fallback Eloquent)
• Testar broadcasting end-to-end ✅ Testes de contrato automatizados com Event::fake
• Push notifications (Firebase) — notificações push via browser/mobile. Adiado para quando houver app mobile (Fase 11)
• SMS/WhatsApp (Twilio) — suspenso por tempo indeterminado (futuro distante)

Documentos & Relatórios

• Ata de Reunião ✅ Implementado (modelo híbrido com participantes)
• Declaração de Membro Ativo ✅ Implementado
• Report Builder drag-n-drop — editor visual para montar templates de documentos personalizados por igreja. Campos dinâmicos vinculados aos dados do sistema (nome do membro, data de batismo, etc.). Cada igreja personaliza com sua identidade visual

Integrações (Fase 12 restante)

• API pública — endpoints REST para integrações de terceiros
• Socialite (login social) ✅ Google + Facebook via callback centralizado no domínio central, auto-link por e-mail, signed URL para autenticação no tenant
• Conciliação bancária — integração com bancos/Open Finance para reconciliação automática

Infraestrutura & Qualidade

• EventModelTest:113 falhando ✅ Corrigido (Scout collection driver)
• Documentação de módulos faltantes ✅ 5 módulos documentados (groups, assets, events, checkins, documents)

---

Sugestões em Avaliação (2026-05-23)

Itens levantados em sessão de revisão. Escala de esforço: XS ≤2h · S 0,5–1d · M 2–4d · L 1–2sem · XL >2sem. Esforço considera 1 dev pleno full-stack incluindo testes e docs.

#	Sugestão	Esforço	Status	Observações
1	Patrimônio e Eventos como menus top-level (paralelos a Financeiro/Secretaria)	XS	✅ feito	Commit ac28872 (sidebar reorganizado)
2	Plano de Contas Contábeis (DRE, balancete, lançamentos)	L	futuro	Módulo financeiro contábil completo: estrutura de plano de contas multinível, lançamentos contábeis duplicados (débito/crédito), relatórios contábeis. Requer especialista contábil.
3	Filtros e ação de exclusão em Documentos Gerados e Relatórios Gerados	S	✅ feito	Filtros de período em documents.index e reports.index, destroy com remoção do PDF físico, paginação no histórico de relatórios. Testes: 22 passing.
4	Tipos de Grupo e Tipos de Evento em Configurações Eclesiásticas	S	✅ feito	CRUD já existia via ReferenceDataController + tabs no Church/ReferenceData/Index.vue. Endurecido com filtro de colunas no CreateReferenceDataAction/UpdateReferenceDataAction (schemas distintos: Igreja* usa mostra_combo, GroupType/EventType usam is_active/sort_order). 5 testes adicionados.
5	Dashboard mostrar dados patrimoniais (valor total, quantidade de bens, depreciação)	S	✅ feito	4 cards no Dashboard atrás de asset.view: valor patrimonial (sum valor_aquisicao excluindo baixados), bens cadastrados, em manutenção, baixados. 2 testes adicionados. Depreciação fica para iteração futura (precisa schema com taxa_depreciacao).
6	Dashboard com filtro por congregação	M	futuro	Refactor das queries de KPI: aceitar congregation_id opcional, propagar via prop Inertia, dropdown no header. Cuidar de permissões (admin-congregacao restrito à própria congregação).
7	Avaliar relevância da função "Efetivar Transação" no Financeiro	XS	✅ manter	Avaliada em 2026-05-23. Status pendente (previsto) → efetivada (com data_pagamento) → distinção essencial para fluxo de caixa (previsto × realizado) e futura DRE. Removê-la quebraria o controle de contas a pagar/receber. Decisão: manter.
8	Auto-cadastro criar apenas Member; promoção a User ficar com a secretaria	M	futuro	Hoje MemberProfileController@store cria User+Member juntos. Refactor: criar apenas Member (sem user_id), expor ação members.promote-to-user na secretaria (gera User, link, envia convite por e-mail). Ajustar middleware EnsureProfileCompleted e fluxo de login para auto-link.
9	Reordenar menu lateral: Igreja, Secretaria, Financeiro, Patrimônio, Eventos, Comunicação	XS	✅ feito	Reordenado em AppSidebar.vue (2026-05-23). Ordem atual: Igreja, Secretaria, Financeiro, Patrimônio, Eventos, Comunicação, WhatsApp.

Total estimado dos itens em aberto (2, 6, 8): ~2–3 semanas para um dev pleno full-stack. Itens 1, 3, 4, 5, 7 e 9 já fechados.

---

Princípios Técnicos

• ULID como identificador público (nunca expor IDs numéricos)
• Actions para lógica de negócio (não Services, exceto integrações externas)
• Models unguarded globalmente, validação via Form Requests
• Testes com SQLite in-memory (não MariaDB)
• PrimeVue unstyled com PT preset global (primevue-pt.ts)
• Faker pt_BR para seeders de desenvolvimento
• Auditoria em todos os models de domínio
• Feature flags por tenant para módulos premium