# Utilitários — Módulo Fantasma (NÃO IMPLEMENTADO)

## 1. O que é o módulo

Grupo de módulos funcionais auxiliares, serviços genéricos e utilidades práticas que dão suporte operacional aos demais módulos ou oferecem funcionalidades menores e ferramentas de uso cotidiano: geradores de QR Code, exportação/importação de dados, encurtadores de link, gerenciador de contatos, etc.

**Status:** NÃO IMPLEMENTADO. Apenas esboço conceitual.

## 2. Estrutura de dados

Inexistente. Não há modelos, migrations ou tabelas.

## 3. Dependências

Inexistentes.

## 4. Tabelas

Nenhuma.

## 5. Arquivos

```
V2/Modules/Utilitarios/
└── README.md        # Apenas esboço conceitual descrevendo o propósito do grupo
```

## 6. Observações/Sugestão

Para implementar seguindo os padrões V2:

1. Possível arquitetura de módulos dentro deste grupo:

   **QR Code Generator:**
   - `V2/Modules/Utilitarios/QRCode/`
   - Gera QR Codes a partir de texto/URL passado por parâmetro
   - Pode ser serviço interno (outros módulos chamam) ou endpoint público
   - Usar biblioteca `simple-qrcode` ou `endroid/qr-code`
   - Model/Service: `QRCodeService::generate($data)` retorna imagem ou SVG
   - Sem migrations ou views — puramente service
   - Pode ter um controller CMS simples para teste

   **Exportador/Importador de Dados:**
   - `V2/Modules/Utilitarios/DataTool/`
   - Exportar dados de qualquer módulo para CSV, XLSX, JSON
   - Importar dados de CSV para qualquer modelo V2
   - Interface CMS para mapear colunas
   - Models: `ExportTemplate`, `ImportLog`
   - Tabelas: `v2_export_templates`, `v2_import_logs`
   - Activity log para todas as operações

   **Encurtador de Links:**
   - `V2/Modules/Utilitarios/ShortLink/`
   - Models: `ShortLink` (slug curto, url_destino, clicks, expires_at)
   - Tabela: `v2_short_links`
   - Rota pública: `/go/{slug}` → redireciona 301
   - Painel CMS para criar e gerenciar links
   - Estatísticas de cliques

   **Gerenciador de Contatos:**
   - `V2/Modules/Utilitarios/Contatos/`
   - Catálogo de contatos institucionais (telefones, e-mails, setores)
   - Models: `Contato` (nome, setor, email, telefone, ordem)
   - Tabela: `v2_contatos`
   - Importação CSV
   - Widget para ser incorporado no footer do portal

2. Estrutura padrão por submódulo:
   ```
   {Modulo}/
   ├── Controllers/{Modulo}CmsController.php
   ├── Models/{Model}.php               # (se houver persistência)
   ├── Services/{Modulo}Service.php
   ├── ModuleProvider.php
   ├── Routes/cms.php, web.php          # (web.php para rotas públicas como /go/{slug})
   ├── Migrations/*.php                # (se houver)
   └── Views/cms/*                     # (se houver interface CMS)
   ```

3. Módulos puramente de serviço (ex: QRCode) podem omitir Controllers, Views e Routes, registrando apenas o service no ModuleProvider.

4. Considerações importantes:
   - QR Code sem dependências externas de API (geração local)
   - Encurtador de links precisa de slugs únicos e previsíveis (evitar colisão)
   - Importador de dados precisa de validação rigorosa e rollback em caso de erro
   - Qualquer módulo que exponha rota pública deve ter rate limiting