# TECNICO — contrato de implementação das fases F7+ > **O que é:** o detalhamento técnico que toda fatia de `wiki/implementation-phases/` deve seguir. > Não é uma decisão nova: `AGENTS.md`, os ADRs e as specs vencem. Se este guia conflitar com eles, > **pare**, registre no `kd` e corrija o guia — nunca “resolva” o conflito no código. > > **Quando ler:** antes de abrir qualquer `P*.md`; junto com o arquivo da fase, o ADR citado e o > código real da área. É leitura obrigatória das fatias P0–P29. ## 1. Ordem de leitura e fontes 1. `AGENTS.md` — constituição, stack, boundaries, gates. 2. ADR da fase (e as ADRs transversais: 001, 007, 012, 013, 015, 016, 017, 024, 033, 034, 035, 038, 040, 041, 042). 3. Este guia — como transformar a decisão em código sem furar o padrão. 4. O `P*.md` da fase — escopo e fatias. 5. Código real da área (o que já existe vence suposição). 6. Skills: `.agents/skills/php-84-correct`, `laravel-12`, `html-moderno`, `css-moderno`, `javascript-moderno`, `web-accessibility`, `postgresql`, `vite`, `playwright-ts-admin`, `sniff-css` — consultar o recorte necessário, não copiar receita de outro projeto. **Regra de ouro:** uma fatia só começa quando o contrato está escrito (rota, tabela, porta, DTO, permissão, evento, i18n, teste) e o caminho de rollback é conhecido. “Estrutura para depois” não é entrega. ## 2. PHP 8.4 — o que usar e o que o projeto proíbe O projeto é **mais restritivo** que a linguagem e que a skill `php-84-correct`: | Regra do projeto | Consequência prática | |---|---| | `declare(strict_types=1)` em todo arquivo PHP | sem exceção; `php -l` deve passar | | **Sem traits, sem abstract, sem generics, sem `Result`** | composição por DI e funções concretas; duplicação explícita é aceitável | | **Sem `new`/`resolve()`/`app()` em corpo de domínio** | dependências no construtor; `app()` só em composition root/provider/teste | | `final` por padrão | classes de domínio, Actions, DTOs e controllers `final`; `readonly` quando o estado é imutável | | Uma Action por arquivo | foco, nome de verbo, `execute(...)`, testável isoladamente | | Sem HTML/CSS/Blade no banco | conteúdo é AST/JSON validado; renderer em código | ### 2.1 Tipos e construções - **Enums** para conjuntos fechados (`Status`, `Area`, `Permission`, `Locale`); persistência com `string` + cast, nunca “enum mágico” sem validação. - **DTOs** `final readonly` para entrada/saída; não passar `array` solto entre camadas quando o shape importa. `fromArray()` valida/normaliza na borda. - **`match`** para branching fechado; se o `match` não for exaustivo, trate o default com erro de domínio — não deixe cair em `null` silencioso. - **`never`** para funções que sempre lançam; **`#[\Override]`** em implementações de contrato. - **Property hooks/asymmetric visibility** só quando o modelo ficar mais simples. Não usar em modelos Eloquent para “esconder” atributos: use `$hidden`, casts e DTOs. Não substituir um cast nativo por hook sem teste. - **`json_decode(..., true, flags: JSON_THROW_ON_ERROR)`** e `json_encode(..., JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE)`. `json_validate()` quando só se quer checar o JSON. - **`array_find`/`array_any`/`array_all`** quando expressarem melhor a intenção; não reescrever laços simples só para “usar 8.4”. - **Nunca** `eval`, `unserialize()` de entrada não confiável, `create_function`, `each()`, `FILTER_SANITIZE_STRING`, `rand()`/`mt_rand()` para token/segredo. - Aleatoriedade/relógio de domínio: **injetar `Core\Contracts\Clock` e `Core\Contracts\IdGen`**. `random_int()`/`Randomizer` são para infraestrutura/segurança, não para IDs de domínio. - Dinheiro: `numeric` no PostgreSQL + string/decimal no PHP; nunca `float` para valor fiscal. - Datas: `timestamptz` + `CarbonImmutable`/`DateTimeImmutable`; exibição via `intl` (`Core\Localization\LocalizedDate`), nunca `date()` com timezone implícito. ### 2.2 Erros e exceções - Exceção de domínio concreta (`InvalidTransition`, `ModuleEssential`, `SettingsValueInvalid`), não `RuntimeException` genérica para tudo. - `catch` específico; se capturar `Throwable`, **rethrow** ou converta com contexto. Nunca “logar e seguir” em fluxo que precisa falhar. - Não usar exceção para fluxo normal; validação de formulário é `FormRequest`/422. - Não vazar mensagem técnica/stack trace para o usuário; RFC 7807 na API e mensagem i18n na UI. - Não usar `@` para silenciar; corrigir a causa. `error_reporting(E_ALL)` em dev; produção sem `display_errors`. ### 2.3 Segurança de linguagem - Saída HTML: `{{ }}`/`e()`; `{!! !!}` só para HTML produzido por renderer confiável (`ContentASTParser`), nunca para conteúdo bruto do CMS. - SQL: Query Builder/Eloquent com bindings; `whereRaw('x = ?', [$v])`; nunca interpolar. - Senhas: `Hash::make`/`Hash::check` (Argon2id configurado); nunca md5/sha1. - Comparação de token: `hash_equals`. - Upload: MIME pelo **conteúdo** (`finfo`), não pelo nome/extensão do cliente; limite de bytes; allowlist; armazenar no disco `s3`; nunca executar. - Segredos: `encrypted` cast/`Crypt`; nunca em log, auditoria, URL ou mensagem de erro. ## 3. Laravel 12 — bordas de versão e uso correto Laravel 12 é “manutenção” sobre 11; o que importa é **não escrever Laravel 10**: | Não existe/está errado em 12 | Faça | |---|---| | `app/Http/Kernel.php`, `app/Console/Kernel.php`, `app/Exceptions/Handler.php` | `bootstrap/app.php` (`withMiddleware`, `withExceptions`, `withSchedule`) | | Providers em `config/app.php` | `bootstrap/providers.php` | | `$this->middleware()` no controller | `HasMiddleware::middleware()` ou middleware na rota | | Base `Controller` com `AuthorizesRequests`/`ValidatesRequests` | `Gate`/`can()` explícito ou traits conscientes | | `env()` fora de `config/` | `config('x.y')`; `env()` só no arquivo de config | | Route closure | controller invokable; `route:cache` não serializa closure | | `$request->all()` em create/update | `$request->validated()`/`safe()` | | `Model::all()` e filtro em PHP | query com `where`, `paginate`, `cursor` | | `latest()` sem tie-breaker | `orderByDesc('published_at')->orderByDesc('id')` ou keyset | ### 3.1 Rotas, controllers e requests - Rotas em `Routes/{area}.php` do módulo, carregadas por convenção; **sem closure**; nomes `{module}.{area}.{action}`; métodos HTTP corretos; mutação só `POST/PUT/PATCH/DELETE`. - Binding implícito com UUID: `whereUuid('user')` quando necessário; escopo aninhado (`scopeBindings`) para não aceitar id de outro pai. - Controller: `final`, invokable quando possível; ordem: autorização → FormRequest → Action → redirect/view. Sem consulta Eloquent, sem regra de negócio. - `FormRequest::authorize()` não é o lugar de recriar a matriz de permissão; a autorização do módulo é `Permission::authorize()`/`Gate` no controller/Action (padrão existente). O request valida **forma**; `prepareForValidation()` normaliza JSON/arrays. - `validated()` devolve só o que tem regra. Cuidado com regras curinga em AST/JSON: elas podem descartar chaves aninhadas (o código de Notícias já documenta isso). Valide o array externo e valide o shape no DTO/parser. - `Rule::unique('schema.table')` interpreta o ponto como conexão. Em tabela com schema, use `DB::table('schema.table')` + closure ou `Rule::unique` com conexão explícita; teste. - Toda mutação: CSRF (`@csrf`), `@method`, confirmação nativa, mensagem de sucesso/erro i18n. - Ações de linha: `POST` + CSRF; nunca `GET` que muta; nunca confiar em botão desabilitado. ### 3.2 Eloquent e banco - `protected $fillable` explícito; `casts()` tipado; `$hidden` para segredo; sem `$guarded = []`. - `Model::shouldBeStrict(! app()->isProduction())` e `preventLazyLoading` no provider de dev/teste. - Eager loading: `with()`, `withCount()`, `withSum()`; `whereIn` para mídia; uma query por widget; `cursor()`/`lazyById()` para volume; nunca `count()` dentro de loop. - `DB::transaction(fn () => ..., attempts: 3)`; efeitos externos (e-mail, fila, S3) **após commit** (`afterCommit`/`DB::afterCommit`); não chamar HTTP dentro da transação. - Concorrência: `lockForUpdate()` **dentro** da transação; unique constraint como verdade final; capturar `QueryException` de violação e devolver 422/409; `lock_version` para edição otimista. - `firstOrCreate`/`updateOrCreate` podem correr; garanta unique e trate a violação. `upsert` para lote idempotente. - Não usar `Model::find()` para autorização; use policy/permissão e escopo. - `down()` nunca dropa dado: renomeie/mova para `backup__` (ADR-017); migração idempotente (`Schema::hasTable`, `CREATE INDEX IF NOT EXISTS`, `ON CONFLICT`). ### 3.3 Cache, filas e storage - Cache de configuração/consulta: chave versionada (`settings.{section}`, `navigation.{menu}.{locale}`), invalidação **síncrona** na escrita; teste de dois requests. Não cachear dado privado sem escopo de usuário/permissão. - `Cache::rememberForever` só para dado imutável/explícito; para conteúdo, TTL + invalidação. - Jobs: `ShouldQueue`, `$tries`, `backoff()`, `WithoutOverlapping`/`ShouldBeUnique` quando o efeito não pode duplicar; `afterCommit()`; payload com IDs, não models serializados; handler idempotente. - `Storage` de domínio é o disco `s3` (RustFS/AWS); URL pública via rota/controller ou `temporaryUrl`; não expor path local. - `Http` client: timeout, retry com backoff, `throw()`, allowlist de host, sem seguir redirect para host arbitrário; nunca segredo em query string. ## 4. Arquitetura e injeção ### 4.1 Boundaries (violação = build vermelho) - `core` **nunca** importa `modules`/`services`; `services` **nunca** importa `modules`; `layout` consome `core`/`services`; `modules/*` **nunca** importa `modules/*`. - Comunicação cross-module: **eventos/listeners nativos** + **portas do Core** (interfaces). Widget/banner: registry no Core, referência por `id`, embed permitido, import proibido. - Serviço: contrato em `src/services/{Name}/Contracts`; módulo depende da interface, nunca da implementação; service headless; UI só superfície admin (`/cms`). - Ordem de providers importa: `ModuleDiscoveryServiceProvider` antes de `ServiceDiscoveryServiceProvider`; registry que módulos usam no `register()` deve viver no **Core** (lição do P5.5), não dentro de um service descoberto depois. ### 4.2 Anatomia de uma fatia ``` src/modules/{Grupo}/{Modulo}/ ModuleProvider.php # register() + config(); permissões, rota, ícone, posição Routes/{portal,cms,api}.php # sem closure; nomes canônicos Logic/Actions/ # uma Action por arquivo; execute(); DI; span/log Logic/Controllers/ # final, fino, autorização + request + action Logic/Requests/ # forma + normalização Logic/DTOs/ # readonly, fromArray() Database/Models/ # fillable, casts, relationships, scopes Database/Migrations/ # idempotente, down() seguro Layout/Views/ # um shell; só
Lang/{locale}/ # 4 locales, namespace do token Test/ # contrato, feature, autorização, i18n ``` - Action: `final readonly`, dependências no construtor, `execute()`; telemetria em volta da operação de domínio; `log_event('{module}.{action}', [...])` com escalares, sem PII. - Controller: `Permission::authorize('{Module}', Permission::EDIT)` **antes** de mutar; use `Permission::allows` para render; 403 nunca 500. - Não criar “service”/“repository” sem segundo consumidor real; não criar abstração para variar driver (PG é o único alvo). - Não criar trait/abstract para “reuso”; duplicação explícita é preferível a hierarquia. ### 4.3 Shells e conteúdo - Toda view de módulo usa **exatamente um** shell (`` ou ``), informa os campos padrão (`title`, `description`, `breadcrumbs`, `canonical`, `robots`, `image`, `schemas`) e preenche **somente** o `
`. - O shell é dono de ``, ``, header/footer/sidebar, a11y bar e `

` do CMS; a view não declara `