# Rota `atestados` — atestados dos alunos por disciplina (regência)

Implementa o card "Atestados dos Alunos" da tela de lançamentos de uma disciplina (ver
`docs/00005 - Rota Lancamentos (Menu por Disciplina).md`): lista os atestados médicos dos
alunos matriculados na turma da regência clicada.

## 1. Endpoint

| Método | Rota | Middleware | Descrição |
|---|---|---|---|
| GET | `/api/v1/atestados` | `identify.tenant`, `ensure.session.tenant`, `auth:sanctum` | Retorna os atestados dos alunos da turma da regência informada |

Parâmetro via query string, validado por `AtestadoAlunoRequest`:

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `regencia` | integer | sim | `regencia_id` da disciplina (o mesmo usado em `GET /api/v1/lancamentos`) |

Diferente de `/lancamentos`, esta rota não recebe `ano`: o filtro por ano letivo já está
embutido na consulta (compara `date_part('year', data_inicio)` com o ano do calendário da
turma da própria regência).

## 2. Fluxo de dados

```
GET /api/v1/atestados?regencia=
  → identify.tenant / ensure.session.tenant / auth:sanctum
    → AtestadoAlunoRequest              (valida regencia)
      → AtestadoAlunoDTO::fromRequest
        → AtestadoAlunoController::index
          → AtestadoAlunoServiceContract::getAtestados(dto)
            → AtestadoAlunoRepositoryInterface::findByRegencia(regencia)
              → DB::connection('tenant')->select(...) na consulta fornecida
                (escola.aluno + e2ti.escola_atestado_aluno + e2ti.escola_atestado +
                 escola.tipoausencia, filtrando por EXISTS na matrícula/turma/regência)
          ← Collection de {aluno_nome, data_inicio, data_fim, tipo_ausencia}
        ← AtestadoAlunoResource::collection(...)
```

Assim como em `EloquentLancamentoMenuRepository`, a consulta é feita via
`DB::connection('tenant')->select()` (não por um Model Eloquent), então o Repository chama
`App\Facades\Utils::convertToUtf8()` (ver `docs/00007 - Facade Utils (convertToUtf8).md`)
em cada linha antes de devolver, convertendo cada string de Latin-1 para UTF-8 — o listener
global (`ConvertEloquentAttributesToUtf8`) só age em models hidratados via Eloquent.

## 3. Arquivos criados

| Arquivo | Camada | O que faz |
|---|---|---|
| `app/Repositories/Contracts/AtestadoAlunoRepositoryInterface.php` | Repository (contrato) | Define `findByRegencia(regencia)` |
| `app/Repositories/EloquentAtestadoAlunoRepository.php` | Repository | Executa a consulta fornecida via `DB::connection('tenant')->select()`, convertendo cada string para UTF-8 |
| `app/DTOs/AtestadoAlunoDTO.php` | DTO | Empacota `regencia` já validado e convertido para inteiro |
| `app/Http/Requests/AtestadoAlunoRequest.php` | FormRequest | Valida `regencia` (obrigatório, inteiro) |
| `app/Services/Contracts/AtestadoAlunoServiceContract.php` | Service (contrato) | Define `getAtestados(AtestadoAlunoDTO $dto)` |
| `app/Services/AtestadoAlunoService.php` | Service | Delega ao Repository |
| `app/Http/Resources/AtestadoAlunoResource.php` | Resource | Formata cada item como `{ aluno_nome, data_inicio, data_fim, tipo_ausencia }` |
| `app/Http/Controllers/Api/V1/AtestadoAlunoController.php` | Controller | `index()`: valida via FormRequest, monta o DTO, chama o Service, devolve `AtestadoAlunoResource::collection(...)` |
| `docs/00006 - Rota Atestados de Alunos.md` | Documentação | Este arquivo |
| `tests/Feature/Api/V1/AtestadoAlunoControllerTest.php` | Teste (Feature) | `GET /atestados`: tenant ausente, autenticação ausente, validação de `regencia`, resposta de sucesso (Service mockado) |
| `tests/Unit/Services/AtestadoAlunoServiceTest.php` | Teste (Unit) | Confirma que o Service delega ao Repository com a `regencia` do DTO |

## 4. Arquivos modificados

| Arquivo | Mudança | Motivo |
|---|---|---|
| `routes/api.php` | Novo `GET /atestados` no grupo autenticado | Expõe o endpoint |
| `app/Providers/AppServiceProvider.php` | Novos bindings (`AtestadoAlunoRepositoryInterface` → `EloquentAtestadoAlunoRepository`, `AtestadoAlunoServiceContract` → `AtestadoAlunoService`) | Injeção de dependência das novas camadas |
| `docs/00000 - Rotas.md` | Documenta o novo endpoint | Manter a lista de rotas atualizada |

## 5. Front-end

O front (`professor-front`) chama esta rota ao clicar no card "Atestados dos Alunos" na
tela de lançamentos da disciplina (`LancamentosDisciplina.jsx`), navegando para
`/disciplina/:regenciaId/lancamentos/atestado` (`AtestadosAlunos.jsx`) — a `regencia` usada
na query string vem do próprio `:regenciaId` da rota (o `state` da navegação só carrega
Escola/Turma/Série/Disciplina, para o cabeçalho). A tela lista os
resultados em uma tabela (Nome do Aluno, Data de Início, Data Final, Tipo de Ausência),
exibindo acima o mesmo caminho `Escola >> Turma / Série >> Disciplina` já usado na tela de
lançamentos.

## 6. Testes

```
composer test
# ou
php artisan test tests/Feature/Api/V1/AtestadoAlunoControllerTest.php tests/Unit/Services/AtestadoAlunoServiceTest.php
```