# Drive (Gerenciador de Mídias) — Resumo Executivo

> **Versão analisada:** `v6` (também existe na `v5`)
> **Slug do módulo:** `drive` (tabela `modulos`, id 30, `status = true`)
> **Natureza:** CMS (painel administrativo) — não há exposição no portal
> **Estado:** migrado v5 -> v6 (com renomeação de `midias` para `drive`)

---

## 1. Objetivo

O “Drive” é o **gerenciador de arquivos do CMS**: uma biblioteca central de mídias (imagens, PDFs, documentos) que o operador envia e consulta a partir de uma única tela. Ele também serve de componente reaproveitado por outros módulos (notícias, secretarias, agenda de eventos, páginas estáticas, destaques), que usam exatamente o mesmo JavaScript de galeria para anexar arquivos a um conteúdo.

## 2. Efeito / Impacto

| Faixa | Efeito |
|---|---|
| Cidadão | Nenhum efeito direto: o Drive é uma ferramenta interna do CMS. O impacto é indireto, pelos arquivos que os módulos públicos publicam |
| Prefeitura (CMS) | Upload múltiplo com pré-visualização, busca por nome, download, cópia do link público e exclusão de arquivos |
| Transparência e legalidade | Guardar em um só lugar os arquivos reutilizados pela publicação (imagens de destaque, logos, documentos) |
| Operação técnica | Uma única tabela `archives` atende o Drive e as galerias de todos os módulos; o upload gera versões `_min`, `_med` e `_larg` da imagem |

## 3. Comportamento

- Não existe tabela, model ou controller “drive”. O Drive é o **modo sem dono** da tabela `archives`: arquivos enviados sem `contents_id`, `static_pages_id` ou `calendar_events_id` ficam órfãos e formam a biblioteca global.
- A tela do Drive é a view de edição da categoria `midias` (`slug = 'midias'`, id 31); o rótulo exibido é “Drive”.
- O upload aceita `image/jpeg`, `image/png`, `image/jpg` (restrição do plugin no cliente) e grava em `storage/content/midias`.
- Cada arquivo é gravado em `archives` com `name`, `path`, `extension`, `type` (MIME) e `hash` (md5).
- A listagem mostra todos os arquivos do sistema, com carregamento progressivo (lotes de 50) por `IntersectionObserver`.
- Cada item tem quatro ações: **Copiar** (link público), **Baixar**, **Visualizar** e **Excluir**.
- O mesmo JavaScript (`assets/js/custom/contents/midias/index.js`) é usado nas telas de edição de notícias, secretarias, agenda de eventos, páginas estáticas, destaques e outros módulos.

## 4. Como o Usuário Interage

**Operador:** menu lateral `Drive` -> `/cms/conteudos/cadastrar/midias`. A página mostra o botão de upload múltiplo, um campo de busca por nome do arquivo e a grade de arquivos. Ao enviar, os arquivos aparecem no topo da grade; o botão “Excluir” remove o registro e o elemento da tela.

**Cidadão:** nada. Não há rota pública para o Drive nem para os arquivos por ele cadastrados (o acesso ocorre pelo caminho `storage/content/midias` publicado).

## 5. Detalhes e Particularidades Técnicas

- Camadas: `Route` (`galeria.*`) -> `Prefecture\ArchiveController` -> `ArchiveRepository`/`Archive` -> `archives` + `storage/`.
- A entrada do CMS é `ContentController@genericGenerate` com `slug = 'midias'`, que **força** a view `edit` (não existe `index` nem `create` para `midias`).
- O upload usa `FileTrait::saveUpload`, que gera nome aleatório (`uniqid` + 5 caracteres) e cria versões comprimidas da imagem.
- O `archives` guarda `contents_id`, `static_pages_id`, `calendar_events_id`, `highlight`, `type_size_id`, `width`, `height` e `order`; no Drive, todos ficam nulos.
- A listagem sem `id` não aplica nenhum filtro: retorna **todos** os arquivos do sistema, inclusive os de outros módulos.

## 6. Estrutura de Dados

| Objeto | Papel |
|---|---|
| `archives` | registro de cada arquivo (com `SoftDeletes`) |
| `types_sizes` | catálogo de tamanhos (Grande 600px, Médio 350px, Pequeno 200px, Personalizado) — **não usado** pelo Drive |
| `category_contents` | categoria `midias` (id 31), que dá nome à tela |
| `contents` | usado apenas como “dono” quando o arquivo pertence a um conteúdo |
| `storage/content/midias/` | diretório físico dos arquivos do Drive |

## 7. Como Testar

- Enviar 3 imagens, conferir a grade, a busca por nome, o “Copiar”, o “Baixar” e o “Excluir”.
- Confirmar que o `archives` recebeu os registros e que os arquivos físicos existem em `public/storage/content/midias`.
- Testes (v7): endpoint de upload (multipart), listagem paginada, exclusão, e o upload no contexto de conteúdo (galeria).

## 8. Migração para Laravel Moderno

- Tabela `media` dedicada (Laravel 12 traz `medialibrary`-like nativo; usar `spatie/laravel-medialibrary` ou tabela própria `media`), com `disk`, `directory`, `path`, `mime_type`, `size`, `width`, `height`, `collection`.
- `Media` model com `HasMedia` e coleções (`galeria`, `destaque`, `drive`).
- `FormRequest` com `mimes` e `max` por tipo; `Policy` `drive.*`.
- Endpoints REST: `GET /api/v1/cms/media`, `POST /api/v1/cms/media` (upload), `DELETE /api/v1/cms/media/{id}`, `PUT /api/v1/cms/media/{id}/ordem`.
- Processamento de imagem com `intervention/image` v3 (`ImageManager` com `GdDriver`), gerando as versões `_min`, `_med` e `_larg`.

## 9. Resumo Geral

O Drive não é um módulo com domínio próprio: é a interface de **gestão de arquivos** do CMS, apoiada na tabela `archives` e nas rotas `galeria.*` do `ArchiveController`. O acesso pelo menu leva a uma tela de “edição” da categoria `midias` — que existe justamente para não exigir uma listagem própria — e o JavaScript de galeria, compartilhado com vários módulos, faz o upload, a busca, a paginação progressiva e as ações por arquivo. A principal dívida é a ausência de escopo: a listagem do Drive devolve todos os arquivos do sistema, e os arquivos do Drive não têm dono, o que torna impossível saber quem os removeu. Na v7, a recomendação é um modelo `Media` com coleções e um endpoint paginado, mantendo a mesma experiência de uso.

---

## 10. Índice de rotas rápidas

| Contexto | URI | Observação |
|---|---|---|
| CMS | `/cms/conteudos/cadastrar/midias` | tela do Drive (menu lateral) |
| CMS | `/cms/galeria` | upload de arquivos (POST) |
| CMS | `/cms/galeria/{column}/{id}` | listagem dos arquivos de um conteúdo (GET) |
| CMS | `/cms/galeria/delete/{id}` | exclusão de um arquivo (POST) |
| CMS | `/cms/galeria/update-title/{id}` | renomear arquivo (PUT) |
| CMS | `/cms/galeria/update-order` | reordenar arquivos (POST) |
| Portal | sem rota pública | — |

## Índice do dossiê

| Arquivo | Conteúdo |
|---|---|
| `00-RESUMO.md` | Este documento |
| `01-ARQUITETURA.md` | Camadas, classes e o diagrama de fluxo |
| `02-MODELAGEM.md` | Estrutura de dados detalhada |
| `03-ROTAS-E-CONTROLADORES.md` | Rotas, controllers, requests, resources |
| `04-VIEWS-E-UX.md` | Telas, componentes, JS, assets |
| `05-REGRAS-E-PORTABILIDADE.md` | Particularidades e armadilhas |
| `06-MIGRACAO-MODERNA.md` | Plano de reconstrução em Laravel moderno |
| `07-TESTES.md` | Estratégia e casos de teste |
| `08-GAPS-E-DIVIDAS.md` | Pendências, riscos, comparativo v5 vs v6 |