# Contrato de produção dos dossiês > **Instanciação para o Portal Municipal.** O contrato **canônico** — que > vale para qualquer projeto — está em > [`../_protocolo/03-CONTRATO.md`](../_protocolo/03-CONTRATO.md). > Este arquivo é a versão com os fatos deste projeto preenchidos: stack, > rotas, middleware, registro de módulos e o precedente de qualidade. > > Ao mapear um projeto novo: copie a pasta `_template/`, atualize a seção 7 > (Contexto da plataforma) e aponte a referência acima para o protocolo. Este arquivo define as regras **obrigatórias** para todos os dossiês em `dossie_modules/`. Cada agente deve lê-lo antes de escrever. --- ## 1. Objetivo do dossiê O dossiê serve como **especificação de referência** para reconstruir o portal municipal em **PHP 8.x + Laravel 11/12** (a "v7"). O leitor é um engenheiro que **não conhece o legado**. Portanto: - Explique **o quê** o módulo faz e **por quê** existe, não apenas como o código está escrito. - Documente o **comportamento observável** (o que o usuário vê/faz), não a implementação linha a linha. - Sempre que houver um *problema* conhecido (bug, gambiarra, acoplamento, risco), **sinalize**. > **Não implemente nada.** Este é um trabalho de investigação e documentação. > Não crie, altere ou apague código de `v5/` ou `v6/`. Não rode migrations. > Não modifique `dossie_modules/` fora da pasta do módulo que lhe coube. ## 2. Estrutura de pastas Um diretório por módulo, nomeado com o **slug do módulo** (kebab-case, ASCII): ``` dossie_modules/ ├── README.md # índice geral (feito por um agente dedicado) ├── _00_panorama/ # visão geral da plataforma (agente dedicado) ├── _template/ # este contrato + templates └── / ├── 00-RESUMO.md ├── 01-ARQUITETURA.md ├── 02-MODELAGEM.md ├── 03-ROTAS-E-CONTROLADORES.md ├── 04-VIEWS-E-UX.md ├── 05-REGRAS-E-PORTABILIDADE.md ├── 06-MIGRACAO-MODERNA.md ├── 07-TESTES.md └── 08-GAPS-E-DIVIDAS.md ``` Se o módulo **não existir** em uma das versões, o dossiê **deve** conter a seção de comparação v5 → v6 explicitamente (ver seção 4). ## 3. Formato dos arquivos - Markdown puro (`.md`), **UTF-8**, sem HTML inline desnecessário. - Escreva **em português do Brasil**. - Use tabelas Markdown para dados tabulares (colunas de banco, rotas, campos). - Use blocos de código com linguagem específica (`php`, `sql`, `bash`, `js`, `blade`). Para Blade, use `blade` como linguagem. - **Cite caminhos de arquivo reais** com o prefixo da versão: `v6/app/Http/Controllers/Prefecture/NewsLetterController.php`, `v5/database/migrations/...`. - **Cite linhas** quando a especificidade importa: `v6/routes/basepro.php:412-418`. - Blocos de código devem ser **reais** (copiados do repositório), não inventados. Se escrever um exemplo novo, marque-o como `// exemplo ilustrativo` ou ```php (ilustrativo)```. - Nunca invente nomes de arquivo, rota, coluna ou tabela. Se não tem certeza, **verifique** com `grep`/`glob` antes de escrever. ## 4. Cobertura obrigatória por dossiê Cada arquivo do dossiê **precisa** cobrir os pontos abaixo: ### `00-RESUMO.md` Objetivo, efeito, comportamento, interação do usuário, particulars técnicas, estrutura de dados (resumo), como testar (resumo), migração (resumo), resumo geral. Ver `_template/00-RESUMO.md`. ### `01-ARQUITETURA.md` - Fluxo da requisição: rota → middleware → controller → request/validator → repository/service → model → view/response. - Lista de classes envolvidas com caminho completo e papel de cada uma. - Diagrama ASCII ou Mermaid do fluxo. - Dependências externas (pacotes composer) usadas pelo módulo. ### `02-MODELAGEM.md` - Tabelas do módulo: nome, colunas, tipos, nullability, defaults, keys. - Relacionamentos (FK, pivot, belongsTo/hasMany/manyToMany). - **Views SQL** (o legado usa muito `CREATE VIEW`): lista e o que elas abrem. - Migrations que criam/alteram essas tabelas (com caminho e data). - Seeds que populam dados iniciais. ### `03-ROTAS-E-CONTROLADORES.md` - Tabela de rotas: método, URI, nome (`->name()`), controller@action, middleware. - Separação CMS (`/cms/...`) vs Portal (público) vs API. - Form Requests / validators: quais regras validam o quê. - API Resources / presenters: formato de saída. - Permissões exigidas (papel/guard). ### `04-VIEWS-E-UX.md` - Arquivos Blade principais e sua função. - Layouts do portal usados (modelo1..modelo5, default). - JS/Ajax: endpoints chamados, eventos, polling. - Exportações (Excel/PDF/CSV): como são geradas. - O que o usuário final vê (portal) e o que o operador vê (CMS). ### `05-REGRAS-E-PORTABILIDADE.md` - Regras de negócio não óbvias. - Acoplamentos: outros módulos dos quais este depende (e vice-versa). - **Armadilhas**: SQL hardcoded, `->whereRaw`, `DB::raw`, N+1, loops com query dentro, `Route::` dentro de controller, uso de `$_SESSION`, etc. - Código duplicado ou copiado entre v5/v6. - Onde a v6 divergiu da v5 (e por quê, se discoverível). ### `06-MIGRACAO-MODERNA.md` Plano concreto de reconstrução: - Schema de migração Laravel (equivalente). - Modelos: atributos, casts, enums sugeridos, relations. - Form Requests com regras. - Policies / autorização. - Endpoints REST/JSON sugeridos (se aplicável). - Recursos de API. - Views Blade modernas / componentes. - Fila, cache, storage. - **Riscos e decisões de equivalência funcional** (o que NÃO pode mudar). ### `07-TESTES.md` - Estratégia (feature/unit). - Casos concretos de teste, comArrange/Act/Assert resumidos em tabela. - Fixtures/factories necessárias. - Fixtures de view/seed para ambiente de teste. - Como rodar (comando exato). ### `08-GAPS-E-DIVIDAS.md` - Bugs/erros conhecidos encontrados. - Funcionalidades incompletas ou mortas. - Itens que existem na v5 e foram removidos na v6 (ou o contrário). - Riscos de dados (migração de schema). - Perguntas em aberto para o negócio. - **Mapa v5 → v6** quando aplicável. ## 5. Regras de estilo - **Não invente.** Se algo não foi verificado, escreva `[NÃO VERIFICADO]` ou omita. Documente o que você não conseguiu acessar. - **Cite a fonte.** Toda afirmação sobre comportamento deve ser rastreável a um arquivo/linha do repositório. - **Densidade alta.** Prefira tabelas e listas a parágrafos vagos. - **Sem enrolação.** Escreva direto ao ponto; o leitor é técnico. - **Sem duplicação.** Se o mesmo conteúdo se aplica a vários módulos, escreva no dossiê do módulo "comportamento" e referencie `..//`. - Respeite o **limite de tamanho**: cada arquivo entre 100 e 400 linhas. Se passar de 400, divida o conteúdo em um arquivo adicional numerado (`09-...md`) e atualize o índice do `00-RESUMO.md`. ## 6. Verificação antes de entregar Antes de reportar conclusão, o agente deve: 1. `ls` a pasta do módulo e confirmar que **todos os 9 arquivos** existem. 2. `grep` nos documentos por marcadores de placeholder (`TODO`, `XXX`, `/*.md \ | sort -u | while read f; do [ -e "$f" ] || echo "MISSING: $f"; done ``` > **A ordem das extensões importa.** O `grep` disponível no shell do agente > faz *leftmost-first* (não *leftmost-longest*): com `js` antes de `json`, > um nome terminado em `.json` é truncado no `.js` e reporta um falso > positivo. Por isso `json` vem **antes** de `js`. Use `-oh` (sem `-c`, sem > prefixo de arquivo) para que o valor capturado seja exatamente o caminho. > Rode a partir da raiz do repositório (`/home/one/projects/maxima/v7`). 4. Conferir o total de linhas por arquivo e dividir se necessário. ## 7. Contexto da plataforma (comum a todos) - **Stack:** Laravel 5.5.50, PHP 7.2.34, PostgreSQL 10 + PostGIS, Redis, APCu. AdminLTE 1.22 (CMS), Bootstrap 4 (portal). Auth: `cartalyst/sentinel`. - **Rotas:** `v6/routes/web.php` (portal), `v6/routes/basepro.php` (CMS `/cms`), `v6/routes/api.php`, `v6/routes/prefecture.php`, `v6/routes/service_letter.php`, `v6/routes/breadcrumbs.php`. - **Namespaces:** `App\Http\Controllers\{Prefecture,Portal,Admin}`, `App\Http\Model\{Prefecture,Admin}`, `App\Repositories\Eloquent\...`, `App\Services\...`. Modelos usam `App\Prefecture\...` quando em `app/Http/Model/Prefecture/` (autoload por classmap). - **Middleware notáveis:** `check.logged` (CMS exige login), `check.site.manutention`, `check.route.permission`, `active.landing`. - **Views:** `v6/resources/views/prefecture/**` (CMS) e `v6/resources/views/portal/**` (público, com `modelo1`..`modelo5`). - **Módulos do sistema:** a tabela `modulos` (migration `v6/database/migrations/2024_11_01_150206_create_modulos_table.php`) lista os 56 módulos do CMS; `resources.modulo_id` e `menu_orders.modulo_id` referenciam essa tabela. - **Documentação legada existente:** `v6/wiki/modules/DiarioOficial/` é o precedente de qualidade. Consulte-o para o módulo Diário Oficial e use como referência de estilo.