sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install -y php8.2 php8.2-cli php8.2-common php8.2-curl php8.2-mbstring php8.2-xml php8.2-zip

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

sudo apt-get install php8.2-pgsql
# Windows: habilite 'extension=pgsql' e 'extension=pdo_pgsql' no php.ini

sudo apt-get install php8.2-mysql
# Windows: habilite 'extension=mysqli' e 'extension=pdo_mysql' no php.ini

# Remove versões antigas
sudo apt-get remove -y docker docker-engine docker.io containerd runc

# Instala dependências
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# Adiciona chave GPG oficial do Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Adiciona repositório
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Instala Docker Engine + Compose plugin
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Permite rodar sem sudo (requer logout/login)
sudo usermod -aG docker $USER

# Apenas PostgreSQL (recomendado)
docker compose up -d postgres

# Apenas MySQL
docker compose up -d mysql

# PostgreSQL + Adminer (interface web na porta 8080)
docker compose up -d postgres adminer

# Tudo (PostgreSQL + MySQL + Adminer)
docker compose up -d

docker compose down          # para e remove containers (dados preservados)
docker compose down -v       # para e remove containers + volumes (apaga dados)

git clone https://github.com/vupi.us/api_vupi.us_php.git
cd api_vupi.us_php

composer install

php vupi setup

php vupi setup --auto --db-mode=docker --server=php --jwt=if-empty

git clone https://github.com/vupi.us/api_vupi.us_php.git
cd api_vupi.us_php
sudo bash install.sh

cp EXEMPLO.env .env

# Gera JWT_SECRET (64 chars hex)
openssl rand -hex 32

# Gera JWT_API_SECRET (64 chars hex)
openssl rand -hex 32

# Ou via CLI do projeto (gera automaticamente se vazios)
php vupi setup --auto --jwt=if-empty

// Rota pública — sem middleware
$router->get('/api/status', [StatusController::class, 'index']);

// Rota autenticada
$router->get('/api/perfil', [PerfilController::class, 'index'], [
    AuthHybridMiddleware::class,
]);

// Rota admin com rate limit
$router->post('/api/usuarios', [UsuarioController::class, 'criar'], [
    AuthHybridMiddleware::class,
    AdminOnlyMiddleware::class,
    [RateLimitMiddleware::class, ['limit' => 5, 'window' => 60, 'key' => 'usuario.criar']],
]);

// Response JSON
return Response::json(['status' => 'ok', 'data' => $dados]);
return Response::json(['error' => 'Não encontrado'], 404);

// Response HTML
return Response::html($html);

// Acessar dados da requisição
$body    = $request->body;          // array do JSON body
$query   = $request->query;         // query string params
$usuario = $request->attribute('auth_user'); // injetado pelo AuthMiddleware
$uuid    = $request->param('uuid');  // parâmetro de rota {uuid}

mkdir -p src/Modules/Usuario/{Controllers,Services,Repositories,Entities,Exceptions,Database/Migrations,Database/Seeders,Routes}

php vupi make:module Usuario

<?php
namespace Src\Modules\Usuario\Exceptions;

class DomainException extends \DomainException {}

<?php
namespace Src\Modules\Usuario\Exceptions;

class InvalidEmailException extends DomainException {}

<?php
namespace Src\Modules\Usuario\Exceptions;

class InvalidPasswordException extends DomainException {}

<?php
namespace Src\Modules\Usuario\Exceptions;

class InvalidUsernameException extends DomainException {}

<?php
namespace Src\Modules\Usuario\Entities;

use DateTimeImmutable;
use Ramsey\Uuid\Uuid;
use Ramsey\Uuid\UuidInterface;
use Src\Kernel\Utils\RelogioTimeZone;
use Src\Modules\Usuario\Exceptions\InvalidEmailException;
use Src\Modules\Usuario\Exceptions\InvalidPasswordException;
use Src\Modules\Usuario\Exceptions\InvalidUsernameException;

final class Usuario
{
    private const NIVEIS_VALIDOS = ['usuario', 'admin', 'moderador', 'admin_system'];

    private function __construct(
        private UuidInterface      $uuid,
        private string             $nomeCompleto,
        private string             $username,
        private string             $email,
        private string             $senhaHash,
        private string             $nivelAcesso,
        private bool               $ativo,
        private bool               $verificado_email,
        private DateTimeImmutable  $criadoEm,
        private ?string            $urlAvatar             = null,
        private ?string            $urlCapa               = null,
        private ?string            $biografia             = null,
        private ?string            $tokenRecuperacaoSenha = null,
        private ?string            $tokenVerificacaoEmail = null,
        private ?DateTimeImmutable $atualizadoEm          = null,
        private string             $statusVerificacao     = 'Não verificado'
    ) {}

    // ── Factories ────────────────────────────────────────────────────────

    /** Cria um novo usuário com validações completas. */
    public static function registrar(
        string  $nomeCompleto,
        string  $username,
        string  $email,
        string  $senha,
        ?string $urlAvatar         = null,
        ?string $urlCapa           = null,
        ?string $biografia         = null,
        string  $nivelAcesso       = 'usuario',
        bool    $verificado_email  = false,
        string  $statusVerificacao = 'Não verificado'
    ): self {
        $username = strtolower(trim($username));
        self::validarUsername($username);
        self::validarEmail($email);
        self::validarSenha($senha);
        self::validarNivelAcesso($nivelAcesso);

        return new self(
            Uuid::uuid4(),
            $nomeCompleto,
            $username,
            $email,
            password_hash($senha, PASSWORD_ARGON2ID),
            $nivelAcesso,
            true,
            $verificado_email,
            RelogioTimeZone::agora(),
            $urlAvatar,
            $urlCapa,
            $biografia,
            null,
            null,
            null,
            $statusVerificacao
        );
    }

    /** Reconstitui um usuário a partir dos dados do banco. */
    public static function reconstituir(
        UuidInterface      $uuid,
        string             $nomeCompleto,
        string             $username,
        string             $email,
        string             $senhaHash,
        string             $nivelAcesso,
        bool               $ativo,
        bool               $verificado_email,
        DateTimeImmutable  $criadoEm,
        ?string            $urlAvatar             = null,
        ?string            $urlCapa               = null,
        ?string            $biografia             = null,
        ?string            $tokenRecuperacaoSenha = null,
        ?string            $tokenVerificacaoEmail = null,
        ?DateTimeImmutable $atualizadoEm          = null,
        string             $statusVerificacao     = 'Não verificado'
    ): self {
        return new self(
            $uuid, $nomeCompleto, strtolower(trim($username)), $email, $senhaHash,
            $nivelAcesso, $ativo, $verificado_email, $criadoEm,
            $urlAvatar, $urlCapa, $biografia,
            $tokenRecuperacaoSenha, $tokenVerificacaoEmail, $atualizadoEm, $statusVerificacao
        );
    }

    // ── Validações privadas ───────────────────────────────────────────────

    private static function validarEmail(string $email): void
    {
        if (trim($email) === '') throw new InvalidEmailException('E-mail não informado.');
        if (!filter_var($email, FILTER_VALIDATE_EMAIL))
            throw new InvalidEmailException('Formato de e-mail inválido.');
    }

    private static function validarUsername(string $u): void
    {
        if (trim($u) === '') throw new InvalidUsernameException('Username não informado.');
        if (preg_match('/^[._]/', $u))
            throw new InvalidUsernameException('Username não pode iniciar com ponto ou underline.');
        if (strlen($u) < 3)
            throw new InvalidUsernameException('Username deve ter ao menos 3 caracteres.');
        if (!preg_match('/^[a-z0-9._]+$/', $u))
            throw new InvalidUsernameException('Username só pode conter letras minúsculas, números, ponto ou underline.');
        if (preg_match_all('/[._]/', $u) > 1)
            throw new InvalidUsernameException('Username pode conter apenas um caractere especial (ponto ou underline).');
    }

    private static function validarSenha(string $s): void
    {
        if (trim($s) === '') throw new InvalidPasswordException('Senha não informada.');
        if (strlen($s) < 8)  throw new InvalidPasswordException('Senha muito curta. Mínimo 8 caracteres.');
        if (!preg_match('/[A-Z]/', $s)) throw new InvalidPasswordException('Senha deve conter ao menos uma letra maiúscula.');
        if (!preg_match('/[a-z]/', $s)) throw new InvalidPasswordException('Senha deve conter ao menos uma letra minúscula.');
        if (!preg_match('/[0-9]/', $s)) throw new InvalidPasswordException('Senha deve conter ao menos um número.');
        if (!preg_match('/[^a-zA-Z0-9]/', $s)) throw new InvalidPasswordException('Senha deve conter ao menos um caractere especial.');
    }

    private static function validarNivelAcesso(string $nivel): void
    {
        if (!in_array($nivel, self::NIVEIS_VALIDOS, true))
            throw new \InvalidArgumentException('Nível de acesso inválido.');
    }

    // ── Comportamentos ────────────────────────────────────────────────────

    public function verificarSenha(string $senhaPlana): bool
    {
        return password_verify($senhaPlana, $this->senhaHash);
    }

    public function alterarSenha(string $senhaPlana): void
    {
        self::validarSenha($senhaPlana);
        $this->senhaHash  = password_hash($senhaPlana, PASSWORD_ARGON2ID);
        $this->atualizadoEm = RelogioTimeZone::agora();
    }

    public function promoverPara(string $nivelAcesso): void
    {
        self::validarNivelAcesso($nivelAcesso);
        $this->nivelAcesso  = $nivelAcesso;
        $this->atualizadoEm = RelogioTimeZone::agora();
    }

    public function ativar(): void   { $this->ativo = true;  $this->atualizadoEm = RelogioTimeZone::agora(); }
    public function desativar(): void { $this->ativo = false; $this->atualizadoEm = RelogioTimeZone::agora(); }

    public function gerarTokenVerificacaoEmail(string $token): void
    {
        $this->tokenVerificacaoEmail = $token;
        $this->atualizadoEm = RelogioTimeZone::agora();
    }

    public function gerarTokenRecuperacaoSenha(string $token): void
    {
        $this->tokenRecuperacaoSenha = $token;
        $this->atualizadoEm = RelogioTimeZone::agora();
    }

    // ── Getters ───────────────────────────────────────────────────────────

    public function getUuid(): UuidInterface            { return $this->uuid; }
    public function getNomeCompleto(): string           { return $this->nomeCompleto; }
    public function getUsername(): string               { return $this->username; }
    public function getEmail(): string                  { return $this->email; }
    public function getSenhaHash(): string              { return $this->senhaHash; }
    public function getNivelAcesso(): string            { return $this->nivelAcesso; }
    public function isAtivo(): bool                     { return $this->ativo; }
    public function isEmailVerificado(): bool           { return $this->verificado_email; }
    public function getStatusVerificacao(): string      { return $this->statusVerificacao; }
    public function getUrlAvatar(): ?string             { return $this->urlAvatar; }
    public function getUrlCapa(): ?string               { return $this->urlCapa; }
    public function getBiografia(): ?string             { return $this->biografia; }
    public function getCriadoEm(): DateTimeImmutable    { return $this->criadoEm; }
    public function getAtualizadoEm(): ?DateTimeImmutable { return $this->atualizadoEm; }
    public function getTokenVerificacaoEmail(): ?string { return $this->tokenVerificacaoEmail; }
    public function getTokenRecuperacaoSenha(): ?string { return $this->tokenRecuperacaoSenha; }

    // ── Setters ───────────────────────────────────────────────────────────

    public function setNomeCompleto(string $v): void    { $this->nomeCompleto = $v; }
    public function setUsername(string $v): void        { self::validarUsername(strtolower(trim($v))); $this->username = strtolower(trim($v)); }
    public function setEmail(string $v): void           { self::validarEmail($v); $this->email = $v; }
    public function setUrlAvatar(?string $v): void      { $this->urlAvatar = $v; }
    public function setUrlCapa(?string $v): void        { $this->urlCapa = $v; }
    public function setBiografia(?string $v): void      { $this->biografia = $v; }
    public function setEmailVerificado(bool $v): void   { $this->verificado_email = $v; }
    public function setStatusVerificacao(string $v): void { $this->statusVerificacao = $v; }
    public function setAtualizadoEm(?DateTimeImmutable $v): void { $this->atualizadoEm = $v; }
    public function setCriadoEm(DateTimeImmutable $v): void      { $this->criadoEm = $v; }
}

<?php
namespace Src\Modules\Usuario\Repositories;

use Src\Kernel\Contracts\UserRepositoryInterface;
use Src\Modules\Usuario\Entities\Usuario;

interface UsuarioRepositoryInterface extends UserRepositoryInterface
{
    public function salvar(Usuario $usuario): void;
    public function deletar(string $uuid): void;
    public function buscarPorUuid(string $uuid): ?Usuario;
    public function buscarPorEmail(string $email): ?Usuario;
    public function buscarPorUsername(string $username): ?Usuario;
    public function buscarTodos(int $limite = 100, int $offset = 0): array;
    public function contar(): int;
    public function emailExiste(string $email, ?string $excluirUuid = null): bool;
    public function usernameExiste(string $username, ?string $excluirUuid = null): bool;
    public function salvarTokenVerificacaoEmail(string $uuid, string $token): void;
    public function buscarPorTokenVerificacaoEmail(string $token): ?Usuario;
    public function marcarEmailComoVerificado(string $uuid, bool $verificado = true): void;
    public function salvarTokenRecuperacaoSenha(string $uuid, string $token): void;
    public function buscarPorTokenRecuperacaoSenha(string $token): ?Usuario;
    public function limparTokenRecuperacaoSenha(string $uuid): void;
    public function buscarPorNomePaginado(string $nome, int $pagina = 1, int $porPagina = 10): array;
    public function buscarComFiltro(int $pagina, int $porPagina, string $busca = '', string $nivel = ''): array;
    public function listarUsernamesAtivos(int $limite = 50000, int $offset = 0): array;
}

<?php
namespace Src\Modules\Usuario\Services;

use Src\Modules\Usuario\Entities\Usuario;

interface UsuarioServiceInterface
{
    public function emailExiste(string $email): bool;
    public function usernameExiste(string $username): bool;
    public function criar(Usuario $usuario): void;
    public function atualizar(string $uuid, array $dados): void;
    public function buscarPorUuid(string $uuid): ?Usuario;
    public function buscarPorUsername(string $username): ?Usuario;
    public function buscarPorEmail(string $email): ?Usuario;
    public function salvarTokenVerificacaoEmail(string $uuid, string $token): void;
    public function buscarPorTokenVerificacaoEmail(string $token): ?Usuario;
    public function marcarEmailComoVerificado(string $uuid): void;
    public function resetarVerificacaoEmail(string $uuid): void;
    public function salvarTokenRecuperacaoSenha(string $uuid, string $token): void;
    public function buscarPorTokenRecuperacaoSenha(string $token): ?Usuario;
    public function limparTokenRecuperacaoSenha(string $uuid): void;
    public function verificarSenha(string $uuid, string $senha): bool;
    public function alterarSenha(string $uuid, string $novaSenha, bool $logoutAll = false): void;
    public function listar(int $pagina = 1, int $porPagina = 20): array;
    public function listarComFiltro(int $pagina, int $porPagina, string $busca = '', string $nivel = ''): array;
    public function desativar(string $uuid): void;
    public function ativar(string $uuid): void;
    public function deletar(string $uuid): void;
    public function listarUsernamesAtivosParaSitemap(int $limite = 50000, int $offset = 0): array;
}

<?php
namespace Src\Modules\Usuario\Repositories;

use PDO;
use PDOException;
use DateTimeImmutable;
use Ramsey\Uuid\Uuid;
use Src\Modules\Usuario\Entities\Usuario;

abstract class UsuarioAbstractRepository implements UsuarioRepositoryInterface
{
    protected string $tabela   = 'usuarios';
    protected string $colunaId = 'uuid';
    protected array  $colunasPermitidas = [
        'email'              => 'email',
        'username'           => 'username',
        'nivel_acesso'       => 'nivel_acesso',
        'ativo'              => 'ativo',
        'status_verificacao' => 'status_verificacao',
    ];

    public function __construct(protected PDO $pdo) {}

    protected function executarQuery(callable $op, string $msg = 'Erro no banco')
    {
        try {
            return $op();
        } catch (PDOException $e) {
            throw new \RuntimeException($msg . ': ' . $e->getMessage(), (int) $e->getCode(), $e);
        }
    }

    public function buscarTodos(int $limite = 100, int $offset = 0): array
    {
        return $this->executarQuery(function () use ($limite, $offset) {
            $stmt = $this->pdo->prepare(
                "SELECT * FROM {$this->tabela} ORDER BY criado_em DESC LIMIT :l OFFSET :o"
            );
            $stmt->bindValue(':l', $limite, PDO::PARAM_INT);
            $stmt->bindValue(':o', $offset, PDO::PARAM_INT);
            $stmt->execute();
            return array_map([$this, 'mapearParaEntity'], $stmt->fetchAll(PDO::FETCH_ASSOC));
        }, 'Erro ao buscar usuários');
    }

    public function buscarPorUuid(string $uuid): ?Usuario    { return $this->buscarUmPor($this->colunaId, $uuid); }
    public function buscarPorUsername(string $u): ?Usuario   { return $this->buscarUmPor('username', $u); }
    public function buscarPorEmail(string $e): ?Usuario      { return $this->buscarUmPor('email', $e); }

    public function deletar(string $uuid): void
    {
        $this->executarQuery(function () use ($uuid) {
            $stmt = $this->pdo->prepare("DELETE FROM {$this->tabela} WHERE {$this->colunaId} = :uuid");
            $stmt->bindValue(':uuid', $uuid);
            $stmt->execute();
        }, 'Erro ao deletar usuário');
    }

    public function contar(): int
    {
        return $this->executarQuery(function () {
            return (int) $this->pdo->query("SELECT COUNT(*) FROM {$this->tabela}")->fetchColumn();
        }, 'Erro ao contar usuários');
    }

    public function emailExiste(string $email, ?string $excluirUuid = null): bool
    {
        $sql    = "SELECT 1 FROM {$this->tabela} WHERE email = :email";
        $params = [':email' => $email];
        if ($excluirUuid) { $sql .= " AND {$this->colunaId} != :uuid"; $params[':uuid'] = $excluirUuid; }
        $stmt = $this->pdo->prepare($sql);
        $stmt->execute($params);
        return $stmt->fetchColumn() !== false;
    }

    public function usernameExiste(string $username, ?string $excluirUuid = null): bool
    {
        $sql    = "SELECT 1 FROM {$this->tabela} WHERE username = :username";
        $params = [':username' => $username];
        if ($excluirUuid) { $sql .= " AND {$this->colunaId} != :uuid"; $params[':uuid'] = $excluirUuid; }
        $stmt = $this->pdo->prepare($sql);
        $stmt->execute($params);
        return $stmt->fetchColumn() !== false;
    }

    public function salvarTokenVerificacaoEmail(string $uuid, string $token): void
    {
        $stmt = $this->pdo->prepare(
            "UPDATE {$this->tabela} SET token_verificacao_email = :token WHERE {$this->colunaId} = :uuid"
        );
        $stmt->execute([':token' => $token, ':uuid' => $uuid]);
    }

    public function buscarPorTokenVerificacaoEmail(string $token): ?Usuario
    {
        if (empty($token)) return null;
        $stmt = $this->pdo->prepare(
            "SELECT * FROM {$this->tabela} WHERE token_verificacao_email = :token LIMIT 1"
        );
        $stmt->execute([':token' => $token]);
        $row = $stmt->fetch(PDO::FETCH_ASSOC);
        return $row ? $this->mapearParaEntity($row) : null;
    }

    public function marcarEmailComoVerificado(string $uuid, bool $verificado = true): void
    {
        $sql = $verificado
            ? "UPDATE {$this->tabela} SET verificado_email = :v, token_verificacao_email = NULL WHERE {$this->colunaId} = :uuid"
            : "UPDATE {$this->tabela} SET verificado_email = :v WHERE {$this->colunaId} = :uuid";
        $stmt = $this->pdo->prepare($sql);
        $stmt->bindValue(':v', $verificado, PDO::PARAM_BOOL);
        $stmt->bindValue(':uuid', $uuid);
        $stmt->execute();
    }

    public function salvarTokenRecuperacaoSenha(string $uuid, string $token): void
    {
        $stmt = $this->pdo->prepare(
            "UPDATE {$this->tabela} SET token_recuperacao_senha = :token WHERE {$this->colunaId} = :uuid"
        );
        $stmt->execute([':token' => $token, ':uuid' => $uuid]);
    }

    public function buscarPorTokenRecuperacaoSenha(string $token): ?Usuario
    {
        $stmt = $this->pdo->prepare(
            "SELECT * FROM {$this->tabela} WHERE token_recuperacao_senha = :token LIMIT 1"
        );
        $stmt->execute([':token' => $token]);
        $row = $stmt->fetch(PDO::FETCH_ASSOC);
        return $row ? $this->mapearParaEntity($row) : null;
    }

    public function limparTokenRecuperacaoSenha(string $uuid): void
    {
        $stmt = $this->pdo->prepare(
            "UPDATE {$this->tabela} SET token_recuperacao_senha = NULL WHERE {$this->colunaId} = :uuid"
        );
        $stmt->execute([':uuid' => $uuid]);
    }

    public function buscarPorNomePaginado(string $nome, int $pagina = 1, int $porPagina = 10): array
    {
        $offset = ($pagina - 1) * $porPagina;
        $stmt   = $this->pdo->prepare(
            "SELECT * FROM {$this->tabela} WHERE nome_completo LIKE :nome ORDER BY criado_em DESC LIMIT :l OFFSET :o"
        );
        $stmt->bindValue(':nome', "%{$nome}%");
        $stmt->bindValue(':l', $porPagina, PDO::PARAM_INT);
        $stmt->bindValue(':o', $offset, PDO::PARAM_INT);
        $stmt->execute();
        return array_map([$this, 'mapearParaEntity'], $stmt->fetchAll(PDO::FETCH_ASSOC));
    }

    public function buscarComFiltro(int $pagina, int $porPagina, string $busca = '', string $nivel = ''): array
    {
        $offset = ($pagina - 1) * $porPagina;
        $params = [];
        $where  = [];
        if ($busca !== '') { $where[] = "(username LIKE :busca OR email LIKE :busca)"; $params[':busca'] = '%' . $busca . '%'; }
        if ($nivel !== '') { $where[] = "nivel_acesso = :nivel"; $params[':nivel'] = $nivel; }
        $wc = $where ? 'WHERE ' . implode(' AND ', $where) : '';

        $stmtCount = $this->pdo->prepare("SELECT COUNT(*) FROM {$this->tabela} {$wc}");
        $stmtCount->execute($params);
        $total = (int) $stmtCount->fetchColumn();

        $stmtRows = $this->pdo->prepare(
            "SELECT * FROM {$this->tabela} {$wc} ORDER BY criado_em DESC LIMIT :l OFFSET :o"
        );
        foreach ($params as $k => $v) $stmtRows->bindValue($k, $v);
        $stmtRows->bindValue(':l', $porPagina, PDO::PARAM_INT);
        $stmtRows->bindValue(':o', $offset, PDO::PARAM_INT);
        $stmtRows->execute();

        return [
            'usuarios'      => array_map([$this, 'mapearParaEntity'], $stmtRows->fetchAll(PDO::FETCH_ASSOC) ?: []),
            'total'         => $total,
            'total_paginas' => max(1, (int) ceil($total / $porPagina)),
        ];
    }

    public function listarUsernamesAtivos(int $limite = 50000, int $offset = 0): array
    {
        $stmt = $this->pdo->prepare(
            "SELECT username, atualizado_em, criado_em FROM {$this->tabela}
             WHERE ativo = :ativo AND username IS NOT NULL AND username <> ''
             ORDER BY criado_em DESC LIMIT :l OFFSET :o"
        );
        $stmt->bindValue(':ativo', true, PDO::PARAM_BOOL);
        $stmt->bindValue(':l', $limite, PDO::PARAM_INT);
        $stmt->bindValue(':o', $offset, PDO::PARAM_INT);
        $stmt->execute();
        return $stmt->fetchAll(PDO::FETCH_ASSOC) ?: [];
    }

    protected function buscarUmPor(string $coluna, mixed $valor): ?Usuario
    {
        $col  = $this->resolverColuna($coluna);
        $sql  = $col === 'username'
            ? "SELECT * FROM {$this->tabela} WHERE LOWER({$col}) = LOWER(:valor) LIMIT 1"
            : "SELECT * FROM {$this->tabela} WHERE {$col} = :valor LIMIT 1";
        $stmt = $this->pdo->prepare($sql);
        $stmt->bindValue(':valor', $valor);
        $stmt->execute();
        $row = $stmt->fetch(PDO::FETCH_ASSOC);
        return $row ? $this->mapearParaEntity($row) : null;
    }

    protected function resolverColuna(string $coluna): string
    {
        if ($coluna === $this->colunaId) return $this->colunaId;
        if (isset($this->colunasPermitidas[$coluna])) return $this->colunasPermitidas[$coluna];
        throw new \InvalidArgumentException('Coluna inválida para busca');
    }

    protected function mapearParaEntity(array $dados): Usuario
    {
        return Usuario::reconstituir(
            Uuid::fromString($dados['uuid']),
            $dados['nome_completo'],
            $dados['username'],
            $dados['email'],
            $dados['senha_hash'],
            $dados['nivel_acesso'],
            (bool) $dados['ativo'],
            (bool) $dados['verificado_email'],
            new DateTimeImmutable($dados['criado_em']),
            $dados['url_avatar']             ?? null,
            $dados['url_capa']               ?? null,
            $dados['biografia']              ?? null,
            $dados['token_recuperacao_senha'] ?? null,
            $dados['token_verificacao_email'] ?? null,
            isset($dados['atualizado_em']) ? new DateTimeImmutable((string) $dados['atualizado_em']) : null,
            $dados['status_verificacao']     ?? 'Não verificado'
        );
    }

    abstract public function salvar(Usuario $usuario): void;
}

<?php
namespace Src\Modules\Usuario\Repositories;

use PDO;
use Src\Kernel\Contracts\UserRepositoryInterface;
use Src\Modules\Usuario\Entities\Usuario;
use Src\Kernel\Utils\RelogioTimeZone;

class UsuarioRepository extends UsuarioAbstractRepository implements UserRepositoryInterface
{
    public function __construct(PDO $pdo)
    {
        parent::__construct($pdo);
    }

    public function salvar(Usuario $usuario): void
    {
        $this->executarQuery(function () use ($usuario) {
            $agora  = RelogioTimeZone::agora()->format('Y-m-d H:i:s');
            $uuid   = $usuario->getUuid()->toString();
            $driver = $this->pdo->getAttribute(PDO::ATTR_DRIVER_NAME);

            if ($driver === 'pgsql') {
                $sql = "INSERT INTO {$this->tabela}
                            (uuid, nome_completo, email, username, senha_hash, url_avatar, url_capa,
                             biografia, nivel_acesso, ativo, status_verificacao, token_verificacao_email, criado_em)
                        VALUES
                            (:uuid, :nome_completo, :email, :username, :senha_hash, :url_avatar, :url_capa,
                             :biografia, :nivel_acesso, :ativo, :status_verificacao, :token_verificacao_email, :criado_em)
                        ON CONFLICT ({$this->colunaId}) DO UPDATE SET
                            nome_completo           = EXCLUDED.nome_completo,
                            email                   = EXCLUDED.email,
                            username                = EXCLUDED.username,
                            senha_hash              = EXCLUDED.senha_hash,
                            url_avatar              = EXCLUDED.url_avatar,
                            url_capa                = EXCLUDED.url_capa,
                            biografia               = EXCLUDED.biografia,
                            nivel_acesso            = EXCLUDED.nivel_acesso,
                            ativo                   = EXCLUDED.ativo,
                            status_verificacao      = EXCLUDED.status_verificacao,
                            token_verificacao_email = EXCLUDED.token_verificacao_email,
                            atualizado_em           = NOW()";
            } else {
                $sql = "INSERT INTO {$this->tabela}
                            (uuid, nome_completo, email, username, senha_hash, url_avatar, url_capa,
                             biografia, nivel_acesso, ativo, status_verificacao, token_verificacao_email, criado_em)
                        VALUES
                            (:uuid, :nome_completo, :email, :username, :senha_hash, :url_avatar, :url_capa,
                             :biografia, :nivel_acesso, :ativo, :status_verificacao, :token_verificacao_email, :criado_em)
                        ON DUPLICATE KEY UPDATE
                            nome_completo           = VALUES(nome_completo),
                            email                   = VALUES(email),
                            username                = VALUES(username),
                            senha_hash              = VALUES(senha_hash),
                            url_avatar              = VALUES(url_avatar),
                            url_capa                = VALUES(url_capa),
                            biografia               = VALUES(biografia),
                            nivel_acesso            = VALUES(nivel_acesso),
                            ativo                   = VALUES(ativo),
                            status_verificacao      = VALUES(status_verificacao),
                            token_verificacao_email = VALUES(token_verificacao_email),
                            atualizado_em           = :atualizado_em";
            }

            $stmt = $this->pdo->prepare($sql);
            $stmt->bindValue(':uuid',                    $uuid);
            $stmt->bindValue(':nome_completo',           $usuario->getNomeCompleto());
            $stmt->bindValue(':email',                   $usuario->getEmail());
            $stmt->bindValue(':username',                $usuario->getUsername());
            $stmt->bindValue(':senha_hash',              $usuario->getSenhaHash());
            $stmt->bindValue(':url_avatar',              $usuario->getUrlAvatar());
            $stmt->bindValue(':url_capa',                $usuario->getUrlCapa());
            $stmt->bindValue(':biografia',               $usuario->getBiografia());
            $stmt->bindValue(':nivel_acesso',            $usuario->getNivelAcesso());
            $stmt->bindValue(':ativo',                   $usuario->isAtivo(), PDO::PARAM_BOOL);
            $stmt->bindValue(':status_verificacao',      $usuario->getStatusVerificacao());
            $stmt->bindValue(':token_verificacao_email', $usuario->getTokenVerificacaoEmail());
            $stmt->bindValue(':criado_em',               $agora);
            if ($driver !== 'pgsql') {
                $stmt->bindValue(':atualizado_em', $agora);
            }
            $stmt->execute();
        }, 'Erro ao salvar usuário');
    }
}

<?php
namespace Src\Modules\Usuario\Services;

use DomainException;
use DateTimeImmutable;
use Src\Modules\Usuario\Entities\Usuario;
use Src\Modules\Usuario\Repositories\UsuarioRepositoryInterface;

class UsuarioService implements UsuarioServiceInterface
{
    public function __construct(
        private UsuarioRepositoryInterface $repository
    ) {}

    public function emailExiste(string $email): bool    { return $this->repository->emailExiste($email); }
    public function usernameExiste(string $u): bool     { return $this->repository->usernameExiste($u); }
    public function buscarPorUuid(string $uuid): ?Usuario    { return $this->repository->buscarPorUuid($uuid); }
    public function buscarPorUsername(string $u): ?Usuario   { return $this->repository->buscarPorUsername($u); }
    public function buscarPorEmail(string $e): ?Usuario      { return $this->repository->buscarPorEmail($e); }

    public function criar(Usuario $usuario): void
    {
        if ($this->repository->emailExiste($usuario->getEmail()))
            throw new DomainException('E-mail já cadastrado.', 409);
        if ($this->repository->usernameExiste($usuario->getUsername()))
            throw new DomainException('Username já cadastrado.', 409);
        $this->repository->salvar($usuario);
    }

    public function atualizar(string $uuid, array $data): void
    {
        $usuario = $this->repository->buscarPorUuid($uuid);
        if (!$usuario) throw new DomainException('Usuário não encontrado.', 404);

        if (isset($data['nome_completo'])) $usuario->setNomeCompleto($data['nome_completo']);
        if (isset($data['username']))      $usuario->setUsername($data['username']);
        if (isset($data['email']))         $usuario->setEmail($data['email']);
        if (isset($data['senha']))         $usuario->alterarSenha($data['senha']);
        if (isset($data['url_avatar']))    $usuario->setUrlAvatar($data['url_avatar']);
        if (isset($data['url_capa']))      $usuario->setUrlCapa($data['url_capa']);
        if (isset($data['biografia']))     $usuario->setBiografia($data['biografia']);
        if (isset($data['nivel_acesso']))  $usuario->promoverPara($data['nivel_acesso']);
        $usuario->setAtualizadoEm(new DateTimeImmutable());

        if ($this->repository->emailExiste($usuario->getEmail(), $uuid))
            throw new DomainException('E-mail já cadastrado.', 409);
        if ($this->repository->usernameExiste($usuario->getUsername(), $uuid))
            throw new DomainException('Username já cadastrado.', 409);

        $this->repository->salvar($usuario);
    }

    public function alterarSenha(string $uuid, string $novaSenha, bool $logoutAll = false): void
    {
        $usuario = $this->repository->buscarPorUuid($uuid);
        if (!$usuario) throw new DomainException('Usuário não encontrado.', 404);
        $usuario->alterarSenha($novaSenha);
        $this->repository->salvar($usuario);
    }

    public function verificarSenha(string $uuid, string $senha): bool
    {
        $usuario = $this->repository->buscarPorUuid($uuid);
        return $usuario ? $usuario->verificarSenha($senha) : false;
    }

    public function desativar(string $uuid): void
    {
        $usuario = $this->repository->buscarPorUuid($uuid);
        if (!$usuario) throw new DomainException('Usuário não encontrado.', 404);
        $usuario->desativar();
        $this->repository->salvar($usuario);
    }

    public function ativar(string $uuid): void
    {
        $usuario = $this->repository->buscarPorUuid($uuid);
        if (!$usuario) throw new DomainException('Usuário não encontrado.', 404);
        $usuario->ativar();
        $this->repository->salvar($usuario);
    }

    public function deletar(string $uuid): void
    {
        $usuario = $this->repository->buscarPorUuid($uuid);
        if (!$usuario) throw new DomainException('Usuário não encontrado.', 404);
        $this->repository->deletar($uuid);
    }

    public function listar(int $pagina = 1, int $porPagina = 20): array
    {
        return $this->repository->buscarPorNomePaginado('', $pagina, $porPagina);
    }

    public function listarComFiltro(int $pagina, int $porPagina, string $busca = '', string $nivel = ''): array
    {
        return $this->repository->buscarComFiltro($pagina, $porPagina, $busca, $nivel);
    }

    public function salvarTokenVerificacaoEmail(string $uuid, string $token): void
    {
        $usuario = $this->repository->buscarPorUuid($uuid);
        if (!$usuario) throw new DomainException('Usuário não encontrado.', 404);
        $usuario->gerarTokenVerificacaoEmail($token);
        $this->repository->salvarTokenVerificacaoEmail($uuid, $token);
    }

    public function buscarPorTokenVerificacaoEmail(string $token): ?Usuario
    {
        return $this->repository->buscarPorTokenVerificacaoEmail($token);
    }

    public function marcarEmailComoVerificado(string $uuid): void
    {
        if (!$this->repository->buscarPorUuid($uuid))
            throw new DomainException('Usuário não encontrado.', 404);
        $this->repository->marcarEmailComoVerificado($uuid);
    }

    public function resetarVerificacaoEmail(string $uuid): void
    {
        $this->repository->marcarEmailComoVerificado($uuid, false);
    }

    public function salvarTokenRecuperacaoSenha(string $uuid, string $token): void
    {
        $usuario = $this->repository->buscarPorUuid($uuid);
        if (!$usuario) throw new DomainException('Usuário não encontrado.', 404);
        $usuario->gerarTokenRecuperacaoSenha($token);
        $this->repository->salvarTokenRecuperacaoSenha($uuid, $token);
    }

    public function buscarPorTokenRecuperacaoSenha(string $token): ?Usuario
    {
        return $this->repository->buscarPorTokenRecuperacaoSenha($token);
    }

    public function limparTokenRecuperacaoSenha(string $uuid): void
    {
        $this->repository->limparTokenRecuperacaoSenha($uuid);
    }

    public function listarUsernamesAtivosParaSitemap(int $limite = 50000, int $offset = 0): array
    {
        return $this->repository->listarUsernamesAtivos($limite, $offset);
    }
}

<?php

namespace Src\Modules\Usuario\Controllers;

use DomainException;
use Src\Kernel\Http\Request\Request;
use Src\Kernel\Http\Response\Response;
use Src\Kernel\Utils\ImageProcessor;
use Src\Kernel\Utils\Sanitizer;
use Src\Modules\Usuario\Entities\Usuario;
use Src\Modules\Usuario\Exceptions\DomainException as ModuleDomainException;
use Src\Modules\Usuario\Services\UsuarioServiceInterface;

class UsuarioController
{
    private ?\PDO $pdo = null;

    public function __construct(
        private UsuarioServiceInterface $service,
        private ?\Src\Kernel\Contracts\EmailSenderInterface $emailSender = null
    ) {}

    private function pdo(): \PDO
    {
        if ($this->pdo === null) {
            $this->pdo = \Src\Kernel\Database\ModuleConnectionResolver::forModule('Usuario');
        }
        return $this->pdo;
    }

    // ── Registro público ──────────────────────────────────────────────────

    public function criar(Request $request): Response
    {
        try {
            $body     = $request->body ?? [];
            $nome     = Sanitizer::string($body['nome_completo'] ?? $body['nome'] ?? '', 150);
            $username = Sanitizer::username($body['username'] ?? '');
            $email    = Sanitizer::email($body['email'] ?? '');
            $senha    = Sanitizer::password($body['senha'] ?? $body['password'] ?? '');
            // nivel_acesso nunca vem do body em registro público — sempre 'usuario'
            $nivel    = 'usuario';

            if ($nome === '' || $username === '' || $email === '' || $senha === '') {
                return Response::json(['status' => 'error', 'message' => 'Campos obrigatórios: nome_completo, username, email, senha.'], 422);
            }

            $usuario = Usuario::registrar($nome, $username, $email, $senha, null, null, null, $nivel);
            $this->service->criar($usuario);

            // Gera token e envia e-mail de confirmação se o módulo estiver disponível
            $this->enviarEmailConfirmacaoRegistro($usuario);

            return Response::json([
                'status'  => 'success',
                'message' => 'Usuário criado com sucesso. Verifique seu e-mail para confirmar o cadastro.',
                'usuario' => $this->serializar($usuario),
            ], 201);
        } catch (DomainException | ModuleDomainException $e) {
            $status = $e->getCode() >= 400 && $e->getCode() <= 599 ? $e->getCode() : 422;
            return Response::json(['status' => 'error', 'message' => $e->getMessage()], $status);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao criar usuário.', 'details' => $this->debug($e)], 500);
        }
    }

    /**
     * Endpoint público: reenviar e-mail de verificação.
     * POST /api/auth/reenviar-verificacao  { "email": "..." }
     */
    public function reenviarVerificacaoEmail(Request $request): Response
    {
        try {
            $body  = $request->body ?? [];
            $email = Sanitizer::email($body['email'] ?? '');

            if ($email === '') {
                return Response::json(['status' => 'error', 'message' => 'E-mail inválido ou não informado.'], 422);
            }

            $usuario = $this->service->buscarPorEmail($email);

            // Resposta genérica em todos os casos para não revelar se o e-mail existe
            $msgGenerica = 'Se o e-mail existir e não estiver verificado, um novo link será enviado em breve.';

            if (!$usuario) {
                // Registra throttle mesmo assim para evitar enumeração por timing
                $this->registrarReenvioVerificacao($email);
                return Response::json(['status' => 'success', 'message' => $msgGenerica]);
            }

            if ($usuario->isEmailVerificado()) {
                return Response::json(['status' => 'success', 'message' => 'E-mail já verificado. Você pode fazer login normalmente.']);
            }

            // enviarEmailConfirmacaoRegistro já verifica throttle e e-mail verificado internamente
            $this->enviarEmailConfirmacaoRegistro($usuario);

            return Response::json(['status' => 'success', 'message' => $msgGenerica]);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao reenviar verificação.'], 500);
        }
    }

    private function podeReenviarVerificacao(string $email): bool
    {
        try {
            return (new \Src\Kernel\Support\EmailThrottle($this->pdo()))->canSend('verification', $email);
        } catch (\Throwable) {
            return true;
        }
    }

    private function registrarReenvioVerificacao(string $email): void
    {
        try {
            (new \Src\Kernel\Support\EmailThrottle($this->pdo()))->record('verification', $email);
        } catch (\Throwable $e) {
            error_log('[UsuarioController] throttle record failed: ' . $e->getMessage());
        }
    }

    /**
     * Gera token de verificação e envia e-mail de confirmação.
     * Não envia se o e-mail já estiver verificado.
     * Não envia se o throttle de 120s ainda estiver ativo.
     */
    private function enviarEmailConfirmacaoRegistro(\Src\Modules\Usuario\Entities\Usuario $usuario): void
    {
        if ($this->emailSender === null) {
            return;
        }

        // Não envia se já verificado
        if ($usuario->isEmailVerificado()) {
            return;
        }

        // Throttle: evita disparos duplicados em menos de 120s
        if (!$this->podeReenviarVerificacao($usuario->getEmail())) {
            return;
        }

        try {
            $token = bin2hex(random_bytes(32));
            $this->service->salvarTokenVerificacaoEmail($usuario->getUuid()->toString(), $token);

            // Registra throttle antes de enviar para evitar race condition
            $this->registrarReenvioVerificacao($usuario->getEmail());

            $base = rtrim($_ENV['APP_URL_FRONTEND'] ?? $_ENV['APP_URL'] ?? '', '/');
            if ($base === '') {
                $scheme = $_SERVER['REQUEST_SCHEME'] ?? 'http';
                $host   = $_SERVER['HTTP_HOST'] ?? 'localhost';
                $base   = $scheme . '://' . $host;
            }
            // Link aponta para o frontend — o frontend chama a API com o token
            $link = $base . '/verificar-email?token=' . urlencode($token);

            $this->emailSender->sendConfirmation(
                $usuario->getEmail(),
                $usuario->getNomeCompleto(),
                $link,
                $_ENV['APP_LOGO_URL'] ?? null
            );
        } catch (\Throwable $e) {
            error_log('[UsuarioController] Falha ao enviar e-mail de confirmação: ' . $e->getMessage());
        }
    }

    // ── Admin: listagem e gerenciamento ───────────────────────────────────

    public function listar(Request $request): Response
    {
        try {
            $pagina    = Sanitizer::positiveInt($request->query['pagina'] ?? $request->query['page'] ?? 1, 1, 10000);
            $porPagina = Sanitizer::positiveInt($request->query['por_pagina'] ?? $request->query['per_page'] ?? 20, 1, 100);
            $busca     = Sanitizer::search($request->query['q'] ?? '');
            $nivel     = Sanitizer::nivelAcesso($request->query['nivel'] ?? '');

            $resultado = $this->service->listarComFiltro($pagina, $porPagina, $busca, $nivel);

            return Response::json([
                'status'        => 'success',
                'pagina'        => $pagina,
                'por_pagina'    => $porPagina,
                'total'         => $resultado['total'],
                'total_paginas' => $resultado['total_paginas'],
                'usuarios'      => array_map([$this, 'serializar'], $resultado['usuarios']),
            ]);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao listar usuários.', 'details' => $this->debug($e)], 500);
        }
    }

    public function buscar(Request $request, string $uuid): Response
    {
        try {
            $usuario = $this->service->buscarPorUuid($uuid);
            if (!$usuario) {
                return Response::json(['status' => 'error', 'message' => 'Usuário não encontrado.'], 404);
            }
            return Response::json(['status' => 'success', 'usuario' => $this->serializar($usuario)]);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao buscar usuário.', 'details' => $this->debug($e)], 500);
        }
    }

    public function atualizar(Request $request, string $uuid): Response
    {
        try {
            $uuid = Sanitizer::uuid($uuid);
            if ($uuid === '') {
                return Response::json(['status' => 'error', 'message' => 'UUID inválido.'], 422);
            }
            $body = $request->body ?? [];
            if (empty($body)) {
                return Response::json(['status' => 'error', 'message' => 'Nenhum dado enviado.'], 422);
            }
            $dados = $this->sanitizarCamposUsuario($body);
            if (isset($body['nivel_acesso'])) {
                // Impede que o usuário logado altere seu próprio nível de acesso
                $authUser = $request->attribute('auth_user');
                if ($authUser && $authUser->getUuid()->toString() === $uuid) {
                    return Response::json(['status' => 'error', 'message' => 'Você não pode alterar seu próprio nível de acesso.'], 403);
                }
                $nivelError = $this->sanitizarNivelAcesso($body['nivel_acesso'], $dados);
                if ($nivelError !== null) {
                    return $nivelError;
                }
            }
            if (empty($dados)) {
                return Response::json(['status' => 'error', 'message' => 'Nenhum campo válido enviado.'], 422);
            }
            $this->service->atualizar($uuid, $dados);
            $usuario = $this->service->buscarPorUuid($uuid);
            return Response::json([
                'status'  => 'success',
                'message' => 'Usuário atualizado.',
                'usuario' => $usuario ? $this->serializar($usuario) : null,
            ]);
        } catch (DomainException | ModuleDomainException $e) {
            $status = $e->getCode() >= 400 && $e->getCode() <= 599 ? $e->getCode() : 422;
            return Response::json(['status' => 'error', 'message' => $e->getMessage()], $status);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao atualizar usuário.', 'details' => $this->debug($e)], 500);
        }
    }

    /** Sanitiza os campos comuns de usuário a partir do body da requisição. */
    private function sanitizarCamposUsuario(array $body): array
    {
        $map = [
            'nome_completo' => static fn($v) => Sanitizer::string($v, 150),
            'username'      => static fn($v) => Sanitizer::username($v),
            'email'         => static fn($v) => Sanitizer::email($v),
            'senha'         => static fn($v) => Sanitizer::password($v),
            'url_avatar'    => static fn($v) => Sanitizer::url($v),
            'url_capa'      => static fn($v) => Sanitizer::url($v),
            'biografia'     => static fn($v) => Sanitizer::text($v, 500),
        ];
        $dados = [];
        foreach ($map as $campo => $sanitize) {
            if (isset($body[$campo])) {
                $dados[$campo] = $sanitize($body[$campo]);
            }
        }
        return $dados;
    }

    /** Valida e adiciona nivel_acesso em $dados. Retorna Response de erro ou null se ok. */
    private function sanitizarNivelAcesso(mixed $valor, array &$dados): ?Response
    {
        $nivel = Sanitizer::nivelAcesso($valor);
        if ($nivel === '') {
            return Response::json(['status' => 'error', 'message' => 'Nível de acesso inválido.'], 422);
        }
        $dados['nivel_acesso'] = $nivel;
        return null;
    }

    public function deletar(Request $request, string $uuid): Response
    {
        try {
            $authUser = $request->attribute('auth_user');
            if ($authUser && $authUser->getUuid()->toString() === $uuid) {
                return Response::json(['status' => 'error', 'message' => 'Você não pode excluir sua própria conta por aqui.'], 403);
            }
            $this->service->deletar($uuid);
            return Response::json(['status' => 'success', 'message' => 'Usuário removido.']);
        } catch (DomainException | ModuleDomainException $e) {
            $status = $e->getCode() >= 400 && $e->getCode() <= 599 ? $e->getCode() : 422;
            return Response::json(['status' => 'error', 'message' => $e->getMessage()], $status);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao remover usuário.', 'details' => $this->debug($e)], 500);
        }
    }

    public function desativar(Request $request, string $uuid): Response
    {
        try {
            $this->service->desativar($uuid);
            return Response::json(['status' => 'success', 'message' => 'Usuário desativado.']);
        } catch (DomainException | ModuleDomainException $e) {
            $status = $e->getCode() >= 400 && $e->getCode() <= 599 ? $e->getCode() : 422;
            return Response::json(['status' => 'error', 'message' => $e->getMessage()], $status);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao desativar usuário.', 'details' => $this->debug($e)], 500);
        }
    }

    public function ativar(Request $request, string $uuid): Response
    {
        try {
            $this->service->ativar($uuid);
            return Response::json(['status' => 'success', 'message' => 'Usuário ativado.']);
        } catch (DomainException | ModuleDomainException $e) {
            $status = $e->getCode() >= 400 && $e->getCode() <= 599 ? $e->getCode() : 422;
            return Response::json(['status' => 'error', 'message' => $e->getMessage()], $status);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao ativar usuário.', 'details' => $this->debug($e)], 500);
        }
    }

    // ── Perfil do usuário autenticado ─────────────────────────────────────

    public function perfil(Request $request): Response
    {
        try {
            $authUser = $request->attribute('auth_user');
            if (!$authUser) {
                return Response::json(['status' => 'error', 'message' => 'Não autenticado.'], 401);
            }
            return Response::json(['status' => 'success', 'usuario' => $this->serializar($authUser)]);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao buscar perfil.', 'details' => $this->debug($e)], 500);
        }
    }

    public function atualizarPerfil(Request $request): Response
    {
        try {
            $authUser = $request->attribute('auth_user');
            if (!$authUser) {
                return Response::json(['status' => 'error', 'message' => 'Não autenticado.'], 401);
            }

            $body  = $request->body ?? [];
            $dados = [];
            if (isset($body['nome_completo'])) $dados['nome_completo'] = Sanitizer::string($body['nome_completo'], 150);
            if (isset($body['username']))       $dados['username']      = Sanitizer::username($body['username']);
            if (isset($body['url_avatar']))     $dados['url_avatar']    = Sanitizer::url($body['url_avatar']);
            if (isset($body['url_capa']))       $dados['url_capa']      = Sanitizer::url($body['url_capa']);
            if (isset($body['biografia']))      $dados['biografia']     = Sanitizer::text($body['biografia'], 500);

            if (empty($dados)) {
                return Response::json(['status' => 'error', 'message' => 'Nenhum campo válido enviado.'], 422);
            }

            $uuid = $authUser->getUuid()->toString();
            $this->service->atualizar($uuid, $dados);
            $usuario = $this->service->buscarPorUuid($uuid);

            return Response::json([
                'status'  => 'success',
                'message' => 'Perfil atualizado.',
                'usuario' => $usuario ? $this->serializar($usuario) : null,
            ]);
        } catch (DomainException | ModuleDomainException $e) {
            $status = $e->getCode() >= 400 && $e->getCode() <= 599 ? $e->getCode() : 422;
            return Response::json(['status' => 'error', 'message' => $e->getMessage()], $status);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao atualizar perfil.', 'details' => $this->debug($e)], 500);
        }
    }

    public function alterarEmail(Request $request): Response
    {
        try {
            $authUser = $request->attribute('auth_user');
            if (!$authUser) {
                return Response::json(['status' => 'error', 'message' => 'Não autenticado.'], 401);
            }

            $body  = $request->body ?? [];
            $email = Sanitizer::email($body['email'] ?? '');
            $senha = Sanitizer::password($body['senha'] ?? $body['password'] ?? '');

            if ($email === '') {
                return Response::json(['status' => 'error', 'message' => 'E-mail inválido ou não informado.'], 422);
            }
            if ($senha === '' || !$authUser->verificarSenha($senha)) {
                return Response::json(['status' => 'error', 'message' => 'Senha incorreta.'], 403);
            }

            $uuid = $authUser->getUuid()->toString();
            $this->service->atualizar($uuid, ['email' => $email]);

            // Reseta verificação e envia novo e-mail de confirmação para o novo endereço
            $usuarioAtualizado = $this->service->buscarPorUuid($uuid);
            if ($usuarioAtualizado) {
                $this->service->resetarVerificacaoEmail($uuid);
                $usuarioAtualizado->setEmailVerificado(false);
                $this->enviarEmailConfirmacaoRegistro($usuarioAtualizado);
            }

            return Response::json(['status' => 'success', 'message' => 'E-mail atualizado. Verifique sua caixa de entrada para confirmar o novo endereço.']);
        } catch (DomainException | ModuleDomainException $e) {
            $status = $e->getCode() >= 400 && $e->getCode() <= 599 ? $e->getCode() : 422;
            return Response::json(['status' => 'error', 'message' => $e->getMessage()], $status);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao alterar e-mail.', 'details' => $this->debug($e)], 500);
        }
    }

    public function alterarSenha(Request $request): Response
    {
        try {
            $authUser = $request->attribute('auth_user');
            if (!$authUser) {
                return Response::json(['status' => 'error', 'message' => 'Não autenticado.'], 401);
            }

            $body        = $request->body ?? [];
            $senhaAtual  = Sanitizer::password($body['senha_atual'] ?? $body['current_password'] ?? '');
            $novaSenha   = Sanitizer::password($body['nova_senha'] ?? $body['new_password'] ?? '');

            if ($senhaAtual === '' || $novaSenha === '') {
                return Response::json(['status' => 'error', 'message' => 'senha_atual e nova_senha são obrigatórios.'], 422);
            }
            if (!$authUser->verificarSenha($senhaAtual)) {
                return Response::json(['status' => 'error', 'message' => 'Senha atual incorreta.'], 403);
            }

            $this->service->alterarSenha($authUser->getUuid()->toString(), $novaSenha);
            return Response::json(['status' => 'success', 'message' => 'Senha alterada com sucesso.']);
        } catch (DomainException | ModuleDomainException $e) {
            $status = $e->getCode() >= 400 && $e->getCode() <= 599 ? $e->getCode() : 422;
            return Response::json(['status' => 'error', 'message' => $e->getMessage()], $status);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao alterar senha.', 'details' => $this->debug($e)], 500);
        }
    }

    public function uploadProfileImage(Request $request): Response
    {
        try {
            $authUser = $request->attribute('auth_user');
            if (!$authUser) {
                return Response::json(['status' => 'error', 'message' => 'Não autenticado.'], 401);
            }

            $tipo  = $this->resolverTipoImagem($request->body['tipo'] ?? 'avatar');
            $file  = $_FILES['imagem'] ?? $_FILES['file'] ?? null;

            $validationError = $this->validarArquivoImagem($file);
            if ($validationError !== null) {
                return $validationError;
            }

            $mime = mime_content_type($file['tmp_name']) ?: '';
            $mimeError = $this->validarMimeImagem($mime);
            if ($mimeError !== null) {
                return $mimeError;
            }

            $uuid      = $authUser->getUuid()->toString();
            $filename  = $this->gerarNomeArquivo($uuid, $tipo, $mime);
            $uploadDir = dirname(__DIR__, 5) . '/public/uploads/perfil/';

            if (!is_dir($uploadDir) && !mkdir($uploadDir, 0755, true) && !is_dir($uploadDir)) {
                return Response::json(['status' => 'error', 'message' => 'Erro ao criar diretório de upload.'], 500);
            }

            [$maxW, $maxH] = $tipo === 'capa' ? [1200, 400] : [400, 400];
            if (!ImageProcessor::resizeAndSave($file['tmp_name'], $uploadDir . $filename, $mime, $maxW, $maxH)) {
                return Response::json(['status' => 'error', 'message' => 'Falha ao processar imagem.'], 500);
            }

            $url   = '/uploads/perfil/' . $filename;
            $campo = $tipo === 'capa' ? 'url_capa' : 'url_avatar';
            $this->service->atualizar($uuid, [$campo => $url]);

            return Response::json(['status' => 'success', 'url' => $url]);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro no upload.', 'details' => $this->debug($e)], 500);
        }
    }

    private function resolverTipoImagem(mixed $tipo): string
    {
        $tipo = trim((string) $tipo);
        return in_array($tipo, ['avatar', 'capa'], true) ? $tipo : 'avatar';
    }

    private function validarArquivoImagem(?array $file): ?Response
    {
        if (!$file || ($file['error'] ?? UPLOAD_ERR_NO_FILE) !== UPLOAD_ERR_OK) {
            return Response::json(['status' => 'error', 'message' => 'Nenhuma imagem enviada ou erro no upload.'], 422);
        }
        if (($file['size'] ?? 0) > 5 * 1024 * 1024) {
            return Response::json(['status' => 'error', 'message' => 'Imagem muito grande. Máximo 5MB.'], 422);
        }
        // Validação real de conteúdo — mime_content_type é falsificável
        set_error_handler(static function (): bool { return true; });
        $imageInfo = getimagesize($file['tmp_name']);
        restore_error_handler();
        if ($imageInfo === false) {
            return Response::json(['status' => 'error', 'message' => 'Arquivo inválido: não é uma imagem.'], 422);
        }
        return null;
    }

    private function validarMimeImagem(string $mime): ?Response
    {
        $allowed = ['image/jpeg', 'image/jpg', 'image/png', 'image/webp'];
        if (!in_array($mime, $allowed, true)) {
            return Response::json(['status' => 'error', 'message' => 'Formato não suportado. Use JPEG, PNG ou WebP.'], 422);
        }
        return null;
    }

    private function gerarNomeArquivo(string $uuid, string $tipo, string $mime): string
    {
        $extMap = ['image/jpeg' => 'jpg', 'image/jpg' => 'jpg', 'image/png' => 'png', 'image/webp' => 'webp'];
        $ext    = $extMap[$mime] ?? 'jpg';
        return $uuid . '_' . $tipo . '_' . time() . '.' . $ext;
    }

    public function deletarMinhaConta(Request $request): Response
    {
        try {
            $authUser = $request->attribute('auth_user');
            if (!$authUser) {
                return Response::json(['status' => 'error', 'message' => 'Não autenticado.'], 401);
            }

            $body = $request->body ?? [];
            $senha = (string) ($body['senha'] ?? $body['password'] ?? '');
            if ($senha === '' || !$authUser->verificarSenha($senha)) {
                return Response::json(['status' => 'error', 'message' => 'Senha incorreta.'], 403);
            }

            $this->service->deletar($authUser->getUuid()->toString());
            return Response::json(['status' => 'success', 'message' => 'Conta removida.']);
        } catch (DomainException | ModuleDomainException $e) {
            $status = $e->getCode() >= 400 && $e->getCode() <= 599 ? $e->getCode() : 422;
            return Response::json(['status' => 'error', 'message' => $e->getMessage()], $status);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao remover conta.', 'details' => $this->debug($e)], 500);
        }
    }

    // ── Perfil público ────────────────────────────────────────────────────

    public function buscarPorUsername(Request $request, string $username): Response
    {
        try {
            $usuario = $this->service->buscarPorUsername($username);
            if (!$usuario || !$usuario->isAtivo()) {
                return Response::json(['status' => 'error', 'message' => 'Usuário não encontrado.'], 404);
            }
            return Response::json(['status' => 'success', 'usuario' => $this->serializarPublico($usuario)]);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao buscar perfil.', 'details' => $this->debug($e)], 500);
        }
    }

    public function exibirPerfilHtml(Request $request, string $username): Response
    {
        try {
            $usuario = $this->service->buscarPorUsername($username);
            if (!$usuario || !$usuario->isAtivo()) {
                return Response::html('<h1>Usuário não encontrado</h1>', 404);
            }
            $nome       = htmlspecialchars($usuario->getNomeCompleto(), ENT_QUOTES, 'UTF-8');
            $usernameHtml = htmlspecialchars($usuario->getUsername(), ENT_QUOTES, 'UTF-8');
            $avatar     = htmlspecialchars($usuario->getUrlAvatar() ?? '', ENT_QUOTES, 'UTF-8');
            $bio        = htmlspecialchars($usuario->getBiografia() ?? '', ENT_QUOTES, 'UTF-8');
            $html = "<!doctype html><meta charset='utf-8'><title>{$nome}</title>"
                  . ($avatar ? "<img src='{$avatar}' alt='Avatar'>" : '')
                  . "<h1>{$nome}</h1><p>@{$usernameHtml}</p>"
                  . ($bio ? "<p>{$bio}</p>" : '');
            return Response::html($html);
        } catch (\Throwable $e) {
            return Response::html('<h1>Erro interno</h1>', 500);
        }
    }

    // ── Verificação de e-mail ─────────────────────────────────────────────

    public function enviarVerificacaoEmail(Request $request, string $uuid): Response
    {
        try {
            $usuario = $this->service->buscarPorUuid($uuid);
            if (!$usuario) {
                return Response::json(['status' => 'error', 'message' => 'Usuário não encontrado.'], 404);
            }
            if ($usuario->isEmailVerificado()) {
                return Response::json(['status' => 'success', 'message' => 'E-mail já verificado.']);
            }
            // Força envio ignorando throttle (ação administrativa explícita)
            $this->enviarEmailVerificacaoForcado($usuario);
            return Response::json(['status' => 'success', 'message' => 'E-mail de verificação enviado.']);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao enviar e-mail.', 'details' => $this->debug($e)], 500);
        }
    }

    public function enviarVerificacaoEmailPorEmail(Request $request): Response
    {
        try {
            $body  = $request->body ?? [];
            $email = trim((string) ($body['email'] ?? ''));
            if ($email === '') {
                return Response::json(['status' => 'error', 'message' => 'E-mail é obrigatório.'], 422);
            }
            $usuario = $this->service->buscarPorEmail($email);
            if (!$usuario) {
                return Response::json(['status' => 'success', 'message' => 'Se o e-mail existir, o link será enviado.']);
            }
            if ($usuario->isEmailVerificado()) {
                return Response::json(['status' => 'success', 'message' => 'E-mail já verificado.']);
            }
            // Força envio ignorando throttle (ação administrativa explícita)
            $this->enviarEmailVerificacaoForcado($usuario);
            return Response::json(['status' => 'success', 'message' => 'E-mail de verificação enviado.']);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao gerar token.', 'details' => $this->debug($e)], 500);
        }
    }

    public function verificarEmailStatus(Request $request): Response
    {
        try {
            $uuid = trim((string) ($request->query['uuid'] ?? ''));
            if ($uuid === '') {
                return Response::json(['status' => 'error', 'message' => 'UUID é obrigatório.'], 422);
            }
            $usuario = $this->service->buscarPorUuid($uuid);
            if (!$usuario) {
                return Response::json(['status' => 'error', 'message' => 'Usuário não encontrado.'], 404);
            }
            return Response::json(['status' => 'success', 'verificado' => $usuario->isEmailVerificado()]);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao verificar status.', 'details' => $this->debug($e)], 500);
        }
    }

    public function verificarEmail(Request $request, string $token): Response
    {
        try {
            $token = trim($token);
            if ($token === '') {
                return Response::json(['status' => 'error', 'message' => 'Token inválido.'], 400);
            }
            $usuario = $this->service->buscarPorTokenVerificacaoEmail($token);
            if (!$usuario) {
                return Response::json(['status' => 'error', 'message' => 'Token inválido ou expirado.'], 400);
            }
            if ($usuario->isEmailVerificado()) {
                return Response::json(['status' => 'success', 'message' => 'E-mail já verificado.']);
            }
            $this->service->marcarEmailComoVerificado($usuario->getUuid()->toString());
            return Response::json(['status' => 'success', 'message' => 'E-mail verificado com sucesso.']);
        } catch (\Throwable $e) {
            return Response::json(['status' => 'error', 'message' => 'Erro ao verificar e-mail.', 'details' => $this->debug($e)], 500);
        }
    }

    // ── Helpers ───────────────────────────────────────────────────────────

    /**
     * Envia e-mail de verificação sem verificar throttle.
     * Usado por ações administrativas explícitas.
     */
    private function enviarEmailVerificacaoForcado(\Src\Modules\Usuario\Entities\Usuario $usuario): void
    {
        if ($this->emailSender === null) {
            return;
        }
        try {
            $token = bin2hex(random_bytes(32));
            $this->service->salvarTokenVerificacaoEmail($usuario->getUuid()->toString(), $token);
            $this->registrarReenvioVerificacao($usuario->getEmail());

            $base = rtrim($_ENV['APP_URL_FRONTEND'] ?? $_ENV['APP_URL'] ?? '', '/');
            if ($base === '') {
                $scheme = $_SERVER['REQUEST_SCHEME'] ?? 'http';
                $host   = $_SERVER['HTTP_HOST'] ?? 'localhost';
                $base   = $scheme . '://' . $host;
            }
            $link = $base . '/verificar-email?token=' . urlencode($token);

            $this->emailSender->sendConfirmation(
                $usuario->getEmail(),
                $usuario->getNomeCompleto(),
                $link,
                $_ENV['APP_LOGO_URL'] ?? null
            );
        } catch (\Throwable $e) {
            error_log('[UsuarioController] Falha ao enviar e-mail de verificação: ' . $e->getMessage());
        }
    }

    private function serializar(Usuario $u): array
    {
        return [
            'uuid'               => $u->getUuid()->toString(),
            'nome_completo'      => $u->getNomeCompleto(),
            'username'           => $u->getUsername(),
            'email'              => $u->getEmail(),
            'nivel_acesso'       => $u->getNivelAcesso(),
            'ativo'              => $u->isAtivo(),
            'verificado_email'   => $u->isEmailVerificado(),
            'url_avatar'         => $u->getUrlAvatar(),
            'url_capa'           => $u->getUrlCapa(),
            'biografia'          => $u->getBiografia(),
            'criado_em'          => $u->getCriadoEm()->format('Y-m-d\TH:i:sP'),
            'atualizado_em'      => $u->getAtualizadoEm()?->format('Y-m-d\TH:i:sP'),
        ];
    }

    private function serializarPublico(Usuario $u): array
    {
        return [
            'username'    => $u->getUsername(),
            'nome_completo' => $u->getNomeCompleto(),
            'url_avatar'  => $u->getUrlAvatar(),
            'url_capa'    => $u->getUrlCapa(),
            'biografia'   => $u->getBiografia(),
        ];
    }

    private function debug(\Throwable $e): ?string
    {
        return ($_ENV['APP_DEBUG'] ?? 'false') === 'true' ? $e->getMessage() : null;
    }
}

<?php
/**
 * Migration: Módulo Usuario — Tabela usuarios
 */
return [
    'up' => function (PDO $pdo): void {
        $driver = $pdo->getAttribute(PDO::ATTR_DRIVER_NAME);
        if ($driver === 'pgsql') {
            $pdo->exec("
                CREATE TABLE IF NOT EXISTS usuarios (
                    uuid                    UUID         NOT NULL PRIMARY KEY,
                    nome_completo           VARCHAR(255) NOT NULL,
                    username                VARCHAR(50)  NOT NULL UNIQUE,
                    email                   VARCHAR(255) NOT NULL UNIQUE,
                    senha_hash              VARCHAR(255) NOT NULL,
                    url_avatar              VARCHAR(255),
                    url_capa                VARCHAR(255),
                    biografia               TEXT,
                    nivel_acesso            VARCHAR(20)  DEFAULT 'usuario'
                        CHECK (nivel_acesso IN ('usuario','admin','moderador','admin_system')),
                    token_recuperacao_senha VARCHAR(255),
                    token_verificacao_email VARCHAR(255),
                    ativo                   BOOLEAN      NOT NULL DEFAULT TRUE,
                    verificado_email        BOOLEAN      NOT NULL DEFAULT FALSE,
                    criado_em               TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
                    atualizado_em           TIMESTAMP,
                    status_verificacao      VARCHAR(30)  DEFAULT 'Não verificado'
                )
            ");
            $pdo->exec("CREATE INDEX IF NOT EXISTS idx_usuarios_email    ON usuarios (email)");
            $pdo->exec("CREATE INDEX IF NOT EXISTS idx_usuarios_username ON usuarios (username)");
            $pdo->exec("CREATE INDEX IF NOT EXISTS idx_usuarios_ativo    ON usuarios (ativo)");
        } else {
            $pdo->exec("
                CREATE TABLE IF NOT EXISTS usuarios (
                    uuid                    CHAR(36)     NOT NULL PRIMARY KEY,
                    nome_completo           VARCHAR(255) NOT NULL,
                    username                VARCHAR(50)  NOT NULL UNIQUE,
                    email                   VARCHAR(255) NOT NULL UNIQUE,
                    senha_hash              VARCHAR(255) NOT NULL,
                    url_avatar              VARCHAR(255),
                    url_capa                VARCHAR(255),
                    biografia               TEXT,
                    nivel_acesso            VARCHAR(20)  DEFAULT 'usuario',
                    token_recuperacao_senha VARCHAR(255),
                    token_verificacao_email VARCHAR(255),
                    ativo                   TINYINT(1)   NOT NULL DEFAULT 1,
                    verificado_email        TINYINT(1)   NOT NULL DEFAULT 0,
                    criado_em               DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
                    atualizado_em           DATETIME,
                    status_verificacao      VARCHAR(30)  DEFAULT 'Não verificado',
                    INDEX idx_email (email),
                    INDEX idx_username (username),
                    INDEX idx_ativo (ativo)
                ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
            ");
        }
    },
    'down' => function (PDO $pdo): void {
        $pdo->exec("DROP TABLE IF EXISTS usuarios");
    },
];

<?php
/**
 * Seeder: Módulo Usuario — Usuário admin padrão
 *
 * Cria o usuário admin_system inicial se não existir.
 *
 * Credenciais padrão:
 *   E-mail: [email protected]
 *   Senha:  admin123
 *
 * Sobrescreva via variáveis de ambiente:
 *   ADMIN_EMAIL, ADMIN_PASSWORD, ADMIN_NAME, ADMIN_USERNAME
 *
 * ⚠ TROQUE A SENHA EM PRODUÇÃO!
 */
return function (PDO $pdo): void {
    $email    = $_ENV['ADMIN_EMAIL']    ?? '[email protected]';
    $senha    = $_ENV['ADMIN_PASSWORD'] ?? 'admin123';
    $nome     = $_ENV['ADMIN_NAME']     ?? 'Administrador';
    $username = $_ENV['ADMIN_USERNAME'] ?? 'admin';

    // Verifica se já existe pelo e-mail
    $stmt = $pdo->prepare("SELECT 1 FROM usuarios WHERE email = :email LIMIT 1");
    $stmt->execute([':email' => $email]);
    if ($stmt->fetchColumn()) {
        echo "  ⊘ Admin já existe: $email
";
        return;
    }

    // Verifica se o username já está em uso
    $stmt = $pdo->prepare("SELECT 1 FROM usuarios WHERE username = :username LIMIT 1");
    $stmt->execute([':username' => $username]);
    if ($stmt->fetchColumn()) {
        $username = 'admin_' . bin2hex(random_bytes(3));
    }

    $uuid = \Ramsey\Uuid\Uuid::uuid4()->toString();

    // Usa PASSWORD_BCRYPT para compatibilidade máxima
    // O seeder cria o hash diretamente — sem passar pela validação de complexidade
    // da entidade Usuario, pois é um usuário de bootstrap do sistema
    $hash = password_hash($senha, PASSWORD_BCRYPT, ['cost' => 12]);

    $driver = $pdo->getAttribute(PDO::ATTR_DRIVER_NAME);

    if ($driver === 'pgsql') {
        $stmt = $pdo->prepare("
            INSERT INTO usuarios
                (uuid, nome_completo, username, email, senha_hash,
                 nivel_acesso, ativo, verificado_email, status_verificacao, criado_em)
            VALUES
                (:uuid, :nome, :username, :email, :hash,
                 'admin_system', TRUE, TRUE, 'verificado', NOW())
        ");
    } else {
        $stmt = $pdo->prepare("
            INSERT INTO usuarios
                (uuid, nome_completo, username, email, senha_hash,
                 nivel_acesso, ativo, verificado_email, status_verificacao, criado_em)
            VALUES
                (:uuid, :nome, :username, :email, :hash,
                 'admin_system', 1, 1, 'verificado', NOW())
        ");
    }

    $stmt->execute([
        ':uuid'     => $uuid,
        ':nome'     => $nome,
        ':username' => $username,
        ':email'    => $email,
        ':hash'     => $hash,
    ]);

    echo "  ✔ Admin criado com sucesso!\n";
    echo "    E-mail:   $email\n";
    echo "    Username: $username\n";
    echo "    Senha:    $senha\n";
    echo "    Nível:    admin_system\n";
    echo "\n  ⚠  TROQUE A SENHA EM PRODUÇÃO!\n";
};

<?php
// Define qual banco de dados este módulo usa.
// Opções: 'core' (DB_*) | 'modules' (DB2_*) | 'auto'
return 'core';

<?php

use Src\Kernel\Middlewares\AuthHybridMiddleware;
use Src\Kernel\Middlewares\AdminOnlyMiddleware;
use Src\Kernel\Middlewares\RateLimitMiddleware;
use Src\Kernel\Middlewares\CircuitBreakerMiddleware;
use Src\Modules\Usuario\Controllers\UsuarioController;

/** @var \Src\Kernel\Contracts\RouterInterface $router */

// Middlewares
$adminProtected = [AuthHybridMiddleware::class, AdminOnlyMiddleware::class];
$userProtected  = [AuthHybridMiddleware::class];

// Circuit breaker para rotas que dependem de DB
$dbCircuit = [CircuitBreakerMiddleware::class, ['service' => 'database', 'threshold' => 5, 'cooldown' => 20]];

// Rate limits
$registroRateLimit  = [RateLimitMiddleware::class, ['limit' => 5,  'window' => 60,  'key' => 'usuario.registro']];
$reenvioRateLimit   = [RateLimitMiddleware::class, ['limit' => 3,  'window' => 300, 'key' => 'usuario.reenvio']];
$perfilRateLimit    = [RateLimitMiddleware::class, ['limit' => 30, 'window' => 60,  'key' => 'usuario.perfil']];
$verificaRateLimit  = [RateLimitMiddleware::class, ['limit' => 10, 'window' => 60,  'key' => 'usuario.verifica']];

// Registro público de usuário
$router->post('/api/criar/usuario', [UsuarioController::class, 'criar'], [$registroRateLimit, $dbCircuit]);
$router->post('/api/registrar',     [UsuarioController::class, 'criar'], [$registroRateLimit, $dbCircuit]);

// Reenvio de e-mail de verificação (público, sem autenticação)
$router->post('/api/auth/reenviar-verificacao', [UsuarioController::class, 'reenviarVerificacaoEmail'], [$reenvioRateLimit]);

// Gerenciamento de usuários (admin)
$router->get('/api/usuarios', [UsuarioController::class, 'listar'], $adminProtected);
$router->get('/api/usuario/{uuid}', [UsuarioController::class, 'buscar'], $adminProtected);
$router->put('/api/usuario/atualizar/{uuid}', [UsuarioController::class, 'atualizar'], $adminProtected);
$router->delete('/api/usuario/deletar/{uuid}', [UsuarioController::class, 'deletar'], $adminProtected);
$router->patch('/api/usuario/{uuid}/desativar', [UsuarioController::class, 'desativar'], $adminProtected);
$router->patch('/api/usuario/{uuid}/ativar', [UsuarioController::class, 'ativar'], $adminProtected);

// Perfil do usuário autenticado
$router->get('/api/perfil', [UsuarioController::class, 'perfil'], $userProtected);
$router->put('/api/perfil', [UsuarioController::class, 'atualizarPerfil'], $userProtected);
$router->put('/api/perfil/email', [UsuarioController::class, 'alterarEmail'], $userProtected);
$router->put('/api/perfil/senha', [UsuarioController::class, 'alterarSenha'], $userProtected);
$router->post('/api/perfil/upload', [UsuarioController::class, 'uploadProfileImage'], $userProtected);
$router->delete('/api/perfil', [UsuarioController::class, 'deletarMinhaConta'], $userProtected);

// Perfil público
$router->get('/api/perfil/{username}', [UsuarioController::class, 'buscarPorUsername'], [$perfilRateLimit]);
$router->get('/perfil/{username}',     [UsuarioController::class, 'exibirPerfilHtml'],  [$perfilRateLimit]);

// Verificação de e-mail
$router->post('/api/usuarios/{uuid}/enviar-verificacao-email', [UsuarioController::class, 'enviarVerificacaoEmail'],        $adminProtected);
$router->post('/api/usuarios/enviar-verificacao-email',        [UsuarioController::class, 'enviarVerificacaoEmailPorEmail'], $adminProtected);
$router->get('/api/usuarios/verificar-email-status',           [UsuarioController::class, 'verificarEmailStatus'],          $adminProtected);
$router->post('/api/usuarios/verificar-email/{token}',         [UsuarioController::class, 'verificarEmail'],                [$verificaRateLimit]);

// Métodos disponíveis
$router->get('/api/recurso',          [Controller::class, 'listar']);
$router->post('/api/recurso',         [Controller::class, 'criar']);
$router->put('/api/recurso/{uuid}',   [Controller::class, 'atualizar']);
$router->patch('/api/recurso/{uuid}', [Controller::class, 'parcial']);
$router->delete('/api/recurso/{uuid}',[Controller::class, 'deletar']);

// Definição
$router->get('/api/usuario/{uuid}', [UsuarioController::class, 'buscar']);

// No Controller
public function buscar(Request $request): Response
{
    $uuid = $request->param('uuid'); // captura {uuid}
    // ...
}

$loginLimit = [RateLimitMiddleware::class, [
    'limit'      => 10,   // max requisições
    'window'     => 60,   // janela em segundos
    'key'        => 'auth.login',  // chave única para este limite
    'user_limit' => 5,    // limite por usuário autenticado (opcional)
]];

$router->post('/api/login', [AuthController::class, 'login'], [$loginLimit]);

<?php
return [
    'up' => function (PDO $pdo): void {
        $driver = $pdo->getAttribute(PDO::ATTR_DRIVER_NAME);

        if ($driver === 'pgsql') {
            $pdo->exec("
                CREATE TABLE IF NOT EXISTS usuarios (
                    uuid             UUID         NOT NULL PRIMARY KEY,
                    nome_completo    VARCHAR(255) NOT NULL,
                    username         VARCHAR(50)  NOT NULL UNIQUE,
                    email            VARCHAR(255) NOT NULL UNIQUE,
                    senha_hash       VARCHAR(255) NOT NULL,
                    nivel_acesso     VARCHAR(20)  DEFAULT 'usuario'
                        CHECK (nivel_acesso IN ('usuario','admin','moderador','admin_system')),
                    ativo            BOOLEAN      NOT NULL DEFAULT TRUE,
                    verificado_email BOOLEAN      NOT NULL DEFAULT FALSE,
                    criado_em        TIMESTAMP    NOT NULL DEFAULT CURRENT_TIMESTAMP,
                    atualizado_em    TIMESTAMP
                )
            ");
            $pdo->exec("CREATE INDEX IF NOT EXISTS idx_usuarios_email    ON usuarios (email)");
            $pdo->exec("CREATE INDEX IF NOT EXISTS idx_usuarios_username ON usuarios (username)");
        } else {
            $pdo->exec("
                CREATE TABLE IF NOT EXISTS usuarios (
                    uuid             CHAR(36)     NOT NULL PRIMARY KEY,
                    nome_completo    VARCHAR(255) NOT NULL,
                    username         VARCHAR(50)  NOT NULL UNIQUE,
                    email            VARCHAR(255) NOT NULL UNIQUE,
                    senha_hash       VARCHAR(255) NOT NULL,
                    nivel_acesso     VARCHAR(20)  DEFAULT 'usuario',
                    ativo            TINYINT(1)   NOT NULL DEFAULT 1,
                    verificado_email TINYINT(1)   NOT NULL DEFAULT 0,
                    criado_em        DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
                    atualizado_em    DATETIME,
                    INDEX idx_email (email),
                    INDEX idx_username (username)
                ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
            ");
        }
    },
    'down' => function (PDO $pdo): void {
        $pdo->exec("DROP TABLE IF EXISTS usuarios");
    },
];

<?php
return [
    'up' => function (PDO $pdo): void {
        $driver = $pdo->getAttribute(PDO::ATTR_DRIVER_NAME);

        if ($driver === 'pgsql') {
            $pdo->exec("ALTER TABLE usuarios ADD COLUMN IF NOT EXISTS biografia TEXT");
            $pdo->exec("ALTER TABLE usuarios ADD COLUMN IF NOT EXISTS url_avatar VARCHAR(255)");
        } else {
            // MySQL não tem ADD COLUMN IF NOT EXISTS — verifica antes
            $cols = $pdo->query("SHOW COLUMNS FROM usuarios LIKE 'biografia'")->fetchAll();
            if (empty($cols)) {
                $pdo->exec("ALTER TABLE usuarios ADD COLUMN biografia TEXT");
                $pdo->exec("ALTER TABLE usuarios ADD COLUMN url_avatar VARCHAR(255)");
            }
        }
    },
    'down' => function (PDO $pdo): void {
        $pdo->exec("ALTER TABLE usuarios DROP COLUMN IF EXISTS biografia");
        $pdo->exec("ALTER TABLE usuarios DROP COLUMN IF EXISTS url_avatar");
    },
];

php vupi migrate              # executa todas as migrations pendentes
php vupi migrate --seed       # migrations + seeders
php vupi migrate --rollback   # desfaz a última migration
php vupi migrate --status     # lista status de cada migration (done/pending)
php vupi migrate --core       # apenas conexão core (DB_*)
php vupi migrate --modules    # apenas conexão modules (DB2_*)

# Alias equivalente
php db migrate
php db seed
php db rollback

<?php
/**
 * Seeder: cria o usuário admin_system inicial.
 * Credenciais configuráveis via .env:
 *   ADMIN_EMAIL, ADMIN_PASSWORD, ADMIN_NAME, ADMIN_USERNAME
 */
return function (PDO $pdo): void {
    $email    = $_ENV['ADMIN_EMAIL']    ?? '[email protected]';
    $senha    = $_ENV['ADMIN_PASSWORD'] ?? 'admin123';
    $nome     = $_ENV['ADMIN_NAME']     ?? 'Administrador';
    $username = $_ENV['ADMIN_USERNAME'] ?? 'admin';

    // Verifica se já existe — idempotência
    $stmt = $pdo->prepare("SELECT 1 FROM usuarios WHERE email = :email LIMIT 1");
    $stmt->execute([':email' => $email]);
    if ($stmt->fetchColumn()) {
        echo "  ⊘ Admin já existe: {$email}\n";
        return;
    }

    // Verifica conflito de username
    $stmt = $pdo->prepare("SELECT 1 FROM usuarios WHERE username = :username LIMIT 1");
    $stmt->execute([':username' => $username]);
    if ($stmt->fetchColumn()) {
        $username = 'admin_' . bin2hex(random_bytes(3));
    }

    $uuid   = \Ramsey\Uuid\Uuid::uuid4()->toString();
    $hash   = password_hash($senha, PASSWORD_BCRYPT, ['cost' => 12]);
    $driver = $pdo->getAttribute(PDO::ATTR_DRIVER_NAME);

    if ($driver === 'pgsql') {
        $stmt = $pdo->prepare("
            INSERT INTO usuarios (uuid, nome_completo, username, email, senha_hash,
                                  nivel_acesso, ativo, verificado_email, criado_em)
            VALUES (:uuid, :nome, :username, :email, :hash,
                    'admin_system', TRUE, TRUE, NOW())
        ");
    } else {
        $stmt = $pdo->prepare("
            INSERT INTO usuarios (uuid, nome_completo, username, email, senha_hash,
                                  nivel_acesso, ativo, verificado_email, criado_em)
            VALUES (:uuid, :nome, :username, :email, :hash,
                    'admin_system', 1, 1, NOW())
        ");
    }

    $stmt->execute([
        ':uuid'     => $uuid,
        ':nome'     => $nome,
        ':username' => $username,
        ':email'    => $email,
        ':hash'     => $hash,
    ]);

    echo "  ✔ Admin criado: {$email} / {$username}\n";
    echo "  ⚠  TROQUE A SENHA EM PRODUÇÃO!\n";
};

php vupi migrate --seed   # migrations + seeders juntos (recomendado)
php db seed                  # apenas seeders

<?php
// src/Modules/MeuModulo/Database/connection.php
// Opções: 'core' (DB_*) | 'modules' (DB2_*) | 'auto'
return 'core';

// ERRADO — vulnerável a SQL Injection
$pdo->query("SELECT * FROM usuarios WHERE email = '$email'");

// CORRETO — sempre assim
$stmt = $pdo->prepare("SELECT * FROM usuarios WHERE email = :email");
$stmt->bindValue(':email', $email);
$stmt->execute();
$row = $stmt->fetch(PDO::FETCH_ASSOC);

use Src\Modules\Usuario\Services\UsuarioService;

class FaturaService
{
    public function __construct(
        private UsuarioService $usuarioService // obrigatorio
    ) {}

    public function emitir(string $userUuid): void
    {
        $usuario = $this->usuarioService->buscarPorUuid($userUuid);
        // ...
    }
}

use Src\Kernel\Contracts\EmailSenderInterface;

class FaturaService
{
    public function __construct(
        private ?EmailSenderInterface $email = null // opcional
    ) {}

    public function processar(): void
    {
        $this->salvarNoBanco();

        // Operador nullsafe: se $email for null, linha ignorada sem erro
        $this->email?->sendCustom('[email protected]', 'Fatura', '<p>Gerada!</p>');
    }
}

php vupi setup                    # menu interativo (23 opções)
php vupi setup --help             # lista todas as flags
php vupi setup --auto             # modo automático sem interação

# Exemplos de uso
php vupi setup --auto --db-mode=docker --server=php --jwt=if-empty
php vupi setup --auto --server=pm2+caddy --caddy=production
php vupi setup --auto --db-mode=skip --caddy=dev
php vupi setup --auto --jwt=if-empty --api-token=generate

php vupi migrate              # executa migrations pendentes (core + módulos)
php vupi migrate --seed       # migrations + seeders
php vupi migrate --rollback   # desfaz a última migration
php vupi migrate --core       # apenas conexão core (DB_*)
php vupi migrate --modules    # apenas conexão modules (DB2_*)
php vupi migrate --status     # status de todas as migrations
php vupi migrate --status --json  # status em formato JSON

# Alias: php db faz a mesma coisa
php db migrate
php db seed
php db rollback

php vupi make:module NomeDoModulo
php vupi make:plugin NomeDoPlugin
php vupi make:plugin NomeDoPlugin --capability=email-sender --description="Envio de e-mails"

php vupi plugin:install    nome-do-plugin   # instala
php vupi plugin:enable     nome-do-plugin   # ativa
php vupi plugin:disable    nome-do-plugin   # desativa
php vupi plugin:uninstall  nome-do-plugin   # remove
php vupi plugin:migrate                     # migrations de todos os plugins
php vupi plugin:rollback   nome-do-plugin   # reverte migrations do plugin
php vupi plugin:validate                    # valida estrutura dos plugins
php vupi plugin:inspect                     # lista plugins instalados

php vupi capability:list                    # lista todas as capacidades
php vupi capability:list email-sender       # detalha uma capacidade específica
php vupi plugin:provider:set email-sender nome-do-plugin  # define o provider

# Docker
make up-pg          # sobe PostgreSQL + Adminer
make up-mysql       # sobe MySQL + Adminer
make up-all         # sobe tudo
make down           # para containers
make restart        # reinicia containers
make logs           # logs em tempo real
make ps             # lista containers
make shell-pg       # abre psql no PostgreSQL
make shell-mysql    # abre mysql no MySQL

# Projeto
make install        # composer install
make migrate        # php vupi migrate
make seed           # php vupi migrate --seed
make test           # testes de segurança
make analyse        # PHPStan nível 6
make setup          # setup completo (banco + deps + migrations)

# Caddy (proxy reverso / HTTPS)
make caddy-install  # instala Caddy no Ubuntu/Debian
make caddy-start    # inicia Caddy em produção (HTTPS Let's Encrypt)
make caddy-stop     # para Caddy
make caddy-reload   # recarrega config sem downtime
make caddy-dev      # HTTPS local com mkcert (desenvolvimento)

# Limpeza
make clean          # remove cache e arquivos temporários
make reset          # para containers e apaga volumes (CUIDADO: apaga dados!)

php -S localhost:3005 index.php                       # desenvolvimento
php vupi setup --auto --server=pm2+caddy           # produção: PM2 + Caddy
php vupi setup --auto --server=pm2                 # produção: apenas PM2

php vendor/bin/phpunit                                    # todos os testes unitários
php tests/SecurityTest.php http://localhost:3005          # OWASP API Top 10
php tests/FuzzTest.php http://localhost:3005              # fuzzing de endpoints
php tests/LoadAttackTest.php http://localhost:3005        # carga + ataque combinado
php tests/PerformanceTest.php http://localhost:3005       # testes de performance
ADMIN_PASSWORD=senha php tests/EnvConfigTest.php          # testes de configuração do .env