# Contrato de Produção dos Dossiês (genérico)

> Este é o contrato **canônico**. A instância para o Portal Municipal está
> em [`../_template/_CONTRATO.md`](../_template/_CONTRATO.md), com os
> caminhos, rotas e middleware daquele projeto preenchidos.
>
> Ao mapear um projeto novo: copie o `_template/`, preencha o bloco
> "Contexto da plataforma" com os fatos do projeto, e use este documento
> como referência de cobertura.

---

## 1. Objetivo do dossiê

O dossiê é uma **especificação de referência** para reconstruir o sistema em
uma base moderna. O leitor é um engenheiro que **não conhece o legado**.

Consequências práticas:

- Explique **o quê** o módulo resolve e **para quem**, não apenas como o
  código está escrito.
- Documente **comportamento observável** (o que o usuário vê e faz), não
  implementação linha a linha.
- **Sinalize** todo problema conhecido: bug, gambiarra, acoplamento, risco.

> **Não implemente nada.** É trabalho de investigação e documentação.
> Não altere o código do projeto analisado. Não rode migrations.
> Não modifique dossiês 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, igual ao identificador no sistema):

```
dossie_modules/
├── README.md                 # índice geral (gerado, nunca escrito à mão)
├── _protocolo/               # este método
├── _tools/                   # ferramentas do protocolo
├── _template/                # contrato + templates
├── _00_panorama/             # visão geral da plataforma
└── <slug-do-modulo>/
    ├── 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
```

Módulos densos recebem arquivos extras numerados (`09-`, `10-`, …), sempre
listados no índice do `00-RESUMO.md` da pasta.

---

## 3. Cobertura obrigatória

### `00-RESUMO.md` — a peça que se lê sozinha
Objetivo · Efeito/impacto · Comportamento · Como o usuário interage ·
Detalhes e particularidades técnicas · Estrutura de dados · Como testar ·
Migração para base moderna · Resumo geral.

> **Teste do arquivo:** alguém que leia **só** este arquivo deve sair
> sabendo o essencial do módulo. Se faltar contexto, ele não está aqui.

### `01-ARQUITETURA.md`
- Fluxo da requisição: rota → middleware → controller → request/validator →
  repository/service → model → view/response.
- Classes envolvidas, com caminho completo e o papel de cada uma.
- Diagrama do fluxo (ASCII ou Mermaid).
- Dependências externas usadas pelo módulo.

### `02-MODELAGEM.md`
- Tabelas: nome, colunas, tipos, nullability, defaults, keys.
- Relacionamentos: FK, pivot, `belongsTo`/`hasMany`/`manyToMany`.
- **Views SQL** (o legado usa muito `CREATE VIEW`): lista e o que 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 por superfície: backoffice / portal público / API.
- Form Requests e validators: quais regras validam o quê.
- API Resources e presenters: formato de saída.
- Permissões exigidas (papel, guard, escopo).

### `04-VIEWS-E-UX.md`
- Blades principais e a função de cada um.
- Layouts usados e quando cada layout entra.
- JS/Ajax: endpoints chamados, eventos, polling, tratamento de erro.
- Exportações (Excel/PDF/CSV): como são geradas.
- O que o usuário final vê e o que o operador vê.

### `05-REGRAS-E-PORTABILIDADE.md`
- Regras de negócio não óbvias.
- Acoplamentos: de quais módulos este depende, e de quais ele é usado.
- **Armadilhas:** SQL hardcoded, `whereRaw`, `DB::raw`, N+1, query dentro de
  loop, rota declarada dentro de controller, `$_SESSION`, `eval`, `extract`.
- Código duplicado entre versões.
- Onde as versões divergiram — e por quê, se for descobrível.

### `06-MIGRACAO-MODERNA.md`
- Schema de migration equivalente.
- Modelos: atributos, casts, enums sugeridos, relações.
- Form Requests com as regras.
- Policies e autorização.
- Endpoints REST/JSON sugeridos, quando aplicável.
- API Resources.
- 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 ou unit, e por quê.
- Casos concretos, em tabela (Arrange / Act / Assert resumido).
- Factories e fixtures necessárias.
- Fixtures de seed para o ambiente de teste.
- Comando exato para rodar.

### `08-GAPS-E-DIVIDAS.md`
- Bugs e erros conhecidos.
- Funcionalidades incompletas ou mortas.
- Itens que existem numa versão e foram removidos na outra.
- Riscos de dados na migração de schema.
- Perguntas em aberto para o negócio.
- **Mapa entre versões**, quando aplicável.

---

## 4. Regras de estilo

- **Não invente.** Se não foi verificado, escreva `[NÃO VERIFICADO]` ou
  omita — e documente o que não conseguiu acessar.
- **Cite a fonte.** Toda afirmação sobre comportamento é rastreável a
  `arquivo:linha`.
- **Blocos de código são reais**, copiados do repositório. Exemplo novo
  recebe o marcador `// exemplo ilustrativo`.
- **Nunca invente** nome de arquivo, rota, coluna ou tabela. Se não tem
  certeza, verifique antes de escrever.
- **Densidade alta.** Tabela e lista valem mais que parágrafo vago.
- **Sem duplicação.** Se o conteúdo vale para vários módulos, escreva no
  dossiê de um e referencie `../<outro-modulo>/`.
- **Tamanho:** 100 a 400 linhas por arquivo. Acima de 400, divida em
  `NN-<assunto>.md` e atualize o índice do `00-RESUMO.md`.
- **Markdown puro**, UTF-8. Tabelas Markdown para dados tabulares. Blocos
  com linguagem específica (`php`, `sql`, `bash`, `js`, `blade`).

---

## 5. Verificação antes de entregar

```bash
# 1. os 9 arquivos existem
ls dossie_modules/<slug>/

# 2. nenhum marcador de texto por preencher
#    (a ferramenta auditar.py faz isso; o comando bruto equivalente usa
#     uma alternancia com as tres sigla de pendencia e o placeholder de nome)
grep -nE 'TODO|FIXME|XXX' dossie_modules/<slug>/*.md

# 3. todo caminho citado existe (a partir da raiz do repositório)
grep -ohE '(v5|v6)/[A-Za-z0-9_/.-]+\.(php|blade|sql|json|md|env|yml|js)' \
     dossie_modules/<slug>/*.md | sort -u | while read -r f; do
  [ -e "$f" ] || echo "MISSING: $f"
done
```

> **A ordem das extensões importa.** O `grep` do shell resolve
> *leftmost-first* (não *leftmost-longest*): com `js` antes de `json`, um
> arquivo terminado em `.json` é truncado no `.js` e reporta 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.
>
> O `auditar.py` do protocolo já faz essa checagem com expressão regular
> de alternativa ordenada, e trata notação de glob (`*`, `?`) como válida.

```bash
# 4. tamanho dentro da faixa
wc -l dossie_modules/<slug>/*.md
```

---

## 6. Checklist de aceite de uma fatia

O agente que produz um dossiê confirma, em uma frase por item:

- [ ] Os 9 arquivos canônicos existem, mais os extras que o `00-RESUMO.md` indexa.
- [ ] Cada arquivo tem 100–400 linhas.
- [ ] Todo caminho citado existe (verificação acima, saída vazia).
- [ ] Nenhum placeholder; nenhum trecho corrompido.
- [ ] O mapa entre versões está presente (quando o módulo existe em mais de uma).
- [ ] `00-RESUMO.md` é autossuficiente.
- [ ] `06-MIGRACAO-MODERNA.md` permite escrever a migration nova sem abrir o legado.
- [ ] Nenhum arquivo do projeto analisado foi alterado.

---

## 7. Contexto da plataforma (preencher por projeto)

Cada projeto tem seu próprio bloco. Registrar **fatos**, não memórias:

| Item | Portal Municipal (referência) |
|---|---|
| Stack | Laravel 5.5.50, PHP 7.2.34, PostgreSQL 10 + PostGIS, Redis, APCu |
| Front | AdminLTE 1.22 (CMS), Bootstrap 4 (portal) |
| Auth | `cartalyst/sentinel` |
| Rotas | `routes/web.php` (portal), `routes/basepro.php` (CMS `/cms`), `routes/api.php` |
| Namespaces | `App\Http\Controllers\{Prefecture,Portal,Admin}`, `App\Http\Model\{Prefecture,Admin}` |
| Middleware | `check.logged`, `check.site.manutention`, `check.route.permission`, `active.landing` |
| Views | `resources/views/prefecture/**` (CMS), `resources/views/portal/**` (público) |
| Registro de módulos | tabela `modulos` (migration `2024_11_01_150206_create_modulos_table.php`) |
| Documentação legada | `wiki/modules/DiarioOficial/` — precedente de qualidade |