Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion backend/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<nome>/src/`)

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
<?php

declare(strict_types=1);

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
public function up(): void
{
Schema::table('email_deliveries', function (Blueprint $table): void {
$table->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']);
});
}
};
11 changes: 11 additions & 0 deletions backend/app-modules/notifications/routes/notifications-routes.php
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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')
Expand Down
14 changes: 13 additions & 1 deletion backend/app-modules/notifications/src/Actions/QueueEmail.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -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,
]);

Expand All @@ -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();
Expand Down
10 changes: 9 additions & 1 deletion backend/app-modules/notifications/src/Actions/ResendEmail.php
Original file line number Diff line number Diff line change
Expand Up @@ -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));

Expand Down
16 changes: 16 additions & 0 deletions backend/app-modules/notifications/src/Enums/DeliveryStatus.php
Original file line number Diff line number Diff line change
Expand Up @@ -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',
};
}
}
19 changes: 19 additions & 0 deletions backend/app-modules/notifications/src/Enums/SuppressionReason.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
<?php

declare(strict_types=1);

namespace PHPeste\Notifications\Enums;

enum SuppressionReason: string
{
case Bounced = 'bounced';
case Complained = 'complained';

public function label(): string
{
return match ($this) {
self::Bounced => 'Bounce permanente (endereço não existe ou recusa)',
self::Complained => 'Marcou o e-mail como spam',
};
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
<?php

declare(strict_types=1);

namespace PHPeste\Notifications\Events;

use Illuminate\Contracts\Events\ShouldDispatchAfterCommit;
use Illuminate\Foundation\Events\Dispatchable;
use PHPeste\Audit\Contracts\Auditable;
use PHPeste\Audit\Data\AuditRecord;

/**
* Endereço bloqueado (bounce permanente ou spam, pelo webhook) ou liberado
* pela organização.
*/
class AddressSuppressionChanged implements Auditable, ShouldDispatchAfterCommit
{
use Dispatchable;

public function __construct(
public readonly string $editionId,
public readonly string $suppressionId,
public readonly string $email,
public readonly string $reason,
public readonly bool $lifted,
public readonly ?string $actorId,
) {}

public function auditRecord(): AuditRecord
{
return new AuditRecord(
$this->editionId,
$this->lifted ? 'notifications.suppression_lifted' : 'notifications.address_suppressed',
'email_suppression',
$this->suppressionId,
$this->actorId,
null,
['email' => $this->email, 'reason' => $this->reason],
);
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
<?php

declare(strict_types=1);

namespace PHPeste\Notifications\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Gate;
use PHPeste\Notifications\Events\AddressSuppressionChanged;
use PHPeste\Notifications\Models\EmailSuppression;

/**
* Endereços bloqueados da edição. Liberar volta a permitir envio; se o
* endereço continuar inválido, o próximo bounce bloqueia de novo.
*/
class EmailSuppressionController
{
public function index(Request $request): JsonResponse
{
Gate::authorize('manage-edition-emails');

$search = mb_strtolower(mb_trim((string) $request->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();
}
}
Loading
Loading