# Public V7 — Concordia · Cadeia de Planos de Implementação > **Versão:** 0.1 (fundação) · **Status:** aguardando aprovação da Onda 0 > **Escopo:** reescrita profunda de `prefeituras_v5` com arquitetura **DDD-lite** > (`core` · `services` · `layout` · `modules`) sob `/src`, execução **Docker-first** > e servidor fiel a **WHM/cPanel** (PHP 8.4). --- ## 1. Como ler esta cadeia Cada plano é **autocontido**, tem um *Definition of Done* verificável e depende apenas dos planos anteriores. Nenhum plano começa sem o DoD do anterior validado. A ordem não é burocrática: é a ordem de **menor retrabalho**. ``` M0 Governança M1 Fundação técnica M2 Núcleo DDD-lite M3 Layout & UX M4 Produto ───────────────── ─────────────────────── ────────────────────── ───────────────────── ────────────────── 01 Análise/ADRs → 03 Esqueleto /src → 07 Core contratos → 09 Design system → 12 Admin/CMS 02 Governança IA → 04 Runtime cont. → 08 Services/persist → 10 Layout slots → 13 Módulo piloto 05 Qualidade max 11 A11y/UX gate → 14 SEO/perf 06 Obs. day-zero → 15 Deploy/migração ``` ### Planos | # | Plano | Milestone | Depende de | |---|-------|-----------|------------| | 01 | [Análise das referências e decisões](./01-analise-e-decisoes.md) | M0 | — | | 02 | [Governança IA-first e especificação viva](./02-governanca-ia-first.md) | M0 | 01 | | 03 | [Esqueleto DDD-lite em `/src`](./03-esqueleto-ddd-lite.md) | M1 | 02 | | 04 | [Runtime em containers (web · FPM · Valkey · PG 18) + edge Apache WHM](./04-runtime-containers.md) | M1 | 03 | | 05 | [Qualidade máxima (PHPStan/Larastan + testes)](./05-qualidade-phpstan-max.md) | M1 | 03 | | 06 | [Observabilidade desde o dia zero](./06-observabilidade-day-zero.md) | M1 | 03 | | 07 | [Core: contratos, discovery e mensageria](./07-core-contratos-discovery.md) | M2 | 05, 06 | | 08 | [Services headless e persistência](./08-servicos-headless-persistencia.md) | M2 | 07 | | 09 | [Design system (Tailwind 4 + daisyUI + Lucide)](./09-design-system-daisyui.md) | M3 | 08 | | 10 | [Layout engine com slots configuráveis](./10-layout-engine-slots.md) | M3 | 09 | | 11 | [Acessibilidade e UX como gate](./11-acessibilidade-ux-gate.md) | M3 | 10 | | 12 | [CMS: shell próprio + views por módulo](./12-admin-cms-editor.md) | M4 | 11 | | 13 | [Módulo piloto + blueprint/stubs](./13-modulo-piloto-blueprint.md) | M4 | 12 | | 14 | [SEO, performance e borda](./14-seo-performance.md) | M4 | 13 | | 15 | [CI/CD, deploy e operação (WHM/cPanel)](./15-cicd-deploy-legado.md) | M4 | 14 | | 16 | [Widgets, banners e construtor de layout](./16-front-builder-widgets-banners.md) | M3→M4 | 09, 10, 12 | | 17 | [Dados abertos, LGPD e governança de dados](./17-dados-abertos-lgpd-governanca.md) | M4 | 08, 12, 14 | | 18 | [Otimização de resposta e hardening (v6)](./18-otimizacao-resposta-hardening.md) | M1→M4 | 04, 06, 08, 14 | | 19 | [Media e Gallery (ingestão, digestão e ``)](./19-media-gallery.md) | M2→M3 | 08, 12 | --- > **Execução:** a ordem sequencial de implementação (fases F0..F6, com `kd task` e DoD) vive em > [`implementation/README.md`](../implementation/README.md). Os planos abaixo são a referência > técnica de cada área; as fases dizem **em que ordem** executá-los. ## 2. Princípios inegociáveis (a "constituição") > **Fundamento (base de todos os princípios):** o projeto deve ser **determinístico, previsível e > padronizado**. Concretamente: builds **reprodutíveis** (digests/lockfiles/vendorização), > conteúdo público com **corpo determinístico** (habilita `ETag`/`304`), **ordem explícita** em > discovery/slots/presets, **clock e aleatoriedade injetados** (sem `now()`/`rand()` soltos), > dados de referência **idempotentes** e **testes sem flaky**. O objetivo é ser **fácil de > integrar, atualizar e materializar como código efetivo**, com **testes exaustivos finais**. > Ver [ADR-001](../adr/ADR-001-nativo-funcional-di-simplicidade.md). 0. **Não reinventar a roda (nativo primeiro).** Todo recurso que o Laravel 12 ou o PHP 8.4 já oferecem (Validation, FormRequest, Casts, Events, Queue, Policies, Gate, API Resources, Blade Components, Flysystem, Cache, Scheduler…) é usado **antes** de qualquer abstração própria. Só criar código quando o nativo não cobre. 1. **PHP concreto, funcional e com DI.** Funções focadas e puras sempre que possível; dependências (DB, HTTP, clock, id-gen, storage) **injetadas** por parâmetro/clausura — nunca `new`/`resolve` no corpo da regra. **Sem traits, sem classes abstratas, sem genéricos** e sem hierarquias de OO: classes só onde o framework exige (Provider, Model, Middleware, Cast, Component). `pipe(...)` em vez de loop mutável. **Autocontido e objetivo**: duplicação eventual é preferível à abstração desnecessária. O critério é funcionalidade e efetividade, não contagem de linhas. 2. **Testabilidade é design.** Toda regra de negócio em uma **Action** única e pequena, com dependências injetadas. Se não dá para testar barato com stub, o desenho está errado. 3. **Lint e formatação padronizados.** PHP: Laravel Pint. JS/TS: Prettier + ESLint. Rodam em `make check`/`make check` e no CI; nenhum merge com sucesso sem eles. 4. **Acessibilidade e UX são requisitos, não polimento.** eMAG 3.1 + WCAG 2.2 AA no *definition of done* de toda tela, validados por gate automatizado. 5. **Observabilidade é infraestrutura.** Todo log é JSON estruturado; todo request tem `request_id` + trace; todo erro é RFC 7807. 6. **Fronteiras físicas entre módulos.** Um módulo nunca importa outro. A comunicação passa pelo Core (eventos/ports). Violação quebra o build. 7. **Paridade dev/prod.** O ambiente de desenvolvimento é o mesmo container fiel ao servidor de produção (WHM/cPanel). Sem "na minha máquina funciona". 8. **Qualidade no nível máximo.** PHPStan/Larastan no nível máximo com baseline que só encolhe; testes estritos; cobertura medida. 9. **Grep-friendly (prefixo de domínio único).** Toda feature/módulo tem um **token canônico** (ex.: `diario-oficial`) e **todos** os artefatos derivam dele — classes, funções, views, rotas, migrations, tabelas, testes, slots e logs. Uma única busca (`grep -riE "diario[-_]?oficial"`) retorna a árvore completa da feature. Ver ADR-004. 10. **Logs estruturados sempre.** Toda ação registra `module`, `action`, `id`, `user`, `ts` e `duration_ms` (JSON) — observabilidade e auditoria de primeira classe, não `var_dump`/texto livre espalhado. 11. **Dados desacoplados da UI.** Migrations, desde a primeira, guardam só o necessário, priorizam `jsonb` e **nunca** armazenam HTML, CSS, classes ou flags de layout; a apresentação vive no tema/slots. `down()` nunca apaga (renomeia para `backup_*`). Ver ADR-017 e `wiki/specs/10-migracoes-e-dados.md`. 12. **Sempre otimizado por padrão.** `php artisan optimize` (config/rotas/views/eventos) é passo obrigatório de build e deploy, com autoload autoritativo, OPcache ligado e `declare(strict_types=1)` em todo arquivo PHP. Otimização/segurança nativas não são etapa posterior. Ver ADR-008. 13. **Web moderna.** HTML semântico primeiro, JS na última opção (progressive enhancement), acessibilidade moderna (eMAG/WCAG 2.2), CSS moderno (Grid/Subgrid, container queries, `oklch`, `:has()`), responsividade real e PWA — sempre alinhado à web moderna. Ver ADR-010. 14. **Segurança em profundidade.** CSP estrita **hash-based e cacheável** (sem `unsafe-inline`; nonce só em página marcada como não-cacheável), Trusted Types, TLS 1.3/HSTS, cookies endurecidos, Argon2id, hardening de PHP/ini, auditoria de dependências (SBOM) e modelo de ameaça leve por módulo. Ver ADR-020. 15. **Mínimo de dependências e tudo vendorizado.** Nada de CDN em runtime; JS/CSS/fontes vêm de build local (Vite/npm) ou SVGs vendorizados; wrapper de terceiro só com justificativa. O **nativo do framework vence a dependência nova**. Ver ADR-009/ADR-010. --- ## 2.1. Topologia do repositório A raiz de `public-v7/` é um **Laravel típico e enxuto** (limpo de tudo que não é necessário). O domínio vive **isolado** em `/src`; o framework fica **fora** de `/src`. Toda a documentação vive em `/wiki`. ```text public-v7/ # Laravel 12 típico (campo do framework) ├── app/ bootstrap/ config/ public/ routes/ storage/ vendor/ # framework ├── database/ # apenas o que o framework exige (o domínio tem o seu) ├── resources/ # apenas o bootstrap de assets/views base do framework ├── artisan composer.json package.json vite.config.* Makefile ├── docker/ docker-compose.yml ├── src/ # SÓ DOMÍNIO │ ├── core/ # auditoria, bus, discovery, erros (invisível ao usuário) │ ├── services/ # serviços agnósticos/headless sempre disponíveis │ ├── layout/ # estrutura de front-end, slots, presets, tema │ ├── modules/ # casos de uso autocontidos: modules/{Grupo}/{Modulo}/ │ └── tests-e2e/ # Playwright isolado (histórias + sniff/axe) └── wiki/ # TODA a documentação ├── plan/ # esta cadeia de planos ├── adr/ # decisões arquiteturais ├── specs/ # especificações vivas └── ARQUITETURA.md ``` > Regra: dentro de `/src` só existem `core`, `services`, `layout`, `modules` e > `tests-e2e`. Nada mais. Testes PHPUnit ficam **dentro** de cada camada > (ex.: `src/modules/Publicacoes/Noticias/Test/`), pois pertencem ao domínio. --- ## 3. Matriz de rastreabilidade (requisito → plano) | Requisito do briefing | Onde é resolvido | |---|---| | Estrutura `core → services → layout → modules` sob `/src` (+ `tests-e2e`) | 03, 07, 08, 09, 10, 11 | | Módulos isolados, falam só via Core | 07 (+ gate de fronteiras em 05) | | Autodescoberta de módulos + agrupamento por pasta | 07 (+ ADR-014), 03, 12, 13 | | Services agnósticos/headless sempre disponíveis (+ `ServiceProvider`/discovery, contrato no service) | 08 (+ ADR-015), 09, 12 | | Controle de acesso: permissões por módulo (`ver/editar/aprovar/arquivar`), perfis e suporte blindado | 07, 08 (+ ADR-033), implementation F2.I3 | | Ativação de módulos em tempo real (guard 404 + cache imediato) | 07 (+ ADR-034), implementation F2.I3 | | Object storage S3-like desde o dia zero (RustFS ↔ AWS S3) | 04, 08, 19 (+ ADR-030) | | Integridade/auditoria com BLAKE3 (extensão pinada) | 08 (+ ADR-029) | | Higiene de repositório (EOL/contexto Docker) e nome derivado do projeto | 03, 15 (+ spec 18) | | Tipografia de conteúdo (Atkinson Hyperlegible Next, vendorizada, ajustável) | 09 (+ ADR-011), 02 | | i18n multilíngue (pt_BR/en/es/fr) nativo + JSONB | 01 (ADR-012), 03, 10, 12, 14 (+ spec 13) | | Dados abertos (dataset, DCAT/INDA, export, licença) | 17 (+ ADR-018), 14 | | LGPD/privacidade (classificação, DSAR, retenção, incidentes) | 17 (+ ADR-019), 08, 15 | | Rate limiting / anti-abuso (borda, app, formulários) | 04, 06, 12 (+ ADR-021) | | Cache de resposta + ETag + CSRF fora do HTML | 18 (+ ADR-022), 14 | | Hardening de resposta (assets immutables, WebP/AVIF, Server-Timing) | 18, 04, 06, 08, 14 | | Mídia (ingestão/digestão, AVIF/WebP, ``, catálogo) | 19 (+ ADR-026), 08, 12, 14 | | Editor de texto rico único (TipTap → AST JSON; parser PHP semântico) | 12 (+ ADR-028), 08, 09, 13, 19 | | SEO (service, JSON-LD `@graph`, arquivos de raiz, redirects, analytics) | 14 (+ ADR-027), 11, 15 | | Áreas restritas invisíveis para indexação (CMS/API, robots/sitemap, segurança mais forte) | 14 (+ ADR-043), 15, 18 | | **Fundamento:** determinismo/previsibilidade/padrão; nativo primeiro; funcional com DI; lint/fmt | 03, 05, 13 (+ ADR-001) | | Grep-friendly: prefixo de domínio em todos os artefatos | 02 (spec 09), 05, 07, 13 (+ ADR-004) | | Migrations seguras; dados sem HTML/estilo, `jsonb` quando cabível | 01 (ADR-017), 03, 08, 13 (+ spec 10) | | Otimização nativa (`optimize`, OPcache, strict types) | 01 (ADR-008), 04, 05, 14, 15 | | Mínimo de dependências / tudo vendorizado (zero CDN) | 05, 09 (+ ADR-002, ADR-009/010), 12, 14 | | Web moderna (semântica, mínimo JS, CSS moderno, PWA) | 01 (ADR-010), 09, 10, 11, 14 | | Segurança web (headers/CSP, cookies, ini hardening, SBOM) | 01 (ADR-020), 04, 06, 12, 15 | | PostgreSQL **18** em container (sem porta; `uuidv7()`, colunas geradas) | 01 (ADR-007/017), 04, 08, 15 | | Layout com "slots" configuráveis (CMS e portal) | 09, 10, 12 | | Widgets/banners por módulo, presets e construtor visual | 16, 09, 10, 12 (+ ADR-016) | | Execução estrita em Docker, arquivos locais | 04 | | Runtime em containers no layout padrão do WHM; proxy burro; arquivos do cPanel ignorados; `up_prod.sh` | 04, 15 (+ ADR-005/006, specs 16/17) | | PHP 8.4 · Laravel 12 · Tailwind 4 · Lucide · daisyUI | 03, 04, 09 | | Logs estruturados em tudo + OpenTelemetry | 06 | | PHPStan + Larastan no nível máximo | 05 | | Testes automatizados + E2E Playwright | 05, 11, 13 | | Acessibilidade e UX | 09, 10, 11 (+ DoD de todos) | --- ## 4. Gates entre milestones (não avançar sem) - **Gate M0→M1:** ADRs 01–34 aprovados; `AGENTS.md`/`wiki/DESIGN.md`/specs vivos; repo inicializado com `/src`. - **Gate M1→M2:** `make up` sobe o servidor fiel; `make check` verde com PHPStan no nível máximo; um log JSON e um trace OTel visíveis ponta a ponta. - **Gate M2→M3:** `make create:module MODULE=Demo` gera módulo que passa em lint/análise/ testes; tentativa de import cruzado entre módulos **falha no build**. - **Gate M3→M4:** página pública renderizando por preset+slots, com eMAG/WCAG AA verde no gate Playwright+axe; tema trocável no CMS sem deploy. - **Gate M4→produção:** módulo piloto com e2e; SEO/sitemap; pipeline de deploy atômico em cPanel; backup/restore e PITR do banco do V7 ensaiados (ADR-042: sem ETL de legado). - **Gate do plano 16:** tema CMS/Portal + preset aplicável sem deploy; widget/banner por módulo com preview real; a11y (dislexia/contraste) vencendo o preset; reorder por teclado. --- ## 5. Convenções de execução - **Tasks granulares:** uma task por fase, aberta e fechada durante a fase (nunca "checklist morto" criado no início e fechado no fim). - **Não-regressão:** bug → teste que reproduz (vermelho) → correção → verde. Feature → testes estruturais durante a implementação (não unitário genérico). - **Staging de contexto:** antes de compactações, escrever `.STAGING.md`. - **ADR por decisão relevante**, versionado em `wiki/adr/` e referenciado no plano que a originou. - **Nativo primeiro + funcional:** antes de criar qualquer classe/abstração, verificar se o Laravel/PHP já resolve. Abstração própria exige justificativa no ADR ou no PR. --- ## 6. Estado atual - `public-v7/`: repositório praticamente vazio (README template + secret detection). - Conhecimento reaproveitável mapeado em [01](./01-analise-e-decisoes.md). - **Próxima ação:** aprovar o pacote de ADRs do plano 01 e executar o plano 02.