# Taxonomia do corpus `sucesu_analise` Contrato normativo. Todo documento do corpus obedece a este arquivo. Em conflito entre este contrato e um documento de unidade, este contrato vence. ## 1. Finalidade Produzir especificação suficiente para **reimplementar o sistema V2 sem acesso ao código legado**: banco, rotas, autenticação, regras de negócio, telas CMS, páginas do portal, componentes de UI e dados iniciais. O corpus **não** é changelog, nem tutorial, nem documentação de usuário. É engenharia reversa verificável, orientada a **comportamento e reuso**, não a inventário de arquivos. ### 1.1 Legado × pilha-alvo Todo documento descreve o **legado** (Laravel 5.5/PHP 7.4/Bootstrap/Sentinel). A reconstrução usa a pilha decidida em `09_reimplementacao/pilha-alvo-public-v7.md` (PHP 8.4/Laravel 12, `src/core|services|layout|modules`, token canônico). Regra de leitura: - **Contrato externo** — URL, status, mensagem literal, payload, semântica de dados, caminho de storage e comportamento de negócio: preservar. - **Mecanismo interno** — biblioteca de auth/UI, nonce, minify, prefixo `v2_`, nome de tabela/rota nomeada/classe, pipeline de assets: seguir a pilha-alvo. Um documento que só faz sentido se o leitor copiar a implementação legada deve declarar isso; a decisão de destino nunca é inferida de um detalhe do legado. ## 2. As quatro dimensões (lei central) Todo documento de unidade (`modulo`, `servico`, `ui`, `arquitetura`) é organizado em torno de quatro perguntas. Elas vêm **antes** do inventário operacional e são o critério de qualidade do documento: | Dimensão | Pergunta obrigatória | Evidência exigida | |---|---|---| | **EFEITO** | O que muda no mundo quando isso executa? Para o usuário, para o banco, para arquivos, e-mails, índice de busca, cache, logs. O que **não** acontece. | entradas → saídas, tabelas/arquivos afetados, mensagens exatas, códigos HTTP | | **ABORDAGEM** | Como o problema foi resolvido? Qual o mecanismo, o fluxo de dados, o algoritmo, a decisão de design e o porquê. | diagrama + mecânica passo a passo + 3–8 trechos de código pivô | | **PARTICULARIDADE** | O que é único, não óbvio ou exclusivo deste ponto? Invariantes, casos-limite, armadilhas, divergências, dívidas, o que só ele faz. | `RN-*`, exemplos de código do trecho peculiar, comparação com pontos semelhantes | | **INTEGRABILIDADE** | Como se consome isso corretamente? Superfície pública, precondições, ordem de inicialização, contratos de UI/JS/HTTP, extensão, falhas, o que não fazer. | assinaturas, props/slots/eventos, receitas de uso, anti-uso | Regra de ouro: se um leitor não consegue responder "o que isso faz", "como faz", "o que tem de especial" e "como eu uso" lendo apenas o documento, o documento falhou. ### 2.1 Ficha de identidade (obrigatória, topo do documento) ```markdown | Campo | Valor | |---|---| | Efeito primário | uma frase observável | | Entrada | rotas, props, eventos, comandos | | Saída | telas, JSON, tabelas, arquivos, e-mails | | Efeitos colaterais | logs, auditoria, busca, cache, feed | | Particularidade central | o que só existe aqui | | Como se integra | namespace, classe, props, endpoint | | Se removido, quebra | consumidores diretos e indiretos | | Superfície pública | classes/métodos/componentes/rotas | ``` ### 2.2 Trechos de código - 3–8 trechos por documento, **5 a 20 linhas cada**, no máximo ~120 linhas de código. - Critério de escolha, nesta ordem: (1) algoritmo/núcleo não óbvio; (2) contrato público; (3) restrição/invariante; (4) contrato de UI/JS (DOM, eventos, props); (5) armadilha. - Todo trecho vem com `caminho:linha`, linguagem e uma linha "o que mostra". - Proibido colar arquivos inteiros, boilerplate de CRUD e código trivial. - Trechos são literais; se resumidos, marcar `// ...` e dizer o que foi omitido. ### 2.3 "Como funciona" e "como se usa" Cada unidade tem, obrigatoriamente: 1. **Mecânica passo a passo** (request/comando → validação → domínio → persistência → efeitos → resposta), com nomes reais. 2. **Receitas de uso** (2–5), em código, mostrando a forma canônica de consumir. 3. **Anti-uso** (1–3), mostrando o que quebra e por quê (acoplamento, ordem, escopo). ## 3. Unidades Uma **unidade** é o recorte atômico de levantamento. IDs vêm de `00_inventario/manifest.json` (fonte única; 56 unidades, 930 arquivos): | Prefixo | Conteúdo | Exemplos | |---|---|---| | `ARCH-` | visão geral | `ARCH-OVERVIEW` | | `CORE-` | infraestrutura V2 | `CORE-BOOT`, `CORE-AUTH`, `CORE-DATA`, `CORE-CMS`, `CORE-RUNTIME` | | `GRP-` | grupo de módulos (README + módulos vazios) | `GRP-API`, `GRP-SUPPORT` | | `MOD--` | módulo de negócio | `MOD-PUBLICACOES-NOTICIAS` | | `SVC-` | serviço compartilhado | `SVC-CONTENTRICHEDITOR` | | `UI-CMS` / `UI-PORTAL` | layouts globais | `UI-PORTAL` | | `DATA-SEEDS-` | seeders | `DATA-SEEDS-BASICPAGES` | Regras: - Um arquivo pertence a **exatamente uma** unidade (validado por `tools/coverage.py`). - Unidade grande pode ser dividida em **fatias** (`NOTICIAS-A`, `NOTICIAS-B`) com **um dono** da unidade, responsável por `spec.md` e pela consolidação. - Grupo sem implementação (`GRP-API`, `GRP-ATOSOFICIAIS`, `GRP-RELACIONAMENTOS`, `GRP-UTILITARIOS`) é documentado como **não implementado**; nunca inventar conteúdo. ## 4. Tipos de documento | Tipo | Pasta | Obrigatório para | |---|---|---| | `arquitetura` | `01_arquitetura/` | mecanismos globais (boot, rotas, auth, dados, cache, assets) | | `servico` | `02_servicos-base/`, `03_servicos-ui/` | unidade `SVC-*` | | `ui` | `04_ui/` | `UI-CMS`, `UI-PORTAL`, design system, acessibilidade | | `modulo` | `05_modulos///` | unidade `MOD-*` | | `dados` | `07_dados-iniciais/` | unidades `DATA-*` | | `matriz` | `08_matriz/` | visões transversais (permissões, entidades, integrações, singularidades) | | `reimplementacao` | `09_reimplementacao/` | plano de reconstrução e paridade | **Serviço de UI (macro-componente):** `SVC-*` que entrega Blade + JS + endpoints e é consumido por vários módulos pelo namespace `v2-service-::`. Conjunto especial: `CONTENTRICHEDITOR`, `LANDINGSECTIONSEDITOR`, `GALLERY`, `MEDIA`, `SEO`, `SEARCH`, `EXCELIMPORTER`. Esses exigem `spec.md` + `ui-contrato.md`. ## 5. Front-matter obrigatório ```yaml --- id: MOD-PUBLICACOES-NOTICIAS # unidade dona (ou ID do documento transversal) tipo: modulo # enum da seção 4 onda: 4 # 0..5 status: pendente # pendente | em_andamento | revisao | concluido unidades: [MOD-PUBLICACOES-NOTICIAS] # unidades cobertas (permite doc agrupado) fontes: # prefixos cobertos, relativos a sucesu-cms/ - V2/Modules/Publicacoes/Noticias/ depende_de: [SVC-CONTENTRICHEDITOR, SVC-GALLERY] consumidores: [MOD-LAYOUTS-HOMEPAGE] criticidade: alta # alta | media | baixa dono: agente-noticias-a # preenchido na execução --- ``` Invariantes: - `fontes` são prefixos; `coverage.py` exige que todo arquivo do manifest esteja sob o prefixo de algum documento e que nenhum arquivo fique fora. - `id` é único no corpus. - `status: concluido` só com lint limpo e checklist respondido. ## 6. Evidência Três níveis, sempre marcados: | Marca | Significado | Exigência | |---|---|---| | `[C]` | confirmado no código | citação `caminho:linha` | | `[I]` | inferido (comportamento não explícito) | citação do ponto de partida + justificativa curta | | `[L]` | lacuna | dizer o que falta e onde procurar | Regras: - Toda afirmação técnica (rota, coluna, validação, permissão, mensagem, efeito) leva citação `caminho:linha` — caminho relativo a `sucesu-cms/`, ex.: `V2/Modules/Publicacoes/Noticias/Models/News.php:88-104`. - README/MODULE.md existentes são **pistas**, não verdade. Divergência entre README e código é registrada em "Particularidades" com as duas fontes. Exemplo real: `V2/README.md` fala "UUIDv7", mas `V2/Core/Migrations/2026_06_01_000001_create_v2_uuid_function.php:17-37` gera UUID v4 aleatório. - Código extenso não é copiado; ver política de trechos (§2.2). - Nomes de classes, métodos, rotas, colunas e chaves de config são literais. - Mensagens de erro/validação são transcritas (texto exato), pois viram contrato. ## 7. Identificadores internos | Prefixo | Uso | Exemplo | |---|---|---| | `RN--NN` | regra de negócio | `RN-NOTICIAS-04` | | `FL--NN` | fluxo | `FL-UNIDADEREGIONAL-02` | | `CT--NN` | contrato de API/UI | `CT-NOTICIASIMPORT-01` | | `UI--NN` | tela/componente | `UI-NOTICIAS-07` | | `LG--NN` | lacuna | `LG-SOBRENOS-02` | | `PC--NN` | item de paridade | `PC-AGENDA-01` | Itens são referenciáveis e estáveis; não renumerar depois de publicado. ## 8. Índices (CSV, `_indices/`) Fonte de verdade transversal. Cada agente grava `_indices/parcial-/.csv` (um arquivo por índice); o coordenador consolida no arquivo canônico. Cabeçalhos fixos: `rotas.csv` ``` id_rota,unidade,tipo,metodo,uri,nome,middleware,controlador,acao,permissao,auth,throttle,cache,request,resposta,efeito,fonte ``` `tabelas.csv` ``` tabela,unidade,papel,pk,colunas,fks,indices,unique_constraints,soft_delete,uuid_fn,migracoes,modelos,consumidores,escrita_em,fonte ``` `componentes.csv` ``` id,unidade,caminho_blade,namespace,props,slots,eventos_js,dom_ids,consumidores,a11y,efeito,fonte ``` `permissoes.csv` ``` slug,unidade,acao,middleware,role_padrao,onde_aplicada,fonte ``` `config.csv` ``` chave,unidade,default,env,tipo,efeito,consumidores,fonte ``` `dados-iniciais.csv` ``` seeder,unidade,tabelas,registros,idempotencia,ordem,fonte ``` `servicos.csv` ``` unidade,efeito,api_publica,ui_surface,particularidade,consumidores,precisa_reimplementacao,fonte ``` `arquivos.csv` ``` caminho,unidade,doc,papel,status ``` Regras dos índices: - `colunas` em `tabelas.csv`: JSON compacto `[{"n":"id","t":"uuid","null":false,...}]` entre aspas — legível por máquina e por humano. - `efeito` é uma frase observável, não um rótulo ("cria o registro e invalida o cache público de /noticias", não "salva"). - Uma linha por rota **declarada** (`Route::*` que registra endpoint); grupos, middlewares e redirects aparecem como `tipo=grupo|redirect`. - `fontes` sempre `caminho:linha`. ## 9. Ciclo de vida 1. Coordenador cria o doc a partir do template (status `pendente`). 2. Agente preenche e muda para `em_andamento`. 3. Agente conclui checklist + lint e muda para `revisao`. 4. Revisor (humano ou `reviewer`) confere amostra e muda para `concluido`. 5. Correção posterior mantém `concluido` e registra a data na seção de evidências. ## 10. Completude (leis) 1. **Lei de arquivos:** todo arquivo do manifest aparece em `fontes` de exatamente um documento (ou em `arquivos.csv` com papel `morto/gerado` justificado). 2. **Lei de rotas:** toda rota registrada tem linha em `rotas.csv` com middleware, controller, permissão e efeito. 3. **Lei de tabelas:** toda tabela criada/alterada por migration tem linha em `tabelas.csv`; colunas, FKs e quem escreve. 4. **Lei de telas:** todo `.blade.php` de página/componente público ou CMS tem entrada em `componentes.csv` e descrição de props/estado/eventos. 5. **Lei de serviços:** toda classe pública de `SVC-*` tem assinatura, efeito, consumidores e receita de uso. 6. **Lei de dados:** todo seeder tem ordem, idempotência e tabelas afetadas. 7. **Lei de paridade:** cada unidade tem checklist testável (PC-*), sem itens vagos. 8. **Lei das quatro dimensões:** nenhum doc `concluido` sem Efeito, Abordagem, Particularidades e Integrabilidade preenchidos, com ≥3 trechos de código citados (exceto unidades sem código, que declaram isso explicitamente). Vago = proibido: "gerencia notícias", "usa permissões", "tem validação". Escrever quais, onde, com que valores, com que efeito. ## 11. Fora de escopo - Internals de bibliotecas vendorizadas (documentar versão, arquivos e API usada). - Arquivos mortos (`.bak`) — registrar como morto, não especificar. - Framework Laravel 5.5 e Sentinel: documentar apenas o uso no projeto. - `REFERENCE/` (HTMLs de design) serve só como comparação visual do portal. - Refatorar, corrigir ou executar o sistema. O levantamento é **read-only** sobre `sucesu-cms/`. ## 12. Definição de pronto (por documento) - Front-matter completo; `status: revisao`. - Ficha de identidade e as quatro dimensões preenchidas, com trechos de código. - Receitas de uso e anti-uso presentes. - Todas as seções operacionais do template preenchidas (ou "não se aplica" justificado). - Checklist de extração respondido item a item. - Índices parciais emitidos e consolidados. - Zero `[PREENCHER]`; lacunas explícitas em `[L]`/`LG-*`. - `python3 sucesu_analise/tools/lint_docs.py` sem erro no arquivo.