# Telefones Úteis — Resumo Executivo > **Versão analisada:** `v6` (o módulo também existe na `v5`, com pequenas diferenças de caminho de view) > **Slug do módulo:** `telefones-uteis` (tabela `modulos`, id 27, `status = true`) > **Natureza:** Ambos (CMS + Portal público) > **Estado:** migrado v5 -> v6 --- ## 1. Objetivo O módulo publica a relação de telefones de contato do município (órgãos, secretarias, serviços de atendimento) para que o cidadão encontre, em um único endereço público, o número correto de cada setor. No CMS, o operador cadastra e edita cada telefone a partir de um formulário simples (título + número); no portal, os telefones são listados em uma página com busca instantânea por texto. ## 2. Efeito / Impacto | Faixa | Efeito | |---|---| | Cidadão | Acesso a uma agenda de contatos oficiais, com filtro por digitação na própria página | | Prefeitura (CMS) | Cadastro rápido de telefones com máscara de entrada e listagem em DataTable, sem dependência das tabelas `phones`/`phones_type` | | Transparência e legalidade | Divulgação de canais oficiais de atendimento; dados versionados em `contents` com trilha de log de atividade | | Operação técnica | Consulta do portal é uma única query Eloquent; o CMS lê uma view SQL de 3 colunas | ## 3. Comportamento - Cada telefone é um registro da tabela `contents` ligado à categoria `category_contents` de `slug = 'telefones-uteis'` (id 30). - O CMS lista os registros via view SQL `telefones_uteis` (colunas `value`, `titulo`, `id`), que já aplica `c.deleted_at IS NULL` e ordena por `created_at DESC`. - O formulário do CMS exige `title` (máx. 120), `category_contents_id` e `text` (o número); o campo `text` recebe máscara `advanced-phone`. - A exclusão pode ser individual (linha da tabela) ou em lote (`ajax.generic.content.deleteAll`). - O portal **não** filtra por `status`: todo conteúdo não apagado da categoria aparece na listagem pública. - A busca do portal é feita no cliente (JavaScript), sem consulta ao servidor. ## 4. Como o Usuário Interage **Operador (CMS):** menu lateral `Telefones Úteis` -> `/cms/conteudos/telefones-uteis`. Tabela com colunas ID, Título e Ações; botão “Cadastrar Telefone” (`cadastrar/telefones-uteis`); ação de edição (`editar/telefones-uteis/{id}`); seleção múltipla com exclusão em lote. **Cidadão (portal):** rota `/telefones-uteis`. Card de cabeçalho com ícone de telefone, campo “Digite para filtrar” e lista `ul#ulItens` com `title` (h5) e `text` (p) de cada registro. O breadcrumb exibido é `Home > Telefones Úteis`. ## 5. Detalhes e Particularidades Técnicas - Camadas: `Route` -> `ContentController`/`UsefulPhonesController` -> `ContentRequest` -> modelo `Content` -> `contents` (view `telefones_uteis` no CMS). - O CMS e o portal usam **caminhos de dados diferentes** para o mesmo conteúdo: o CMS lê a view `telefones_uteis`; o portal lê `contents` via `Content::whereHas('categoryContents')`. - As tabelas `phones` e `phones_type` **não participam** deste módulo: elas guardam telefones de contato do cidadão no fluxo LAI (`Portal\InformationController`). - A view SQL precisa ser recriada a cada migração; não há coluna de “status” exposta. - Dependências: `yajra/laravel-datatables`, `cartalyst/sentinel` (permissões `telefones-uteis.*`). ## 6. Estrutura de Dados | Objeto | Tipo | Papel no módulo | |---|---|---| | `contents` | tabela | Armazena título e número do telefone (`text`) | | `category_contents` | tabela | Categoria `telefones-uteis` (id 30) | | `telefones_uteis` | view SQL | Projeção `value`, `titulo`, `id` usada pelo DataTable do CMS | | `links` | tabela | Não utilizada por este módulo (o telefone fica em `contents.text`) | | `phones` / `phones_type` | tabelas | Pertencem ao fluxo LAI, não a este módulo | Migrations relevantes: `v6/database/migrations/2023_03_16_093714_create_view_to_telefones_uteis.php`, `v6/database/migrations/2018_04_02_180433_create_contents_table.php`, `v6/database/migrations/2018_04_01_180916_create_category_contents_table.php`. ## 7. Como Testar - Funcional: criar telefone no CMS, conferir na listagem e na página `/telefones-uteis`; digitar na busca e filtrar; excluir em lote. - Automatizado (v7): feature test da rota pública com 2 conteúdos da categoria; feature test do endpoint de DataTable verificando `titulo` e `id`; unit test da view SQL equivalent. ## 8. Migração para Laravel Moderno - Modelo `UsefulPhone` (tabela `contents` filtrada por categoria) ou, de preferência, tabela dedicada `useful_phones` com `title`, `phone`, `slug`, `active`. - `FormRequest` com `title`/`phone` obrigatórios e validação de máscara. - `Policy` por permissão (`telefones-uteis.create|edit|delete`). - Endpoint público JSON `GET /api/v1/telefones-uteis` para a busca do portal. - Componente Blade `` com filtro client-side ou endpoint de busca. ## 9. Resumo Geral Telefones Úteis é um módulo de conteúdo genérico: o dado real mora em `contents` (colunas `title` e `text`) e a categoria `telefones-uteis` apenas o classifica. O CMS usa o controller genérico de conteúdos e um DataTable alimentado pela view SQL `telefones_uteis`; o portal usa `Portal\UsefulPhonesController` e uma view por layout (`modelo1`..`modelo6`, `default`, `newsbit`) com busca em JavaScript. As tabelas `phones`/`phones_type` existem no mesmo projeto mas servem a outro fluxo (fale com a prefeitura) e não devem ser confundidas com este módulo. Na reconstrução, o ganho principal é separar o telefone do texto genérico de `contents` e expor um endpoint de leitura em vez de depender de view SQL. --- ## 10. Índice de rotas rápidas | Contexto | URI | Nome da rota | |---|---|---| | Portal | `/telefones-uteis` | `telefones-uteis.index` | | CMS listagem | `/cms/conteudos/telefones-uteis` | `listar-conteudo` (parâmetro `slug`) | | CMS cadastro | `/cms/conteudos/cadastrar/telefones-uteis` | `cadastrar-conteudo` | | CMS edição | `/cms/conteudos/editar/telefones-uteis/{id}` | `editar-conteudo` | | CMS DataTable | `/cms/datatable/telefones_uteis` | `telefones_uteis` (grupo `datatable`) | | CMS gravação | `/cms/conteudo` e `/cms/conteudo/{id}` | `conteudo.store` / `conteudo.update` | | CMS exclusão em lote | `/cms/conteudo/deleteAll` | `ajax.generic.content.deleteAll` | ## Í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 |