diff --git a/README.md b/README.md index 6d6ca4c..9a91d76 100644 --- a/README.md +++ b/README.md @@ -128,8 +128,9 @@ composer update modules/ Tudo o que não cabe neste README fica em [`docs/`](docs/): - [`produto.md`](docs/produto.md): visão, módulos do MVP e fases seguintes, decisões em aberto +- [`arquitetura/`](docs/arquitetura/): documento visual da arquitetura (PDF): tenancy por edição, módulos e como conversam, banco, papéis, fluxos de compra, CFP e dinheiro, segurança, telas - [Design do admin](https://claude.ai/artifact/3B7ZWqjBQPDFZ5vhGgNs4N#page-dcb81aee8d83): protótipo/telas do `front-admin` -- ADRs com o porquê de cada decisão de arquitetura (a escrever) +- [`adr/`](docs/adr/): o porquê de cada decisão de arquitetura (0001–0009) - Guia para a comunidade anfitriã: criar a edição, conectar o gateway, tematizar e abrir o CFP (a escrever) diff --git a/backend/CLAUDE.md b/backend/CLAUDE.md index 575aafd..9c9190d 100644 --- a/backend/CLAUDE.md +++ b/backend/CLAUDE.md @@ -82,6 +82,10 @@ Policy ou Gate de outro módulo confere permissão, nunca papel: `EditionMembers - Segredo nunca vai pro repositório — ver `docs/adr/0006-politica-de-segredos.md`. - Macro/bind que uma rota de módulo usa (ex.: `Route::apiV1()`) tem que ser registrada no `register()` do provider, nunca no `boot()` — o `internachi/modular` carrega as rotas de cada módulo num hook `booting()` que dispara antes do `boot()` de qualquer provider (inclusive do `AppServiceProvider`). +## Documento de arquitetura + +`../docs/arquitetura/` tem o documento visual de como tudo se encaixa (PDF de 18 páginas gerado por `docs/arquitetura/fonte/gerar.py`). **Todo PR que muda a arquitetura atualiza o documento no mesmo PR**: módulo novo ou que deixa de ser casca, tabela, contrato ou ponto de extensão novo, papel ou permissão, rotina agendada, serviço externo, ou mudança de fluxo (compra, CFP, dinheiro, tenancy). Edite o `gerar.py` (os números estão escritos lá), atualize `RETRATO`, rode `python3 docs/arquitetura/fonte/gerar.py && node docs/arquitetura/fonte/imprimir.mjs` na raiz e confira as páginas com `imprimir.mjs `. Ver `docs/arquitetura/README.md`. + ## Comandos ```bash diff --git a/docs/arquitetura/PHPeste_Arquitetura.pdf b/docs/arquitetura/PHPeste_Arquitetura.pdf new file mode 100644 index 0000000..46881c6 Binary files /dev/null and b/docs/arquitetura/PHPeste_Arquitetura.pdf differ diff --git a/docs/arquitetura/README.md b/docs/arquitetura/README.md new file mode 100644 index 0000000..4b19be8 --- /dev/null +++ b/docs/arquitetura/README.md @@ -0,0 +1,56 @@ +# Arquitetura da PHPeste Platform + +**[PHPeste_Arquitetura.pdf](PHPeste_Arquitetura.pdf)** (18 páginas, A4 paisagem). O mesmo conteúdo, para abrir no navegador: [`fonte/arquitetura.html`](fonte/arquitetura.html). + +| Página | Conteúdo | +|--------|----------| +| 1 | Capa, resumo e legenda | +| 2 | Visão geral do sistema: painel, site, API, fila, banco, serviços externos | +| 3 | Tenancy: comunidade, edição como tenant e o que é global | +| 4 | Como uma requisição encontra a edição (rotas, middleware, jobs, eventos, host) | +| 5 | Ciclo de vida da edição, transições, clonagem e Visão geral | +| 6 | Os 15 módulos do backend | +| 7 | Como os módulos conversam: contratos e pontos de extensão | +| 8 | Banco de dados por domínio (65 tabelas) | +| 9 | Papéis e permissões | +| 10 | Ingresso: da compra ao QR | +| 11 | CFP: da proposta à grade | +| 12 | Dinheiro: patrocínio, fornecedores e finanças | +| 13 | Fila, rotinas agendadas, e-mail e auditoria | +| 14 | Segurança | +| 15 | Desenvolvimento, CI e deploy | +| 16 | Telas: o design do painel (`docs/design/`) | +| 17 | Telas: o painel em uso (capturas do front-admin) | +| 18 | Onde estamos e o que falta | + +Retrato de 19/11/2026, main em `b4293b3`. + +## Como atualizar + +O documento é gerado: não edite o HTML nem o PDF à mão. Os diagramas são SVG escritos em `fonte/gerar.py`, e os números (tabelas, rotas, contratos, permissões) estão escritos lá. A partir da raiz do repositório: + +```bash +python3 docs/arquitetura/fonte/gerar.py # gera fonte/arquitetura.html +node docs/arquitetura/fonte/imprimir.mjs # gera o PDF (usa o Playwright do front-admin/) +``` + +Para salvar também um PNG de cada página (bom para revisar o layout): `node docs/arquitetura/fonte/imprimir.mjs /tmp/paginas`. + +Os prints do painel (`telas/`) saem do front-admin rodando com a API simulada: + +```bash +cd front-admin && CAPTURAR_TELAS=1 npx playwright test e2e/capturas-arquitetura.spec.ts +``` + +Os números do documento conferem com o código assim: + +```bash +cd backend +grep -ho "Schema::create('[a-z_]*'" app-modules/*/database/migrations/*.php database/migrations/*.php | sort -u | wc -l # tabelas +php artisan route:list --json | python3 -c "import sys,json; print(sum(1 for r in json.load(sys.stdin) if r['uri'].startswith('api/')))" # rotas da API +ls app-modules/*/src/Contracts/*.php | wc -l # contratos +``` + +## Quando atualizar + +No mesmo PR que muda a arquitetura: módulo novo ou que deixa de ser casca, tabela nova, contrato ou ponto de extensão novo, papel ou permissão nova, rotina agendada nova, serviço externo novo, mudança de fluxo (compra, CFP, dinheiro), ou tela nova que valha um print. Atualize também a data e o commit em `RETRATO`, no topo do `gerar.py`. diff --git a/docs/arquitetura/fonte/arquitetura.html b/docs/arquitetura/fonte/arquitetura.html new file mode 100644 index 0000000..565f9b0 --- /dev/null +++ b/docs/arquitetura/fonte/arquitetura.html @@ -0,0 +1,1060 @@ + + +Arquitetura PHPeste Platform + + + +
+
+
PHPeste Platform · documentação de arquitetura
+

Uma plataforma, um banco,
uma edição por vez

+

Como funciona a plataforma que organiza o PHPeste todo ano: o painel da organização, o site público de cada + edição e a API Laravel em módulos por trás dos dois. Cada comunidade anfitriã cria a sua edição, e a edição é o tenant: + todo dado de evento carrega edition_id e só aparece dentro dela.

+
+
+
+

Resumo em cinco pontos

+
    +
  1. Monorepo com três partes. backend/ (Laravel 13, API), front-admin/ (Nuxt SPA da organização) e front-public/ (Nuxt SSR do site da edição, resolvido pelo domínio).
  2. +
  3. A edição é o tenant (ADR 0007). Um banco só; escopo global por edition_id e a edição no contexto só durante a requisição ou o job.
  4. +
  5. 15 módulos (internachi/modular) que só conversam por contratos e eventos. 12 já têm lógica; Program, CheckIn, Tasks e Engagement ainda são casca.
  6. +
  7. A plataforma não toca no dinheiro (ADR 0009). Cada edição usa a conta do próprio gateway (Asaas ou Mercado Pago); a receita é calculada dos pedidos, nunca guardada.
  8. +
  9. Toda ação sensível vira trilha de auditoria por evento, com segredo removido e dado pessoal mascarado.
  10. +
+
+
+

Conteúdo

+
  1. Visão geral do sistema2
  2. Tenancy: comunidade, edição e o que é global3
  3. Como uma requisição encontra a edição4
  4. Ciclo de vida da edição5
  5. Os 15 módulos do backend6
  6. Como os módulos conversam7
  7. Banco de dados por domínio8
  8. Papéis e permissões9
  9. Ingresso: da compra ao QR10
  10. CFP: da proposta à grade11
  11. Dinheiro: patrocínio, fornecedores e finanças12
  12. Fila, rotinas agendadas, e-mail e auditoria13
  13. Segurança14
  14. Desenvolvimento, CI e deploy15
  15. Telas: design e painel16
  16. Telas: painel em uso17
  17. Onde estamos e o que falta18
+
+
+

Legenda usada nos diagramas

+Front-end (painel, site, app) + +Backend Laravel + +Dado da edição (tenant) + +Dado global ou da comunidade + +Banco, cache e arquivos + +Serviço externo + +Infra e operação + +Planejado, ainda vazio + +chamada ou dependência + +assíncrono (evento, fila, webhook)
+
Fonte: código da main, backend/CLAUDE.md, docs/produto.md e ADRs 0001–0009.19/11/2026 · main em b4293b3 · página 1
+
+
+
+
02 · Visão geral
+

Visão geral do sistema

+

Dois front-ends Nuxt e um site próprio opcional falam com uma API só. O Caddy emite o certificado de cada domínio de edição na hora; a API resolve a edição pelo host.

+
+
Quem usa + +Painel da organização +front-admin · Nuxt 4 SPA +organizador, financeiro, +avaliador, check-in + +Site da edição +front-public · Nuxt 4 SSR +site, CFP, checkout, +área do palestrante e +do participante + +Site próprio da comunidade +opcional: chama só a +API pública (CORS por edição) + +App Flutter +ainda não iniciado + +Gateways (webhooks) +Asaas e Mercado Pago + +Caddy +proxy reverso +TLS sob demanda +para domínio de +cada edição +(tls-check) + + + + +API · Laravel 13 · PHP 8.4 · /api/v1 + +Rotas por tipo +/editions/{id}/… painel (Sanctum + papel na edição) +/speaker, /attendee, /checkout/editions/{id}/… publicada +/public/… site, tema, ingressos (cache + ETag) +/webhooks/payments/{token} assinado + +15 módulos (app-modules/) +Identity · Community · Branding · Cfp · Ticketing +Payments · Notifications · Audit · Sponsors +Suppliers · Finance +casca: Program · CheckIn · Tasks · Engagement + +Horizon (fila) +e-mail, webhooks, +importação, clonagem +de edição, emissão +de ingressos + +Scheduler +cfp:sync-status +ticketing:expire-orders +ticketing:reconcile +payments:retry-webhooks +…8 rotinas + +Regras que valem para todo módulo +Tenancy por edição (BelongsToEdition) +Mutação só em Action · validação em FormRequest +Módulo não usa model de outro (arch test) +Ação sensível → evento Auditable +Logs JSON com segredo redigido · Sentry opcional + + +MySQL 8 +um banco · 65 tabelas +UUID em toda tabela + +Redis +cache, filas, locks, +rate limit + +Disco privado +CSV de importação, anexos, +comprovantes (URL assinada) + +Asaas · Mercado Pago +conta de cada edição (ADR 0009) + +Resend (e-mail) +Mailpit no dev + +GitHub OAuth +login de palestrante + +Sentry +opcional, sem DSN fica desligado + + + + + + +
+
  • Painel e site são projetos separados (decisão: front-admin SPA, front-public SSR). O token é Bearer do Sanctum nos dois (ADR 0005).
  • Fila e agendador rodam a mesma imagem do backend (horizon e scheduler no infra/docker-compose.yml).
+
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 2
+
+
+
+
03 · Tenancy
+

Tenancy: comunidade, edição e o que é global

+

ADR 0007: uma instalação e um banco. A edição é o tenant; usuários e perfis de palestrante são globais para guardar o histórico entre edições. Toda chave é UUID.

+
+
Global (da plataforma) + +users +conta única: organização, palestrante e +participante · login por senha ou GitHub +social_accounts · password_reset_tokens + +speaker_profiles +perfil público do palestrante, vale em todas +as edições · dados sensíveis cifrados à parte + +communities +PHP-PB, PHPCE… dona das edições + +suppliers + supplier_contacts +global DA COMUNIDADE: reaproveitado entre +as edições dela, nunca visto por outra +contato só para quem é de uma edição dele + +infra do Laravel +personal_access_tokens (um por dispositivo) +jobs, cache, sessions +audit_logs: global, mas cada registro +leva o edition_id +Por edição (o tenant) · toda tabela tem edition_id + escopo global + +editions +community_id · status (máquina +de estados) · datas, cidade +site_mode: plataforma ou +site próprio + +Equipe e configuração +edition_members (papel na edição) · edition_invitations +edition_settings (tema) · edition_domains +cfp_settings · ticketing_settings · sponsor_settings +email_templates · finance_categories + +Conteúdo +cfp_tracks · cfp_criteria · proposals +proposal_speakers · review_assignments +reviews · speaker_confirmations · speaker_logistics + +Vendas +ticket_types · ticket_batches · coupons +orders · order_items · tickets +payment_accounts · payment_charges +webhook_events · payment_refunds + +Organização +sponsors · sponsorships · sponsor_tiers +edition_suppliers · supplier_quotes +expenses + +Comunicação e operação +email_deliveries · email_unsubscribes +ticket_imports · reconciliation_issues +edition_clones + +Como o isolamento é garantido +Model de edição usa o trait BelongsToEdition: liga o EditionScope e preenche edition_id ao criar. +Sem edição no contexto, a consulta não devolve nada e criar sem edition_id lança LogicException. +Ler outra edição de propósito exige ->forEdition($id) explícito (clonagem, rotinas agendadas). +Comunidade A nunca vê edição, fornecedor ou dado da comunidade B. + +community_id
+
  • Por que não um banco por comunidade: a mesma pessoa palestra no PHPeste de um ano e compra ingresso no outro, e o perfil dela é um só.
  • Dado de edição que vai para a próxima ("criar edição a partir da anterior") é copiado por um EditionCloner de cada módulo, nunca dado de pessoa.
+
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 3
+
+
+
+
04 · Tenancy na prática
+

Como uma requisição encontra a edição

+

Toda rota do painel passa pela mesma esteira; o módulo só escreve a regra de negócio. A edição entra no contexto e sai no fim, e o escopo global faz o resto.

+
+
+1 · Rota +Route::apiV1Edition('ticketing') +/api/v1/editions/{edition}/… + + +2 · auth:sanctum +token Bearer válido +(um por dispositivo) + + +3 · Papel na edição +edition_members tem a +pessoa? senão 403 + + +4 · CurrentEdition +liga a edição no contexto +só durante a requisição + + +5 · Gate da permissão +Gate::authorize( +'orders.refund') + + +6 · FormRequest → Action +valida, depois a Action +muda o Model + +Rotas de quem não é da equipe +Route::apiV1PublishedEdition('speaker', 'proposals', ['auth:sanctum']) +→ /api/v1/speaker/editions/{edition}/proposals +só aceita edição publicada (rascunho = 404) e liga a edição no contexto +sem exigir papel. Usado por palestrante, participante e checkout. +A posse do dado é conferida na Action (a proposta é dela?). + +Rotas públicas e de máquina +/api/v1/public/resolve?host=… site descobre a edição pelo domínio +/api/v1/public/editions/{id}/theme tema publicado com ETag +/api/v1/webhooks/payments/{token} assinatura do gateway +/api/v1/sponsors/attachments/{id}/download URL assinada +CORS: só a origem do site próprio da edição, só em /public/* + +Job e listener +recebem edition_id explícito no construtor e rodam dentro de +resolve(CurrentEdition::class)->run($editionId, fn () => …) +nunca herdam a edição de quem disparou: a fila roda depois, +em outro processo, e a edição do contexto já não existe. + +Evento de domínio +carrega ids e enums, nunca Model de outro módulo +ex.: EditionStatusChanged(editionId, from, to) +ShouldDispatchAfterCommit: só sai se a transação gravou +evento Auditable vira registro em audit_logs + +Front-public: a edição vem do host +O site chama /public/resolve com o host da requisição, recebe edition_id e o domínio principal e redireciona se for preciso (ADR 0008). +O host é normalizado (minúsculas, sem porta, IDN em punycode) e nunca é usado para montar URL sem passar pela tabela edition_domains.
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 4
+
+
+
+
05 · Edição
+

Ciclo de vida da edição

+

EditionStatus é uma máquina de estados com o que cada etapa libera e bloqueia (effects()). Só anda para a frente; o painel mostra a etapa atual e a próxima.

+
+
+Rascunho +preparação, nada público + +CFP aberto +site e domínios públicos +propostas na janela +tema publicado vale +slug da URL travado + +Vendas abertas +venda de ingressos +CFP segue a janela +exige gateway pronto + se houver lote pago + +Em andamento +check-in +presença de palestrante +não volta a vender + +Encerrada +relatórios finais +só consulta +não reabre + + + + + +rascunho pode ir direto para vendas + +Quem decide a transição +A organização muda o status no painel. +Cada módulo pode barrar a mudança com um +EditionTransitionGuard (ex.: SalesReadinessGuard +do Ticketing: lote pago sem conta de gateway +pronta = não abre vendas). + +Quem reage +EditionStatusChanged (auditado) dispara: +Cfp: CfpOpened / CfpClosed, derivados da janela + e do status (cfp:sync-status a cada minuto) +Branding: tema publicado passa a valer +Ticketing: rotação de lotes e expiração + +Criar a partir da anterior +Job CloneEdition: nova edição em rascunho, +sem datas, e cada EditionCloner escolhido +copia numa transação só: tema, domínios, +equipe, CFP, e-mails, ingressos, cotas, +fornecedores contratados, orçamento. + +Visão geral da edição (um endpoint, vários módulos) +GET /editions/{id}/overview junta o que cada módulo devolve no seu EditionOverviewContributor: indicadores (ingressos, receita, propostas, +palestrantes, patrocínio, fornecedores), pendências com caminho e filtro (propostas sem revisor, divergência na conciliação, entregas e despesas +vencidas) e marcos. O Community filtra cada pendência pela permissão de quem vê: o voluntário não vê pendência de finanças.
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 5
+
+
+
+
06 · Backend
+

Os 15 módulos do backend

+

Cada módulo é um pacote Composer real em backend/app-modules/<nome> (ADR 0002), com namespace PHPeste\<Nome>: Models, Actions, Contracts, Events, Http, Jobs. 247 rotas na API.

+
+
+Identity +contas, login (senha e GitHub), sessões por +dispositivo, perfil e perfil de palestrante + +22 rotas + +Community +comunidades, edições, estados, equipe, convites, +tenancy, Visão geral, clonagem + +26 rotas + +Branding +tema por edição (rascunho/publicado), presets, +contraste AA, logos, domínios e TLS + +17 rotas + +Cfp +chamada, trilhas, critérios, propostas, +avaliação cega, decisão, cota do Nordeste, +confirmação + +52 rotas + +Ticketing +tipos, lotes, cupons, pedidos, estoque atômico, +ingressos com QR, transferência, importação, +conciliação + +50 rotas + +Payments +contas de gateway por edição, drivers Asaas e +Mercado Pago, cobranças, webhooks, reembolsos + +8 rotas + +Notifications +e-mail transacional por edição com modelos +editáveis, descadastro, Resend + +9 rotas + +Audit +trilha append-only das ações sensíveis, com +redação de segredos + +1 rotas + +Sponsors +cotas, funil, vagas, pagamentos, entregas, +anexos por URL assinada + +28 rotas + +Suppliers +cadastro da comunidade, orçamentos, contratação, +anexos, reaproveitamento + +19 rotas + +Finance +despesas, orçamento por categoria, receita +calculada, saldo, planilha + +14 rotas + +Program +salas, sessões e grade (B35–B37) + +casca + +CheckIn +leitura de QR, entrada, modo offline (B38–B39) + +casca + +Tasks +kanban da organização (B34) + +casca + +Engagement +feedback, certificados, sorteio (B42) + +casca
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 6
+
+
+
+
07 · Backend
+

Como os módulos conversam

+

Módulo nunca usa model de outro: ou chama um contrato (interface em Contracts/, ligada no service provider) ou escuta um evento. 24 contratos hoje. O arch test barra dependência de App\.

+
+
+Community +EditionMemberships +EditionDirectory +pontos de extensão (tags) ↓ + +EditionOverviewContributor +números da Visão geral + + +EditionCloner +copiar para a próxima + + +EditionTransitionGuard +barrar mudança de status + + +EditionParticipation +quem participa (Identity) + + +Cfp +→ UserAccounts, SpeakerProfiles (Identity) +→ EditionMailer (Notifications) +→ EditionSites (Branding) +ReviewLedger ← quem conta avaliações + +Ticketing +→ PaymentProcessor, PaymentLedger +→ PaymentAccounts (Payments) +AccountUsage, TicketVerifier, +TicketRevenue ← Payments, CheckIn, Finance + +Payments +→ PaymentGateway (driver Asaas/MP) +ChargeStatusChanged → Ticketing +RefundAccepted → Ticketing +sem acesso a pedidos: só referência + +Finance +→ TicketRevenue (Ticketing) +→ SponsorRevenue (Sponsors) +→ PaymentAccounts::all (Payments) +→ EditionSuppliers (Suppliers) + +Sponsors · Suppliers +→ EditionMemberships (responsável) +→ UserAccounts (nomes) +Suppliers → EditionDirectory::communityId +para não vazar entre comunidades + +Audit · Notifications +Auditable: qualquer evento vira registro +pelo listener genérico RecordAuditableEvent +EditionMailer::send(...): todo e-mail +passa por aqui, com tema da edição
+
  • Ponto de extensão é registrado com $app->tag([...], Contrato::TAG): o Community não conhece os módulos, só a tag. Módulo novo aparece na Visão geral e na clonagem sem mexer no Community.
+
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 7
+
+
+
+
08 · Dados
+

Banco de dados por domínio

+

MySQL 8, 65 tabelas, todas com UUID como chave. Verde é da edição (tem edition_id); azul é global. ● em Suppliers: global da comunidade (community_id).

+
+
+Identity · 5 +users +social_accounts +password_reset_tokens +speaker_profiles +speaker_private_details + +Community · 5 +communities +editions +edition_members +edition_invitations +edition_clones + +Branding · 2 +edition_settings +edition_domains + +Cfp · 10 +cfp_settings +cfp_tracks +cfp_criteria +proposals +proposal_speakers +review_assignments +reviews +review_scores +speaker_confirmations +speaker_logistics + +Ticketing · 12 +ticketing_settings +ticket_types +ticket_batches +coupons +coupon_redemptions +orders +order_items +tickets +ticket_transfers +reconciliation_issues +ticket_imports +ticket_import_rejections + +Payments · 4 +payment_accounts +payment_charges +webhook_events +payment_refunds + +Notifications · 3 +email_templates +email_deliveries +email_unsubscribes + +Audit · 1 +audit_logs + +Sponsors · 8 +sponsor_settings +sponsor_tiers +sponsors +sponsorships +sponsorship_payments +sponsor_deliverables +sponsor_contacts +sponsor_attachments + +Suppliers · 6 +suppliers ● +supplier_contacts ● +edition_suppliers +supplier_quotes +supplier_attachments +supplier_activities + +Finance · 2 +finance_categories +expenses + +Laravel · 7 +personal_access_tokens +jobs · job_batches +failed_jobs +cache · cache_locks +sessions
+
  • Dinheiro sempre em centavos (inteiro). Dado sensível cifrado no banco: CPF de quem compra, credenciais do gateway, acessibilidade, corpo de webhook, linhas de importação. APP_PREVIOUS_KEYS + comandos *:reencrypt-* para trocar a chave.
  • Estoque e cupom nunca são lidos e depois gravados: UPDATE … WHERE allocated + q <= quantity. Testes com 12 processos simultâneos provam que não vende além do lote.
+
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 8
+
+
+
+
09 · Acesso
+

Papéis e permissões

+

Cinco papéis por edição e doze permissões. O organizador tem todas.

+
+
PermissãoO que liberaOrganizadorFinanceiroAvaliadorCheck-inVoluntário
edition.manageConfigurar edição e identidade●
edition.teamGerenciar equipe e convites●
cfp.reviewAvaliar propostas●●
program.manageGerenciar palestrantes e grade●
speakers.privateVer acessibilidade e alimentação●
orders.viewVer pedidos e pagamentos●●
orders.refundReembolsar pedidos●●
payments.gatewayEditar chaves do gateway●
checkin.scanFazer check-in●●
sponsors.manageGerenciar patrocinadores●
suppliers.manageGerenciar fornecedores●
finance.manageVer e editar finanças●●
+
+

Como funciona

+
    +
  • O papel é por edição (edition_members): a mesma pessoa pode organizar uma edição e só avaliar outra.
  • +
  • Papel e permissão vivem em código (EditionRole::permissions()). Cada permissão vira um Gate com o próprio nome.
  • +
  • Policy e Gate conferem permissão, nunca papel: Gate::authorize('orders.refund').
  • +
  • Outro módulo pergunta pelo contrato: EditionMemberships::can($edition, $user, $permissão).
  • +
  • A edição nunca fica sem organizador: trocar o papel ou remover o último é bloqueado.
  • +
  • O painel lê a tabela em GET /roles e monta o menu por papel.
  • +
  • Palestrante e participante não têm papel: entram pelas rotas de edição publicada.
  • +
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 9
+
+
+
+
10 · Fluxo
+

Ingresso: da compra ao QR

+

O pedido nasce reservando estoque; o pagamento só confirma quando a API consulta o gateway. Evento falso, repetido ou fora de ordem não muda pedido.

+
+
+Quem compra (site) + +Ticketing + +Payments + +Gateway + +Fila e rotinas + +Escolhe ingressos +tipo, lote, cupom, +participantes + +PlaceOrder +reserva estoque e cupom +numa transação +Idempotency-Key + +Pix ou cartão +sem dado de cartão +na nossa API + +ChargeService +cobrança na conta da +edição · trava clique duplo + +Asaas / Mercado Pago +Pix com QR, cartão +na fatura ou token + +Webhook assinado +→ /webhooks/payments/{t} + +webhook_events +caixa de entrada, 2xx +antes de processar + +ProcessWebhookEvent +consulta o gateway: +não confia no corpo + +Pedido pago +TransitionOrder +IssueTicketsWhenPaid + +E-mail + QR +QR assinado (HMAC) +/ingressos no site + + + + + + + +job na fila + +sync + + +Rotinas que fecham as pontas +ticketing:expire-orders (1/min) devolve estoque de reserva vencida · ticketing:rotate-batches abre o próximo lote +payments:retry-webhooks (1, 5, 15, 60 min) · ticketing:reconcile (diário) grava divergência com o gateway
+
  • Reembolso: PaymentLedger::refund reserva o valor antes de chamar o gateway (dois reembolsos ao mesmo tempo nunca passam do pago). Pedido importado de outra plataforma entra pago, sem cobrança, e não passa por reembolso nem conciliação.
+
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 10
+
+
+
+
11 · Fluxo
+

CFP: da proposta à grade

+

A chamada de trabalhos é o coração do Marco 1. O estatuto do PHPeste pede pelo menos metade de palestrantes do Nordeste e um de cada estado; a decisão mostra isso antes de gravar.

+
+
+Configuração +janela, trilhas com +vagas, critérios com +peso, cota Nordeste, +avaliação anônima + + +Submissão +palestrante com perfil +global · rascunho e +envio na janela · até +3 coautores · limite + + +Atribuição +manual ou automática +(menor carga primeiro) +sem conflito: autoria +ou mesma empresa + + +Avaliação +notas 1–5 por critério +nota ponderada na hora +revisor não vê autor +quando é anônima + + +Decisão +ranking por trilha +respeitando vagas · simula +cobertura por UF e % do +Nordeste antes de gravar + + +Confirmação +e-mail com prazo +lembrete 48 h antes +recusa libera vaga e +sugere lista de espera + +Status do CFP é derivado, nunca editado +CfpStatus vem da janela + status da edição. +cfp:sync-status (1/min) e o listener de +EditionStatusChanged disparam CfpOpened e +CfpClosed uma vez cada. + +Convite direto +organização convida pelo e-mail: cria a conta +sem senha se precisar, proposta já aprovada +(origin = invited), fora da avaliação mas +ocupando vaga da trilha. + +Depois do aceite +logística por palestrante (viagem, hospedagem) +quadro de palestrantes com os 9 estados do +Nordeste · acessibilidade e alimentação só +com speakers.private · presença no evento + +Próximo passo: grade (Program, B35–B37) +Propostas confirmadas viram sessões em salas e horários, com validação de conflito; a programação sai pela API pública com cache, e quem vai ao evento +monta a agenda pessoal. É o que falta para o Marco 3. + +Telas prontas no painel +Configurar CFP (A10) · Avaliar propostas com teclado (A11) · Palestrantes: lista, cobertura e detalhe (A12) · no site público: formulário de +proposta e área do palestrante com entrar pelo GitHub (P03, P11).
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 11
+
+
+
+
12 · Fluxo
+

Dinheiro: patrocínio, fornecedores e finanças

+

Patrocínio, fornecedores e ingressos expõem os números por contratos; o Finance só soma. O teste de propriedade confere, em 25 rodadas aleatórias, que a receita bate com os pedidos pagos menos reembolsos.

+
+
+Sponsors +cotas: valor, vagas, contrapartidas +funil: prospecção → negociando → +fechado → pago · perdido com motivo +fechar acima das vagas exige confirmação +pagamento registrado à mão; cobrir o valor +passa para pago sozinho +contrapartida vira entrega com prazo + +Suppliers +cadastro global DA COMUNIDADE +na edição: a contatar → em orçamento → +contratado · recusado com motivo +orçado = menor orçamento válido +contato só para quem é de uma edição +em que ele aparece +reaproveitar de edição anterior + +Ticketing +pedidos pagos e reembolsados com valor +taxa real (conciliação) ou estimada +pelo percentual da edição +por conta de recebimento +(CPF ou CNPJ, inclusive conta trocada) +pedido gratuito e importado ficam fora + +Finance: calculado na hora, nunca guardado +receita de ingressos = pagos − reembolsos − taxas +receita total = ingressos líquido + patrocínio recebido +saldo = receita − despesas pagas +previsão = saldo + patrocínio a receber − despesas a pagar +orçamento por categoria × comprometido × pago +despesas com fornecedor e comprovante por URL assinada +planilha XLSX (4 abas) e CSV + +SponsorRevenue + +EditionSuppliers + +TicketRevenue + +ADR 0009: a plataforma não recebe nem repassa dinheiro +Cada edição cadastra a conta do próprio gateway; a API valida as chaves e um webhook assinado antes de abrir vendas. Credenciais cifradas; a API só mostra os 4 últimos caracteres.
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 12
+
+
+
+
13 · Operação
+

Fila, rotinas agendadas, e-mail e auditoria

+

O que roda sem ninguém clicar. Todas as rotinas usam withoutOverlapping() e são idempotentes: rodar duas vezes não muda o resultado.

+
+
QuandoComandoPara quê
* * * * *cfp:sync-statusabre e fecha o CFP pela janela
0 * * * *cfp:confirmation-deadlineslembra 48 h antes e marca sem resposta
* * * * *ticketing:expire-ordersexpira reserva vencida e devolve estoque
* * * * *ticketing:rotate-batchesencerra lote esgotado e abre o próximo
*/5 * * * *ticketing:resume-importsretoma importação parada
04:00 BRTticketing:reconcileconfere pedidos com o gateway
* * * * *payments:retry-webhooksreenfileira webhook com erro (1, 5, 15, 60 min)
03:30audit:pruneapaga trilha além de AUDIT_RETENTION_DAYS
+
+

Fila (Redis + Horizon)

+
    +
  • Job recebe edition_id explícito e roda em CurrentEdition::run.
  • +
  • afterCommit(): o job só entra na fila se a transação gravou.
  • +
  • Importação grande: um lote de linhas por job, posição em bytes gravada com o lote, retoma do ponto exato.
  • +
+

E-mail (Notifications)

+
    +
  • Todo e-mail sai por EditionMailer::send: registra em email_deliveries e enfileira com 5 tentativas.
  • +
  • Modelo editável por edição, variáveis {nome} sem Blade, HTML escapado, layout com o tema publicado.
  • +
  • Não transacional leva descadastro com link assinado e List-Unsubscribe.
  • +
+

Auditoria

+
    +
  • Evento que implementa Auditable vira linha em audit_logs pelo listener genérico. 21 eventos hoje.
  • +
  • Segredo removido, dado pessoal mascarado; o model recusa update e delete.
  • +
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 13
+
+
+
+
14 · Segurança
+

Segurança

+

As travas que valem para todo módulo. A maioria é verificada por teste.

+
+
TemaComo está
AutenticaçãoSanctum Bearer, um token por dispositivo com expiração (SANCTUM_EXPIRATION_MINUTES); revogar é imediato. Senha mínima de 10 e checagem de vazamento.
IsolamentoEscopo global por edição; outra comunidade recebe 404; arch test impede módulo de depender de App\ e controller de usar $request->all().
Rate limitLimiters nomeados: login, password-reset, checkout, webhooks, configuráveis por .env.
Headers e CORSCSP, HSTS, nosniff, Referrer-Policy, Permissions-Policy. CORS por ambiente e, em /public/*, só a origem do site próprio da edição.
Dados sensíveisCifrados no banco (CPF, credenciais, acessibilidade, webhooks). Logs JSON com password, token, secret e cartão redigidos automaticamente.
ArquivosDisco privado; download só por URL assinada que expira (10 min), sempre como anexo, com nosniff e CSP sandbox. SVG sanitizado.
PagamentoSem dado de cartão na API; webhook com assinatura do driver e reconsulta ao gateway; idempotência no banco (unique(edition_id, idempotency_key)).
SegredosADR 0006: nada de segredo no repositório; APP_PREVIOUS_KEYS para trocar a chave sem perder o que já foi cifrado.
LGPDEncarregado e política por edição, anonimização após o evento (B43 em aberto). Decisão em aberto: comunidade controladora, PHPeste operador.
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 14
+
+
+
+
15 · Operação
+

Desenvolvimento, CI e deploy

+

Ambiente local em Docker Compose (ADR 0003); a CI roda o mesmo composer check. O deploy de produção ainda está no plano do Marco 4.

+
+
Desenvolvimento (infra/docker-compose.yml) + +backend +Sail PHP 8.4 +porta 8000 + +horizon +mesma imagem + +scheduler +mesma imagem + +MySQL 8 +volume local + +Redis +cache e fila + +Mailpit +e-mail em :8025 + +infra/dev.sh up | down | reset | shell | logs +sobe os seis serviços (cria infra/.env na primeira vez) +front-admin e front-public rodam com npm run dev +CI (GitHub Actions) + +backend-ci +Pint (estilo) +Larastan nível 8 +Pest (~1040 testes) +composer audit + +front-admin-ci · front-public-ci +lint, typecheck, testes +unitários e build; e2e na CI +do front-public; o do painel +(82 testes) roda local + +composer check (local, antes de abrir PR) +pint + phpstan + rector --dry-run + pest +Teste de concorrência com processos PHP reais (estoque, cupom, +reembolso, idempotência), SQLite com transaction_mode IMMEDIATE +Produção (planejado, B45) + +Caddy +TLS automático do domínio +da plataforma e on-demand +para domínios de edição +(pergunta à API: tls-check) + +API + Horizon + scheduler +mesma imagem +variáveis por ambiente +Sentry com DSN + +MySQL + Redis +backup e restauração +ainda a definir + +Resend + gateways +RESEND_API_KEY +contas de produção +de cada edição + +Em aberto para o evento +teste de carga, backups, runbook do dia do evento (B45) · dados de demonstração e documentação publicada (B46)
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 15
+
+
+
+
16 · Telas
+

Telas: o design do painel

+

Referências de design do painel (tema Sertão, cores, tipografia Lexend) que o front-admin segue; o protótipo completo está no link de design do README. O tema é por edição: a comunidade escolhe um preset (Sertão, Maré, Brasa) e ajusta as cores com checagem de contraste AA.

+
+
+
Design da Visão geral do painel
Design: Visão geral da edição
+
Tokens do tema Sertão
Design: tokens do tema Sertão
+
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 16
+
+
+
+
17 · Telas
+

Telas: o painel em uso

+

Capturas do front-admin rodando, com a API simulada (front-admin/e2e/capturas-arquitetura.spec.ts). O menu muda pelo papel: o avaliador só vê Visão geral e Avaliar propostas.

+
+
+
Visão geral
Organizador: Visão geral, com etapa, indicadores, pendências e meta do Nordeste
+
Avaliação de propostas
Avaliador: fila de propostas com nota por critério, sem ver o autor
+
Login
Entrar com e-mail e senha ou GitHub
+
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 17
+
+
+
+
18 · Roadmap
+

Onde estamos e o que falta

+

Os milestones do GitHub e o board PHPeste Platform são a fonte da verdade do andamento; esta página é o retrato no dia da geração.

+
+
MarcoSituaçãoO que tem
Marco 0 · FundaçãoConcluídoesqueleto Laravel 13, módulos, Docker, convenções de API, segurança base, painel e componentes
Marco 1 · Núcleo e CFPBackend concluídoIdentity, Community, Branding, Notifications, CFP inteiro, Audit; telas A05–A12, A24, A25; site P01, P03
Marco 2 · IngressosBackend quase concluídoingressos, cupons, pedidos, Asaas, Mercado Pago, webhooks, reembolso, conciliação, QR, importação, patrocínio, fornecedores, finanças; falta B34 (tarefas) e as telas A14–A23, P04–P06
Marco 3 · Evento prontoA fazergrade e programação (B35–B37), check-in com modo offline (B38–B39), push (B40), API pública e checkout embutível (B41), site da edição (P02, P07–P09)
Marco 4 · OperaçãoA fazerengajamento (B42), LGPD (B43), relatórios (B44), carga, backups e runbook (B45), dados de demonstração (B46), acessibilidade e e2e (A26, A27)
+ +
PHPeste Platform · Arquitetura19/11/2026 · main em b4293b3 · página 18
+
+ diff --git a/docs/arquitetura/fonte/gerar.py b/docs/arquitetura/fonte/gerar.py new file mode 100644 index 0000000..4f665b2 --- /dev/null +++ b/docs/arquitetura/fonte/gerar.py @@ -0,0 +1,637 @@ +#!/usr/bin/env python3 +""" +Gera docs/arquitetura/fonte/arquitetura.html (diagramas em SVG inline). +O PDF sai de `node docs/arquitetura/fonte/imprimir.mjs`. + +Uso (na raiz do repo): + python3 docs/arquitetura/fonte/gerar.py && node docs/arquitetura/fonte/imprimir.mjs + +Os números das páginas (tabelas, rotas, módulos) estão escritos aqui à mão: +ao mudar a arquitetura, atualize este arquivo no mesmo PR (ver CLAUDE.md). +""" +from html import escape +from pathlib import Path + +OUT = Path(__file__).with_name("arquitetura.html") +RETRATO = "19/11/2026 · main em b4293b3" + +# ---------------------------------------------------------------- estilo --- +# Cores do tema Sertão (front-admin) para o que é da plataforma, e neutras +# para o que é de fora. +K = { + "client": ("#FDF1DD", "#B8761E"), + "backend": ("#F7E9E1", "#6B2A14"), + "edition": ("#E6F2EC", "#2F7D5B"), + "global": ("#E8F0FB", "#3B6FD8"), + "data": ("#FFF6E5", "#C98A12"), + "external": ("#F3F4F6", "#6B7280"), + "infra": ("#F1F5F9", "#475569"), + "todo": ("#FFFFFF", "#94A3B8"), + "alert": ("#FDECEC", "#C2410C"), +} +INK = "#2B1408" +MUTED = "#5B4636" + + +def t(x, y, s, size=10.5, weight=400, color=INK, anchor="start", mono=False, italic=False): + fam = "'JetBrains Mono','SF Mono',Menlo,monospace" if mono else "inherit" + st = ' font-style="italic"' if italic else "" + return (f'{escape(s)}') + + +def box(x, y, w, h, title, lines=(), kind="backend", dashed=False, mono=False, title_size=12, line_h=14, center=False, badge=None, size=10): + fill, stroke = K[kind] + dash = ' stroke-dasharray="6 4"' if dashed else "" + out = [f''] + tx, anchor = (x + w / 2, "middle") if center else (x + 10, "start") + out.append(t(tx, y + 19, title, size=title_size, weight=700, anchor=anchor)) + for i, line in enumerate(lines): + color, weight, s = MUTED, 400, line + if line.startswith("+ "): + color, weight, s = K["edition"][1], 600, line[2:] + elif line.startswith("! "): + color, weight, s = K["alert"][1], 600, line[2:] + out.append(t(tx, y + 36 + i * line_h, s, size=size, color=color, weight=weight, anchor=anchor, mono=mono)) + if badge: + label, bkind = badge + bw = 10 + len(label) * 6 + out.append(f'') + out.append(t(x + w - bw / 2 - 7, y + 18, label, size=9, weight=700, color="#FFFFFF", anchor="middle")) + return "\n".join(out) + + +def group(x, y, w, h, label, kind="infra", dashed=True, label_size=11): + fill, stroke = K[kind] + dash = ' stroke-dasharray="7 5"' if dashed else "" + return (f'' + t(x + 13, y + 18, label, size=label_size, weight=700, color=stroke)) + + +def arrow(points, kind="infra", dashed=False, label=None, at=0, both=False, dy=-6, label_anchor="middle"): + stroke = K[kind][1] + d = "M " + " L ".join(f"{px} {py}" for px, py in points) + dash = ' stroke-dasharray="6 4"' if dashed else "" + start = f' marker-start="url(#a-{kind})"' if both else "" + out = [f''] + if label: + (x1, y1), (x2, y2) = points[at], points[at + 1] + out.append(t((x1 + x2) / 2, (y1 + y2) / 2 + dy, label, size=9.5, weight=600, color=stroke, anchor=label_anchor)) + return "\n".join(out) + + +def svg(body, w=1100, h=560): + markers = [f'' for k, (_, s) in K.items()] + return f'{"".join(markers)}{body}' + + +def page(num, kicker, title, subtitle, content, notes=None): + notes_html = '
    ' + "".join(f"
  • {n}
  • " for n in notes) + "
" if notes else "" + return f""" +
+
+
{num:02d} · {escape(kicker)}
+

{escape(title)}

+

{subtitle}

+
+
{content}
+ {notes_html} +
PHPeste Platform · Arquitetura{RETRATO} · página {num}
+
""" + + +def table(head, rows, cls="cmp"): + th = "".join(f"{h}" for h in head) + body = "".join("" + "".join(f"{c}" for c in row) + "" for row in rows) + return f'{th}{body}
' + + +def legend(): + items = [ + ("client", "Front-end (painel, site, app)"), ("backend", "Backend Laravel"), ("edition", "Dado da edição (tenant)"), + ("global", "Dado global ou da comunidade"), ("data", "Banco, cache e arquivos"), ("external", "Serviço externo"), + ("infra", "Infra e operação"), ("todo", "Planejado, ainda vazio"), + ] + out = [] + for i, (k, label) in enumerate(items): + x, y = 10 + (i % 4) * 255, 10 + (i // 4) * 32 + f, s = K[k] + dash = ' stroke-dasharray="6 4"' if k == "todo" else "" + out.append(f'') + out.append(t(x + 44, y + 15, label, size=12)) + out.append(arrow([(10, 88), (60, 88)], "infra")) + out.append(t(70, 92, "chamada ou dependência", size=12)) + out.append(arrow([(265, 88), (315, 88)], "infra", dashed=True)) + out.append(t(325, 92, "assíncrono (evento, fila, webhook)", size=12)) + return svg("\n".join(out), w=1020, h=100) + + +pages = [] + +# =================================================================== 1 capa +toc = [ + "Visão geral do sistema", "Tenancy: comunidade, edição e o que é global", "Como uma requisição encontra a edição", + "Ciclo de vida da edição", "Os 15 módulos do backend", "Como os módulos conversam", "Banco de dados por domínio", + "Papéis e permissões", "Ingresso: da compra ao QR", "CFP: da proposta à grade", "Dinheiro: patrocínio, fornecedores e finanças", + "Fila, rotinas agendadas, e-mail e auditoria", "Segurança", "Desenvolvimento, CI e deploy", "Telas: design e painel", + "Telas: painel em uso", "Onde estamos e o que falta", +] +pages.append(f""" +
+
+
PHPeste Platform · documentação de arquitetura
+

Uma plataforma, um banco,
uma edição por vez

+

Como funciona a plataforma que organiza o PHPeste todo ano: o painel da organização, o site público de cada + edição e a API Laravel em módulos por trás dos dois. Cada comunidade anfitriã cria a sua edição, e a edição é o tenant: + todo dado de evento carrega edition_id e só aparece dentro dela.

+
+
+
+

Resumo em cinco pontos

+
    +
  1. Monorepo com três partes. backend/ (Laravel 13, API), front-admin/ (Nuxt SPA da organização) e front-public/ (Nuxt SSR do site da edição, resolvido pelo domínio).
  2. +
  3. A edição é o tenant (ADR 0007). Um banco só; escopo global por edition_id e a edição no contexto só durante a requisição ou o job.
  4. +
  5. 15 módulos (internachi/modular) que só conversam por contratos e eventos. 12 já têm lógica; Program, CheckIn, Tasks e Engagement ainda são casca.
  6. +
  7. A plataforma não toca no dinheiro (ADR 0009). Cada edição usa a conta do próprio gateway (Asaas ou Mercado Pago); a receita é calculada dos pedidos, nunca guardada.
  8. +
  9. Toda ação sensível vira trilha de auditoria por evento, com segredo removido e dado pessoal mascarado.
  10. +
+
+
+

Conteúdo

+
    {"".join(f"
  1. {escape(item)}{i + 2}
  2. " for i, item in enumerate(toc))}
+
+
+

Legenda usada nos diagramas

{legend()}
+
Fonte: código da main, backend/CLAUDE.md, docs/produto.md e ADRs 0001–0009.{RETRATO} · página 1
+
""") + +# ========================================================= 2 visão geral +b = [] +b.append(group(10, 30, 230, 500, "Quem usa", "client")) +b.append(box(24, 62, 202, 92, "Painel da organização", ["front-admin · Nuxt 4 SPA", "organizador, financeiro,", "avaliador, check-in"], "client")) +b.append(box(24, 168, 202, 104, "Site da edição", ["front-public · Nuxt 4 SSR", "site, CFP, checkout,", "área do palestrante e", "do participante"], "client")) +b.append(box(24, 286, 202, 78, "Site próprio da comunidade", ["opcional: chama só a", "API pública (CORS por edição)"], "client", dashed=True)) +b.append(box(24, 378, 202, 64, "App Flutter", ["ainda não iniciado"], "todo", dashed=True)) +b.append(box(24, 456, 202, 62, "Gateways (webhooks)", ["Asaas e Mercado Pago"], "external")) + +b.append(box(275, 200, 120, 150, "Caddy", ["proxy reverso", "TLS sob demanda", "para domínio de", "cada edição", "(tls-check)"], "infra", center=True)) +for y in (108, 220, 325, 487): + b.append(arrow([(226, y), (275, 275)], "infra")) + +b.append(group(430, 30, 380, 500, "API · Laravel 13 · PHP 8.4 · /api/v1", "backend", dashed=False)) +b.append(box(445, 62, 350, 86, "Rotas por tipo", ["/editions/{id}/… painel (Sanctum + papel na edição)", "/speaker, /attendee, /checkout/editions/{id}/… publicada", "/public/… site, tema, ingressos (cache + ETag)", "/webhooks/payments/{token} assinado"], "backend", mono=False, size=9.5)) +b.append(box(445, 160, 350, 98, "15 módulos (app-modules/)", ["Identity · Community · Branding · Cfp · Ticketing", "Payments · Notifications · Audit · Sponsors", "Suppliers · Finance", "casca: Program · CheckIn · Tasks · Engagement"], "backend", size=9.5)) +b.append(box(445, 270, 170, 112, "Horizon (fila)", ["e-mail, webhooks,", "importação, clonagem", "de edição, emissão", "de ingressos"], "backend")) +b.append(box(625, 270, 170, 112, "Scheduler", ["cfp:sync-status", "ticketing:expire-orders", "ticketing:reconcile", "payments:retry-webhooks", "…8 rotinas"], "backend", size=9.5)) +b.append(box(445, 394, 350, 122, "Regras que valem para todo módulo", ["Tenancy por edição (BelongsToEdition)", "Mutação só em Action · validação em FormRequest", "Módulo não usa model de outro (arch test)", "Ação sensível → evento Auditable", "Logs JSON com segredo redigido · Sentry opcional"], "backend", size=9.5)) +b.append(arrow([(395, 275), (430, 275)], "infra")) + +b.append(box(845, 40, 245, 70, "MySQL 8", ["um banco · 65 tabelas", "UUID em toda tabela"], "data")) +b.append(box(845, 122, 245, 70, "Redis", ["cache, filas, locks,", "rate limit"], "data")) +b.append(box(845, 204, 245, 70, "Disco privado", ["CSV de importação, anexos,", "comprovantes (URL assinada)"], "data")) +b.append(box(845, 292, 245, 56, "Asaas · Mercado Pago", ["conta de cada edição (ADR 0009)"], "external")) +b.append(box(845, 360, 245, 50, "Resend (e-mail)", ["Mailpit no dev"], "external")) +b.append(box(845, 422, 245, 50, "GitHub OAuth", ["login de palestrante"], "external")) +b.append(box(845, 484, 245, 46, "Sentry", ["opcional, sem DSN fica desligado"], "external")) +for y in (75, 157, 239): + b.append(arrow([(810, y), (845, y)], "data")) +for y in (320, 385, 447, 507): + b.append(arrow([(810, y), (845, y)], "external")) +pages.append(page(2, "Visão geral", "Visão geral do sistema", + "Dois front-ends Nuxt e um site próprio opcional falam com uma API só. O Caddy emite o certificado de cada domínio de edição na hora; a API resolve a edição pelo host.", + svg("\n".join(b), h=545), + ["Painel e site são projetos separados (decisão: front-admin SPA, front-public SSR). O token é Bearer do Sanctum nos dois (ADR 0005).", + "Fila e agendador rodam a mesma imagem do backend (horizon e scheduler no infra/docker-compose.yml)."])) + +# ======================================================= 3 tenancy +b = [] +b.append(group(10, 20, 340, 520, "Global (da plataforma)", "global")) +b.append(box(25, 52, 310, 92, "users", ["conta única: organização, palestrante e", "participante · login por senha ou GitHub", "social_accounts · password_reset_tokens"], "global")) +b.append(box(25, 156, 310, 78, "speaker_profiles", ["perfil público do palestrante, vale em todas", "as edições · dados sensíveis cifrados à parte"], "global")) +b.append(box(25, 246, 310, 64, "communities", ["PHP-PB, PHPCE… dona das edições"], "global")) +b.append(box(25, 322, 310, 90, "suppliers + supplier_contacts", ["global DA COMUNIDADE: reaproveitado entre", "as edições dela, nunca visto por outra", "contato só para quem é de uma edição dele"], "global")) +b.append(box(25, 424, 310, 104, "infra do Laravel", ["personal_access_tokens (um por dispositivo)", "jobs, cache, sessions", "audit_logs: global, mas cada registro", "leva o edition_id"], "infra")) + +b.append(group(380, 20, 710, 520, "Por edição (o tenant) · toda tabela tem edition_id + escopo global", "edition")) +b.append(box(395, 52, 230, 120, "editions", ["community_id · status (máquina", "de estados) · datas, cidade", "site_mode: plataforma ou", "site próprio"], "edition")) +b.append(box(640, 52, 435, 120, "Equipe e configuração", ["edition_members (papel na edição) · edition_invitations", "edition_settings (tema) · edition_domains", "cfp_settings · ticketing_settings · sponsor_settings", "email_templates · finance_categories"], "edition", size=9.8)) +b.append(box(395, 186, 335, 110, "Conteúdo", ["cfp_tracks · cfp_criteria · proposals", "proposal_speakers · review_assignments", "reviews · speaker_confirmations · speaker_logistics"], "edition", size=9.8)) +b.append(box(745, 186, 330, 110, "Vendas", ["ticket_types · ticket_batches · coupons", "orders · order_items · tickets", "payment_accounts · payment_charges", "webhook_events · payment_refunds"], "edition", size=9.8)) +b.append(box(395, 310, 335, 96, "Organização", ["sponsors · sponsorships · sponsor_tiers", "edition_suppliers · supplier_quotes", "expenses"], "edition", size=9.8)) +b.append(box(745, 310, 330, 96, "Comunicação e operação", ["email_deliveries · email_unsubscribes", "ticket_imports · reconciliation_issues", "edition_clones"], "edition", size=9.8)) +b.append(box(395, 420, 680, 108, "Como o isolamento é garantido", ["Model de edição usa o trait BelongsToEdition: liga o EditionScope e preenche edition_id ao criar.", "Sem edição no contexto, a consulta não devolve nada e criar sem edition_id lança LogicException.", "Ler outra edição de propósito exige ->forEdition($id) explícito (clonagem, rotinas agendadas).", "Comunidade A nunca vê edição, fornecedor ou dado da comunidade B."], "edition", size=9.8)) +b.append(arrow([(335, 278), (365, 278), (365, 112), (395, 112)], "global")) +b.append(t(370, 200, "community_id", size=9.5, weight=600, color=K["global"][1])) +pages.append(page(3, "Tenancy", "Tenancy: comunidade, edição e o que é global", + "ADR 0007: uma instalação e um banco. A edição é o tenant; usuários e perfis de palestrante são globais para guardar o histórico entre edições. Toda chave é UUID.", + svg("\n".join(b), h=550), + ["Por que não um banco por comunidade: a mesma pessoa palestra no PHPeste de um ano e compra ingresso no outro, e o perfil dela é um só.", + "Dado de edição que vai para a próxima (\"criar edição a partir da anterior\") é copiado por um EditionCloner de cada módulo, nunca dado de pessoa."])) + +# ============================================ 4 requisição encontra a edição +b = [] +steps = [ + ("1 · Rota", ["Route::apiV1Edition('ticketing')", "/api/v1/editions/{edition}/…"], "backend"), + ("2 · auth:sanctum", ["token Bearer válido", "(um por dispositivo)"], "backend"), + ("3 · Papel na edição", ["edition_members tem a", "pessoa? senão 403"], "edition"), + ("4 · CurrentEdition", ["liga a edição no contexto", "só durante a requisição"], "edition"), + ("5 · Gate da permissão", ["Gate::authorize(", "'orders.refund')"], "backend"), + ("6 · FormRequest → Action", ["valida, depois a Action", "muda o Model"], "backend"), +] +for i, (title, lines, kind) in enumerate(steps): + x = 10 + i * 182 + b.append(box(x, 30, 168, 82, title, lines, kind)) + if i < len(steps) - 1: + b.append(arrow([(x + 168, 71), (x + 182, 71)], "backend")) +b.append(box(10, 140, 530, 140, "Rotas de quem não é da equipe", ["Route::apiV1PublishedEdition('speaker', 'proposals', ['auth:sanctum'])", "→ /api/v1/speaker/editions/{edition}/proposals", "só aceita edição publicada (rascunho = 404) e liga a edição no contexto", "sem exigir papel. Usado por palestrante, participante e checkout.", "A posse do dado é conferida na Action (a proposta é dela?)."], "edition", size=9.8)) +b.append(box(560, 140, 530, 140, "Rotas públicas e de máquina", ["/api/v1/public/resolve?host=… site descobre a edição pelo domínio", "/api/v1/public/editions/{id}/theme tema publicado com ETag", "/api/v1/webhooks/payments/{token} assinatura do gateway", "/api/v1/sponsors/attachments/{id}/download URL assinada", "CORS: só a origem do site próprio da edição, só em /public/*"], "infra", size=9.8)) +b.append(box(10, 305, 530, 120, "Job e listener", ["recebem edition_id explícito no construtor e rodam dentro de", "resolve(CurrentEdition::class)->run($editionId, fn () => …)", "nunca herdam a edição de quem disparou: a fila roda depois,", "em outro processo, e a edição do contexto já não existe."], "backend", size=9.8)) +b.append(box(560, 305, 530, 120, "Evento de domínio", ["carrega ids e enums, nunca Model de outro módulo", "ex.: EditionStatusChanged(editionId, from, to)", "ShouldDispatchAfterCommit: só sai se a transação gravou", "evento Auditable vira registro em audit_logs"], "backend", size=9.8)) +b.append(box(10, 450, 1080, 80, "Front-public: a edição vem do host", ["O site chama /public/resolve com o host da requisição, recebe edition_id e o domínio principal e redireciona se for preciso (ADR 0008).", "O host é normalizado (minúsculas, sem porta, IDN em punycode) e nunca é usado para montar URL sem passar pela tabela edition_domains."], "client", size=9.8)) +pages.append(page(4, "Tenancy na prática", "Como uma requisição encontra a edição", + "Toda rota do painel passa pela mesma esteira; o módulo só escreve a regra de negócio. A edição entra no contexto e sai no fim, e o escopo global faz o resto.", + svg("\n".join(b), h=540))) + +# ===================================================== 5 ciclo de vida +b = [] +states = [("Rascunho", "draft", 30), ("CFP aberto", "cfp_open", 245), ("Vendas abertas", "sales_open", 460), ("Em andamento", "ongoing", 675), ("Encerrada", "closed", 890)] +eff = { + "draft": ["preparação, nada público"], + "cfp_open": ["+ site e domínios públicos", "+ propostas na janela", "+ tema publicado vale", "! slug da URL travado"], + "sales_open": ["+ venda de ingressos", "+ CFP segue a janela", "! exige gateway pronto", " se houver lote pago"], + "ongoing": ["+ check-in", "+ presença de palestrante", "! não volta a vender"], + "closed": ["+ relatórios finais", "! só consulta", "! não reabre"], +} +for label, key, x in states: + b.append(box(x, 50, 180, 150, label, eff[key], "edition", size=9.8)) +for a, c in ((30, 245), (245, 460), (460, 675), (675, 890)): + b.append(arrow([(a + 180, 125), (c, 125)], "edition")) +b.append(arrow([(120, 200), (120, 230), (550, 230), (550, 200)], "edition", label="rascunho pode ir direto para vendas", at=1, dy=14)) +b.append(box(30, 270, 340, 130, "Quem decide a transição", ["A organização muda o status no painel.", "Cada módulo pode barrar a mudança com um", "EditionTransitionGuard (ex.: SalesReadinessGuard", "do Ticketing: lote pago sem conta de gateway", "pronta = não abre vendas)."], "backend", size=9.8)) +b.append(box(385, 270, 340, 130, "Quem reage", ["EditionStatusChanged (auditado) dispara:", "Cfp: CfpOpened / CfpClosed, derivados da janela", " e do status (cfp:sync-status a cada minuto)", "Branding: tema publicado passa a valer", "Ticketing: rotação de lotes e expiração"], "backend", size=9.8)) +b.append(box(740, 270, 330, 130, "Criar a partir da anterior", ["Job CloneEdition: nova edição em rascunho,", "sem datas, e cada EditionCloner escolhido", "copia numa transação só: tema, domínios,", "equipe, CFP, e-mails, ingressos, cotas,", "fornecedores contratados, orçamento."], "backend", size=9.8)) +b.append(box(30, 420, 1040, 110, "Visão geral da edição (um endpoint, vários módulos)", ["GET /editions/{id}/overview junta o que cada módulo devolve no seu EditionOverviewContributor: indicadores (ingressos, receita, propostas,", "palestrantes, patrocínio, fornecedores), pendências com caminho e filtro (propostas sem revisor, divergência na conciliação, entregas e despesas", "vencidas) e marcos. O Community filtra cada pendência pela permissão de quem vê: o voluntário não vê pendência de finanças."], "edition", size=9.8)) +pages.append(page(5, "Edição", "Ciclo de vida da edição", + "EditionStatus é uma máquina de estados com o que cada etapa libera e bloqueia (effects()). Só anda para a frente; o painel mostra a etapa atual e a próxima.", + svg("\n".join(b), h=540))) + +# ===================================================== 6 os 15 módulos +mods = [ + ("Identity", "contas, login (senha e GitHub), sessões por dispositivo, perfil e perfil de palestrante", 22, "backend"), + ("Community", "comunidades, edições, estados, equipe, convites, tenancy, Visão geral, clonagem", 26, "backend"), + ("Branding", "tema por edição (rascunho/publicado), presets, contraste AA, logos, domínios e TLS", 17, "backend"), + ("Cfp", "chamada, trilhas, critérios, propostas, avaliação cega, decisão, cota do Nordeste, confirmação", 52, "backend"), + ("Ticketing", "tipos, lotes, cupons, pedidos, estoque atômico, ingressos com QR, transferência, importação, conciliação", 50, "backend"), + ("Payments", "contas de gateway por edição, drivers Asaas e Mercado Pago, cobranças, webhooks, reembolsos", 8, "backend"), + ("Notifications", "e-mail transacional por edição com modelos editáveis, descadastro, Resend", 9, "backend"), + ("Audit", "trilha append-only das ações sensíveis, com redação de segredos", 1, "backend"), + ("Sponsors", "cotas, funil, vagas, pagamentos, entregas, anexos por URL assinada", 28, "backend"), + ("Suppliers", "cadastro da comunidade, orçamentos, contratação, anexos, reaproveitamento", 19, "backend"), + ("Finance", "despesas, orçamento por categoria, receita calculada, saldo, planilha", 14, "backend"), + ("Program", "salas, sessões e grade (B35–B37)", 0, "todo"), + ("CheckIn", "leitura de QR, entrada, modo offline (B38–B39)", 0, "todo"), + ("Tasks", "kanban da organização (B34)", 0, "todo"), + ("Engagement", "feedback, certificados, sorteio (B42)", 0, "todo"), +] +b = [] +for i, (name, desc, routes, kind) in enumerate(mods): + col, row = i % 3, i // 3 + x, y = 10 + col * 365, 20 + row * 104 + words, lines, cur = desc.split(" "), [], "" + for w in words: + if len(cur) + len(w) + 1 > 48: + lines.append(cur) + cur = w + else: + cur = (cur + " " + w).strip() + lines.append(cur) + b.append(box(x, y, 350, 94, name, lines[:3], kind, dashed=kind == "todo", badge=(f"{routes} rotas", "backend") if routes else ("casca", "todo"), size=9.8)) +pages.append(page(6, "Backend", "Os 15 módulos do backend", + "Cada módulo é um pacote Composer real em backend/app-modules/<nome> (ADR 0002), com namespace PHPeste\\<Nome>: Models, Actions, Contracts, Events, Http, Jobs. 247 rotas na API.", + svg("\n".join(b), h=545))) + +# ================================================= 7 como conversam +b = [] +b.append(box(430, 20, 240, 96, "Community", ["EditionMemberships", "EditionDirectory", "pontos de extensão (tags) ↓"], "backend", center=True)) +ext = [("EditionOverviewContributor", "números da Visão geral"), ("EditionCloner", "copiar para a próxima"), ("EditionTransitionGuard", "barrar mudança de status"), ("EditionParticipation", "quem participa (Identity)")] +for i, (name, what) in enumerate(ext): + x = 20 + i * 270 + b.append(box(x, 150, 255, 52, name, [what], "edition", mono=False, size=9.5, title_size=11)) + b.append(arrow([(550, 116), (x + 127, 150)], "edition", dashed=True)) +pairs = [ + (20, 240, "Cfp", ["→ UserAccounts, SpeakerProfiles (Identity)", "→ EditionMailer (Notifications)", "→ EditionSites (Branding)", "ReviewLedger ← quem conta avaliações"]), + (390, 240, "Ticketing", ["→ PaymentProcessor, PaymentLedger", "→ PaymentAccounts (Payments)", "AccountUsage, TicketVerifier,", "TicketRevenue ← Payments, CheckIn, Finance"]), + (760, 240, "Payments", ["→ PaymentGateway (driver Asaas/MP)", "ChargeStatusChanged → Ticketing", "RefundAccepted → Ticketing", "sem acesso a pedidos: só referência"]), + (20, 395, "Finance", ["→ TicketRevenue (Ticketing)", "→ SponsorRevenue (Sponsors)", "→ PaymentAccounts::all (Payments)", "→ EditionSuppliers (Suppliers)"]), + (390, 395, "Sponsors · Suppliers", ["→ EditionMemberships (responsável)", "→ UserAccounts (nomes)", "Suppliers → EditionDirectory::communityId", "para não vazar entre comunidades"]), + (760, 395, "Audit · Notifications", ["Auditable: qualquer evento vira registro", "pelo listener genérico RecordAuditableEvent", "EditionMailer::send(...): todo e-mail", "passa por aqui, com tema da edição"]), +] +for x, y, title, lines in pairs: + b.append(box(x, y, 340, 130, title, lines, "backend", size=9.8)) +pages.append(page(7, "Backend", "Como os módulos conversam", + "Módulo nunca usa model de outro: ou chama um contrato (interface em Contracts/, ligada no service provider) ou escuta um evento. 24 contratos hoje. O arch test barra dependência de App\\.", + svg("\n".join(b), h=540), + ["Ponto de extensão é registrado com $app->tag([...], Contrato::TAG): o Community não conhece os módulos, só a tag. Módulo novo aparece na Visão geral e na clonagem sem mexer no Community."])) + +# ====================================================== 8 banco +dom = [ + ("Identity", ["users", "social_accounts", "password_reset_tokens", "speaker_profiles", "speaker_private_details"], "global"), + ("Community", ["communities", "editions", "edition_members", "edition_invitations", "edition_clones"], "edition"), + ("Branding", ["edition_settings", "edition_domains"], "edition"), + ("Cfp", ["cfp_settings", "cfp_tracks", "cfp_criteria", "proposals", "proposal_speakers", "review_assignments", "reviews", "review_scores", "speaker_confirmations", "speaker_logistics"], "edition"), + ("Ticketing", ["ticketing_settings", "ticket_types", "ticket_batches", "coupons", "coupon_redemptions", "orders", "order_items", "tickets", "ticket_transfers", "reconciliation_issues", "ticket_imports", "ticket_import_rejections"], "edition"), + ("Payments", ["payment_accounts", "payment_charges", "webhook_events", "payment_refunds"], "edition"), + ("Notifications", ["email_templates", "email_deliveries", "email_unsubscribes"], "edition"), + ("Audit", ["audit_logs"], "infra"), + ("Sponsors", ["sponsor_settings", "sponsor_tiers", "sponsors", "sponsorships", "sponsorship_payments", "sponsor_deliverables", "sponsor_contacts", "sponsor_attachments"], "edition"), + ("Suppliers", ["suppliers ●", "supplier_contacts ●", "edition_suppliers", "supplier_quotes", "supplier_attachments", "supplier_activities"], "edition"), + ("Finance", ["finance_categories", "expenses"], "edition"), + ("Laravel", ["personal_access_tokens", "jobs · job_batches", "failed_jobs", "cache · cache_locks", "sessions"], "infra"), +] +b = [] +cols = [10, 285, 560, 835] +heights = [0, 0, 0, 0] +for name, tables, kind in dom: + col = heights.index(min(heights)) + h = 30 + len(tables) * 14 + 8 + count = {"Laravel": 7}.get(name, len(tables)) + b.append(box(cols[col], 12 + heights[col], 260, h, f"{name} · {count}", tables, kind, mono=True, size=9.5, line_h=14)) + heights[col] += h + 12 +pages.append(page(8, "Dados", "Banco de dados por domínio", + "MySQL 8, 65 tabelas, todas com UUID como chave. Verde é da edição (tem edition_id); azul é global. ● em Suppliers: global da comunidade (community_id).", + svg("\n".join(b), h=max(heights) + 20), + ["Dinheiro sempre em centavos (inteiro). Dado sensível cifrado no banco: CPF de quem compra, credenciais do gateway, acessibilidade, corpo de webhook, linhas de importação. APP_PREVIOUS_KEYS + comandos *:reencrypt-* para trocar a chave.", + "Estoque e cupom nunca são lidos e depois gravados: UPDATE … WHERE allocated + q <= quantity. Testes com 12 processos simultâneos provam que não vende além do lote."])) + +# ====================================================== 9 papéis +perms = [ + ("edition.manage", "Configurar edição e identidade", "●", "", "", "", ""), + ("edition.team", "Gerenciar equipe e convites", "●", "", "", "", ""), + ("cfp.review", "Avaliar propostas", "●", "", "●", "", ""), + ("program.manage", "Gerenciar palestrantes e grade", "●", "", "", "", ""), + ("speakers.private", "Ver acessibilidade e alimentação", "●", "", "", "", ""), + ("orders.view", "Ver pedidos e pagamentos", "●", "●", "", "", ""), + ("orders.refund", "Reembolsar pedidos", "●", "●", "", "", ""), + ("payments.gateway", "Editar chaves do gateway", "●", "", "", "", ""), + ("checkin.scan", "Fazer check-in", "●", "", "", "●", ""), + ("sponsors.manage", "Gerenciar patrocinadores", "●", "", "", "", ""), + ("suppliers.manage", "Gerenciar fornecedores", "●", "", "", "", ""), + ("finance.manage", "Ver e editar finanças", "●", "●", "", "", ""), +] +content = '
' + table(["Permissão", "O que libera", "Organizador", "Financeiro", "Avaliador", "Check-in", "Voluntário"], [(f"{p}", d, *r) for p, d, *r in perms], "cmp perms") + """ +
+

Como funciona

+
    +
  • O papel é por edição (edition_members): a mesma pessoa pode organizar uma edição e só avaliar outra.
  • +
  • Papel e permissão vivem em código (EditionRole::permissions()). Cada permissão vira um Gate com o próprio nome.
  • +
  • Policy e Gate conferem permissão, nunca papel: Gate::authorize('orders.refund').
  • +
  • Outro módulo pergunta pelo contrato: EditionMemberships::can($edition, $user, $permissão).
  • +
  • A edição nunca fica sem organizador: trocar o papel ou remover o último é bloqueado.
  • +
  • O painel lê a tabela em GET /roles e monta o menu por papel.
  • +
  • Palestrante e participante não têm papel: entram pelas rotas de edição publicada.
  • +
""" +pages.append(page(9, "Acesso", "Papéis e permissões", "Cinco papéis por edição e doze permissões. O organizador tem todas.", content)) + +# ============================================= 10 ingresso: compra ao QR +b = [] +lanes = [("Quem compra (site)", "client"), ("Ticketing", "backend"), ("Payments", "backend"), ("Gateway", "external"), ("Fila e rotinas", "infra")] +for i, (label, kind) in enumerate(lanes): + y = 18 + i * 104 + b.append(f'') + b.append(t(20, y + 16, label, size=10.5, weight=700, color=K[kind][1])) +flow = [ + (0, 30, "Escolhe ingressos", ["tipo, lote, cupom,", "participantes"]), + (1, 180, "PlaceOrder", ["reserva estoque e cupom", "numa transação", "Idempotency-Key"]), + (0, 330, "Pix ou cartão", ["sem dado de cartão", "na nossa API"]), + (2, 330, "ChargeService", ["cobrança na conta da", "edição · trava clique duplo"]), + (3, 480, "Asaas / Mercado Pago", ["Pix com QR, cartão", "na fatura ou token"]), + (3, 680, "Webhook assinado", ["→ /webhooks/payments/{t}"]), + (2, 680, "webhook_events", ["caixa de entrada, 2xx", "antes de processar"]), + (4, 880, "ProcessWebhookEvent", ["consulta o gateway:", "não confia no corpo"]), + (1, 860, "Pedido pago", ["TransitionOrder", "IssueTicketsWhenPaid"]), + (0, 860, "E-mail + QR", ["QR assinado (HMAC)", "/ingressos no site"]), +] +for lane, x, title, lines in flow: + b.append(box(x, 18 + lane * 104 + 24, 170 if x < 860 or lane == 4 else 210, 66, title, lines, lanes[lane][1], size=9.5, title_size=11)) +b.append(arrow([(115, 108), (200, 146)], "backend")) +b.append(arrow([(350, 146), (400, 108)], "client")) +b.append(arrow([(420, 108), (420, 250)], "backend")) +b.append(arrow([(500, 284), (565, 354)], "external")) +b.append(arrow([(650, 384), (680, 384)], "external", dashed=True)) +b.append(arrow([(765, 354), (765, 316)], "external", dashed=True)) +b.append(arrow([(850, 283), (930, 458)], "infra", dashed=True, label="job na fila", at=0, dy=-4, label_anchor="start")) +b.append(arrow([(1030, 458), (1030, 212)], "infra", dashed=True, label="sync", at=0, dy=0, label_anchor="start")) +b.append(arrow([(960, 146), (960, 108)], "backend")) +b.append(box(30, 458, 600, 70, "Rotinas que fecham as pontas", ["ticketing:expire-orders (1/min) devolve estoque de reserva vencida · ticketing:rotate-batches abre o próximo lote", "payments:retry-webhooks (1, 5, 15, 60 min) · ticketing:reconcile (diário) grava divergência com o gateway"], "infra", size=9.5, title_size=11)) +pages.append(page(10, "Fluxo", "Ingresso: da compra ao QR", + "O pedido nasce reservando estoque; o pagamento só confirma quando a API consulta o gateway. Evento falso, repetido ou fora de ordem não muda pedido.", + svg("\n".join(b), h=540), + ["Reembolso: PaymentLedger::refund reserva o valor antes de chamar o gateway (dois reembolsos ao mesmo tempo nunca passam do pago). Pedido importado de outra plataforma entra pago, sem cobrança, e não passa por reembolso nem conciliação."])) + +# ================================================== 11 CFP +b = [] +cfp = [ + ("Configuração", ["janela, trilhas com", "vagas, critérios com", "peso, cota Nordeste,", "avaliação anônima"]), + ("Submissão", ["palestrante com perfil", "global · rascunho e", "envio na janela · até", "3 coautores · limite"]), + ("Atribuição", ["manual ou automática", "(menor carga primeiro)", "sem conflito: autoria", "ou mesma empresa"]), + ("Avaliação", ["notas 1–5 por critério", "nota ponderada na hora", "revisor não vê autor", "quando é anônima"]), + ("Decisão", ["ranking por trilha", "respeitando vagas · simula", "cobertura por UF e % do", "Nordeste antes de gravar"]), + ("Confirmação", ["e-mail com prazo", "lembrete 48 h antes", "recusa libera vaga e", "sugere lista de espera"]), +] +for i, (title, lines) in enumerate(cfp): + x = 10 + i * 182 + b.append(box(x, 30, 168, 120, title, lines, "edition", size=9.6)) + if i < len(cfp) - 1: + b.append(arrow([(x + 168, 90), (x + 182, 90)], "edition")) +b.append(box(10, 180, 350, 130, "Status do CFP é derivado, nunca editado", ["CfpStatus vem da janela + status da edição.", "cfp:sync-status (1/min) e o listener de", "EditionStatusChanged disparam CfpOpened e", "CfpClosed uma vez cada."], "backend", size=9.8)) +b.append(box(375, 180, 350, 130, "Convite direto", ["organização convida pelo e-mail: cria a conta", "sem senha se precisar, proposta já aprovada", "(origin = invited), fora da avaliação mas", "ocupando vaga da trilha."], "backend", size=9.8)) +b.append(box(740, 180, 350, 130, "Depois do aceite", ["logística por palestrante (viagem, hospedagem)", "quadro de palestrantes com os 9 estados do", "Nordeste · acessibilidade e alimentação só", "com speakers.private · presença no evento"], "backend", size=9.8)) +b.append(box(10, 335, 1080, 90, "Próximo passo: grade (Program, B35–B37)", ["Propostas confirmadas viram sessões em salas e horários, com validação de conflito; a programação sai pela API pública com cache, e quem vai ao evento", "monta a agenda pessoal. É o que falta para o Marco 3."], "todo", dashed=True, size=9.8)) +b.append(box(10, 445, 1080, 85, "Telas prontas no painel", ["Configurar CFP (A10) · Avaliar propostas com teclado (A11) · Palestrantes: lista, cobertura e detalhe (A12) · no site público: formulário de", "proposta e área do palestrante com entrar pelo GitHub (P03, P11)."], "client", size=9.8)) +pages.append(page(11, "Fluxo", "CFP: da proposta à grade", + "A chamada de trabalhos é o coração do Marco 1. O estatuto do PHPeste pede pelo menos metade de palestrantes do Nordeste e um de cada estado; a decisão mostra isso antes de gravar.", + svg("\n".join(b), h=540))) + +# ================================================== 12 dinheiro +b = [] +b.append(box(10, 30, 330, 170, "Sponsors", ["cotas: valor, vagas, contrapartidas", "funil: prospecção → negociando →", "fechado → pago · perdido com motivo", "fechar acima das vagas exige confirmação", "pagamento registrado à mão; cobrir o valor", "passa para pago sozinho", "+ contrapartida vira entrega com prazo"], "backend", size=9.6)) +b.append(box(385, 30, 330, 170, "Suppliers", ["cadastro global DA COMUNIDADE", "na edição: a contatar → em orçamento →", "contratado · recusado com motivo", "orçado = menor orçamento válido", "contato só para quem é de uma edição", "em que ele aparece", "+ reaproveitar de edição anterior"], "backend", size=9.6)) +b.append(box(760, 30, 330, 170, "Ticketing", ["pedidos pagos e reembolsados com valor", "taxa real (conciliação) ou estimada", "pelo percentual da edição", "por conta de recebimento", "(CPF ou CNPJ, inclusive conta trocada)", "pedido gratuito e importado ficam fora"], "backend", size=9.6)) +b.append(box(300, 270, 500, 180, "Finance: calculado na hora, nunca guardado", ["receita de ingressos = pagos − reembolsos − taxas", "receita total = ingressos líquido + patrocínio recebido", "saldo = receita − despesas pagas", "previsão = saldo + patrocínio a receber − despesas a pagar", "orçamento por categoria × comprometido × pago", "despesas com fornecedor e comprovante por URL assinada", "planilha XLSX (4 abas) e CSV"], "edition", size=9.8)) +b.append(arrow([(175, 200), (400, 270)], "backend", label="SponsorRevenue", at=0, dy=-2)) +b.append(arrow([(550, 200), (550, 270)], "backend", label="EditionSuppliers", at=0, dy=4, label_anchor="start")) +b.append(arrow([(925, 200), (700, 270)], "backend", label="TicketRevenue", at=0, dy=-2)) +b.append(box(10, 470, 1080, 60, "ADR 0009: a plataforma não recebe nem repassa dinheiro", ["Cada edição cadastra a conta do próprio gateway; a API valida as chaves e um webhook assinado antes de abrir vendas. Credenciais cifradas; a API só mostra os 4 últimos caracteres."], "alert", size=9.8)) +pages.append(page(12, "Fluxo", "Dinheiro: patrocínio, fornecedores e finanças", + "Patrocínio, fornecedores e ingressos expõem os números por contratos; o Finance só soma. O teste de propriedade confere, em 25 rodadas aleatórias, que a receita bate com os pedidos pagos menos reembolsos.", + svg("\n".join(b), h=540))) + +# ================================================== 13 fila, rotina, email, auditoria +sched = [ + ("* * * * *", "cfp:sync-status", "abre e fecha o CFP pela janela"), + ("0 * * * *", "cfp:confirmation-deadlines", "lembra 48 h antes e marca sem resposta"), + ("* * * * *", "ticketing:expire-orders", "expira reserva vencida e devolve estoque"), + ("* * * * *", "ticketing:rotate-batches", "encerra lote esgotado e abre o próximo"), + ("*/5 * * * *", "ticketing:resume-imports", "retoma importação parada"), + ("04:00 BRT", "ticketing:reconcile", "confere pedidos com o gateway"), + ("* * * * *", "payments:retry-webhooks", "reenfileira webhook com erro (1, 5, 15, 60 min)"), + ("03:30", "audit:prune", "apaga trilha além de AUDIT_RETENTION_DAYS"), +] +content = '
' + table(["Quando", "Comando", "Para quê"], [(f"{a}", f"{c}", d) for a, c, d in sched], "cmp sched") + """ +
+

Fila (Redis + Horizon)

+
    +
  • Job recebe edition_id explícito e roda em CurrentEdition::run.
  • +
  • afterCommit(): o job só entra na fila se a transação gravou.
  • +
  • Importação grande: um lote de linhas por job, posição em bytes gravada com o lote, retoma do ponto exato.
  • +
+

E-mail (Notifications)

+
    +
  • Todo e-mail sai por EditionMailer::send: registra em email_deliveries e enfileira com 5 tentativas.
  • +
  • Modelo editável por edição, variáveis {nome} sem Blade, HTML escapado, layout com o tema publicado.
  • +
  • Não transacional leva descadastro com link assinado e List-Unsubscribe.
  • +
+

Auditoria

+
    +
  • Evento que implementa Auditable vira linha em audit_logs pelo listener genérico. 21 eventos hoje.
  • +
  • Segredo removido, dado pessoal mascarado; o model recusa update e delete.
  • +
""" +pages.append(page(13, "Operação", "Fila, rotinas agendadas, e-mail e auditoria", "O que roda sem ninguém clicar. Todas as rotinas usam withoutOverlapping() e são idempotentes: rodar duas vezes não muda o resultado.", content)) + +# ================================================== 14 segurança +sec = [ + ("Autenticação", "Sanctum Bearer, um token por dispositivo com expiração (SANCTUM_EXPIRATION_MINUTES); revogar é imediato. Senha mínima de 10 e checagem de vazamento."), + ("Isolamento", "Escopo global por edição; outra comunidade recebe 404; arch test impede módulo de depender de App\\ e controller de usar $request->all()."), + ("Rate limit", "Limiters nomeados: login, password-reset, checkout, webhooks, configuráveis por .env."), + ("Headers e CORS", "CSP, HSTS, nosniff, Referrer-Policy, Permissions-Policy. CORS por ambiente e, em /public/*, só a origem do site próprio da edição."), + ("Dados sensíveis", "Cifrados no banco (CPF, credenciais, acessibilidade, webhooks). Logs JSON com password, token, secret e cartão redigidos automaticamente."), + ("Arquivos", "Disco privado; download só por URL assinada que expira (10 min), sempre como anexo, com nosniff e CSP sandbox. SVG sanitizado."), + ("Pagamento", "Sem dado de cartão na API; webhook com assinatura do driver e reconsulta ao gateway; idempotência no banco (unique(edition_id, idempotency_key))."), + ("Segredos", "ADR 0006: nada de segredo no repositório; APP_PREVIOUS_KEYS para trocar a chave sem perder o que já foi cifrado."), + ("LGPD", "Encarregado e política por edição, anonimização após o evento (B43 em aberto). Decisão em aberto: comunidade controladora, PHPeste operador."), +] +pages.append(page(14, "Segurança", "Segurança", "As travas que valem para todo módulo. A maioria é verificada por teste.", table(["Tema", "Como está"], sec, "cmp sec"))) + +# ================================================== 15 dev, CI, deploy +b = [] +b.append(group(10, 20, 520, 270, "Desenvolvimento (infra/docker-compose.yml)", "infra")) +b.append(box(25, 52, 160, 64, "backend", ["Sail PHP 8.4", "porta 8000"], "backend")) +b.append(box(195, 52, 160, 64, "horizon", ["mesma imagem"], "backend")) +b.append(box(365, 52, 150, 64, "scheduler", ["mesma imagem"], "backend")) +b.append(box(25, 128, 160, 64, "MySQL 8", ["volume local"], "data")) +b.append(box(195, 128, 160, 64, "Redis", ["cache e fila"], "data")) +b.append(box(365, 128, 150, 64, "Mailpit", ["e-mail em :8025"], "external")) +b.append(box(25, 204, 490, 74, "infra/dev.sh up | down | reset | shell | logs", ["sobe os seis serviços (cria infra/.env na primeira vez)", "front-admin e front-public rodam com npm run dev"], "infra")) +b.append(group(560, 20, 530, 270, "CI (GitHub Actions)", "infra")) +b.append(box(575, 52, 245, 105, "backend-ci", ["Pint (estilo)", "Larastan nível 8", "Pest (~1040 testes)", "composer audit"], "infra")) +b.append(box(830, 52, 245, 105, "front-admin-ci · front-public-ci", ["lint, typecheck, testes", "unitários e build; e2e na CI", "do front-public; o do painel", "(82 testes) roda local"], "infra", title_size=11)) +b.append(box(575, 170, 500, 108, "composer check (local, antes de abrir PR)", ["pint + phpstan + rector --dry-run + pest", "Teste de concorrência com processos PHP reais (estoque, cupom,", "reembolso, idempotência), SQLite com transaction_mode IMMEDIATE"], "infra", size=9.8)) +b.append(group(10, 310, 1080, 220, "Produção (planejado, B45)", "todo")) +b.append(box(25, 342, 250, 110, "Caddy", ["TLS automático do domínio", "da plataforma e on-demand", "para domínios de edição", "(pergunta à API: tls-check)"], "infra")) +b.append(box(290, 342, 250, 110, "API + Horizon + scheduler", ["mesma imagem", "variáveis por ambiente", "Sentry com DSN"], "backend")) +b.append(box(555, 342, 250, 110, "MySQL + Redis", ["backup e restauração", "ainda a definir"], "data", dashed=True)) +b.append(box(820, 342, 255, 110, "Resend + gateways", ["RESEND_API_KEY", "contas de produção", "de cada edição"], "external")) +b.append(box(25, 464, 1050, 54, "Em aberto para o evento", ["teste de carga, backups, runbook do dia do evento (B45) · dados de demonstração e documentação publicada (B46)"], "todo", dashed=True, size=9.8)) +pages.append(page(15, "Operação", "Desenvolvimento, CI e deploy", + "Ambiente local em Docker Compose (ADR 0003); a CI roda o mesmo composer check. O deploy de produção ainda está no plano do Marco 4.", + svg("\n".join(b), h=540))) + +# ================================================== 16 telas design +pages.append(page(16, "Telas", "Telas: o design do painel", + "Referências de design do painel (tema Sertão, cores, tipografia Lexend) que o front-admin segue; o protótipo completo está no link de design do README. O tema é por edição: a comunidade escolhe um preset (Sertão, Maré, Brasa) e ajusta as cores com checagem de contraste AA.", + """
+
Design da Visão geral do painel
Design: Visão geral da edição
+
Tokens do tema Sertão
Design: tokens do tema Sertão
+
""")) + +# ================================================== 17 telas painel +pages.append(page(17, "Telas", "Telas: o painel em uso", + "Capturas do front-admin rodando, com a API simulada (front-admin/e2e/capturas-arquitetura.spec.ts). O menu muda pelo papel: o avaliador só vê Visão geral e Avaliar propostas.", + """
+
Visão geral
Organizador: Visão geral, com etapa, indicadores, pendências e meta do Nordeste
+
Avaliação de propostas
Avaliador: fila de propostas com nota por critério, sem ver o autor
+
Login
Entrar com e-mail e senha ou GitHub
+
""")) + +# ================================================== 18 status +status = [ + ("Marco 0 · Fundação", "Concluído", "esqueleto Laravel 13, módulos, Docker, convenções de API, segurança base, painel e componentes"), + ("Marco 1 · Núcleo e CFP", "Backend concluído", "Identity, Community, Branding, Notifications, CFP inteiro, Audit; telas A05–A12, A24, A25; site P01, P03"), + ("Marco 2 · Ingressos", "Backend quase concluído", "ingressos, cupons, pedidos, Asaas, Mercado Pago, webhooks, reembolso, conciliação, QR, importação, patrocínio, fornecedores, finanças; falta B34 (tarefas) e as telas A14–A23, P04–P06"), + ("Marco 3 · Evento pronto", "A fazer", "grade e programação (B35–B37), check-in com modo offline (B38–B39), push (B40), API pública e checkout embutível (B41), site da edição (P02, P07–P09)"), + ("Marco 4 · Operação", "A fazer", "engajamento (B42), LGPD (B43), relatórios (B44), carga, backups e runbook (B45), dados de demonstração (B46), acessibilidade e e2e (A26, A27)"), +] +pages.append(page(18, "Roadmap", "Onde estamos e o que falta", + "Os milestones do GitHub e o board PHPeste Platform são a fonte da verdade do andamento; esta página é o retrato no dia da geração.", + table(["Marco", "Situação", "O que tem"], [(f"{a}", b_, c) for a, b_, c in status], "cmp roadmap"))) + +# =================================================================== HTML +CSS = """ +@page { size: A4 landscape; margin: 0; } +* { box-sizing: border-box; } +html, body { margin: 0; padding: 0; background: #fff; } +body { font-family: 'Lexend', 'Inter', -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif; color: #2B1408; -webkit-print-color-adjust: exact; print-color-adjust: exact; } +code { font-family: 'JetBrains Mono', 'SF Mono', Menlo, monospace; font-size: .88em; background: #F7EFE3; padding: 0 3px; border-radius: 3px; } +.page { width: 297mm; height: 210mm; padding: 10mm 13mm 8mm; display: flex; flex-direction: column; page-break-after: always; break-after: page; position: relative; overflow: hidden; } +.page::before { content: ""; position: absolute; left: 0; right: 0; top: 0; height: 2.2mm; background: repeating-linear-gradient(90deg, #E8B23A 0 6mm, #B4441B 6mm 12mm); } +.page:last-child { page-break-after: auto; break-after: auto; } +header { margin-bottom: 3mm; } +.kicker { font-size: 9.5pt; font-weight: 700; letter-spacing: .06em; text-transform: uppercase; color: #B4441B; } +h1 { font-size: 19pt; margin: 1.5mm 0 1mm; letter-spacing: -.01em; color: #3A1708; } +.sub { margin: 0; font-size: 10.3pt; color: #5B4636; max-width: 262mm; line-height: 1.4; } +.content { flex: 1; min-height: 0; display: flex; align-items: center; justify-content: center; } +.content svg { width: 100%; height: 100%; max-height: 100%; } +.notes { margin: 2mm 0 0; padding: 0 0 0 4.5mm; font-size: 8.8pt; color: #5B4636; line-height: 1.38; } +.notes li { margin: .4mm 0; } +footer { display: flex; justify-content: space-between; font-size: 8pt; color: #A08B78; border-top: 1px solid #EADBC8; padding-top: 2mm; margin-top: 2.5mm; } +.cover { background: linear-gradient(135deg, #FBF4E6 0%, #FFFFFF 60%); } +.cover-top { margin-top: 4mm; } +.cover-title { font-size: 28pt; line-height: 1.12; margin: 3mm 0 3mm; } +.cover-sub { font-size: 11pt; color: #5B4636; max-width: 240mm; line-height: 1.45; margin: 0; } +.cover-grid { display: grid; grid-template-columns: 1.4fr 1fr; gap: 6mm; margin-top: 5mm; } +.cover-card { border: 1px solid #EADBC8; border-radius: 12px; padding: 4mm 5mm; background: #fff; } +.cover-card h3, .cover-legend h3 { margin: 0 0 2mm; font-size: 11pt; } +.cover-card ol { margin: 0; padding-left: 5mm; font-size: 9.3pt; line-height: 1.4; } +.cover-card ol li { margin: .8mm 0; } +.toc { font-size: 8.8pt !important; } +.toc li { margin: .2mm 0 !important; } +.toc li span:first-child { display: inline-block; width: 85%; } +.toc li span:last-child { float: right; color: #A08B78; font-weight: 600; } +.cover-legend { margin-top: 4mm; } +.cover-legend svg { width: 100%; height: auto; max-height: 26mm; } +.cover footer { margin-top: auto; } +table.cmp { width: 100%; border-collapse: collapse; font-size: 9.4pt; align-self: flex-start; } +table.cmp th, table.cmp td { text-align: left; padding: 1.6mm 2.4mm; border-bottom: 1px solid #EADBC8; vertical-align: top; line-height: 1.35; } +table.cmp th { background: #3A1708; color: #FBF4E6; font-weight: 700; font-size: 9pt; } +table.cmp tr:nth-child(even) td { background: #FBF6EE; } +table.perms { font-size: 8.6pt; } +table.perms th, table.perms td { padding: 1.1mm 2mm; } +table.perms td:nth-child(n+3), table.perms th:nth-child(n+3) { text-align: center; width: 17mm; } +table.perms td:nth-child(n+3) { color: #6B2A14; font-weight: 700; } +table.perms td:nth-child(2) { width: 58mm; } +table.sec td:first-child, table.roadmap td:first-child { width: 42mm; font-weight: 700; } +table.roadmap td:nth-child(2) { width: 42mm; color: #6B2A14; font-weight: 600; } +.two { display: grid; grid-template-columns: 1.85fr 1fr; gap: 7mm; width: 100%; align-self: flex-start; } +.side { font-size: 9.2pt; line-height: 1.4; } +.side h3 { font-size: 10.5pt; margin: 0 0 1mm; color: #6B2A14; } +.side ul { margin: 0 0 3mm; padding-left: 4.5mm; } +.side li { margin: .6mm 0; } +.shots { display: grid; gap: 5mm; width: 100%; height: 100%; align-items: start; } +.two-shots { grid-template-columns: 1fr 1fr; } +.mosaic { grid-template-columns: 1.05fr 1fr; grid-template-rows: 1fr 1fr; } +.mosaic .big { grid-row: span 2; } +.mosaic figure:not(.big) img { max-height: 64mm; } +figure { margin: 0; display: flex; flex-direction: column; gap: 1.5mm; min-height: 0; } +figure img { width: 100%; max-height: 145mm; object-fit: contain; object-position: top; border: 1px solid #EADBC8; border-radius: 8px; background: #FBF4E6; } +figcaption { font-size: 8.8pt; color: #5B4636; } +""" + +OUT.write_text(f""" + +Arquitetura PHPeste Platform + + +{"".join(pages)} + +""", encoding="utf-8") +print(f"ok: {OUT} ({len(pages)} páginas)") diff --git a/docs/arquitetura/fonte/imprimir.mjs b/docs/arquitetura/fonte/imprimir.mjs new file mode 100644 index 0000000..dfcb405 --- /dev/null +++ b/docs/arquitetura/fonte/imprimir.mjs @@ -0,0 +1,33 @@ +// Converte arquitetura.html em ../PHPeste_Arquitetura.pdf usando o Chromium +// do Playwright que já vem com o front-admin/. +// +// Uso (na raiz do repo): +// python3 docs/arquitetura/fonte/gerar.py && node docs/arquitetura/fonte/imprimir.mjs +// Com uma pasta no fim, salva também um PNG de cada página: +// node docs/arquitetura/fonte/imprimir.mjs /tmp/paginas +import { createRequire } from 'node:module' +import { dirname, join } from 'node:path' +import { fileURLToPath, pathToFileURL } from 'node:url' + +const here = dirname(fileURLToPath(import.meta.url)) +const require = createRequire(join(here, '../../../front-admin/package.json')) +const { chromium } = require('playwright-core') + +const html = join(here, 'arquitetura.html') +const pdf = join(here, '..', 'PHPeste_Arquitetura.pdf') +const shot = process.argv[2] + +const browser = await chromium.launch() +const page = await browser.newPage({ viewport: { width: 1123, height: 794 } }) +await page.goto(pathToFileURL(html).href, { waitUntil: 'networkidle' }) +await page.pdf({ path: pdf, format: 'A4', landscape: true, printBackground: true, preferCSSPageSize: true }) + +if (shot) { + const pages = await page.locator('section.page').all() + for (const [i, el] of pages.entries()) { + await el.screenshot({ path: join(shot, `pagina-${String(i + 1).padStart(2, '0')}.png`) }) + } +} + +await browser.close() +console.log(`ok: ${pdf}`) diff --git a/docs/arquitetura/telas/painel-avaliacao-cfp.png b/docs/arquitetura/telas/painel-avaliacao-cfp.png new file mode 100644 index 0000000..49cc833 Binary files /dev/null and b/docs/arquitetura/telas/painel-avaliacao-cfp.png differ diff --git a/docs/arquitetura/telas/painel-componentes.png b/docs/arquitetura/telas/painel-componentes.png new file mode 100644 index 0000000..e76360f Binary files /dev/null and b/docs/arquitetura/telas/painel-componentes.png differ diff --git a/docs/arquitetura/telas/painel-login.png b/docs/arquitetura/telas/painel-login.png new file mode 100644 index 0000000..6a3957a Binary files /dev/null and b/docs/arquitetura/telas/painel-login.png differ diff --git a/docs/arquitetura/telas/painel-visao-geral.png b/docs/arquitetura/telas/painel-visao-geral.png new file mode 100644 index 0000000..d3e276e Binary files /dev/null and b/docs/arquitetura/telas/painel-visao-geral.png differ diff --git a/front-admin/CLAUDE.md b/front-admin/CLAUDE.md index 5915e8c..621fa5c 100644 --- a/front-admin/CLAUDE.md +++ b/front-admin/CLAUDE.md @@ -110,3 +110,7 @@ Tokens oficiais em `../docs/design/tema-sertao-tokens.png`, aplicados em `app/as - No generator/skill scaffolding a new module — creating one is by hand, following `login`'s shape and `docs/ARCHITECTURE.md`. - Cadastro aberto (`register`) não existe por decisão: a entrada no painel é por convite da organização. + +## Documento de arquitetura + +Tela nova que mude o que o painel ou o site mostram, ou mudança de como o front fala com a API (resolução da edição pelo host, autenticação, tema), atualiza `../docs/arquitetura/` no mesmo PR. Ver `../docs/arquitetura/README.md`. Os prints do painel saem de `CAPTURAR_TELAS=1 npx playwright test e2e/capturas-arquitetura.spec.ts`. diff --git a/front-admin/e2e/capturas-arquitetura.spec.ts b/front-admin/e2e/capturas-arquitetura.spec.ts new file mode 100644 index 0000000..93c81ec --- /dev/null +++ b/front-admin/e2e/capturas-arquitetura.spec.ts @@ -0,0 +1,87 @@ +// Gera os prints do painel usados em docs/arquitetura (não é teste de +// comportamento; só roda com CAPTURAR_TELAS=1): +// CAPTURAR_TELAS=1 npx playwright test e2e/capturas-arquitetura.spec.ts +// A API é simulada com page.route, como nos outros testes e2e. +import { fileURLToPath } from 'node:url' +import { expect, test } from '@nuxt/test-utils/playwright' +import type { Page } from '@playwright/test' + +const out = (name: string) => fileURLToPath(new URL(`../../docs/arquitetura/telas/${name}.png`, import.meta.url)) +const session = { user: { id: 'u-me', name: 'Rita Organiza', email: 'rita@php-pb.net', avatarUrl: null }, token: 'e2e-token' } +const edition = (role: string) => ({ + id: 'ed-27', slug: '2027', name: 'PHPeste 2027', community_id: 'c1', community: { id: 'c1', name: 'PHP-PB', slug: 'php-pb' }, + status: 'cfp_open', status_label: 'CFP aberto', starts_on: '2027-10-08', ends_on: '2027-10-09', city: 'João Pessoa', state: 'PB', year: 2027, site_url: null, role, +}) +const overview = { + edition: { id: 'ed-27', name: 'PHPeste 2027', starts_on: '2027-10-08', ends_on: '2027-10-09', city: 'João Pessoa', state: 'PB' }, + stage: { + current: 'cfp_open', + days_until_event: 339, + steps: [ + { status: 'draft', label: 'Rascunho', note: 'Preparação', state: 'done' }, + { status: 'cfp_open', label: 'CFP aberto', note: 'Chamada de trabalhos', state: 'current' }, + { status: 'sales_open', label: 'Vendas abertas', note: 'Venda de ingressos', state: 'next' }, + { status: 'ongoing', label: 'Em andamento', note: 'Evento', state: 'upcoming' }, + { status: 'closed', label: 'Encerrada', note: 'Pós-evento', state: 'upcoming' }, + ], + }, + indicators: { tickets: { sold: 128, available: 400 }, revenue: { gross: 1920000, net: 1850000 }, proposals: { total: 47, reviewed: 31 }, speakers: { confirmed: 6, goal: 24 } }, + sections: { + tickets_per_week: [12, 18, 25, 31, 22, 40, 55, 48], + nordeste: { base: 'confirmed', people: 8, percent: 62, quota: 50, require_quota: true, missing_states: [{ uf: 'AL', name: 'Alagoas' }, { uf: 'SE', name: 'Sergipe' }] }, + }, + pending: [ + { key: 'proposals_without_reviewer', title: '7 propostas sem revisor', tone: 'warn', tag: 'Atenção', action_label: 'Atribuir', action_path: '/cfp/avaliacao?filtro=sem-revisor' }, + { key: 'speakers_no_response', title: '2 palestrantes sem resposta à confirmação', tone: 'warn', tag: 'Atenção', action_label: 'Ver palestrantes', action_path: '/palestrantes?confirmacao=sem-resposta' }, + ], + milestones: [ + { key: 'cfp_closes', title: 'Fechamento do CFP', description: 'Propostas deixam de ser aceitas', date: '2027-04-15' }, + { key: 'cfp_results', title: 'Resultado para palestrantes', description: 'E-mails de aprovação e lista de espera', date: '2027-04-30' }, + ], +} +const criteria = [{ id: 'c-1', name: 'Relevância para a comunidade', description: 'O tema interessa?', weight: 3 }, { id: 'c-2', name: 'Clareza da proposta', description: null, weight: 2 }] +const proposal = (number: number, title: string) => ({ + id: `p-${number}`, number, title, track: { id: 't', name: 'Backend e arquitetura' }, summary: 'Como rodar Laravel Octane em produção sem surpresas: memória, estado entre requisições e deploy sem derrubar ninguém.', audience: 'Quem já usa Laravel em produção.', + format: 'talk', format_label: 'Palestra de 30 min', duration_minutes: 30, level: 'intermediate', level_label: 'Intermediário', language: 'pt_BR', nordeste: true, speakers_hidden: true, +}) + +test.skip(!process.env.CAPTURAR_TELAS, 'Só gera os prints da documentação com CAPTURAR_TELAS=1') +test.use({ viewport: { width: 1440, height: 900 } }) + +async function signedIn(page: Page, role = 'organizador') { + await page.addInitScript((value) => localStorage.setItem('app.auth', JSON.stringify(value)), session) + await page.route('**/api/v1/editions', (route) => route.fulfill({ status: 200, json: { data: [edition(role)] } })) +} + +test('login', async ({ page, goto }) => { + await goto('/login', { waitUntil: 'hydration' }) + await page.screenshot({ path: out('painel-login') }) +}) + +test('visão geral', async ({ page, goto }) => { + await page.setViewportSize({ width: 1440, height: 1150 }) + await signedIn(page) + await page.route('**/api/v1/editions/ed-27/**', (route) => route.request().url().endsWith('/overview') ? route.fulfill({ status: 200, json: { data: overview } }) : route.fulfill({ status: 404, json: {} })) + await goto('/', { waitUntil: 'hydration' }) + await expect(page.getByRole('heading', { name: 'Visão geral', level: 1 })).toBeVisible() + await page.screenshot({ path: out('painel-visao-geral') }) +}) + +test('avaliação de propostas', async ({ page, goto }) => { + await signedIn(page, 'avaliador') + await page.route('**/api/v1/editions/ed-27/overview', (route) => route.abort()) + await page.route('**/api/v1/editions/ed-27/cfp/**', (route) => { + const path = new URL(route.request().url()).pathname.replace('/api/v1/editions/ed-27/cfp', '') + if (path === '/reviews/queue') return route.fulfill({ status: 200, json: { data: [{ ...proposal(1, 'Octane em produção'), my_review_status: 'pending' }, { ...proposal(2, 'Filas e idempotência'), my_review_status: 'pending' }] } }) + if (path.endsWith('/review')) return route.fulfill({ status: 200, json: { data: { proposal: proposal(1, 'Octane em produção'), criteria, review: null } } }) + return route.fulfill({ status: 404, json: {} }) + }) + await goto('/cfp/avaliacao', { waitUntil: 'hydration' }) + await expect(page.getByRole('heading', { name: 'Octane em produção', level: 2 })).toBeVisible() + await page.screenshot({ path: out('painel-avaliacao-cfp') }) +}) + +test('catálogo de componentes', async ({ page, goto }) => { + await goto('/_dev/componentes', { waitUntil: 'hydration' }) + await page.screenshot({ path: out('painel-componentes') }) +}) diff --git a/front-public/CLAUDE.md b/front-public/CLAUDE.md index 6b7901d..f51875a 100644 --- a/front-public/CLAUDE.md +++ b/front-public/CLAUDE.md @@ -49,3 +49,7 @@ Para testar vários hosts no dev: `NUXT_TRUST_FORWARDED_HOST=true npm run dev` e - Tudo que vai para o `` a partir do tema passa pelas validações de `shared/edition` (cor, fonte, URL https); nunca injete valor da API sem validar. - Página nova de conta, palestrante ou checkout entra em `AREA_PREFIXES` (para funcionar no site próprio) e, se depende de sessão, em `routeRules` com `ssr: false`. - Os mesmos padrões do painel valem aqui: services não traduzem resposta, views não chamam service, e mudança de tela se verifica com `npm run test:e2e`. + +## Documento de arquitetura + +Tela nova que mude o que o painel ou o site mostram, ou mudança de como o front fala com a API (resolução da edição pelo host, autenticação, tema), atualiza `../docs/arquitetura/` no mesmo PR. Ver `../docs/arquitetura/README.md`.