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
3 changes: 2 additions & 1 deletion backend/CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ API Laravel 13 / PHP 8.4 da PHPeste Platform. Módulos de domínio vivem em `app
## Módulos

MVP: `identity`, `community`, `branding`, `cfp`, `program`, `ticketing`, `payments`, `check-in`, `notifications`, `audit`.
Fase 2/3: `sponsors`, `suppliers` e `finance` (já implementados); scaffold vazio, sem lógica ainda: `tasks`, `engagement`.
Fase 2/3: `sponsors`, `suppliers`, `finance` e `tasks` (já implementados); scaffold vazio, sem lógica ainda: `engagement`.
Ver `docs/produto.md` na raiz do monorepo para a responsabilidade de cada um.

Com implementação real até agora:
Expand All @@ -20,6 +20,7 @@ Com implementação real até agora:
- `sponsors`: patrocínio por edição, tudo sob a permissão `sponsors.manage` (só organizador), em `/editions/{id}/sponsors`. Cotas (`sponsor_tiers`: valor, vagas, nulo = sem limite, e contrapartidas em texto), empresas (`sponsors`, com contato e observações), acordos (`sponsorships`, o card do funil: empresa, cota, valor, que por padrão é o preço da cota, e responsável da equipe) e meta da edição (`sponsor_settings.goal_cents`). Funil `SponsorshipStage`: prospecção, negociando, fechado, pago e perdido (com motivo). Fechado e pago ocupam vaga da cota: `EnsureTierSlot` trava a cota e conta os acordos fechados; sem vaga, mover, criar já fechado ou trocar a cota de um acordo fechado só passa com `confirm=true`, e o evento `SponsorshipStageChanged` (auditado como `sponsors.stage_changed`) registra `over_slots`. A primeira vez que o acordo fecha cria uma entrega (`sponsor_deliverables`: responsável da equipe, prazo, status) para cada contrapartida da cota. Pagamentos são registrados à mão (`sponsorship_payments`, ADR 0009) e nunca passam do valor do acordo; quando cobrem o valor, o acordo vai sozinho para pago, e remover um pagamento que deixa faltar dinheiro volta para fechado (auditado como `sponsors.payment_recorded`/`payment_removed`). Histórico de contatos em `sponsor_contacts`. Anexos (`sponsor_attachments`: contrato, logo vetorial, outro) ficam no disco privado `SPONSORS_ATTACHMENTS_DISK` (SVG sanitizado) e nunca têm link direto: `GET .../attachments/{id}/url` devolve uma URL assinada que expira em `SPONSORS_ATTACHMENTS_URL_MINUTES`, e o download (`/api/v1/sponsors/attachments/{id}/download`, middleware `signed`, sem login) sai sempre como anexo, com `nosniff` e CSP `sandbox`. `SponsorTotals` dá meta, fechado, recebido, em negociação e contagem e valor por etapa para o funil (`GET .../board`) e para a Visão geral (`indicators.sponsors`, mais a pendência de entregas atrasadas). `SponsorTiersCloner` leva cotas e meta para a próxima edição; empresas, acordos e contatos não vão. Nome de responsável e autor vem do contrato `UserAccounts` (`Http/People`).
- `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.

## Estrutura de cada módulo (`app-modules/<nome>/src/`)
Expand Down
2 changes: 2 additions & 0 deletions backend/app-modules/community/src/Enums/EditionPermission.php
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ enum EditionPermission: string
case ManageSponsors = 'sponsors.manage';
case ManageSuppliers = 'suppliers.manage';
case ManageFinance = 'finance.manage';
case ManageTasks = 'tasks.manage';

public function label(): string
{
Expand All @@ -34,6 +35,7 @@ public function label(): string
self::ManageSponsors => 'Gerenciar patrocinadores',
self::ManageSuppliers => 'Gerenciar fornecedores',
self::ManageFinance => 'Ver e editar finanças',
self::ManageTasks => 'Gerenciar tarefas da organização',
};
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ function cloneEdition(object $test, array $parts, string $slug = '2028'): TestRe
it('lista o que pode ser copiado e o que nunca é', function (): void {
$this->getJson("{$this->base}/clone-options")
->assertOk()
->assertJsonPath('data.parts', fn (array $parts): bool => collect($parts)->pluck('id')->sort()->values()->all() === ['cfp', 'emails', 'finance', 'identity', 'sponsor_tiers', 'suppliers', 'team', 'ticketing'])
->assertJsonPath('data.parts', fn (array $parts): bool => collect($parts)->pluck('id')->sort()->values()->all() === ['cfp', 'emails', 'finance', 'identity', 'sponsor_tiers', 'suppliers', 'tasks', 'team', 'ticketing'])
->assertJsonPath('data.never_copied', fn (array $items): bool => in_array('Propostas', $items, true) && in_array('Participantes', $items, true));
});

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
EditionPermission::ManageSponsors->value => [EditionRole::Organizer],
EditionPermission::ManageSuppliers->value => [EditionRole::Organizer],
EditionPermission::ManageFinance->value => [EditionRole::Organizer, EditionRole::Finance],
EditionPermission::ManageTasks->value => [EditionRole::Organizer],
];

$cases = [];
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
use Laravel\Sanctum\NewAccessToken;
use Laravel\Sanctum\PersonalAccessToken;
use PHPeste\Identity\Contracts\UserAccounts;
use PHPeste\Identity\Enums\NotificationTopic;
use PHPeste\Identity\Models\User;

class EloquentUserAccounts implements UserAccounts
Expand Down Expand Up @@ -90,6 +91,11 @@ public function checkPassword(string $userId, string $password): bool
return $hash !== null && Hash::check($password, $hash);
}

public function wantsNotification(string $userId, NotificationTopic $topic): bool
{
return User::query()->find($userId)?->wantsNotification($topic) ?? false;
}

public function issueToken(string $userId, string $deviceName): NewAccessToken
{
return User::query()->findOrFail($userId)->createToken($deviceName);
Expand Down
6 changes: 6 additions & 0 deletions backend/app-modules/identity/src/Contracts/UserAccounts.php
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
namespace PHPeste\Identity\Contracts;

use Laravel\Sanctum\NewAccessToken;
use PHPeste\Identity\Enums\NotificationTopic;

interface UserAccounts
{
Expand All @@ -31,5 +32,10 @@ public function findOrCreateInvited(string $name, string $email): array;

public function checkPassword(string $userId, string $password): bool;

/**
* Se a pessoa quer receber e-mail deste assunto (preferência em /me).
*/
public function wantsNotification(string $userId, NotificationTopic $topic): bool;

public function issueToken(string $userId, string $deviceName): NewAccessToken;
}
13 changes: 13 additions & 0 deletions backend/app-modules/notifications/src/Enums/EmailTemplate.php
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@ enum EmailTemplate: string
case ProposalReceived = 'proposal_received';
case SpeakerConfirmationReminder = 'speaker_confirmation_reminder';
case SpeakerInvited = 'speaker_invited';
case TaskAssigned = 'task_assigned';
case TaskDueSoon = 'task_due_soon';

public function label(): string
{
Expand All @@ -32,6 +34,8 @@ public function label(): string
self::ProposalReceived => 'Proposta recebida',
self::SpeakerConfirmationReminder => 'Lembrete de confirmação do palestrante',
self::SpeakerInvited => 'Convite para palestrar',
self::TaskAssigned => 'Tarefa atribuída',
self::TaskDueSoon => 'Prazo de tarefa chegando',
};
}

Expand All @@ -48,6 +52,8 @@ public function trigger(): string
self::ProposalReceived => 'Ao enviar uma proposta',
self::SpeakerConfirmationReminder => '2 dias antes do prazo de confirmação',
self::SpeakerInvited => 'Ao convidar alguém direto para palestrar',
self::TaskAssigned => 'Ao virar responsável por uma tarefa',
self::TaskDueSoon => '1 dia antes do prazo da tarefa',
};
}

Expand All @@ -70,6 +76,7 @@ public function variables(): array
self::TeamInvite => ['nome', 'edicao', 'papel'],
self::ProposalReceived => ['nome', 'edicao', 'proposta', 'data'],
self::SpeakerConfirmationReminder, self::SpeakerInvited => ['nome', 'edicao', 'proposta', 'prazo'],
self::TaskAssigned, self::TaskDueSoon => ['nome', 'edicao', 'tarefa', 'prazo'],
};
}

Expand All @@ -87,6 +94,8 @@ public function defaultSubject(): string
self::ProposalReceived => 'Recebemos sua proposta para o {edicao}',
self::SpeakerConfirmationReminder => 'Confirme sua palestra no {edicao} até {prazo}',
self::SpeakerInvited => 'Convite para palestrar no {edicao}',
self::TaskAssigned => 'Nova tarefa para você no {edicao}: {tarefa}',
self::TaskDueSoon => 'O prazo de "{tarefa}" é {prazo}',
};
}

Expand All @@ -104,6 +113,8 @@ public function defaultBody(): string
self::ProposalReceived => "Oi, {nome}!\n\nRecebemos a proposta \"{proposta}\" para o {edicao}. Você pode editar ou retirar a proposta até o fechamento do CFP.",
self::SpeakerConfirmationReminder => "Oi, {nome}!\n\nAinda não recebemos sua confirmação para a palestra \"{proposta}\" no {edicao}. O prazo vai até {prazo}; depois disso a vaga pode ir para a lista de espera.",
self::SpeakerInvited => "Oi, {nome}!\n\nA organização do {edicao} convidou você para apresentar \"{proposta}\". Confirme sua participação pelo link abaixo até {prazo}.\n\nPara entrar, use este e-mail: se ainda não tem senha na plataforma, entre pelo GitHub ou peça uma senha em \"Esqueci minha senha\".",
self::TaskAssigned => "Oi, {nome}!\n\nVocê é responsável pela tarefa \"{tarefa}\" no {edicao}. Prazo: {prazo}.",
self::TaskDueSoon => "Oi, {nome}!\n\nA tarefa \"{tarefa}\" do {edicao}, que está com você, vence {prazo}. Se já terminou, mova para a coluna de concluídas no painel."
};
}

Expand All @@ -120,6 +131,7 @@ public function actionLabel(): string
self::TeamInvite => 'Aceitar convite',
self::ProposalReceived => 'Ver minha proposta',
self::SpeakerConfirmationReminder, self::SpeakerInvited => 'Confirmar participação',
self::TaskAssigned, self::TaskDueSoon => 'Ver tarefa',
};
}

Expand All @@ -138,6 +150,7 @@ public function sampleVariables(): array
'proposta' => 'Laravel no sertão: filas sem drama',
'papel' => 'organizador',
'prazo' => '20 de maio',
'tarefa' => 'Fechar o buffet do coffee break',
];
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
it('lista os modelos da edição com o padrão de cada um', function (): void {
$this->getJson($this->url)
->assertOk()
->assertJsonCount(11, 'data')
->assertJsonCount(13, 'data')
->assertJsonPath('data.0.id', 'order_confirmed')
->assertJsonPath('data.0.label', 'Confirmação de compra')
->assertJsonPath('data.0.trigger', 'Ao pagar o pedido')
Expand All @@ -30,7 +30,9 @@
->assertJsonPath('data.0.last_sent_at', null)
->assertJsonPath('data.6.transactional', false)
->assertJsonPath('data.10.id', 'speaker_invited')
->assertJsonPath('data.10.subject', 'Convite para palestrar no {edicao}');
->assertJsonPath('data.10.subject', 'Convite para palestrar no {edicao}')
->assertJsonPath('data.12.id', 'task_due_soon')
->assertJsonPath('data.12.variables', ['nome', 'edicao', 'tarefa', 'prazo']);
});

it('salva um modelo personalizado e restaura o padrão', function (): void {
Expand Down
42 changes: 42 additions & 0 deletions backend/app-modules/sponsors/src/Overview/SponsorshipTaskLinks.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
<?php

declare(strict_types=1);

namespace PHPeste\Sponsors\Overview;

use PHPeste\Sponsors\Models\Sponsorship;
use PHPeste\Tasks\Contracts\TaskLinkProvider;

/**
* Deixa uma tarefa apontar para um acordo de patrocínio desta edição.
*/
class SponsorshipTaskLinks implements TaskLinkProvider
{
public function key(): string
{
return 'sponsorship';
}

public function label(): string
{
return 'Patrocinador';
}

public function names(string $editionId, array $ids): array
{
return Sponsorship::query()->forEdition($editionId)->with(['sponsor:id,name', 'tier:id,name'])->whereKey($ids)->get()
->mapWithKeys(fn (Sponsorship $deal): array => [$deal->id => $this->name($deal)])->all();
}

public function options(string $editionId): array
{
return array_values(Sponsorship::query()->forEdition($editionId)->with(['sponsor:id,name', 'tier:id,name'])->get()
->map(fn (Sponsorship $deal): array => ['id' => $deal->id, 'name' => $this->name($deal)])
->sortBy('name')->all());
}

private function name(Sponsorship $deal): string
{
return $deal->tier === null ? $deal->sponsor->name : sprintf('%s (%s)', $deal->sponsor->name, $deal->tier->name);
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,9 @@
use PHPeste\Sponsors\Contracts\SponsorRevenue;
use PHPeste\Sponsors\Http\People;
use PHPeste\Sponsors\Overview\SponsorRevenueReport;
use PHPeste\Sponsors\Overview\SponsorshipTaskLinks;
use PHPeste\Sponsors\Overview\SponsorsOverviewContributor;
use PHPeste\Tasks\Contracts\TaskLinkProvider;

class SponsorsServiceProvider extends ServiceProvider
{
Expand All @@ -22,6 +24,7 @@ public function register(): void
$this->app->bind(SponsorRevenue::class, SponsorRevenueReport::class);
$this->app->tag([SponsorsOverviewContributor::class], EditionOverviewContributor::TAG);
$this->app->tag([SponsorTiersCloner::class], EditionCloner::TAG);
$this->app->tag([SponsorshipTaskLinks::class], TaskLinkProvider::TAG);
}

public function boot(): void {}
Expand Down
Loading
Loading