# Módulo de Notificações — Orvox Influencers

Este overlay adiciona um módulo completo de notificações internas para o painel do influencer, mantendo vínculo com `tenant_id` e `store_id` para a futura evolução mini-SaaS.

## Objetivo

Permitir que o admin envie notificações para influenciadores de forma individual, selecionada ou geral, com rastreabilidade de entrega/leitura e anexos privados.

Também inclui notificação automática quando um pagamento é marcado como pago.

## Tabelas criadas

### `notification_messages`

Mensagem principal enviada pelo admin ou pelo sistema.

Campos principais:

- `tenant_id`
- `store_id`
- `created_by_user_id`
- `type`: `manual`, `payment`, `system`, `campaign`
- `audience`: `all`, `selected`, `individual`
- `title`
- `body`
- `status`: `draft`, `sent`, `cancelled`
- `sent_at`
- `metadata`

### `notification_recipients`

Uma linha por influencer destinatário. Esta tabela garante rastreabilidade.

Campos principais:

- `notification_message_id`
- `tenant_id`
- `store_id`
- `influencer_id`
- `user_id`
- `status`: `delivered`, `read`
- `received_at`
- `read_at`
- `read_ip`
- `read_user_agent`

### `notification_attachments`

Arquivos anexados às notificações.

Campos principais:

- `notification_message_id`
- `tenant_id`
- `store_id`
- `uploaded_by_user_id`
- `disk`
- `path`
- `original_name`
- `mime_type`
- `size_bytes`

Os anexos ficam no disk `local` por padrão, ou seja, privados. O download passa por controller com validação de permissão.

## Arquivos principais

### Enums

- `app/Enums/NotificationType.php`
- `app/Enums/NotificationAudience.php`
- `app/Enums/NotificationStatus.php`
- `app/Enums/NotificationRecipientStatus.php`

### Models

- `app/Models/NotificationMessage.php`
- `app/Models/NotificationRecipient.php`
- `app/Models/NotificationAttachment.php`

### Service

- `app/Services/NotificationService.php`

Responsável por:

- enviar notificação para todos os influencers ativos da loja;
- enviar para influencers selecionados;
- enviar individual;
- salvar anexos;
- criar rastreabilidade por recipient;
- gerar notificação automática de pagamento pago.

### Controllers

Admin:

- `app/Http/Controllers/Admin/NotificationController.php`

Influencer:

- `app/Http/Controllers/Influencer/NotificationController.php`

### Observer

- `app/Observers/PaymentRecordObserver.php`

Quando um `PaymentRecord` é criado ou atualizado para `paid`, o observer cria uma notificação automática para o influencer.

## Rotas criadas

Admin:

```text
GET  /admin/notifications
GET  /admin/notifications/create
POST /admin/notifications
GET  /admin/notifications/{notification}
GET  /admin/notification-attachments/{attachment}/download
```

Influencer:

```text
GET /app/notifications
GET /app/notifications/{notification}
GET /app/notification-attachments/{attachment}/download
```

## Telas adicionadas

Admin:

- listagem de notificações;
- criação de notificação;
- detalhe com rastreabilidade por influencer;
- download de anexo.

Influencer:

- caixa de entrada;
- contador de não lidas no topo;
- detalhe da notificação;
- download de anexos permitidos.

## Configuração

Opcional no `.env`:

```env
NOTIFICATION_ATTACHMENTS_DISK=local
NOTIFICATION_ATTACHMENTS_MAX_KB=10240
```

## Testes adicionados

### Feature/Admin

`tests/Feature/Admin/NotificationManagementTest.php`

Cobre:

- envio geral para todos os influencers ativos;
- anexos;
- rastreabilidade por recipient;
- envio individual;
- bloqueio de envio para influencer de outro tenant/store.

### Feature/Influencer

`tests/Feature/Influencer/NotificationInboxTest.php`

Cobre:

- influencer vê notificações;
- leitura marca `read_at`, `read_ip`, `read_user_agent`;
- influencer não acessa notificação de outro influencer;
- download de anexo somente por destinatário autorizado.

### Feature

`tests/Feature/PaymentNotificationTest.php`

Cobre:

- pagamento marcado como pago gera notificação automática;
- notificação automática não duplica ao atualizar o registro.

### E2E

`tests/Feature/E2E/NotificationFlowE2ETest.php`

Simula fluxo completo:

1. admin envia notificação individual com anexo;
2. recipient é criado com tenant/store;
3. influencer vê na caixa de entrada;
4. influencer abre a notificação;
5. sistema registra leitura;
6. admin vê rastreabilidade como lida.

## Comandos

Após copiar o overlay:

```bash
./vendor/bin/sail artisan migrate
./vendor/bin/sail artisan optimize:clear
```

Rodar todos os testes do módulo:

```bash
./vendor/bin/sail test tests/Feature/Admin/NotificationManagementTest.php
./vendor/bin/sail test tests/Feature/Influencer/NotificationInboxTest.php
./vendor/bin/sail test tests/Feature/PaymentNotificationTest.php
./vendor/bin/sail test tests/Feature/E2E/NotificationFlowE2ETest.php
```

Ou tudo:

```bash
./vendor/bin/sail test
```

## Decisão SaaS

Todas as entidades principais carregam `tenant_id` e `store_id`. Mesmo que hoje exista apenas a Orvox, as notificações já nascem segregadas por cliente e loja.

A regra é:

- admin só enxerga notificações da store atual;
- influencer só enxerga recipients vinculados ao próprio `influencer_id`;
- envio geral materializa uma linha de recipient para cada influencer ativo no momento do envio.

Isso preserva histórico mesmo que o influencer seja inativado depois.