diff --git a/backend/CLAUDE.md b/backend/CLAUDE.md index 9d69299..2a6f4d6 100644 --- a/backend/CLAUDE.md +++ b/backend/CLAUDE.md @@ -21,7 +21,7 @@ Com implementação real até agora: - `suppliers`: fornecedores, sob a permissão `suppliers.manage` (só organizador), em `/editions/{id}/suppliers`. O cadastro (`suppliers`, com contatos em `supplier_contacts`) é global **da comunidade**, não da plataforma: toda consulta passa por `Access\SupplierAccess`, que filtra pelo `community_id` da edição (lido do contrato `EditionDirectory::communityId`), então outra comunidade recebe 404. Nome (comparado por `name_key`, sem acento e caixa) e CNPJ/CPF não se repetem na comunidade. O contato e o documento só aparecem para quem é da equipe de alguma edição em que o fornecedor está (`canSeeContacts`); para os outros, vem `contacts: null` e `contacts_visible: false`. Na edição, o vínculo (`edition_suppliers`) tem status `SupplierStatus` (a contatar, em orçamento, contratado, recusado), responsável da equipe e valor contratado. O primeiro orçamento (`supplier_quotes`) passa para "em orçamento"; contratar exige um orçamento (que vira aceito) ou um valor, recusar exige motivo, e a mudança é auditada como `suppliers.status_changed`. O "orçado" de cada fornecedor é o menor orçamento recebido ou aceito. A lista (`GET /suppliers`, sem paginação) devolve os totais de orçado (sem os recusados) e contratado calculados sobre a mesma lista filtrada (`SupplierTotals`), que também vão para a Visão geral (`indicators.suppliers`). Histórico em `supplier_activities`: anotações da equipe com canal e registros automáticos de status, orçamento e anexo. Anexos (`supplier_attachments`: orçamento, contrato, nota fiscal) seguem o mesmo esquema dos patrocinadores: disco privado `SUPPLIERS_ATTACHMENTS_DISK` e download só por URL assinada que expira (`/api/v1/suppliers/attachments/{id}/download`). Reaproveitar fornecedor: `GET /suppliers/directory?q=` busca no cadastro da comunidade e mostra em que edições ele esteve e com que status; `POST /suppliers/directory/{supplier}` traz para esta edição como "a contatar". `SuppliersCloner` leva os contratados para a próxima edição como "a contatar", sem valores nem orçamentos. - `finance`: finanças da edição, sem nota fiscal, sob a permissão `finance.manage` (organizador e financeiro), em `/editions/{id}/finance`. A receita não é guardada: `Reports\FinanceReport` calcula na hora a partir dos contratos `Ticketing\Contracts\TicketRevenue` (pedidos pagos ou reembolsados com valor, por conta de recebimento: vendido, reembolsos, taxa do gateway real em `orders.gateway_fee_cents` ou estimada pelo percentual da edição, e líquido) e `Sponsors\Contracts\SponsorRevenue` (patrocínio recebido e a receber), com o titular de cada conta (CPF ou CNPJ, documento mascarado, inclusive contas trocadas) vindo de `PaymentAccounts::all`. Pedido gratuito e importado ficam de fora. Saldo = receita líquida recebida − despesas pagas; previsão = saldo + patrocínio a receber − despesas a pagar. Despesas (`expenses`) com categoria, fornecedor opcional da edição (contrato `Suppliers\Contracts\EditionSuppliers`), valor, vencimento, status (a pagar, paga, que exige data, ou cancelada) e comprovante no disco privado `FINANCE_RECEIPTS_DISK`, baixado só por URL assinada que expira; criar, mudar e remover são auditados (`finance.expense_*`). Categorias (`finance_categories`) com orçamento: a edição ganha as padrão (`FinanceCategory::DEFAULTS`) na primeira leitura, e o resumo compara orçado, comprometido (a pagar e paga) e pago por categoria. `GET .../export` gera XLSX com as abas Resumo, Receita por conta, Orçamento e Despesas (`Export\XlsxWriter`, sem biblioteca, com `ZipArchive`; valores como número), e `?format=csv` gera só as despesas, com ponto e vírgula e BOM. Texto que começa com `=`, `+`, `-` ou `@` ganha apóstrofo para não virar fórmula. A Visão geral recebe a pendência de despesas vencidas (só para quem tem `finance.manage`), e `FinanceCloner` leva categorias e orçamento para a próxima edição. - `tasks`: quadro kanban da organização, em `/editions/{id}/tasks`. Toda a equipe da edição vê o quadro (`GET /board?filter=mine|overdue`); `tasks.manage` (só organizador) cria, edita, remove e mexe nas colunas, e o responsável move a própria tarefa. Colunas (`task_columns`, as quatro de `TaskColumn::DEFAULTS` nascem na primeira leitura) com `is_done`: tarefa que entra nela ganha `completed_at` e deixa de ficar atrasada; o quadro nunca fica sem coluna de concluídas e só remove coluna vazia. Mover (`MoveTask`): trava as colunas de origem e destino pelo id, em ordem, e renumera as duas de 0 a n−1 na mesma transação; se a tarefa mudou de coluna enquanto isso, tenta de novo. `TaskReorderConcurrencyTest` prova com 12 processos PHP simultâneos que não duplica nem perde posição. Atrasada = prazo antes de hoje e não concluída (pendência na Visão geral). E-mail só para o responsável, se ainda é da equipe e se não desligou `assigned_tasks` (`UserAccounts::wantsNotification`): `task_assigned` ao virar responsável (menos quando a pessoa se atribui) e `task_due_soon` pelo `tasks:due-reminders` (08:00 de Brasília), uma vez por prazo; mudar o prazo libera outro lembrete. Vínculo da tarefa (`link_type`, `link_id`) por ponto de extensão: o módulo dono implementa `Tasks\Contracts\TaskLinkProvider` e registra com `$app->tag([...], TaskLinkProvider::TAG)` (hoje `supplier`, do Suppliers, e `sponsorship`, do Sponsors; a sessão entra com o Program). `TasksCloner` leva colunas e tarefas para a próxima edição como checklist, sem responsável, prazo nem vínculo. -- `notifications`: e-mail transacional por edição. Outro módulo envia pelo contrato `EditionMailer::send(editionId, EmailTemplate, email, nome, variáveis, url)`, que registra o envio em `email_deliveries` e enfileira `SendEmailDelivery` (5 tentativas, backoff 30s → 30min). Os tipos de e-mail ficam em `EmailTemplate` (assunto/corpo padrão, variáveis permitidas, transacional ou não), e a edição só sobrescreve assunto e corpo (`email_templates`). O corpo é texto com `{variavel}`, substituído sem Blade e com todo HTML escapado. O layout usa o tema publicado (Branding). Não transacional leva link assinado e `List-Unsubscribe` (one-click), e quem se descadastra fica em `email_unsubscribes`. Produção usa Resend (`MAIL_MAILER=resend`, `RESEND_API_KEY`) e dev usa o Mailpit. +- `notifications`: e-mail transacional por edição. Outro módulo envia pelo contrato `EditionMailer::send(editionId, EmailTemplate, email, nome, variáveis, url)`, que registra o envio em `email_deliveries` e enfileira `SendEmailDelivery` (5 tentativas, backoff 30s → 30min). Os tipos de e-mail ficam em `EmailTemplate` (assunto/corpo padrão, variáveis permitidas, transacional ou não), e a edição só sobrescreve assunto e corpo (`email_templates`). O corpo é texto com `{variavel}`, substituído sem Blade e com todo HTML escapado. O layout usa o tema publicado (Branding). Não transacional leva link assinado e `List-Unsubscribe` (one-click), e quem se descadastra fica em `email_unsubscribes`. Produção usa Resend (`MAIL_MAILER=resend`, `RESEND_API_KEY`) e dev usa o Mailpit. O transport do Resend grava o id do Resend como Message-ID, e o envio guarda esse id em `provider_message_id`. Webhooks do Resend em `POST /api/v1/webhooks/resend` (`throttle:webhooks`): assinatura Svix verificada com `RESEND_WEBHOOK_SECRET` e janela de 5 minutos (`Webhooks\SvixSignature`, 401 e nada muda se falhar), um registro por `svix-id` em `email_webhook_events` (entrega repetida responde `duplicate: true`) e a edição descoberta pelo envio (`provider_message_id`), nunca pelo que o webhook manda. `email.delivered` marca entregue; bounce permanente e `email.complained` marcam o envio e bloqueiam o endereço na edição (`email_suppressions`, auditado como `notifications.address_suppressed`), inclusive para e-mail transacional e para o que já estava na fila; bounce temporário e `email.delivery_delayed` só registram o motivo em `provider_detail`. A organização vê os bloqueados em `GET /emails/suppressions` e libera em `DELETE /emails/suppressions/{id}` (`notifications.suppression_lifted`); reenviar para endereço bloqueado é recusado. ## Estrutura de cada módulo (`app-modules//src/`) diff --git a/backend/app-modules/notifications/database/migrations/2026_12_03_100000_add_delivery_tracking_and_suppressions.php b/backend/app-modules/notifications/database/migrations/2026_12_03_100000_add_delivery_tracking_and_suppressions.php new file mode 100644 index 0000000..a49ec99 --- /dev/null +++ b/backend/app-modules/notifications/database/migrations/2026_12_03_100000_add_delivery_tracking_and_suppressions.php @@ -0,0 +1,59 @@ +timestamp('delivered_at')->nullable(); + $table->timestamp('bounced_at')->nullable(); + $table->timestamp('complained_at')->nullable(); + $table->string('provider_detail', 500)->nullable(); + + $table->index('provider_message_id'); + }); + + // Endereço que não recebe mais nada da edição (nem transacional) até a + // organização liberar: bounce permanente ou reclamação de spam. + Schema::create('email_suppressions', function (Blueprint $table): void { + $table->uuid('id')->primary(); + $table->foreignUuid('edition_id')->constrained('editions')->cascadeOnDelete(); + $table->string('email'); + $table->string('reason', 16); + $table->string('detail', 500)->nullable(); + $table->uuid('email_delivery_id')->nullable(); + $table->timestamps(); + + $table->unique(['edition_id', 'email']); + }); + + // Caixa de entrada dos webhooks do Resend, um registro por svix-id: + // a mesma entrega repetida não tem efeito duas vezes. + Schema::create('email_webhook_events', function (Blueprint $table): void { + $table->uuid('id')->primary(); + $table->string('svix_id', 100)->unique(); + $table->string('type', 40); + $table->string('provider_message_id', 100)->nullable(); + $table->uuid('edition_id')->nullable()->index(); + $table->string('outcome', 16); + $table->timestamps(); + }); + } + + public function down(): void + { + Schema::dropIfExists('email_webhook_events'); + Schema::dropIfExists('email_suppressions'); + + Schema::table('email_deliveries', function (Blueprint $table): void { + $table->dropIndex(['provider_message_id']); + $table->dropColumn(['delivered_at', 'bounced_at', 'complained_at', 'provider_detail']); + }); + } +}; diff --git a/backend/app-modules/notifications/routes/notifications-routes.php b/backend/app-modules/notifications/routes/notifications-routes.php index 34907a5..e533b0f 100644 --- a/backend/app-modules/notifications/routes/notifications-routes.php +++ b/backend/app-modules/notifications/routes/notifications-routes.php @@ -5,7 +5,9 @@ use Illuminate\Support\Facades\Route; use PHPeste\Notifications\Enums\EmailTemplate; use PHPeste\Notifications\Http\Controllers\EmailDeliveryController; +use PHPeste\Notifications\Http\Controllers\EmailSuppressionController; use PHPeste\Notifications\Http\Controllers\EmailTemplateController; +use PHPeste\Notifications\Http\Controllers\ResendWebhookController; use PHPeste\Notifications\Http\Controllers\UnsubscribeController; Route::apiV1Edition('emails')->group(function (): void { @@ -33,8 +35,17 @@ Route::post('/deliveries/{delivery}/resend', [EmailDeliveryController::class, 'resend']) ->whereUuid('delivery') ->name('notifications.deliveries.resend'); + + Route::get('/suppressions', [EmailSuppressionController::class, 'index'])->name('notifications.suppressions.index'); + Route::delete('/suppressions/{suppression}', [EmailSuppressionController::class, 'destroy']) + ->whereUuid('suppression') + ->name('notifications.suppressions.destroy'); }); +Route::apiV1('webhooks')->post('/resend', ResendWebhookController::class) + ->middleware('throttle:webhooks') + ->name('notifications.webhooks.resend'); + Route::apiV1('public')->match(['get', 'post'], '/editions/{edition}/unsubscribe', UnsubscribeController::class) ->whereUuid('edition') ->middleware('signed') diff --git a/backend/app-modules/notifications/src/Actions/QueueEmail.php b/backend/app-modules/notifications/src/Actions/QueueEmail.php index c41c8ad..6e90c22 100644 --- a/backend/app-modules/notifications/src/Actions/QueueEmail.php +++ b/backend/app-modules/notifications/src/Actions/QueueEmail.php @@ -9,6 +9,7 @@ use PHPeste\Notifications\Enums\EmailTemplate; use PHPeste\Notifications\Jobs\SendEmailDelivery; use PHPeste\Notifications\Models\EmailDelivery; +use PHPeste\Notifications\Models\EmailSuppression; use PHPeste\Notifications\Models\EmailUnsubscribe; class QueueEmail implements EditionMailer @@ -33,7 +34,8 @@ public function queue( bool $isTest = false, ): EmailDelivery { $email = mb_strtolower(mb_trim($email)); - $suppressed = !$template->isTransactional() && !$isTest && $this->isUnsubscribed($editionId, $email); + $blocked = $this->isBlocked($editionId, $email); + $suppressed = $blocked || (!$template->isTransactional() && !$isTest && $this->isUnsubscribed($editionId, $email)); $delivery = EmailDelivery::create([ 'edition_id' => $editionId, @@ -44,6 +46,7 @@ public function queue( 'content' => $content, 'action_url' => $actionUrl, 'status' => $suppressed ? DeliveryStatus::Suppressed : DeliveryStatus::Queued, + 'provider_detail' => $blocked ? 'Endereço bloqueado nesta edição por bounce permanente ou spam' : null, 'is_test' => $isTest, ]); @@ -54,6 +57,15 @@ public function queue( return $delivery; } + /** + * Bounce permanente ou reclamação: nada sai para o endereço, nem e-mail + * transacional, até a organização liberar. + */ + public function isBlocked(string $editionId, string $email): bool + { + return EmailSuppression::query()->forEdition($editionId)->where('email', $email)->exists(); + } + private function isUnsubscribed(string $editionId, string $email): bool { return EmailUnsubscribe::query()->forEdition($editionId)->where('email', $email)->exists(); diff --git a/backend/app-modules/notifications/src/Actions/ResendEmail.php b/backend/app-modules/notifications/src/Actions/ResendEmail.php index c187201..1a5c01d 100644 --- a/backend/app-modules/notifications/src/Actions/ResendEmail.php +++ b/backend/app-modules/notifications/src/Actions/ResendEmail.php @@ -11,15 +11,23 @@ class ResendEmail { + public function __construct(private readonly QueueEmail $queue) {} + public function handle(EmailDelivery $delivery): EmailDelivery { + if ($this->queue->isBlocked($delivery->edition_id, $delivery->to_email)) { + throw ValidationException::withMessages([ + 'delivery' => 'Este endereço está bloqueado por bounce ou spam. Libere em "Endereços bloqueados" antes de reenviar.', + ]); + } + if ($delivery->status === DeliveryStatus::Queued) { throw ValidationException::withMessages([ 'delivery' => 'Este envio ainda está na fila.', ]); } - $delivery->update(['status' => DeliveryStatus::Queued, 'last_error' => null]); + $delivery->update(['status' => DeliveryStatus::Queued, 'last_error' => null, 'provider_detail' => null, 'delivered_at' => null, 'bounced_at' => null, 'complained_at' => null]); dispatch(new SendEmailDelivery($delivery->edition_id, $delivery->id)); diff --git a/backend/app-modules/notifications/src/Enums/DeliveryStatus.php b/backend/app-modules/notifications/src/Enums/DeliveryStatus.php index 6a22c72..f5d3a8b 100644 --- a/backend/app-modules/notifications/src/Enums/DeliveryStatus.php +++ b/backend/app-modules/notifications/src/Enums/DeliveryStatus.php @@ -8,6 +8,22 @@ enum DeliveryStatus: string { case Queued = 'queued'; case Sent = 'sent'; + case Delivered = 'delivered'; + case Bounced = 'bounced'; + case Complained = 'complained'; case Failed = 'failed'; case Suppressed = 'suppressed'; + + public function label(): string + { + return match ($this) { + self::Queued => 'Na fila', + self::Sent => 'Enviado', + self::Delivered => 'Entregue', + self::Bounced => 'Voltou (bounce)', + self::Complained => 'Marcado como spam', + self::Failed => 'Falhou', + self::Suppressed => 'Não enviado: endereço bloqueado', + }; + } } diff --git a/backend/app-modules/notifications/src/Enums/SuppressionReason.php b/backend/app-modules/notifications/src/Enums/SuppressionReason.php new file mode 100644 index 0000000..5453625 --- /dev/null +++ b/backend/app-modules/notifications/src/Enums/SuppressionReason.php @@ -0,0 +1,19 @@ + 'Bounce permanente (endereço não existe ou recusa)', + self::Complained => 'Marcou o e-mail como spam', + }; + } +} diff --git a/backend/app-modules/notifications/src/Events/AddressSuppressionChanged.php b/backend/app-modules/notifications/src/Events/AddressSuppressionChanged.php new file mode 100644 index 0000000..728602a --- /dev/null +++ b/backend/app-modules/notifications/src/Events/AddressSuppressionChanged.php @@ -0,0 +1,41 @@ +editionId, + $this->lifted ? 'notifications.suppression_lifted' : 'notifications.address_suppressed', + 'email_suppression', + $this->suppressionId, + $this->actorId, + null, + ['email' => $this->email, 'reason' => $this->reason], + ); + } +} diff --git a/backend/app-modules/notifications/src/Http/Controllers/EmailSuppressionController.php b/backend/app-modules/notifications/src/Http/Controllers/EmailSuppressionController.php new file mode 100644 index 0000000..7e45e1c --- /dev/null +++ b/backend/app-modules/notifications/src/Http/Controllers/EmailSuppressionController.php @@ -0,0 +1,61 @@ +query('q'))); + $page = EmailSuppression::query() + ->when($search !== '', fn ($query) => $query->where('email', 'like', "%{$search}%")) + ->latest()->orderByDesc('id') + ->paginate(50); + + return response()->json([ + 'data' => collect($page->items())->map(fn (EmailSuppression $suppression): array => [ + 'id' => $suppression->id, + 'email' => $suppression->email, + 'reason' => $suppression->reason->value, + 'reason_label' => $suppression->reason->label(), + 'detail' => $suppression->detail, + 'delivery_id' => $suppression->email_delivery_id, + 'created_at' => $suppression->created_at->clone()->utc()->toIso8601ZuluString(), + ])->all(), + 'meta' => ['current_page' => $page->currentPage(), 'last_page' => $page->lastPage(), 'per_page' => $page->perPage(), 'total' => $page->total()], + ]); + } + + public function destroy(Request $request): Response + { + Gate::authorize('manage-edition-emails'); + + $id = $request->route('suppression'); + abort_unless(is_string($id), 404); + $suppression = EmailSuppression::query()->whereKey($id)->firstOrFail(); + $actor = $request->user()?->getAuthIdentifier(); + + DB::transaction(function () use ($suppression, $actor): void { + $suppression->delete(); + event(new AddressSuppressionChanged($suppression->edition_id, $suppression->id, $suppression->email, $suppression->reason->value, true, is_string($actor) ? $actor : null)); + }); + + return response()->noContent(); + } +} diff --git a/backend/app-modules/notifications/src/Http/Controllers/ResendWebhookController.php b/backend/app-modules/notifications/src/Http/Controllers/ResendWebhookController.php new file mode 100644 index 0000000..cb0c7f6 --- /dev/null +++ b/backend/app-modules/notifications/src/Http/Controllers/ResendWebhookController.php @@ -0,0 +1,41 @@ +getContent(); + $signature = new SvixSignature((string) config('services.resend.webhook_secret')); + + if (!$signature->valid($request->header('svix-id'), $request->header('svix-timestamp'), $request->header('svix-signature'), $body)) { + Log::warning('Webhook do Resend com assinatura inválida.', ['svix_id' => $request->header('svix-id')]); + + return response()->json(['code' => 'invalid_signature', 'message' => 'Assinatura inválida.'], 401); + } + + $payload = json_decode($body, true); + + if (!is_array($payload)) { + return response()->json(['code' => 'invalid_payload', 'message' => 'Corpo inválido.'], 400); + } + + /** @var array $payload */ + $outcome = $process->handle((string) $request->header('svix-id'), $payload); + + return response()->json(['data' => ['outcome' => $outcome, 'duplicate' => $outcome === 'duplicate']]); + } +} diff --git a/backend/app-modules/notifications/src/Http/Resources/EmailDeliveryResource.php b/backend/app-modules/notifications/src/Http/Resources/EmailDeliveryResource.php index d9be432..63a246d 100644 --- a/backend/app-modules/notifications/src/Http/Resources/EmailDeliveryResource.php +++ b/backend/app-modules/notifications/src/Http/Resources/EmailDeliveryResource.php @@ -27,6 +27,11 @@ public function toArray(Request $request): array 'to_email' => $delivery->to_email, 'to_name' => $delivery->to_name, 'status' => $delivery->status->value, + 'status_label' => $delivery->status->label(), + 'provider_detail' => $delivery->provider_detail, + 'delivered_at' => $this->isoDate($delivery->delivered_at), + 'bounced_at' => $this->isoDate($delivery->bounced_at), + 'complained_at' => $this->isoDate($delivery->complained_at), 'attempts' => $delivery->attempts, 'last_error' => $delivery->last_error, 'is_test' => $delivery->is_test, diff --git a/backend/app-modules/notifications/src/Jobs/SendEmailDelivery.php b/backend/app-modules/notifications/src/Jobs/SendEmailDelivery.php index 4253755..3b2c653 100644 --- a/backend/app-modules/notifications/src/Jobs/SendEmailDelivery.php +++ b/backend/app-modules/notifications/src/Jobs/SendEmailDelivery.php @@ -7,6 +7,7 @@ use Illuminate\Contracts\Queue\ShouldQueue; use Illuminate\Foundation\Queue\Queueable; use Illuminate\Support\Facades\Mail; +use PHPeste\Notifications\Actions\QueueEmail; use PHPeste\Notifications\Enums\DeliveryStatus; use PHPeste\Notifications\Mail\EditionMail; use PHPeste\Notifications\Mail\EmailComposer; @@ -42,6 +43,14 @@ public function handle(EmailComposer $composer): void return; } + // O endereço pode ter sido bloqueado (bounce, spam) enquanto o envio + // esperava na fila. + if (resolve(QueueEmail::class)->isBlocked($delivery->edition_id, $delivery->to_email)) { + $delivery->update(['status' => DeliveryStatus::Suppressed, 'provider_detail' => 'Endereço bloqueado nesta edição por bounce permanente ou spam']); + + return; + } + $delivery->update(['attempts' => $delivery->attempts + 1]); try { diff --git a/backend/app-modules/notifications/src/Models/EmailDelivery.php b/backend/app-modules/notifications/src/Models/EmailDelivery.php index 0534d5c..347fd34 100644 --- a/backend/app-modules/notifications/src/Models/EmailDelivery.php +++ b/backend/app-modules/notifications/src/Models/EmailDelivery.php @@ -28,10 +28,14 @@ * @property string|null $provider_message_id * @property bool $is_test * @property Carbon|null $sent_at + * @property Carbon|null $delivered_at + * @property Carbon|null $bounced_at + * @property Carbon|null $complained_at + * @property string|null $provider_detail * @property Carbon $created_at * @property Carbon $updated_at */ -#[Fillable(['edition_id', 'template', 'to_email', 'to_name', 'variables', 'content', 'action_url', 'status', 'attempts', 'last_error', 'provider_message_id', 'is_test', 'sent_at'])] +#[Fillable(['edition_id', 'template', 'to_email', 'to_name', 'variables', 'content', 'action_url', 'status', 'attempts', 'last_error', 'provider_message_id', 'is_test', 'sent_at', 'delivered_at', 'bounced_at', 'complained_at', 'provider_detail'])] #[Table(name: 'email_deliveries')] class EmailDelivery extends Model { @@ -51,6 +55,9 @@ protected function casts(): array 'attempts' => 'integer', 'is_test' => 'boolean', 'sent_at' => 'datetime', + 'delivered_at' => 'datetime', + 'bounced_at' => 'datetime', + 'complained_at' => 'datetime', ]; } } diff --git a/backend/app-modules/notifications/src/Models/EmailSuppression.php b/backend/app-modules/notifications/src/Models/EmailSuppression.php new file mode 100644 index 0000000..22a067f --- /dev/null +++ b/backend/app-modules/notifications/src/Models/EmailSuppression.php @@ -0,0 +1,39 @@ + + */ + protected function casts(): array + { + return ['reason' => SuppressionReason::class]; + } +} diff --git a/backend/app-modules/notifications/src/Models/EmailWebhookEvent.php b/backend/app-modules/notifications/src/Models/EmailWebhookEvent.php new file mode 100644 index 0000000..984788a --- /dev/null +++ b/backend/app-modules/notifications/src/Models/EmailWebhookEvent.php @@ -0,0 +1,28 @@ + $payload + * @return string `processed`, `ignored` ou `duplicate` + */ + public function handle(string $svixId, array $payload): string + { + $type = is_string($payload['type'] ?? null) ? $payload['type'] : 'unknown'; + $data = is_array($payload['data'] ?? null) ? $payload['data'] : []; + $messageId = is_string($data['email_id'] ?? null) ? $data['email_id'] : null; + $delivery = $messageId === null ? null : EmailDelivery::query()->withoutGlobalScopes()->where('provider_message_id', $messageId)->first(); + + try { + return DB::transaction(function () use ($svixId, $type, $data, $messageId, $delivery): string { + $outcome = $delivery instanceof EmailDelivery + ? (string) $this->currentEdition->run($delivery->edition_id, fn (): string => $this->apply($delivery, $type, $data)) + : 'ignored'; + + EmailWebhookEvent::create([ + 'svix_id' => $svixId, + 'type' => mb_substr($type, 0, 40), + 'provider_message_id' => $messageId === null ? null : mb_substr($messageId, 0, 100), + 'edition_id' => $delivery?->edition_id, + 'outcome' => $outcome, + ]); + + return $outcome; + }); + } catch (UniqueConstraintViolationException) { + return 'duplicate'; + } + } + + /** + * @param array $data o `data` do evento, como veio do Resend + */ + private function apply(EmailDelivery $delivery, string $type, array $data): string + { + $bounce = is_array($data['bounce'] ?? null) ? $data['bounce'] : []; + $detail = mb_substr(mb_trim(implode(' · ', array_filter([ + is_string($bounce['type'] ?? null) ? $bounce['type'] : null, + is_string($bounce['subType'] ?? null) ? $bounce['subType'] : null, + is_string($bounce['message'] ?? null) ? $bounce['message'] : null, + ]))), 0, 500); + + switch ($type) { + case 'email.delivered': + if (in_array($delivery->status, [DeliveryStatus::Sent, DeliveryStatus::Queued], true)) { + $delivery->update(['status' => DeliveryStatus::Delivered, 'delivered_at' => now()]); + } + + return 'processed'; + + case 'email.bounced': + if (mb_strtolower((string) ($bounce['type'] ?? '')) !== 'permanent') { + $delivery->update(['provider_detail' => 'Bounce temporário'.($detail === '' ? '' : ': '.$detail)]); + + return 'processed'; + } + + $delivery->update(['status' => DeliveryStatus::Bounced, 'bounced_at' => now(), 'provider_detail' => $detail === '' ? 'Bounce permanente' : $detail]); + $this->suppress($delivery, SuppressionReason::Bounced, $detail); + + return 'processed'; + + case 'email.delivery_delayed': + $delivery->update(['provider_detail' => 'Entrega atrasada: o servidor de destino ainda não aceitou']); + + return 'processed'; + + case 'email.complained': + $delivery->update(['status' => DeliveryStatus::Complained, 'complained_at' => now()]); + $this->suppress($delivery, SuppressionReason::Complained, null); + + return 'processed'; + + default: + return 'ignored'; + } + } + + private function suppress(EmailDelivery $delivery, SuppressionReason $reason, ?string $detail): void + { + $suppression = EmailSuppression::query()->forEdition($delivery->edition_id)->firstOrCreate( + ['edition_id' => $delivery->edition_id, 'email' => $delivery->to_email], + ['reason' => $reason, 'detail' => $detail === '' ? null : $detail, 'email_delivery_id' => $delivery->id], + ); + + if ($suppression->wasRecentlyCreated) { + Log::warning('Endereço bloqueado por bounce ou reclamação.', ['edition_id' => $delivery->edition_id, 'reason' => $reason->value, 'delivery_id' => $delivery->id]); + event(new AddressSuppressionChanged($delivery->edition_id, $suppression->id, $delivery->to_email, $reason->value, false, null)); + } + } +} diff --git a/backend/app-modules/notifications/src/Webhooks/SvixSignature.php b/backend/app-modules/notifications/src/Webhooks/SvixSignature.php new file mode 100644 index 0000000..fae4912 --- /dev/null +++ b/backend/app-modules/notifications/src/Webhooks/SvixSignature.php @@ -0,0 +1,48 @@ +secret === '' || $id === null || $timestamp === null || $signatures === null || !ctype_digit($timestamp)) { + return false; + } + + if (abs(($now ?? now()->getTimestamp()) - (int) $timestamp) > self::TOLERANCE_SECONDS) { + return false; + } + + $expected = $this->sign($id, $timestamp, $body); + + foreach (explode(' ', $signatures) as $candidate) { + [$version, $signature] = array_pad(explode(',', $candidate, 2), 2, ''); + + if ($version === 'v1' && hash_equals($expected, $signature)) { + return true; + } + } + + return false; + } + + public function sign(string $id, string $timestamp, string $body): string + { + $key = base64_decode(str_starts_with($this->secret, 'whsec_') ? mb_substr($this->secret, 6) : $this->secret, true); + + return base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$body}", $key === false ? '' : $key, true)); + } +} diff --git a/backend/app-modules/notifications/tests/Feature/ResendWebhookTest.php b/backend/app-modules/notifications/tests/Feature/ResendWebhookTest.php new file mode 100644 index 0000000..2c3fb5f --- /dev/null +++ b/backend/app-modules/notifications/tests/Feature/ResendWebhookTest.php @@ -0,0 +1,159 @@ +set('services.resend.webhook_secret', RESEND_SECRET); + $this->travelTo('2027-06-10 12:00:00'); + $this->edition = Edition::factory()->status(EditionStatus::SalesOpen)->create(['name' => 'PHPeste 2027']); + $this->delivery = EmailDelivery::query()->forEdition($this->edition->id)->findOrFail( + resolve(EditionMailer::class)->send($this->edition->id, EmailTemplate::OrderConfirmed, 'ana@exemplo.com', 'Ana', ['nome' => 'Ana', 'pedido' => '#1']), + ); + $this->delivery->update(['provider_message_id' => 're_4ef9a417-02e9-4d39-ad75-9611e0fcc33c']); +}); + +function resendEvent(object $test, string $type, array $data = [], ?string $svixId = null, ?int $timestamp = null, ?string $secret = null): TestResponse +{ + $body = json_encode(['type' => $type, 'created_at' => '2027-06-10T12:00:00Z', 'data' => ['email_id' => 're_4ef9a417-02e9-4d39-ad75-9611e0fcc33c', 'to' => ['ana@exemplo.com'], ...$data]], JSON_THROW_ON_ERROR); + $svixId ??= 'msg_'.bin2hex(random_bytes(6)); + $timestamp ??= now()->getTimestamp(); + $signature = new SvixSignature($secret ?? RESEND_SECRET)->sign($svixId, (string) $timestamp, $body); + + return $test->call('POST', '/api/v1/webhooks/resend', [], [], [], [ + 'CONTENT_TYPE' => 'application/json', + 'HTTP_ACCEPT' => 'application/json', + 'HTTP_SVIX_ID' => $svixId, + 'HTTP_SVIX_TIMESTAMP' => (string) $timestamp, + 'HTTP_SVIX_SIGNATURE' => "v1,outra-assinatura v1,{$signature}", + ], $body); +} + +function resendDelivery(object $test): EmailDelivery +{ + return EmailDelivery::query()->forEdition($test->edition->id)->findOrFail($test->delivery->id); +} + +it('marca o envio como entregue', function (): void { + resendEvent($this, 'email.delivered')->assertOk()->assertJsonPath('data.outcome', 'processed'); + + expect(resendDelivery($this)->status)->toBe(DeliveryStatus::Delivered) + ->and(resendDelivery($this)->delivered_at)->not->toBeNull() + ->and(EmailWebhookEvent::query()->sole()->edition_id)->toBe($this->edition->id); +}); + +it('rejeita assinatura inválida, segredo errado ou timestamp fora da janela, sem mudar nada', function (): void { + resendEvent($this, 'email.bounced', ['bounce' => ['type' => 'Permanent']], secret: 'whsec_'.base64_encode('outro-segredo'))->assertUnauthorized(); + resendEvent($this, 'email.bounced', ['bounce' => ['type' => 'Permanent']], timestamp: now()->subMinutes(6)->getTimestamp())->assertUnauthorized(); + resendEvent($this, 'email.bounced', ['bounce' => ['type' => 'Permanent']], timestamp: now()->addMinutes(6)->getTimestamp())->assertUnauthorized(); + $this->postJson('/api/v1/webhooks/resend', ['type' => 'email.bounced'])->assertUnauthorized(); + + config()->set('services.resend.webhook_secret'); + resendEvent($this, 'email.bounced', ['bounce' => ['type' => 'Permanent']])->assertUnauthorized(); + + expect(resendDelivery($this)->status)->toBe(DeliveryStatus::Sent) + ->and(EmailSuppression::query()->forEdition($this->edition->id)->count())->toBe(0) + ->and(EmailWebhookEvent::query()->count())->toBe(0); +}); + +it('o mesmo evento recebido duas vezes não duplica efeito', function (): void { + resendEvent($this, 'email.bounced', ['bounce' => ['type' => 'Permanent', 'subType' => 'General', 'message' => 'mailbox does not exist']], svixId: 'msg_repetido')->assertOk(); + resendEvent($this, 'email.bounced', ['bounce' => ['type' => 'Permanent']], svixId: 'msg_repetido')->assertOk()->assertJsonPath('data.duplicate', true); + + expect(EmailWebhookEvent::query()->count())->toBe(1) + ->and(EmailSuppression::query()->forEdition($this->edition->id)->count())->toBe(1) + ->and(AuditLog::query()->where('action', 'notifications.address_suppressed')->count())->toBe(1); +}); + +it('bounce permanente bloqueia o endereço, inclusive para e-mail transacional, até a organização liberar', function (): void { + resendEvent($this, 'email.bounced', ['bounce' => ['type' => 'Permanent', 'subType' => 'General', 'message' => 'mailbox does not exist']])->assertOk(); + + $bounced = resendDelivery($this); + expect($bounced->status)->toBe(DeliveryStatus::Bounced) + ->and($bounced->bounced_at)->not->toBeNull() + ->and($bounced->provider_detail)->toBe('Permanent · General · mailbox does not exist'); + + $next = EmailDelivery::query()->forEdition($this->edition->id)->findOrFail( + resolve(EditionMailer::class)->send($this->edition->id, EmailTemplate::TicketTransferred, 'ANA@exemplo.com', 'Ana', ['nome' => 'Ana']), + ); + expect($next->status)->toBe(DeliveryStatus::Suppressed)->and($next->provider_detail)->toContain('bloqueado'); + + $organizer = User::factory()->create(); + EditionMember::factory()->for($this->edition)->create(['user_id' => $organizer->id, 'role' => EditionRole::Organizer]); + Sanctum::actingAs($organizer); + $api = "/api/v1/editions/{$this->edition->id}/emails"; + + $this->postJson("{$api}/deliveries/{$next->id}/resend")->assertUnprocessable()->assertJsonValidationErrors(['delivery']); + + $list = $this->getJson("{$api}/suppressions")->assertOk()->json('data'); + expect($list)->toHaveCount(1) + ->and($list[0])->toMatchArray(['email' => 'ana@exemplo.com', 'reason' => 'bounced', 'delivery_id' => $this->delivery->id]); + + $this->getJson("{$api}/deliveries?status=bounced")->assertOk()->assertJsonCount(1, 'data')->assertJsonPath('data.0.status_label', 'Voltou (bounce)'); + + $this->deleteJson("{$api}/suppressions/{$list[0]['id']}")->assertNoContent(); + expect(AuditLog::query()->where('action', 'notifications.suppression_lifted')->value('actor_id'))->toBe($organizer->id); + + $this->postJson("{$api}/deliveries/{$next->id}/resend")->assertOk()->assertJsonPath('data.status', 'sent'); +}); + +it('bounce temporário e entrega atrasada não bloqueiam o endereço', function (): void { + resendEvent($this, 'email.bounced', ['bounce' => ['type' => 'Transient', 'subType' => 'MailboxFull', 'message' => 'mailbox full']])->assertOk(); + resendEvent($this, 'email.delivery_delayed')->assertOk(); + + expect(resendDelivery($this)->status)->toBe(DeliveryStatus::Sent) + ->and(resendDelivery($this)->provider_detail)->toBe('Entrega atrasada: o servidor de destino ainda não aceitou') + ->and(EmailSuppression::query()->forEdition($this->edition->id)->count())->toBe(0); + + $next = resolve(EditionMailer::class)->send($this->edition->id, EmailTemplate::OrderConfirmed, 'ana@exemplo.com', 'Ana', ['nome' => 'Ana']); + expect(EmailDelivery::query()->forEdition($this->edition->id)->findOrFail($next)->status)->toBe(DeliveryStatus::Sent); +}); + +it('reclamação de spam marca o envio e bloqueia o endereço', function (): void { + resendEvent($this, 'email.delivered')->assertOk(); + resendEvent($this, 'email.complained')->assertOk(); + + expect(resendDelivery($this)->status)->toBe(DeliveryStatus::Complained) + ->and(EmailSuppression::query()->forEdition($this->edition->id)->sole()->reason->value)->toBe('complained'); +}); + +it('a edição vem do envio, nunca do webhook; envio desconhecido é ignorado', function (): void { + $other = Edition::factory()->create(); + + resendEvent($this, 'email.bounced', ['email_id' => 're_desconhecido', 'bounce' => ['type' => 'Permanent'], 'edition_id' => $other->id])->assertOk()->assertJsonPath('data.outcome', 'ignored'); + resendEvent($this, 'email.opened')->assertOk()->assertJsonPath('data.outcome', 'ignored'); + + expect(EmailSuppression::query()->withoutGlobalScopes()->count())->toBe(0) + ->and(EmailWebhookEvent::query()->count())->toBe(2); +}); + +it('envio que estava na fila não sai se o endereço for bloqueado antes', function (): void { + EmailSuppression::create(['edition_id' => $this->edition->id, 'email' => 'bia@exemplo.com', 'reason' => 'bounced']); + $queued = EmailDelivery::create(['edition_id' => $this->edition->id, 'template' => EmailTemplate::OrderConfirmed, 'to_email' => 'bia@exemplo.com', 'to_name' => 'Bia', 'variables' => [], 'status' => DeliveryStatus::Queued]); + + dispatch_sync(new SendEmailDelivery($this->edition->id, $queued->id)); + + expect($queued->fresh()->status)->toBe(DeliveryStatus::Suppressed); + Mail::assertNotSent(EditionMail::class, fn ($mail): bool => $mail->hasTo('bia@exemplo.com')); +}); diff --git a/backend/config/services.php b/backend/config/services.php index 03b1971..cf8026f 100644 --- a/backend/config/services.php +++ b/backend/config/services.php @@ -22,6 +22,8 @@ 'resend' => [ 'key' => env('RESEND_API_KEY'), + // Segredo de assinatura do webhook (whsec_...), em Resend → Webhooks. + 'webhook_secret' => env('RESEND_WEBHOOK_SECRET'), ], 'github' => [ diff --git a/docs/arquitetura/PHPeste_Arquitetura.pdf b/docs/arquitetura/PHPeste_Arquitetura.pdf index bc32369..8f70457 100644 Binary files a/docs/arquitetura/PHPeste_Arquitetura.pdf and b/docs/arquitetura/PHPeste_Arquitetura.pdf differ diff --git a/docs/arquitetura/README.md b/docs/arquitetura/README.md index 94db2ec..33e8bdd 100644 --- a/docs/arquitetura/README.md +++ b/docs/arquitetura/README.md @@ -11,7 +11,7 @@ | 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 (67 tabelas) | +| 8 | Banco de dados por domínio (69 tabelas) | | 9 | Papéis e permissões | | 10 | Ingresso: da compra ao QR | | 11 | CFP: da proposta à grade | @@ -23,7 +23,7 @@ | 17 | Telas: o painel em uso (capturas do front-admin) | | 18 | Onde estamos e o que falta | -Retrato de 19/11/2026, com a B34 (tarefas). +Retrato de 19/11/2026, com a B47 (webhooks do Resend). ## Como atualizar diff --git a/docs/arquitetura/fonte/arquitetura.html b/docs/arquitetura/fonte/arquitetura.html index 6e54207..f4b4716 100644 --- a/docs/arquitetura/fonte/arquitetura.html +++ b/docs/arquitetura/fonte/arquitetura.html @@ -106,7 +106,7 @@

Conteúdo

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 · B34 (tarefas) · página 1
+
Fonte: código da main, backend/CLAUDE.md, docs/produto.md e ADRs 0001–0009.19/11/2026 · B47 (webhooks do Resend) · página 1
@@ -183,7 +183,7 @@

Visão geral do sistema

MySQL 8 -um banco · 67 tabelas +um banco · 69 tabelas UUID em toda tabela Redis @@ -198,7 +198,7 @@

Visão geral do sistema

conta de cada edição (ADR 0009) Resend (e-mail) -Mailpit no dev +webhook de entrega · Mailpit no dev GitHub OAuth login de palestrante @@ -213,7 +213,7 @@

Visão geral do sistema

  • 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 · B34 (tarefas) · página 2
+
PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 2
@@ -288,7 +288,7 @@

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

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 · B34 (tarefas) · página 3
+
PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 3
@@ -336,7 +336,7 @@

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

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/webhooks/payments/{token} e /webhooks/resend assinados /api/v1/sponsors/attachments/{id}/download URL assinada CORS: só a origem do site próprio da edição, só em /public/* @@ -356,7 +356,7 @@

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

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 · B34 (tarefas) · página 4
+
PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 4
@@ -422,13 +422,13 @@

Ciclo de vida da edição

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 · B34 (tarefas) · página 5
+
PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · 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. 257 rotas na API.

+

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

Identity @@ -471,9 +471,9 @@

Os 15 módulos do backend

Notifications e-mail transacional por edição com modelos -editáveis, descadastro, Resend - -9 rotas +editáveis, descadastro, Resend com bounce e spam + +12 rotas Audit trilha append-only das ações sensíveis, com @@ -521,7 +521,7 @@

Os 15 módulos do backend

casca
-
PHPeste Platform · Arquitetura19/11/2026 · B34 (tarefas) · página 6
+
PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 6
@@ -587,13 +587,13 @@

Como os módulos conversam

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. O mesmo vale para TaskLinkProvider (Tasks): Suppliers e Sponsors registram o que uma tarefa pode apontar, e o Program vai registrar a sessão.
-
PHPeste Platform · Arquitetura19/11/2026 · B34 (tarefas) · página 7
+
PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 7
08 · Dados

Banco de dados por domínio

-

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

+

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

Identity · 5 @@ -645,32 +645,34 @@

Banco de dados por domínio

payment_charges webhook_events payment_refunds - -Notifications · 3 + +Notifications · 5 email_templates email_deliveries email_unsubscribes +email_suppressions +email_webhook_events ● 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 + +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 @@ -687,7 +689,7 @@

Banco de dados por domínio

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 · B34 (tarefas) · página 8
+
PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 8
@@ -708,7 +710,7 @@

Como funciona

  • Palestrante e participante não têm papel: entram pelas rotas de edição publicada.
  • -
    PHPeste Platform · Arquitetura19/11/2026 · B34 (tarefas) · página 9
    +
    PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 9
    @@ -782,7 +784,7 @@

    Ingresso: da compra ao QR

    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 · B34 (tarefas) · página 10
    +
    PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 10
    @@ -858,7 +860,7 @@

    CFP: da proposta à grade

    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 · B34 (tarefas) · página 11
    +
    PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 11
    @@ -911,7 +913,7 @@

    Dinheiro: patrocínio, fornecedores e finanças

    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 · B34 (tarefas) · página 12
    +
    PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 12
    @@ -932,14 +934,15 @@

    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.
  • +
  • Webhook do Resend (assinatura Svix): entregue, bounce e spam. Bounce permanente ou spam bloqueia o endereço na edição, até para transacional, até a organização liberar.
  • Auditoria

      -
    • Evento que implementa Auditable vira linha em audit_logs pelo listener genérico. 21 eventos hoje.
    • +
    • Evento que implementa Auditable vira linha em audit_logs pelo listener genérico. 22 eventos hoje.
    • Segredo removido, dado pessoal mascarado; o model recusa update e delete.
    -
    PHPeste Platform · Arquitetura19/11/2026 · B34 (tarefas) · página 13
    +
    PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 13
    @@ -949,7 +952,7 @@

    Segurança

    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 · B34 (tarefas) · página 14
    +
    PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 14
    @@ -1024,7 +1027,7 @@

    Desenvolvimento, CI e deploy

    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 · B34 (tarefas) · página 15
    +
    PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 15
    @@ -1037,7 +1040,7 @@

    Telas: o design do painel

    Tokens do tema Sertão
    Design: tokens do tema Sertão
    -
    PHPeste Platform · Arquitetura19/11/2026 · B34 (tarefas) · página 16
    +
    PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 16
    @@ -1051,7 +1054,7 @@

    Telas: o painel em uso

    Login
    Entrar com e-mail e senha ou GitHub
    -
    PHPeste Platform · Arquitetura19/11/2026 · B34 (tarefas) · página 17
    +
    PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 17
    @@ -1061,6 +1064,6 @@

    Onde estamos e o que falta

    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 concluídoingressos, cupons, pedidos, Asaas, Mercado Pago, webhooks, reembolso, conciliação, QR, importação, patrocínio, fornecedores, finanças, tarefas; faltam as telas A14–A23 e 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 · B34 (tarefas) · página 18
    +
    PHPeste Platform · Arquitetura19/11/2026 · B47 (webhooks do Resend) · página 18
    diff --git a/docs/arquitetura/fonte/gerar.py b/docs/arquitetura/fonte/gerar.py index 7ce223d..bd344ec 100644 --- a/docs/arquitetura/fonte/gerar.py +++ b/docs/arquitetura/fonte/gerar.py @@ -13,7 +13,7 @@ from pathlib import Path OUT = Path(__file__).with_name("arquitetura.html") -RETRATO = "19/11/2026 · B34 (tarefas)" +RETRATO = "19/11/2026 · B47 (webhooks do Resend)" # ---------------------------------------------------------------- estilo --- # Cores do tema Sertão (front-admin) para o que é da plataforma, e neutras @@ -186,11 +186,11 @@ def legend(): 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 · 67 tabelas", "UUID em toda tabela"], "data")) +b.append(box(845, 40, 245, 70, "MySQL 8", ["um banco · 69 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, 360, 245, 50, "Resend (e-mail)", ["webhook de entrega · 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): @@ -244,7 +244,7 @@ def legend(): 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(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} e /webhooks/resend assinados", "/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)) @@ -283,7 +283,7 @@ def legend(): ("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"), + ("Notifications", "e-mail transacional por edição com modelos editáveis, descadastro, Resend com bounce e spam", 12, "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"), @@ -307,7 +307,7 @@ def legend(): 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. 257 rotas na API.", + "Cada módulo é um pacote Composer real em backend/app-modules/<nome> (ADR 0002), com namespace PHPeste\\<Nome>: Models, Actions, Contracts, Events, Http, Jobs. 260 rotas na API.", svg("\n".join(b), h=545))) # ================================================= 7 como conversam @@ -341,7 +341,7 @@ def legend(): ("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"), + ("Notifications", ["email_templates", "email_deliveries", "email_unsubscribes", "email_suppressions", "email_webhook_events ●"], "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"), @@ -359,7 +359,7 @@ def legend(): 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, 67 tabelas, todas com UUID como chave. Verde é da edição (tem edition_id); azul é global. ● em Suppliers: global da comunidade (community_id).", + "MySQL 8, 69 tabelas, todas com UUID como chave. Verde é da edição (tem edition_id); azul é global. ● em Suppliers: global da comunidade (community_id); em Notifications: global, a edição vem do envio.", 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."])) @@ -493,10 +493,11 @@ def legend():
  • 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.
  • +
  • Webhook do Resend (assinatura Svix): entregue, bounce e spam. Bounce permanente ou spam bloqueia o endereço na edição, até para transacional, até a organização liberar.
  • Auditoria

      -
    • Evento que implementa Auditable vira linha em audit_logs pelo listener genérico. 21 eventos hoje.
    • +
    • Evento que implementa Auditable vira linha em audit_logs pelo listener genérico. 22 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))