# Obras — Exportações e Endpoints do Front

> Complemento de `04-VIEWS-E-UX.md` (v5). As seções "Endpoints consumidos pelo
> front" e "Exportações" foram movidas para cá para manter todos os arquivos
> dentro do limite de 400 linhas.

---

## 1. Endpoints consumidos pelo front

| Endpoint | Chamado de |
|---|---|
| `GET /cms/datatable/listagem_obras` | `datatable.js` |
| `GET /cms/datatable/listagem_categorias_obras` | `categorias-datatable.js` |
| `GET /cms/obras/get-geolocation-data?address=...` | `script.js` |
| `GET /cms/galerias-obras/{id}` | `edit.blade.php` (`chargeGallery`) |
| `POST /cms/galerias-obras` | `edit.blade.php` (`setupUpload`) |
| `POST /cms/galeria/delete/{id}` | `script.js` (`deleteFile`) |
| `DELETE /cms/obras/{id}` | `table.js` (`addDelete`) |
| `DELETE /cms/categorias-obras/{id}` | `table.js` (`addDelete`) |
| `https://viacep.com.br/ws/{cep}/json/` | `script.js` (externo) |
| `https://maps.googleapis.com/maps/api/geocode/json` | `GeocodingService` (externo, server-side) |
| `https://servicodados.ibge.gov.br/api/v4/...` | `geo.js` (externo) |

## 2. Exportações

### 2.1 Excel / CSV (servidor)

Classe: `v5/app/Exports/WorksExport.php` (implementa `FromView` do
`maatwebsite/excel`).

```php
class WorksExport implements FromView
{
    public $works;

    public function __construct($works)
    {
        $this->works = $works;
    }

    public function view(): View
    {
        return view('exports.works', ['obras' => $this->works]);
    }
}
```

Controller:

```php
public function export($obras, $type)
{
    if ($type == 'xls') {
        return Excel::download(new WorksExport($obras), 'obras.xlsx');
    } elseif ($type == 'csv') {
        return Excel::download(new WorksExport($obras), 'obras.csv');
    } else {
        return $this->exportTxt($obras, 'obras.txt');
    }
}
```

> **Só a página corrente é exportada.** O `index()` faz
> `$result = $result->orderBy(...)->paginate(10);` **antes** de checar
> `Route::currentRouteName() == 'portal-obras.exportacao'`. Logo,
> `export()` recebe o `LengthAwarePaginator` — e o Blade de exportação itera
> `$obras` (o paginator), ou seja, **apenas os 10 registros da página 1**.
> Um usuário que filtrou por "Finalizada" e quer a planilha completa recebe
> só 10 linhas.

View: `v5/resources/views/exports/works.blade.php` — HTML tabular de 10
colunas: Título, Categoria, Situação, Valor, Valor Pago, Data de Início, Data
de Término, Previsão de Conclusão, Percentual Concluído, Descrição. Usa
`{{ $obra->workCategory->name }}` e `{{ $obra->status->name }}` — **N+1** em
cada linha exportada (o paginator não usa `with()`).

> Os valores monetários saem **sem formatação**: `R$ {{ $obra->value }}`
> imprime o `varchar` cru (ex.: `R$ 123456.78`).

### 2.2 TXT (servidor)

```php
function gerarTxt($models) {
    $txt =  "Título   | Categoria    | Situação | Valor    | Valor Pago    | Data Início  | Data Fim    ".
          "\n---------|--------------| ---------|----------|---------------|--------------|-------------";
    foreach ($models as $model) {
        $txt .= "\n{$model->title} | {$model->workCategory->name} | {$model->status->name} | R$ {$model->value} | R$ {$model->value_paid} | {$model->start_date} | {$model->end_date}";
    }
    return $txt ;
}
```

> O TXT **não inclui** descrição, previsão de conclusão, percentual nem
> justificativa — é um subconjunto do Excel. E as datas saem no formato bruto
> do cast (`Y-m-d`), não `d/m/Y`.

### 2.3 PDF (navegador)

Gerado em `index.blade.php` (todos os modelos) com
`jspdf.umd.min.js` + `jspdf-autotable.min.js` + `gerar-pdf-obras.js`, a partir
do array `obras` injetado no HTML. Detalhes e defeitos em `3.5`.