# Services - Lógica de Negócio SIGED

## Overview

Os Services encapsulam toda a lógica de negócio do sistema, separando-a dos Controllers. Cada Service é responsável por uma funcionalidade específica.

## 1. AlunoService

### Localização
```
app/Services/AlunoService.php
```

### Responsabilidades
- Criar novo aluno
- Atualizar dados do aluno
- Validar dados antes de salvar
- Calcular média de notas
- Calcular frequência
- Transferir aluno
- Exportar dados do aluno
- Importar alunos em lote

### Métodos Principais

```php
<?php

namespace App\Services;

use App\Models\Aluno;
use App\Models\AnoLetivo;
use Illuminate\Support\Collection;

class AlunoService
{
    /**
     * Criar novo aluno
     */
    public function criar(array $dados): Aluno
    {
        // Validar matrícula única
        // Calcular idade
        // Salvar foto se enviada
        // Retornar aluno criado
    }

    /**
     * Atualizar aluno
     */
    public function atualizar(Aluno $aluno, array $dados): Aluno
    {
        // Validar dados
        // Atualizar registro
        // Retornar aluno atualizado
    }

    /**
     * Calcular média de notas
     */
    public function calcularMedia(Aluno $aluno, int $ano = null): float
    {
        // Buscar notas do aluno
        // Calcular média ponderada por bimestre
        // Retornar média
    }

    /**
     * Calcular frequência
     */
    public function calcularFrequencia(Aluno $aluno): float
    {
        // Buscar chamadas biométricas
        // Contar presentes
        // Contar total
        // Calcular percentual
    }

    /**
     * Transferir aluno
     */
    public function transferir(Aluno $aluno, string $motivo): void
    {
        // Marcar como transferido
        // Gerar documento
        // Enviar notificação
    }

    /**
     * Importar alunos (CSV)
     */
    public function importarCSV(string $caminho): Collection
    {
        // Ler arquivo CSV
        // Validar dados
        // Criar alunos
        // Retornar relatório
    }

    /**
     * Exportar dados
     */
    public function exportarExcel(array $alunoIds): string
    {
        // Buscar alunos
        // Formatar dados
        // Gerar Excel
        // Retornar caminho arquivo
    }
}
```

---

## 2. NotaService

### Localização
```
app/Services/NotaService.php
```

### Responsabilidades
- Criar nota
- Atualizar nota com validação
- Calcular média por aluno
- Calcular média por turma
- Identificar alunos em recuperação
- Validar intervalo de notas (0-10)
- Lançamento em lote

### Métodos Principais

```php
<?php

namespace App\Services;

use App\Models\Nota;
use App\Models\Aluno;
use App\Models\Turma;

class NotaService
{
    /**
     * Criar nota
     */
    public function criar(array $dados): Nota
    {
        // Validar intervalo (0-10)
        // Validar aluno/disciplina
        // Criar nota
        // Dispara evento
    }

    /**
     * Validar nota
     */
    public function validar(float $nota, int $bimestre): bool
    {
        // Verificar se está entre 0 e 10
        // Verificar bimestre válido
        // Retornar resultado
    }

    /**
     * Calcular média aluno
     */
    public function mediaAluno(Aluno $aluno, int $bimestre = null): float
    {
        // Buscar notas
        // Calcular média
        // Retornar
    }

    /**
     * Calcular média turma
     */
    public function mediaTurma(Turma $turma, int $bimestre = null): float
    {
        // Buscar notas da turma
        // Calcular média
        // Retornar
    }

    /**
     * Identificar alunos em recuperação
     */
    public function alunosEmRecuperacao(Turma $turma, int $bimestre): Collection
    {
        // Buscar notas < 7
        // Retornar alunos
    }

    /**
     * Lançamento em lote
     */
    public function lancarEmLote(array $notas): Collection
    {
        // Validar cada nota
        // Criar em transação
        // Retornar resultado
    }

    /**
     * Gerar boletim
     */
    public function gerarBoletim(Aluno $aluno, int $ano): array
    {
        // Buscar notas por bimestre
        // Calcular média
        // Formatar dados
        // Retornar boletim
    }
}
```

---

## 3. DisciplinaryService

### Localização
```
app/Services/DisciplinaryService.php
```

### Responsabilidades
- Registrar ocorrência disciplinar
- Aplicar punição
- Assinar ocorrência
- Gerar termo de punição
- Calcular nota disciplinar do aluno
- Validar enquadramento
- Histórico disciplinar

### Métodos Principais

```php
<?php

namespace App\Services;

use App\Models\OcorrenciaDisciplinar;
use App\Models\Aluno;

class DisciplinaryService
{
    /**
     * Registrar ocorrência
     */
    public function registrar(array $dados): OcorrenciaDisciplinar
    {
        // Validar dados
        // Criar ocorrência
        // Notificar responsável
        // Retornar
    }

    /**
     * Aplicar punição
     */
    public function aplicarPunicao(OcorrenciaDisciplinar $ocorrencia, array $dados): void
    {
        // Validar tipo de punição
        // Definir duração
        // Salvar em banco
        // Enviar notificação
    }

    /**
     * Assinar ocorrência
     */
    public function assinar(OcorrenciaDisciplinar $ocorrencia, array $assinatura): void
    {
        // Validar assinatura
        // Marcar como assinada
        // Registrar data/hora
        // Gerar documento
    }

    /**
     * Gerar termo
     */
    public function gerarTermo(OcorrenciaDisciplinar $ocorrencia): string
    {
        // Formatar dados
        // Gerar PDF
        // Retornar caminho arquivo
    }

    /**
     * Calcular nota disciplinar
     */
    public function calcularNotaDisciplinar(Aluno $aluno): float
    {
        // Buscar ocorrências
        // Aplicar penalidades
        // Calcular nota final
        // Retornar
    }

    /**
     * Obter histórico
     */
    public function obterHistorico(Aluno $aluno): Collection
    {
        // Buscar ocorrências
        // Ordenar por data
        // Retornar
    }
}
```

---

## 4. BiometricService

### Localização
```
app/Services/BiometricService.php
```

### Responsabilidades
- Registrar entrada/saída biométrica
- Integrar com dispositivos biométricos
- Validar qualidade de biometria
- Reconhecimento facial (se habilitado)
- Marcar como presente/ausente
- Gerar relatório de frequência

### Métodos Principais

```php
<?php

namespace App\Services;

use App\Models\ChamadaBiometrica;
use App\Models\Aluno;

class BiometricService
{
    /**
     * Registrar entrada
     */
    public function registrarEntrada(Aluno $aluno, string $tipo = 'BIOMETRICA'): ChamadaBiometrica
    {
        // Validar aluno
        // Registrar entrada
        // Salvar qualidade
        // Retornar
    }

    /**
     * Registrar saída
     */
    public function registrarSaida(Aluno $aluno): void
    {
        // Buscar chamada do dia
        // Registrar saída
        // Marcar como presente
    }

    /**
     * Validar qualidade
     */
    public function validarQualidade(float $qualidade): bool
    {
        // Verificar threshold mínimo
        // Retornar resultado
    }

    /**
     * Reconhecimento facial
     */
    public function reconhecerRosto(string $imagem): ?Aluno
    {
        // Integrar com API facial
        // Processar imagem
        // Retornar aluno identificado
    }

    /**
     * Marcar presente
     */
    public function marcarPresente(Aluno $aluno): void
    {
        // Buscar chamada do dia
        // Marcar como presente
        // Salvar
    }

    /**
     * Gerar relatório
     */
    public function gerarRelatorioFrequencia(Turma $turma, string $periodo): array
    {
        // Buscar chamadas
        // Calcular presença por aluno
        // Formatar dados
        // Retornar
    }
}
```

---

## 5. WhatsAppService

### Localização
```
app/Services/WhatsAppService.php
```

### Responsabilidades
- Enviar mensagens WhatsApp
- Integração com API Evolution ou Twilio
- Gerenciar templates de mensagem
- Webhook para receber mensagens
- Histórico de mensagens
- Notificações de eventos

### Métodos Principais

```php
<?php

namespace App\Services;

use App\Models\Usuario;

class WhatsAppService
{
    /**
     * Enviar mensagem
     */
    public function enviar(string $telefone, string $mensagem): bool
    {
        // Validar telefone
        // Integrar com API
        // Enviar mensagem
        // Salvar histórico
    }

    /**
     * Obter template
     */
    public function obterTemplate(string $tipo, array $dados = []): string
    {
        // Buscar template
        // Substituir variáveis
        // Retornar mensagem
    }

    /**
     * Notificar responsável
     */
    public function notificarResponsavel(Aluno $aluno, string $tipo, array $dados): void
    {
        // Obter template
        // Enviar para responsável
        // Registrar
    }

    /**
     * Processar webhook
     */
    public function processarWebhook(array $dados): void
    {
        // Validar webhook
        // Processar mensagem recebida
        // Salvar histórico
    }

    /**
     * Obter histórico
     */
    public function obterHistorico(Usuario $usuario, int $limite = 50): Collection
    {
        // Buscar mensagens
        // Ordenar por data
        // Retornar
    }
}
```

---

## 6. ReportService

### Localização
```
app/Services/ReportService.php
```

### Responsabilidades
- Gerar relatório acadêmico
- Gerar relatório disciplinar
- Gerar relatório de frequência
- Exportar para Excel/PDF
- Aplicar filtros
- Cache de relatórios

### Métodos Principais

```php
<?php

namespace App\Services;

use App\Models\Turma;
use App\Models\Aluno;

class ReportService
{
    /**
     * Relatório acadêmico
     */
    public function relatorioAcademico(Turma $turma, int $bimestre): array
    {
        // Buscar dados
        // Calcular estatísticas
        // Formatar
        // Retornar
    }

    /**
     * Relatório disciplinar
     */
    public function relatorioDisciplinar(Turma $turma, string $periodo): array
    {
        // Buscar ocorrências
        // Agrupar por tipo
        // Calcular totalizações
        // Retornar
    }

    /**
     * Relatório de frequência
     */
    public function relatorioFrequencia(Turma $turma, string $periodo): array
    {
        // Buscar chamadas
        // Calcular presença
        // Identificar faltosos
        // Retornar
    }

    /**
     * Exportar para Excel
     */
    public function exportarExcel(array $dados, string $nome): string
    {
        // Formatar dados
        // Criar arquivo Excel
        // Salvar
        // Retornar caminho
    }

    /**
     * Exportar para PDF
     */
    public function exportarPdf(array $dados, string $nome): string
    {
        // Formatar dados
        // Criar PDF
        // Salvar
        // Retornar caminho
    }
}
```

---

## 7. TenantService

### Localização
```
app/Services/TenantService.php
```

### Responsabilidades
- Criar novo tenant
- Gerenciar banco de dados do tenant
- Migrar dados entre tenants
- Verificar limite de alunos
- Renovar contrato
- Suspender tenant

### Métodos Principais

```php
<?php

namespace App\Services;

use App\Models\Tenant;

class TenantService
{
    /**
     * Criar tenant
     */
    public function criar(array $dados): Tenant
    {
        // Validar dados
        // Criar registro
        // Criar banco de dados
        // Executar migrations
        // Retornar
    }

    /**
     * Verificar limite
     */
    public function verificarLimitAlunos(Tenant $tenant): array
    {
        // Contar alunos
        // Comparar com limite
        // Retornar status
    }

    /**
     * Renovar contrato
     */
    public function renovarContrato(Tenant $tenant, int $dias): void
    {
        // Estender data de expiração
        // Salvar
        // Enviar confirmação
    }

    /**
     * Suspender tenant
     */
    public function suspender(Tenant $tenant, string $motivo): void
    {
        // Desativar acesso
        // Enviar notificação
        // Registrar motivo
    }
}
```

---

## 8. ExportService

### Localização
```
app/Services/ExportService.php
```

### Responsabilidades
- Exportar alunos
- Exportar notas
- Exportar relatórios
- Gerar ZIP com múltiplos arquivos
- Formatar dados para export

---

## 9. EmailService

### Localização
```
app/Services/EmailService.php
```

### Responsabilidades
- Enviar emails do sistema
- Templates de email
- Filas de email
- Confirmação de envio

---

## Padrão de Implementação

### Template Básico de Service

```php
<?php

namespace App\Services;

use App\Models\Model;
use Illuminate\Support\Collection;

class MeuService
{
    /**
     * Construtor (se necessário injetar dependências)
     */
    public function __construct()
    {
        // 
    }

    /**
     * Método principal
     *
     * @param array $dados
     * @return Model
     * @throws \Exception
     */
    public function metodo(array $dados): Model
    {
        try {
            // Validar dados
            $this->validar($dados);
            
            // Processar
            $resultado = $this->processar($dados);
            
            // Retornar
            return $resultado;
        } catch (\Exception $e) {
            \Log::error('Erro em MeuService::metodo', [
                'erro' => $e->getMessage(),
                'dados' => $dados,
            ]);
            throw $e;
        }
    }

    /**
     * Validar dados
     */
    private function validar(array $dados): void
    {
        // Validação customizada
    }

    /**
     * Processar dados
     */
    private function processar(array $dados)
    {
        // Lógica de negócio
    }
}
```

### Injeção de Dependência em Controllers

```php
<?php

namespace App\Http\Controllers;

use App\Services\MeuService;

class MeuController extends Controller
{
    public function __construct(private MeuService $meuService)
    {
        //
    }

    public function store(Request $request)
    {
        $resultado = $this->meuService->metodo($request->validated());
        return response()->json($resultado);
    }
}
```

---

## Próximos Passos

1. Implementar Services em ordem de prioridade
2. Criar testes unitários para cada Service
3. Integrar com Controllers
4. Documentar métodos com examples
5. Optimizar performance com cache

---

**Status**: Em Desenvolvimento
**Última atualização**: 2024