# Rotina de Limpeza de Avisos Expirados — Guia Operacional

> Ambiente: cPanel (Homologação / Produção) · sem acesso direto ao `php artisan`

---

## Arquitetura da Solução

A rotina funciona com **autenticação por token secreto** — sem necessidade de login via sessão ou CSRF.

```
Cron Job (cPanel)
    └── limpar_avisos_expirados.sh
            └── POST /api/notices/purge-expired
                    Header: X-Purge-Secret: <token>
                        └── APINoticesController::purgeExpired()
                                └── NoticeService::deleteExpiredNotices()
                                        └── DELETE FROM notices WHERE expires_at <= now()
```

> [!IMPORTANT]
> Esta abordagem foi escolhida porque o `bootstrap/app.php` do projeto não registra `api.php` separadamente — todas as rotas ficam sob o middleware `web` (com CSRF). Por isso, a rota de limpeza usa `withoutMiddleware(VerifyCsrfToken::class)` e se protege com o token secreto do `.env`.

---

## O que foi implementado no sistema

### 1 · Método `deleteExpiredNotices()` — NoticeService

```php
// app/Services/Notice/NoticeService.php
public function deleteExpiredNotices(): int
{
    $expired = Notice::withoutGlobalScopes()
        ->whereNotNull('expires_at')
        ->where('expires_at', '<=', now())
        ->get();

    $count = $expired->count();
    foreach ($expired as $notice) {
        $notice->delete();
    }
    return $count;
}
```

- Usa `withoutGlobalScopes()` para operar em **todos** os clientes e condomínios.
- Remove fisicamente os registros (`delete()`, não soft-delete).
- Retorna a quantidade de registros removidos.

---

### 2 · Rota de API — `POST /api/notices/purge-expired`

```php
// routes/api.php (fora do grupo auth:sanctum)
Route::post('/api/notices/purge-expired', [\App\Http\Controllers\Api\APINoticesController::class, 'purgeExpired'])
    ->withoutMiddleware([\Illuminate\Foundation\Http\Middleware\VerifyCsrfToken::class]);
```

### 3 · Controller — `APINoticesController::purgeExpired()`

```php
public function purgeExpired(Request $request): JsonResponse
{
    $secret = env('PURGE_NOTICES_SECRET');

    if (!$secret || $request->header('X-Purge-Secret') !== $secret) {
        return response()->json(['success' => false, 'message' => 'Não autorizado.'], 403);
    }

    $deleted = $this->noticeService->deleteExpiredNotices();

    return response()->json([
        'success' => true,
        'deleted' => $deleted,
        'message' => "Limpeza concluída. {$deleted} aviso(s) expirado(s) removido(s).",
    ]);
}
```

**Resposta de sucesso:**

```json
{
  "success": true,
  "deleted": 5,
  "message": "Limpeza concluída. 5 aviso(s) expirado(s) removido(s)."
}
```

### 4 · Variável de ambiente — `.env`

```env
# Limpeza automática de avisos expirados (Cron Job)
# Token secreto para acionar a rota /api/notices/purge-expired sem login
PURGE_NOTICES_SECRET=cereus-purge-secret-2026
```

> [!CAUTION]
> Em produção/homologação, gere um token forte: `openssl rand -hex 32`
> Nunca use o valor de exemplo acima em servidor real.

---

## Script Bash — `scripts/limpar_avisos_expirados.sh`

O script já está no repositório em `scripts/limpar_avisos_expirados.sh`. Para uso no cPanel, copie-o para o servidor.

```bash
#!/bin/bash
# =============================================================================
# limpar_avisos_expirados.sh
# Remove avisos expirados do mural via token secreto (sem necessidade de login).
# Lê APP_URL e PURGE_NOTICES_SECRET diretamente do arquivo .env do projeto.
# =============================================================================

SCRIPT_PATH=$(readlink -f "$0")
SCRIPTS_DIR=$(dirname "$SCRIPT_PATH")
PROJECT_ROOT=$(dirname "$SCRIPTS_DIR")
ENV_FILE="$PROJECT_ROOT/.env"

if [ ! -f "$ENV_FILE" ]; then
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] ERRO: Arquivo .env não encontrado em: $ENV_FILE" >&2
    exit 1
fi

# Carrega variáveis do .env (ignora comentários e linhas vazias)
export $(grep -v '^\s*#' "$ENV_FILE" | grep -v '^\s*$' | xargs) 2>/dev/null

TIMESTAMP="[$(date '+%Y-%m-%d %H:%M:%S')]"

if [ -z "$APP_URL" ]; then
    echo "$TIMESTAMP ERRO: APP_URL não definida no .env." >&2
    exit 1
fi

if [ -z "$PURGE_NOTICES_SECRET" ]; then
    echo "$TIMESTAMP ERRO: PURGE_NOTICES_SECRET não definida no .env." >&2
    exit 1
fi

echo "$TIMESTAMP Iniciando limpeza de avisos expirados em: $APP_URL"

RESPONSE=$(curl -s \
     --max-time 30 \
     -X POST "${APP_URL}/api/notices/purge-expired" \
     -H "Accept: application/json" \
     -H "X-Purge-Secret: ${PURGE_NOTICES_SECRET}")

echo "$TIMESTAMP Resposta da API: $RESPONSE"

if echo "$RESPONSE" | grep -q '"success":true'; then
    DELETED=$(echo "$RESPONSE" | grep -oP '(?<="deleted":)\d+')
    echo "$TIMESTAMP SUCESSO: $DELETED aviso(s) expirado(s) removido(s)."
    exit 0
else
    echo "$TIMESTAMP ERRO: A limpeza falhou. Verifique o PURGE_NOTICES_SECRET e a URL." >&2
    exit 1
fi
```

---

## Passo a Passo de Implantação no cPanel

### Passo 1 — Configurar o `.env` do servidor

Acesse o `.env` da aplicação no servidor (via File Manager do cPanel ou SSH) e adicione:

```env
PURGE_NOTICES_SECRET=seu-token-forte-aqui
```

Para gerar um token seguro via terminal SSH:

```bash
openssl rand -hex 32
```

### Passo 2 — Subir o script ao servidor

Via SSH ou File Manager, crie a pasta e copie o script:

```bash
mkdir -p /home/USUARIO/scripts
mkdir -p /home/USUARIO/logs
```

Copie o conteúdo de `scripts/limpar_avisos_expirados.sh` para `/home/USUARIO/scripts/limpar_avisos_expirados.sh` e dê permissão:

```bash
chmod +x /home/USUARIO/scripts/limpar_avisos_expirados.sh
```

> [!TIP]
> O script lê `APP_URL` e `PURGE_NOTICES_SECRET` diretamente do `.env` do projeto. Nenhum arquivo de credenciais separado é necessário.

### Passo 3 — Configurar o Cron Job no cPanel

No cPanel acesse: **Cron Jobs → Add New Cron Job**

Selecione **"Once a Day"** (ou configure manualmente):

| Campo | Valor |
|-------|-------|
| Minuto | `0` |
| Hora | `0` |
| Dia | `*` |
| Mês | `*` |
| Dia da Semana | `*` |

**Comando:**

```bash
/bin/bash /home/USUARIO/scripts/limpar_avisos_expirados.sh >> /home/USUARIO/logs/avisos_expirados.log 2>&1
```

> [!TIP]
> Substitua `USUARIO` pelo usuário real do cPanel.
> O diretório `/home/USUARIO/logs/` deve existir com permissão de escrita.

### Passo 4 — Verificar os logs

```bash
tail -f /home/USUARIO/logs/avisos_expirados.log
```

**Saída esperada em caso de sucesso:**

```
[2026-03-25 00:00:01] Iniciando limpeza de avisos expirados em: https://seu-dominio.com.br
[2026-03-25 00:00:02] Resposta da API: {"success":true,"deleted":3,"message":"Limpeza concluída. 3 aviso(s) expirado(s) removido(s)."}
[2026-03-25 00:00:02] SUCESSO: 3 aviso(s) expirado(s) removido(s).
```

---

## Testes em Ambiente de Desenvolvimento

### Pré-requisito: servidor Laravel em execução

O script chama a URL `APP_URL` — que em desenvolvimento local é `http://localhost:8000`. Para que funcione, o Laravel precisa estar servindo requisições.

```bash
# Terminal 1 — inicie o servidor Laravel
php artisan serve
```

### Executar o script manualmente

```bash
# Terminal 2 — execute a partir da raiz do projeto
bash scripts/limpar_avisos_expirados.sh
```

O script localiza automaticamente o `.env` na raiz do projeto (pasta pai de `scripts/`).

**Saída esperada:**

```
[2026-03-25 15:55:09] Iniciando limpeza de avisos expirados em: http://localhost:8000
[2026-03-25 15:55:09] Resposta da API: {"success":true,"deleted":0,"message":"Limpeza concluída. 0 aviso(s) expirado(s) removido(s)."}
[2026-03-25 15:55:09] SUCESSO: 0 aviso(s) expirado(s) removido(s).
```

> [!TIP]
> Para testar com avisos reais, crie um aviso no painel com data de expiração no passado e execute o script novamente.

---

## Resumo dos arquivos criados/modificados

| Arquivo | O que foi feito |
|---------|----------------|
| `app/Services/Notice/NoticeService.php` | Novo método `deleteExpiredNotices()` |
| `app/Http/Controllers/Api/APINoticesController.php` | Novo action `purgeExpired()` com validação por token secreto |
| `routes/api.php` | Rota `POST /api/notices/purge-expired` com `withoutMiddleware(VerifyCsrfToken)` |
| `.env` | Adicionada variável `PURGE_NOTICES_SECRET` |
| `.env.example` | Adicionada variável `PURGE_NOTICES_SECRET` como referência |
| `scripts/limpar_avisos_expirados.sh` | Script Bash final (no repositório) |

---

## Cuidados de Segurança

> [!WARNING]
> - O valor de `PURGE_NOTICES_SECRET` **nunca deve ser versionado** no Git — ele fica apenas no `.env` do servidor.
> - Em produção, use um token gerado com `openssl rand -hex 32` — nunca use valores simples ou previsíveis.
> - A rota não exige autenticação de usuário, mas **sem o token correto retorna HTTP 403** imediatamente.
> - O `.env` no servidor deve ter permissão restrita: `chmod 600 /caminho/.env`.
