# Carta de Serviços (ServiceLetter) — Resumo Executivo > **Versão analisada:** `v6` (módulo **novo** na v6 — não existe na v5) > **Slug do módulo:** `carta-de-servicos` — registrado em `modulos` (id 57), `resources` (id 4) e `menu_orders` (id 3) > **Natureza:** CMS (painel administrativo) + Portal (público) > **Estado:** novo na v6 --- ## 1. Objetivo A Carta de Serviços é o catálogo oficial de serviços públicos do município. O módulo permite ao operador cadastrar, documentar e publicar cada serviço prestado pela prefeitura, organizando-o por **assunto**, vinculando-o a uma **secretaria** e descrevendo, de forma estruturada, **como o cidadão deve solicitar** o serviço: canais de atendimento, etapas do fluxo, documentos exigidos, responsáveis, custos e prazos. O cidadão acessa essa informação no portal público por assunto, com busca, filtro por secretaria e uma versão consolidada em PDF. ## 2. Efeito / Impacto | Faixa | Efeito | |---|---| | Cidadão | Consulta serviços por assunto, com busca textual e filtro por secretaria; visualiza etapas, documentos exigidos, canais, responsáveis, custos e prazos; baixa a Carta de Serviços completa em PDF. | | Prefeitura (CMS) | CRUD de serviços, assuntos, canais, etapas, documentos, anexos e responsáveis; configurações de identidade visual do PDF; histórico de geração de PDF. | | Transparência e legalidade | Formaliza o procedimento de cada serviço (etapas/prazos/documentos), atendendo ao princípio da publicidade e à Lei 13.460/2017 (Carta de Serviços ao Cidadão). | | Operação técnica | Módulo 100% novo na v6: 13 migrations, 10 models, 9 controllers, 5 views CMS, 30 views de portal (6 modelos × 5 arquivos), 4 arquivos JS. | ## 3. Comportamento - **Serviço** é a entidade central (`service_letters`). Pertence a uma **secretaria** (`contents` com `category_contents_id = 7`, categoria "Secretarias") e pode estar vinculado a **vários assuntos** (N:N em `service_letters_subjects_rel`). - **Exibição do serviço** tem dois modos, gravados em `tipo_exibicao`: `pagina` (página interna no portal, com todo o detalhe) ou `link_externo` (apenas um botão "Acessar Serviço Online" apontando para `link_externo`). - **Publicação**: um serviço só aparece no portal se `ativo = true` **e** `publicado = true`. `publicado_em` é gravado na primeira publicação. - **Etapas** (`service_letter_steps`) têm `numero`, `titulo`, `descricao`, `prazo` (texto livre, ex.: "5 dias úteis") e `ordem`. São exibidas no portal em ordem de `numero`; a ordenação na relação Eloquent é por `ordem`. - **Canais** (`service_letter_channels`) têm `tipo` ∈ {`online`, `telefone`, `presencial`} e, conforme o tipo, o campo de contato correspondente (`url`, `telefone`, `endereco`). - **Documentos necessários** (`service_letter_documents`) têm `nome`, `descricao` e flag `obrigatorio`. - **Responsáveis** (`service_letter_responsaveis`) têm `nome`, `cargo`, `email`, `telefone`, `foto`, `ordem`. - **Anexos** (`service_letter_attachments`) são arquivos enviados pelo operador (limite de 10 MB) com nome, descrição, mime type e tamanho. - **PDF**: o operador dispara a geração; o PDF consolidado é gravado em disco e registrado em `service_letter_pdfs` com contagem de serviços, ordenação e total de páginas. - **Visualizações**: cada abertura da página de um serviço incrementa o contador `service_letters.visualizacoes`. - **Destaque** (`destaque`) é uma flag independente de `publicado`, alternável pela rota de toggle. ## 4. Como o Usuário Interage **CMS** (`/cms/carta-de-servicos`): - Tela de **Serviços** com DataTable (nome, secretaria, assuntos, menu, status, destaque) e botões "Gerar PDF", "Configurações", "Cadastrar Serviço", além de exclusão em lote. - Tela de **Assuntos** com DataTable (visual, nome, ordem, status) e CRUD próprio. - Formulário de serviço (abas): dados básicos, formas de acesso, informações do serviço, custos, prazos, atendimento, e — **somente no modo `pagina`** — abas de **Responsáveis, Canais, Etapas, Documentos e Anexos**, cada uma com tabela própria e modal de cadastro alimentado por AJAX. - Tela de **Configurações**: nome, ordenação dos serviços, sumário, textos fixos (cabeçalho, rodapé, antes/depois do sumário, encerramento), tipo de capa (editor ou PDF) e tipografia (fonte/tamanho/cor de texto e título). - Tela de **PDFs Gerados**: listagem paginada com visualizar, download e excluir. **Portal** (`/carta-de-servicos`): - `/carta-de-servicos` redireciona para o primeiro assunto ativo; se não houver assunto, mostra a listagem de assuntos. - `/carta-de-servicos/{slugAssunto}` mostra a lista paginada de serviços do assunto, com busca por texto e filtro por secretaria, recarregados por AJAX sem recarregar a página. - `/carta-de-servicos/{slugAssunto}/{slugServico}` mostra a ficha completa do serviço. ## 5. Detalhes e Particularidades Técnicas - Fluxo: `routes/service_letter.php` (CMS, carregado via `require` em `routes/basepro.php:512`) → `check.logged` → controller com `check.route.permission` → validação inline (`$request->validate`) → model Eloquent direto (o módulo **não usa repositories**) → view Blade. - O portal **também** usa `check.site.manutention` (grupo em `routes/web.php:7`). - A listagem do CMS lê **views SQL** (`listagem_servicos_carta_de_servicos`, `listagem_assuntos_carta_de_servicos`) via Yajra DataTables. - Dependências de terceiros: `yajra/laravel-datatables`, `laralabs/toaster`, `spatie/laravel-activitylog` (log de auditoria), `laravelcollective/html` (`Form::open`), `laravellegends/pt-br-validator`. - **Risco verificado**: o controller de PDF referencia `App\Services\ServiceLetterPdfService`, classe **inexistente** em `v6/app/Services/` — a geração de PDF falha com erro de classe não encontrada. - **Risco verificado**: o form do serviço referencia `assets/css/custom/contents/carta-de-servicos/style.css`, arquivo **inexistente** em `public/assets/css/`. ## 6. Estrutura de Dados 10 tabelas próprias (`service_letters`, `service_letter_subjects`, `service_letter_configs`, `service_letter_channels`, `service_letter_steps`, `service_letter_documents`, `service_letter_attachments`, `service_letter_responsaveis`, `service_letter_pdfs`, `service_letter_access_logs`), 1 pivot (`service_letters_subjects_rel`) e 2 views SQL. Detalhe em `02-MODELAGEM.md`. ## 7. Como Testar Cenários manuais e automatizados propostos em `07-TESTES.md` — cobrem publicação, filtro do portal, CRUD de etapas via AJAX, validação de responsável, geração de PDF e increment de visualizações. ## 8. Migração para Laravel Moderno Reescrever com Eloquent enxuto, Form Requests dedicated (`StoreServiceRequest`, `StoreStepRequest`, `StoreChannelRequest`, `StoreResponsavelRequest`), Resources JSON, Policies por verbo (`viewAny`, `create`, `update`, `delete`), enums para `tipo_exibicao`, `menu_acesso_rapido`, `tipo` de canal e `status` de PDF, e um `ServiceLetterPdfService` real (a classe ausente é a lacuna central). Detalhe em `06-MIGRACAO-MODERNA.md`. ## 9. Resumo Geral A Carta de Serviços é um módulo **inteiramente novo na v6**, sem equivalente na v5. Ele nasce de uma migration que, além de criar 10 tabelas, insere o próprio módulo no registro `modulos` (`carta-de-servicos`, id 57) e no menu do CMS. O operador cadastra serviços, os vincula a assuntos e secretarias, e detalha cada um com etapas, canais, documentos, anexos e responsáveis — todos editados por modais AJAX sem sair da tela. O público consulta esses dados por assunto no portal, com busca e filtro, e pode baixar a carta completa em PDF. A arquitetura é simples (controller → model → view, sem repository), o que torna a migração para Laravel moderno relativamente direta, mas o módulo carrega duas falhas graves a resolver: o **serviço de geração de PDF não existe** e o **CSS referenciado pelo formulário não existe**. Há ainda inconsistências menores a auditar: ordenação dupla de etapas (`numero` vs `ordem`), divergência entre a assinatura `menu_acesso_rapido` do seeder (`true`) e a validação (`cidadao|empresa|servidor`), ausência de qualquer gravação em `service_letter_access_logs` (tabela criada e nunca usada) e a rota de reordenação de etapas sem consumidor em JavaScript. --- ## Índice do dossiê | Arquivo | Conteúdo | |---|---| | `00-RESUMO.md` | Este documento | | `01-ARQUITETURA.md` | Camadas, classes, diagramas de fluxo e dependências | | `02-MODELAGEM.md` | Tabelas do módulo, colunas, FKs, relacionamentos | | `03-ROTAS-E-CONTROLADORES.md` | Rotas CMS/Portal, controllers, validações, permissões | | `04-VIEWS-E-UX.md` | Blades do CMS e do portal, JS/Ajax, exportações, assets | | `05-REGRAS-E-PORTABILIDADE.md` | Regras de negócio, acoplamentos e armadilhas | | `06-MIGRACAO-MODERNA.md` | Schema Laravel 11/12, models, Form Requests, Policies, API Resources | | `07-TESTES.md` | Estratégia, fixtures e casos de teste concretos | | `08-GAPS-E-DIVIDAS.md` | Bugs, funcionalidades mortas, riscos, mapa v5 → v6, prioridades | | `09-WORKFLOW-ETAPAS-E-CANAIS.md` | **Workflow de etapas ponta a ponta (foco do módulo)** | | `10-PDF-E-ANEXOS.md` | **Gerador de PDF, anexos, responsáveis e arquivos** | | `11-VIEWS-SQL-MIGRACOES-E-SEEDS.md` | Views SQL, inventário das 13 migrations e do seed | | `12-PLANO-DE-IMPLANTACAO.md` | Fases 2 e 3: views modernas, fila, cache, storage, riscos | ## 10. Como este dossiê está organizado A leitura mínima para entender o módulo é `00-RESUMO.md` → `01-ARQUITETURA.md` → `09-WORKFLOW-ETAPAS-E-CANAIS.md`. Quem vai **reconstruir** o módulo deve ler, nesta ordem: `02-MODELAGEM.md` e `11-VIEWS-SQL-MIGRACOES-E-SEEDS.md` (o que existe hoje), `05-REGRAS-E-PORTABILIDADE.md` (o que não pode ser quebrado), `08-GAPS-E-DIVIDAS.md` (o que precisa ser consertado) e, por fim, `06-MIGRACAO-MODERNA.md` + `12-PLANO-DE-IMPLANTACAO.md` (o plano). `03-ROTAS-E-CONTROLADORES.md` e `04-VIEWS-E-UX.md` servem de referência de contrato para quem for reescrever as rotas e as telas; `07-TESTES.md` é o contrato de qualidade. Os documentos distinguem explicitamente o que foi **verificado no código/banco** do que é **[INFERÊNCIA]** ou **[NÃO VERIFICADO]** — em especial nos pontos de segurança (sanitização do HTML do editor, symlink `public/storage`, permissões em runtime) que exigem teste em ambiente real.