# Contrato de implementação — `v7_implementation`

Normativo. Vale para todos os documentos desta árvore. Em conflito com um documento de
unidade, este contrato vence.

## 1. Objetivo

Transformar o corpus `sucesu_analise/` em **planos de implementação executáveis** para a
pilha do `public-v7` (ADR-001/004), sem perder o contrato observável do V2.

Cada pasta representa **uma unidade implementável**: um `service`, um `module` ou uma
`feature` de fundação/UI/dados. O documento `README.md` da pasta é o artefato; não há
código solto nesta árvore.

## 2. Hierarquia

| Pasta | O que contém | Exemplos |
|---|---|---|
| `core/` | fundação compartilhada (equivalente a `src/core`) | boot, rotas, auth, dados, runtime |
| `services/` | serviços headless/UI (equivalente a `src/services`) | mídia, editor rico, SEO, busca |
| `modules/` | casos de uso (equivalente a `src/modules/{Grupo}/{Modulo}`) | notícias, associados, homepage |
| `ui/` | shell e design system (equivalente a `src/layout`) | CMS, portal, acessibilidade |
| `data/` | dados iniciais e referência | seeds de páginas, SLE, demo |
| `nao-implementados/` | grupos vazios do legado | API, AtosOficiais, Relacionamentos |

`_template/` e `_contract/` não são unidades.

## 3. Fonte da verdade

1. **Comportamento:** `sucesu_analise/05_modulos/...`, `02_servicos-base/...`,
   `03_servicos-ui/...`, `01_arquitetura/...`, `08_matriz/...`, `_indices/*.csv`.
2. **Destino:** `sucesu_analise/09_reimplementacao/pilha-alvo-public-v7.md` e as ADR do
   `public-v7` (001, 004, 007, 009, 012, 013, 014, 017, 020, 022, 024, 026, 027, 028,
   033, 034, 035, 038, 040, 041).
3. **Código legado:** o V2 é **read-only** e só deve ser aberto para dirimir dúvida que o
   corpus não resolve. Não copie APIs de framework do legado.

## 4. Fronteira “preservar × trocar”

| Preservar | Trocar |
|---|---|
| URL, método, status, headers, mensagens literais de negócio | classe, namespace, nome de rota nomeada, biblioteca |
| Payload JSON, AST, formatos de e-mail/RSS, caminho de storage | classes CSS, jQuery, Bootstrap, AdminLTE |
| Semântica de tabelas/colunas, chaves, índices, soft delete | nome físico (`v2_*` → token), UUIDv4 → UUIDv7 |
| Regras, precedências, ordenações, limites | nonce por request, `HtmlMinify`, `eval`, HTML livre |
| Acessibilidade: atalhos, skip links, preferências, VLibras | meta: eMAG 3.1 + WCAG 2.2 AA (não “AAA” declarado) |

Se a unidade exigir uma exceção, ela deve ser explícita no doc: **o quê**, **por quê**,
**evidência** e **teste**.

## 5. Convenções de código

- `declare(strict_types=1)` em todo PHP.
- Sem traits, classes abstratas, genéricos ou `Result<T>`; exceção: traits exigidos pelo
  framework (`SoftDeletes`) e classes base exigidas pelo Laravel.
- DI por construtor/parâmetro; proibido `new`/`resolve()` no corpo de regra.
- Clock, aleatoriedade e IDs injetados (`Clock`, `Random\Randomizer`, `IdGen`/UUIDv7).
- Sem `now()`, `rand()`, `md5()` em regra de negócio; logs estruturados sem PII.
- Native first: FormRequest, Validation, Casts, Events, Jobs, Policies/Gate, Resources,
  Blade Components, Flysystem, Cache, Scheduler.
- Um módulo **não** importa outro módulo; use porta/evento do Core (ADR-013).
- Nomes: identidade Pascal; token de busca sem separador; kebab para URL/rota/slot; snake
  para tabela/coluna/permissão. Prefixo `v2_` é proibido no alvo.
- Views: `cms::` e `portal::` para shells; `<token>::` para views de módulo/serviço
  (`noticias::cms.index`).
- Rotas nomeadas: `cms.<token>.*`, `portal.<token>.*`, `api.<token>.*`.
- Tabelas: nome canônico em snake, plural quando coleção (`noticias`, `eventos`).

## 6. Estrutura obrigatória do documento

Todo `README.md` de unidade contém, nesta ordem:

1. Front-matter (ver §7).
2. **Contrato** — o que entrega, entradas/saídas, invariantes, não-objetivos.
3. **Estrutura alvo** — árvore de arquivos com caminhos reais.
4. **Implementação** — 4 a 8 trechos de código PHP 8.4/Laravel 12, Blade, SQL ou JS,
   com o “porquê” antes de cada trecho.
5. **Dados e migração** — schema, índices, constraints, idempotência, mapa do legado.
6. **Fluxos e estados** — passo a passo e, quando houver, máquina de estados.
7. **Segurança e limites** — authz, validação, CSP, rate limit, upload, PII.
8. **Testes** — tabela de casos (unit/feature/e2e) e pelo menos um exemplo de teste.
9. **Validação** — comandos reproduzíveis (teste, análise estática, curl, axe).
10. **Aceite** — checklist verificável.
11. **Riscos e armadilhas** — herdados do corpus + decisões.
12. **Evidências** — links para docs do corpus e ADR aplicáveis.

Mínimo: 180 linhas; máximo sugerido: 350. Sem `TODO`, `PREENCHER`, “implementar depois”
ou pseudocódigo no lugar de código.

## 7. Front-matter

```yaml
---
id: IMPL-<TOKEN>
tipo: core | service | module | ui | feature | data
status: pronto
token: <token-kebab>
camada: core | services | layout | modules | data
unidade_fonte: [<IDs do corpus>]
adrs: [ADR-001, ADR-004, ...]
depende_de: [<pastas/ids>]
---
```

`status: pronto` significa “documento completo para implementação”, não “código escrito”.

## 8. Testes e validação (filosofia v7)

- **PHPUnit 13** (feature/unit) + **Playwright** (e2e) + **axe** (a11y).
- Cobertura de linhas **≥ 90%**; mutation testing nos caminhos críticos.
- PHPStan `level: max`, baseline zero; Pint/Prettier/ESLint.
- Determinismo: `freezeTime`, IDs fixos por `IdGen` fake, ordenação explícita.
- Todo caso de teste tem nome, pré-condição, ação e resultado observável.
- Comandos canônicos: `php artisan test --filter=...`, `./vendor/bin/phpstan analyse`,
  `npx playwright test`, `make check`.

## 9. Regra de ouro

Se um implementador não consegue, lendo só o doc da unidade, saber **o que criar**, **onde**,
**como testar** e **o que não fazer**, o documento falhou.