--- id: MOD-- tipo: modulo onda: <0-5> status: pendente unidades: [MOD--] fontes: - V2/Modules/// depende_de: [] consumidores: [] criticidade: dono: --- # / > Guia: substituir todo texto entre `>` por conteúdo citado. Não manter marcadores. > As seções 0–4 são o núcleo do documento; as seguintes são o inventário de apoio. ## 0. Ficha de identidade | Campo | Valor | |---|---| | Efeito primário | | | Entrada | | | Saída | | | Efeitos colaterais | | | Particularidade central | | | Como se integra | | | Se removido, quebra | | | Superfície pública | | ## 1. Efeito ### 1.1 O que o usuário consegue fazer (CMS / portal / API) > Ações concretas e resultado visível. Ex.: "operador regional cria notícia; ela nasce > `pending_approval` e não aparece no portal até aprovação". ### 1.2 O que muda no sistema > Tabelas/colunas escritas, arquivos, e-mails, índice de busca, feed, cache, logs e > auditoria. Uma linha por efeito, com o ponto do código que o produz. | Efeito | Onde é produzido | Fonte | |---|---|---| ### 1.3 Contrato observável (entrada → saída) > Para cada rota/comando: entrada válida → resultado; entradas inválidas → erro exato. ### 1.4 O que este módulo NÃO faz > Limites explícitos que evitam reimplementação errada (ex.: "não publica direto", > "não envia e-mail", "não apaga fisicamente"). ## 2. Abordagem ### 2.1 Estratégia em uma página > Como o problema foi resolvido, em prosa + diagrama. ```mermaid flowchart LR A[entrada] --> B[validação] --> C[domínio] --> D[(persistência)] --> E[efeitos] ``` ### 2.2 Mecânica passo a passo > Passo a passo com classes e métodos reais, do request ao efeito final. Numerar. ### 2.3 Decisões de design e por quê > Decisões observáveis (ex.: categoria regional derivada no servidor; token por > unidade; widget registry). Marcar `[C]`/`[I]`. ### 2.4 Trechos de código pivô > 3–8 trechos, 5–20 linhas, com citação e explicação. Escolher núcleo, contrato, > invariante, UI/JS e armadilha. ```php // V2/Modules/.../Arquivo.php:123-138 — o que este trecho mostra ``` > Explicação do trecho e do efeito dele. ### 2.5 Algoritmos, consultas e custos > Eloquent/SQL relevante, escopos, ordenação, paginação, N+1, índices usados. ## 3. Particularidades ### 3.1 O que só existe aqui > Conceitos de propriedade exclusiva deste módulo (ex.: fonte única de categoria > regional). Se outro ponto duplica, apontar e comparar. ### 3.2 Invariantes e regras não óbvias > `RN--NN` com condição, efeito, erro e fonte. | ID | Regra | Efeito | Fonte | |---|---|---|---| ### 3.3 Casos-limite e comportamentos surpreendentes > O que acontece com dado ausente, duplicado, concorrente, desativado, sem permissão. ### 3.4 Armadilhas de reimplementação > O que parece igual a outro módulo mas não é; ordem obrigatória; dependências ocultas. ### 3.5 Divergências documentação × código e dívidas > README/MODULE.md vs código, código morto, acoplamentos indevidos, `app()` inline. ## 4. Integrabilidade ### 4.1 Superfície pública > O que pode ser usado de fora, com assinatura e precondição. | Símbolo | Tipo | Assinatura | Precondição | Consumidores | |---|---|---|---|---| ### 4.2 Contrato de UI/JS (quando aplicável) > Componentes Blade (namespace, props, slots), eventos JS, IDs de DOM, endpoints > AJAX, inicialização e teardown. ### 4.3 Ordem e ciclo de vida > Boot, registro de rotas/views, hooks de model, eventos, cache, dependências de > inicialização. ### 4.4 Receitas de uso > 2–5 exemplos canônicos em código (PHP/Blade/HTTP/artisan) com resultado esperado. ### 4.5 Anti-uso > 1–3 formas erradas e o que quebra (acoplamento, escopo, duplicação de regra). ### 4.6 Custos e limites da integração > Performance, quotas, throttling, tamanho de payload, cache, consistência eventual. ## 5. Rotas e contratos HTTP | Tipo | Método | URI | Nome | Middleware | Controller@ação | Permissão | Efeito | Fonte | |---|---|---|---|---|---|---|---|---| > Para API: payload (campos, tipos, obrigatoriedade, validações, limites), resposta, > erros e corpos, autenticação, throttling, escopo. Para CMS: redirect/flash. Para > portal: query, paginação, filtros, cache, SEO. ## 6. Dados e modelo de domínio > Uma subseção por tabela: PK, colunas (tipo/null/default/cast), FKs, índices, > unique, soft delete, UUID, timestamps, quem escreve. > Models: `$table`, `$fillable`, `$casts`, accessors, scopes, relações, eventos, > hooks. Diagrama `erDiagram`. Invariantes e dados derivados. ## 7. Fluxos e estados > `stateDiagram-v2` + `FL--NN` (sequenceDiagram) para criar, editar, > publicar, arquivar, restaurar, importar, autenticar. Efeitos colaterais por fluxo. ## 8. UI CMS > Por tela: rota, permissão, layout, objetivo, estados (vazio/erro/carregando), > árvore da tela, campos (nome, tipo, obrigatório, default, validação client/server, > ajuda, visibilidade condicional), colunas da listagem, filtros, ordenação, > paginação, bulk actions, modais, mensagens exatas, atalhos, JS (arquivo, função, > evento, AJAX, endpoint, CSRF), acessibilidade. ## 9. UI Portal > Dados exibidos, consultas/escopos, estrutura de seções, SEO (title/description/OG/ > Twitter/JSON-LD/canonical/robots e origem dos valores), mídia e variantes, `alt`, > lazy loading, responsividade, print, cache (TTL, chave, invalidação), a11y. ## 10. Configuração, permissões e flags > `config/v2.php` e demais chaves (nome, default, efeito), permissões e middleware, > `ModuleProvider::getConfig()` completo, flag de módulo e comportamento desativado. ## 11. Observabilidade, erros e limites > Logs (canal, nível, mensagem), auditoria, códigos HTTP e payloads, fail-open/closed, > limites (upload, throttle, paginação, timeout). ## 12. Seeds e dados iniciais > Seeder, ordem, idempotência, registros, dependências, dados semeados por migration. ## 13. Lacunas > `LG--NN`: o que não foi possível determinar, onde procurar, impacto. ## 14. Checklist de paridade > Itens `PC--NN`: ação → resultado observável → fonte. - [ ] `PC-...-01` — ... - [ ] `PC-...-02` — ... ## 15. Evidências consultadas > Arquivos lidos com faixas de linhas relevantes.