`; `

` é do shell): - geral (`estatisticas-index`): cards resolvidos por `ResolveDashboardCards`, série diária em tabela semântica (`caption`, `th scope="col|row"`, dia UTC), top 10 rotas, top 10 módulos e distribuição por classe de status (4 linhas canônicas, participação inteira); - páginas (`estatisticas-paginas`): ranking de rotas nomeadas (requisições, duração média, `4xx / 5xx`, bots), teto de 100 rotas e 20/página, ordenação explícita por link (`requests`/`duration`/`errors`/`route`) com `aria-sort`; paginação nativa preservando filtro/ordem; página fora da faixa fixada na última; nunca path/query; - módulos (`estatisticas-modulos`): requisições, participação (%) e tendência percentual contra a janela anterior de mesmo tamanho (sem base = “sem base anterior”); - conteúdo (`estatisticas-conteudo`): contadores dos cards de conteúdo via `ResolveDashboardCards` (permissão do módulo dono + ativação), sem os cards de estado do Core; sem card visível = estado vazio (nenhum número de módulo que o perfil não vê). Nenhum PII: a dimensão exibida é nome de rota, token de módulo, classe de status, contadores, duração e bots. Sem gráfico obrigatório — a tabela é a leitura canônica. - Cache (`Logic/Support/EstatisticasCache`): TTL 60 s, chave versionada `estatisticas.report.v1.{sha256(report, preset, from, to, module, locale[, sort, dir, page])}`; invalidação só por TTL; permissão não é cacheada (o `authorize` roda por request). O cache guarda apenas arrays de escalares (política `serializable_classes => false`). Sem ETag (CMS privado). - i18n: namespace `estatisticas` com 4 seções (`menu`, `cms`, `validation`, `modules`) nos 4 locales; rótulos de módulo traduzidos (`estatisticas::modules.*`, fallback = token para módulo novo), status traduzidos (`status_2xx`…), navegação interna com `route()`. - Observabilidade: cada Action de relatório injeta `Telemetry` e emite span + `log_event` com o mesmo nome, apenas no cálculo (cache miss): `estatisticas.report`, `estatisticas.pages`, `estatisticas.modules`, `estatisticas.content`; contexto só com escalares (sem PII/path). ### Contrato (assinaturas) ```php // EstatisticasFilter (DTO) public function __construct(MetricsFilter $metrics, string $preset, ?string $notice = null); public function fromDay(): string; public function toDay(): string; public function days(): int; public function module(): ?string; public function locale(): ?string; public function isCustom(): bool; /** @return array */ public function query(array $overrides = []): array; // EstatisticasFilterParser public const array PRESETS = ['7', '30', '90', 'custom']; public function parse(Request $request): EstatisticasFilter; // nunca lança: fallback com notice // Ações de relatório (TTL 60 s, chave versionada) /** @return array{series: list<...>, routes: list<...>, modules: list<...>, status: list<...>, totals: array{...}} */ public function execute(EstatisticasFilter $filter): array; // Overview public function execute(EstatisticasFilter $filter, string $sort, string $direction, int $page): LengthAwarePaginator; /** @return array{total: int, rows: list} */ public function execute(EstatisticasFilter $filter): array; // ModuleTrends /** @return list / public function execute(): array; // ContentCards ``` ### Arquivos/superfícies para revisar - `src/modules/Infraestrutura/Estatisticas/ModuleProvider.php`, `Routes/cms.php`, `MODULE.md`. - `src/modules/Infraestrutura/Estatisticas/Logic/{Actions,Controllers,DTOs,Support}/`. - `src/modules/Infraestrutura/Estatisticas/Layout/Views/cms/` (4 telas + partial de filtro). - `src/modules/Infraestrutura/Estatisticas/Lang/{pt_BR,en,es,fr}/{menu,cms,validation,modules}.php`. - `src/modules/Infraestrutura/Estatisticas/Test/{EstatisticasCmsTest,EstatisticasI18nTest}.php`, `tests/Feature/EstatisticasContentTest.php`. - Contratos consumidos (sem alteração): `src/core/Contracts/{Metrics,Clock,Telemetry}.php`, `src/core/Metrics/`, `src/core/Area/Cms/Logic/Actions/ResolveDashboardCards.php`. ### Pontos de revisão (D1–D14) - D1 — Simplicidade/PHP 8.4: `declare(strict_types=1)`, `final readonly`, `match`, DTO único de filtro; sem trait/abstract/generic/`Result`; DI no construtor (Clock, cache, Telemetry, validator); nenhum `new` de serviço em corpo de domínio. - D2 — Laravel 12: 4 rotas `GET` sem closure, controller invokable, `Permission::authorize` no controller; `env()` não aparece; filtro em `GET` via `Validator` (não recria matriz de permissão). - D3 — Determinismo: período/fallback derivados do `Clock` injetado; `MetricsPeriod::lastDays`; ordenação total com desempate `route_name` + `module`; página fora da faixa fixada; `usort` com comparador total (sem depender de estabilidade); testes com `FixedClock`. - D4 — Fronteiras: o módulo importa só `Core\` (`Permissions`, `Metrics`, `MetricsFilter`, `ResolveDashboardCards`, `Locales`); teste de conteúdo com models de outros módulos ficou em `tests/Feature` (um módulo nunca importa outro); `arch-check` verde. - D5 — Dependências: nenhuma nova; ícones Lucide já vendorizados (`bar-chart`, `chart-line`, `table`, `trending-up`, `layers`). - D6/D7 — CSS/HTML/a11y: só utilitários/componentes existentes; `caption` + `th scope` em todas as tabelas; `aria-sort` nas colunas ordenáveis; estado vazio textual; status/tendência em texto (não só cor); filtro com `label`/`help` dos componentes da casa; `h1` único (shell). - D8 — i18n: 4 locales com paridade (`menu`, `cms`, `validation`, `modules`); nenhuma string visível fixa; rótulos de módulo/status traduzidos; links internos por `route()`; teste HTTP em 4 locales sem chave crua (`EstatisticasI18nTest`). - D9 — Grep-friendly: token `estatisticas`/`Estatisticas` em ModuleProvider, Actions, Controllers, DTO/Support, views, testes e chaves; `name-check` verde. - D10 — Dados: nenhuma migração/tabela nova; leitura apenas de `core.core_metrics_daily` com binding (`day`/`module`/`locale`); nenhuma coluna de PII lida. - D11 — Segurança/LGPD: `estatisticas.ver` deny-by-default antes da consulta; filtros fechados (allowlist); tentativa de injeção cai no fallback e não muda o SQL; cards de conteúdo mantêm a permissão do módulo dono; nenhum path/query/IP/UA exibido ou cacheado; cache não guarda permissão. - D12 — Observabilidade: span + `log_event` com mesmo nome por relatório calculado; contexto apenas escalares, sem PII; leitura de painel continua na trilha (`audit.access`), métrica não é auditoria. - D13 — Testes/evidência: `EstatisticasCmsTest` 19 casos (403/404 de módulo inativo, 4 telas, série/top/status, presets com Clock, custom inclusivo, 7 entradas inválidas + injeção, locale/módulo, paginação/ordenação/`aria-sort`/teto de 100, participação/tendência, cache de dois requests + chave por filtro, shell único, únicos do dia (HLL) e parâmetros em array), `EstatisticasI18nTest` 3 e `tests/Feature/EstatisticasContentTest` 1; sem `sleep`; `ModuleI18nTest`/`IconTest`/`LayoutContractTest`/`DocsReferencesTest`/`ModulesTelemetryTest` verdes. (O número antigo — “13” — era o estado anterior à S5; o fechamento real está em `## P4.FIX`.) - D14 — Documentação: `MODULE.md` (rotas, filtros, cache, eventos, a11y), esta ficha, fila e inventário. P4.FIX atualizou `wiki/implementation-phases/{P4-estatisticas,README,INVENTARIO}.md` (P4 passou a `em revisão`, antes ainda `planejado`). ### Riscos e observações - Fallback × 422: o contrato da fatia aceitava “mensagem i18n ou 422”; escolhemos o fallback (200 + aviso) para um `GET` de leitura — um `FormRequest` devolveria 302/422 antes da autorização, invertendo a ordem “autorização → validação”. O parser valida depois do `authorize`. - Teto de 100 rotas: a ordenação por duração/erros é aplicada sobre as 100 rotas mais requisitadas do período (limite do contrato `Metrics::topRoutes`). Ordenar por outra coluna não alcança rotas fora desse teto — comportamento documentado no `caption` (“até 100 rotas”). - Dia em ISO (`Y-m-d`): a série diária exibe o dia UTC sem `LocalizedDate` (é dado de relatório, não data editorial); o locale não muda o significado do bucket. `period_summary` deixa claro que a janela é UTC. - Participação/tendência inteiras: arredondamento explícito para inteiro (sem separador decimal dependente de locale); tendência sem base anterior é `null` (não 0%). - Rótulos de módulo vêm de `estatisticas::modules.` (mapa local, 4 locales) com fallback para o token: um módulo novo aparece com o token até ganhar rótulo — sem importar `ModuleDiscovery`. - Cache por página: a chave inclui ordenação/página; cada combinação paga uma agregação no primeiro acesso após o TTL (as 100 rotas são lidas uma vez por combinação, não por item). - Conteúdo sem filtro: os cards de conteúdo são contadores atuais (não janelados), por isso a tela não oferece filtro de período — evita um filtro que não muda nada. ### Comandos úteis ```bash docker compose exec -T php-fpm ./vendor/bin/phpunit \ --filter='EstatisticasCmsTest|EstatisticasI18nTest|EstatisticasContentTest' docker compose exec -T php-fpm ./vendor/bin/phpunit \ --filter='ModuleI18nTest|DocsReferencesTest|ModulesTelemetryTest|LayoutContractTest|IconTest' docker compose exec -T php-fpm ./vendor/bin/phpstan analyse --memory-limit=1G --no-progress docker compose exec -T php-fpm php tools/arch-check && docker compose exec -T php-fpm bash tools/name-check.sh php artisan core:cache-modules # o manifesto precisa incluir o módulo novo ``` ### Evidência (2026-10-25) - Testes: 18 casos verdes (`EstatisticasCmsTest` 14 · `EstatisticasI18nTest` 3 · `tests/Feature/EstatisticasContentTest` 1), 1.330 asserções; `ModuleI18nTest`, `IconTest`, `LayoutContractTest`, `BladeStaticCallsTest`, `DocsReferencesTest` e `ModulesTelemetryTest` verdes junto. - Cobertura do módulo (produção, sem `Test/`): 812/818 linhas = 99,3% — as 6 restantes são o `throw` defensivo de `EstatisticasFilterParser::date()`, inalcançável pela validação. - Gates: PHPStan max `0`; Pint `PASS`; `arch-check`, `migration-check`, `name-check` (`--grep estatisticas`) e `docs-check` OK. - `make check` 2× verde no estado final (24 OK / 0 FAIL; cobertura global ≥90, a11y OK) e `make check E2E=1` verde (e2e 135 s + perf 62 s, 0 FAIL) — UI nova exercitada pelo axe/shell existentes; a jornada métrica→relatório fica no S5 (P4 §3/S5). - Manifesto recacheado (`core:cache-modules`) — 11 módulos; o clone limpo descobre o módulo pela convenção (sem manifesto). ## S5 — export CSV, retenção, LGPD e E2E (`task_015t3ggc`) ### O que foi implementado - Export CSV (`GET /estatisticas/exportar`, nome `estatisticas.cms.export`, permissão `estatisticas.ver`): `EstatisticasExportController` (autoriza → `EstatisticasFilterParser` → `EstatisticasCsvExport` → `response()->streamDownload`). Allowlist `relatorio` = `paginas|modulos|serie` (valor desconhecido cai em `paginas`) e a mesma validação de filtros do S4 (presets/custom, locale e módulo allowlist; entrada inválida → fallback de 7 dias, sem erro de formulário em `GET`). As telas de período linkam o próprio relatório (a visão geral oferece os três, `data-export-report` no link). - Streaming e cabeçalhos: `Content-Type: text/csv; charset=UTF-8`, `Content-Disposition: attachment; filename="estatisticas-{relatorio}-{de}-{ate}.csv"` — o nome usa só relatório + datas do período, nunca a query string. Corpo gerado por `EstatisticasCsv::lines()` (`Generator`) e escrito linha a linha com `fputcsv` (sem montar o arquivo em memória). - CSV injection: `EstatisticasCsv::cell()` neutraliza toda célula de texto iniciada por `=`, `+`, `-` ou `@` com o prefixo `'`; número (inclusive negativo, ex.: tendência) é dado e preserva o valor — a mesma regra do export de Dados Abertos (ADR-051). Coberto por teste com as quatro formas. - Sem PII/path/query: as linhas carregam nome de rota, token de módulo, dia UTC e contadores; nenhum path, slug, parâmetro, IP, user-agent ou locale por linha (o locale só escolhe o cabeçalho traduzido). O `paginas` reusa `EstatisticasRouteRanking::rows()` (extraído de `build()`), então a tela paginada e o arquivo nunca divergem. - Ação sensível auditada: o nome `estatisticas.cms.export` casa `export*` em `config('audit.sensitive')`; o middleware `audit.access` da área CMS grava `AuditEntry::access('estatisticas', 'estatisticas.view', 'estatisticas.cms.export')` — provado por `EstatisticasExportTest` (sem código de auditoria no controller). - Retenção agendada: `Schedule::command('metrics:expunge')->daily()` em `routes/console.php`, além do `retention:expunge` mensal (que já inclui o alvo `metrics-daily`); `audit:expunge` mensal, `queue:prune-failed` e `media:backup` intactos. `--dry-run`/relatório e “não toca a auditoria” provados em `MetricsRetentionTest` (novo caso: `metrics:expunge` real com linha de auditoria presente → contagem inalterada). - LGPD/transparência: seção “Medição e cookies” da política (`Portal/Lgpd`) ganhou três parágrafos factuais nos 4 locales: métricas agregadas (rota nomeada, idioma, classe de status, duração, rótulo de robô), sem IP/user-agent/cookie de analytics/parâmetros de URL/identificador entre dias; retenção de agregados 400 dias e HLL 90 dias; GA de terceiros só opt-in (o texto de terceiros continua condicional a `lgpd.analytics.third_party`). A chave antiga genérica (`analytics_privacy_first`) foi removida (substituída pelo texto verificável) — `ModuleI18nTest` cobre a paridade e `LgpdTest` cobra o texto renderizado nos 4 locales. - E2E nova (`histories/24-estatisticas.md` + `tests/24-estatisticas.spec.ts`, projeto `cms-desktop`): visita ao portal → abre a visão geral e o ranking, confere `lgpd.privacy` com contagem ≥ 1, filtra o período pela UI (`periodo=30` + resumo) e um período personalizado no dia UTC corrente; baixa o CSV pelo link da tela e valida nome/cabeçalho/linha do relatório; axe A/AA na visão geral e no ranking. Sem mutação global: `fullyParallel: false` mantido e nenhum projeto serial novo. - Escolha registrada (E2E × feature): “módulo desativado → histórico permanece, não cresce” e “retenção remove” ficaram em PHPUnit (`EstatisticasCmsTest` + `MetricsRetentionTest`/`RetentionScheduleTest`) — a `23-suporte-painel` já cobre ativação em runtime no E2E, e envelhecer/expurgar agregados numa jornada de UI exigiria atalho de banco. O E2E fica com o caminho métrica → relatório → export. - Seed demo: o perfil `administrador` deriva as permissões do manifesto (`CmsUserSeeder::declaredPermissions()`), então `php artisan db:seed` (pré-condição já documentada no README do E2E) passou a conceder `estatisticas.ver`; nenhuma permissão é hardcoded. ### Contrato (assinaturas) ```php // EstatisticasCsvExport public const string DEFAULT_REPORT = 'paginas'; public const array REPORTS = ['paginas', 'modulos', 'serie']; public static function resolve(string $report): string; /** @return array{report: string, filename: string, columns: list, rows: list>} */ public function execute(EstatisticasFilter $filter, string $report): array; // EstatisticasCsv public const string MIME = 'text/csv; charset=UTF-8'; /** @param list $columns @param list> $rows @return Generator> */ public static function lines(array $columns, array $rows): Generator; public static function cell(string|int $value): string; // prefixo ' em texto = + - @ // EstatisticasRouteRanking (extraído do build) /** @return list / public function rows(EstatisticasFilter $filter, string $sort, string $direction): array; ``` ### Arquivos/superfícies para revisar - `src/modules/Infraestrutura/Estatisticas/Logic/Actions/EstatisticasCsvExport.php` - `src/modules/Infraestrutura/Estatisticas/Logic/Actions/EstatisticasRouteRanking.php` (`rows()`) - `src/modules/Infraestrutura/Estatisticas/Logic/Controllers/EstatisticasExportController.php` - `src/modules/Infraestrutura/Estatisticas/Logic/Support/EstatisticasCsv.php` - `src/modules/Infraestrutura/Estatisticas/Routes/cms.php`, `Layout/Views/cms/partials/estatisticas-filter.blade.php` (links de export), `Lang/{pt_BR,en,es,fr}/cms.php` (`export_`), `MODULE.md` - `src/modules/Infraestrutura/Estatisticas/Test/EstatisticasExportTest.php` - `routes/console.php` (agendamento diário), `src/core/Internal/Metrics/README.md` - `src/core/Internal/Metrics/Test/MetricsRetentionTest.php` (auditoria intocada), `tests/Feature/RetentionScheduleTest.php` - `src/modules/Portal/Lgpd/Lang/{pt_BR,en,es,fr}/privacy.php`, `src/modules/Portal/Lgpd/Layout/Views/privacy.blade.php`, `src/modules/Portal/Lgpd/Test/LgpdTest.php` - `src/tests-e2e/{playwright.config.ts,histories/24-estatisticas.md,tests/24-estatisticas.spec.ts,README.md}`, `src/tests-e2e/tests/17-cms-configuracoes.spec.ts` (locator `exact`), `wiki/specs/04-acessibilidade-ux.md`, `AGENTS.md` (contagem de histórias) ### Pontos de revisão (D1–D14) - D1 — Simplicidade/PHP 8.4: Action `final readonly` com DI (Actions de relatório + Telemetry); `match` para o relatório; `Generator` tipado; sem trait/abstract/generic/`Result`; nenhum `new`/`resolve` no corpo. - D2 — Laravel 12: rota `GET` sem closure; `streamDownload` nativo; `Schedule::command` no `routes/console.php` (não há `Kernel`); `env()` não aparece. - D3 — Determinismo: filtro/período do `Clock` injetado; ordem do CSV = ordem da tela (`rows()` com comparador total); nome do arquivo só com datas validadas; nenhum `now()` no export (datas vêm do `EstatisticasFilter`); teste do schedule verifica a expressão cron real. - D4 — Fronteiras: só o módulo (export) e o Core (agenda/retention test); o E2E usa rotas públicas; `arch-check` verde. - D5 — Dependências: nenhuma nova; ícone `download` já vendorizado. - D6/D7 — CSS/HTML/a11y: export é anexo (não há tabela nova); os links usam `btn btn-outline` dos componentes da casa, com ícone `aria-hidden` e texto visível; axe E2E A/AA nas duas telas. - D8 — i18n: 4 locales para `export_csv`/`export_paginas`/`export_modulos`/`export_serie`; o cabeçalho do CSV segue o locale ativo; a política de privacidade tem o texto factual nos 4 locales (teste de paridade + texto renderizado). - D9 — Grep-friendly: tokens `estatisticas`/`Estatisticas` nos arquivos novos; `name-check` verde (`--grep estatisticas`). - D10 — Dados: nenhuma migração/tabela nova; leitura via portas do Core; nenhuma coluna de PII. - D11 — Segurança/LGPD: permissão antes da geração; filtros fechados (mesmo parser); CSV injection neutralizado em toda célula de texto; nenhum path/query/PII no arquivo ou no nome; auditoria de acesso registrada; política de privacidade factual (sem promessa não cumprida). - D12 — Observabilidade: `estatisticas.export` (span + `log_event` com escalares `report`/`days`/`module_filter`/`locale`/`rows`), sem PII; leitura na trilha via `audit.access`. - D13 — Testes/evidência: `EstatisticasExportTest` (11 casos: convidado/403, anexo+colunas, filtros iguais aos das telas + fallback + allowlist, neutralização das 4 formas, célula numérica, módulos/série, cabeçalho por locale, auditoria, módulo inativo, links das telas); `EstatisticasCmsTest` (histórico de módulo desativado que não cresce e permanece no relatório); `MetricsRetentionTest` (auditoria intocada); `RetentionScheduleTest` (3 casos: diário, mensal e jobs preservados); `LgpdTest` (política nos 4 locales); E2E `24-estatisticas` (2 casos). - D14 — Documentação: `MODULE.md` (rota, relatórios, streaming, neutralização, retenção), README de métricas (agenda), `AGENTS.md`/spec 04/README do E2E (história 24), esta ficha, fila e inventário. ### Riscos e observações - `-` em número: a neutralização preserva `-20` (tendência) e prefixa texto `'-1+1`. É a regra do export de Dados Abertos e a única que não corrompe valor; o teste fixa os dois lados. - `fputcsv` cita campos com espaço: cabeçalhos como `"Duração média (ms)"` saem entre aspas — é CSV válido; o teste do arquivo compara o cabeçalho exato (o E2E também). - Cache × export: o export usa as Actions cacheadas (`modulos`/`serie`) e `rows()` sem cache para páginas; um arquivo baixado dentro dos 60 s vê o mesmo recorte da tela (proposital). - Schedule mensal + diário: os dois tocam o alvo `metrics-daily`; é idempotente (DELETE por `day < corte`), não duplica efeito e mantém o mensal como rede de segurança. - `retention:expunge` mensal continua o único caminho dos demais alvos — o diário é só métrica. - Seed/precondição do E2E: sem `db:seed` o perfil demo não tem `estatisticas.ver` e o spec falha em 403 (pré-condição documentada); não se cria permissão por atalho no teste. - E2E `--no-deps`: ao rodar só a spec 24 fora do `make check`, o projeto dependente `cms-serial` não roda; no `make check E2E=1` a ordem normal (serial antes) é mantida. - Regressão exposta pelo seed: o perfil `administrador` passou a ver o subitem “Visão geral” (Estatísticas) e a spec 17 usava `getByRole('link', { name: 'Geral' })` sem `exact` — o nome acessível “Visão geral” casa por substring. Corrigido no locator da spec (`exact: true`); a UI não mudou. É o tipo de acoplamento que o E2E deve evitar, não um defeito de produto. ### Comandos úteis ```bash docker compose exec -T php-fpm ./vendor/bin/phpunit \ --filter='EstatisticasExportTest|EstatisticasCmsTest|EstatisticasI18nTest|MetricsRetentionTest|RetentionScheduleTest|LgpdTest' docker compose exec -T php-fpm ./vendor/bin/phpstan analyse --memory-limit=1G --no-progress BASE_URL=http://localhost:50700 npx playwright test tests/24-estatisticas.spec.ts --project=cms-desktop make check && make check && make check E2E=1 ``` ### Evidência (2026-10-25) - Testes alvo (PHPUnit): `EstatisticasExportTest` 11 casos / 70 asserções (P4.FIX elevou a 13) · `EstatisticasCmsTest` 15 (S4 + o caso novo de módulo desativado) · `EstatisticasI18nTest` 3 · `EstatisticasContentTest` 1 · `MetricsRetentionTest` 7 (novo: auditoria intocada) · `RetentionScheduleTest` 3 (P4.FIX elevou a 4) · `LgpdTest` 21 (novo: política de métricas nos 4 locales) — todos verdes. - Suíte completa: `OK (1332 tests, 22879 assertions)`; cobertura `src/` = 93,88% (17.276/18.402) — piso ≥90%. Módulo `Estatisticas` (produção, sem `Test/`): 942/946 = 99,6%; as 4 linhas restantes são defensivas/inalcançáveis (3 no `throw` de `EstatisticasFilterParser::date()` e 1 no guard de `fopen` do controller de export). - Gates estáticos: PHPStan `max` 0; Pint `PASS`; `arch-check`, `migration-check`, `name-check`, `docs-check`, `optimize-check`/`optimize-verify` e `check-gates` OK. - `make check` 2× verde (22 OK · 0 FAIL · 11 SKIP — SKIPs são os passos caros já frescos) e `make check E2E=1` verde (24 OK · 0 FAIL · 9 SKIP; `e2e` 140 s, `perf` 62 s, `a11y` OK). - E2E: 132 testes — 131 passed + 1 skipped (`07-cms-shell`, opt-in condicional); a spec nova `24-estatisticas` passa os 2 casos (portal→relatório/filtro e export como anexo) no `cms-desktop`; nenhum flaky observado (uma rodada anterior reprovou o locator ambíguo da spec 17, corrigido com `exact: true` e revalidado nas duas rodadas seguintes). - Manifesto recacheado (`core:cache-modules`, 11 módulos) e `db:seed` executado (perfil demo passou a receber `estatisticas.ver` pelo manifesto). ## P4.FIX — correções da revisão paralela (`task_01m2zeqa`) Revisão paralela (8 recortes: dados, cards, ingestão, export, testes, docs, transversal) concluída em 2026-10-25. Cada correção abaixo tem teste de regressão; o estado final é 🟡 não revisado. | # | Achado (sev.) | Correção | Teste | |---|---|---|---| | 1 | `pfadd` com hash escalar — phpredis 6 exige array; HLL morto em produção (P1) | `ValkeyUniqueCounter` chama `pfadd($key, [$hash])`; o fake passou a validar a assinatura do cliente (`pfadd`/`expire`/`pfcount`) e rejeita escalar | `UniqueCounterTest` (3 novos) + prova real com `metrics.uniques.driver=valkey` | | 2 | `url()`/`label()`/`icon()` fora do `try` → card com URL que lança derrubava `/cms` (P2) | `ResolveDashboardCards` resolve todos os metadados dentro da isolação; `ResolvedMetricCard` carrega `label`/`icon` já resolvidos e a view nunca chama o card | `DashboardCardsTest` (`ThrowingUrlCard`, `ThrowingLabelCard`) | | 3 | Cards de Notícias/Dados Abertos contavam `status=publicado` ignorando `published_at` futuro (P2) | Cards usam os escopos canônicos `publicadas()`/`publicados()` | fixture com data futura em `NoticiasMetricCardsTest`/`DadosAbertosMetricCardTest` | | 4 | Falha de cache descartava valor calculado e emitia `metrics.card_failed` (P2) | Cache best-effort (`get` falha → calcula; `put` falha → mantém) + evento próprio `metrics.card_cache_failed` (`operation=get|put`) | `DashboardCardsTest` com repositório de cache que lança | | 5 | `media.stream` dominava o ranking e pagava upsert/HLL por imagem (P2) | Allowlist configurável `metrics.ignored_routes` (`media.`, `seo.`) avaliada no `shouldCollect` | `MetricsIngestionTest` (asset excluído / página continua) | | 6 | Home (`Route::view` → `ViewController`) gravava `module=core`; guard `/up` inalcançável e teste de falso verde (P2) | Fallback pelo nome da rota também para controller não de módulo (`portal.home` → `home`); guard `/up` removido; teste de health trocado pelo de asset real | `MetricsIngestionTest` (`/` → `home`, `/build/`, allowlist) | | 7 | Fallback GET transformou `POST/PUT` em 405 e `OPTIONS` em 200 em path inexistente (P2) | Semântica aceita e documentada (README de métricas + MODULE/ficha): corrigir exigiria trocar o fallback por catch-all, que quebra o 405 de rota viva. Testado | `MetricsIngestionTest` (`405`/`200` sem coleta; 405 de rota viva) | | 8 | HLL coletado sem superfície de leitura (P2) | Visão geral e CSV `serie` ganharam “únicos (estimativa)” por dia/global (sem dimensão de rota); fora do TTL (90 d) ou sem pepper → indisponível (célula vazia), nunca `0` | `EstatisticasCmsTest` (2), `EstatisticasExportTest` (1) | | 9 | `MetricsRetentionTest` dependia do relógio do host; dry-run não provava a contagem (P2/P3) | `Clock` fixo no `setUp`; asserção `1 registro(s) (dry-run)`; schedule prova ausência de `--dry-run` | `MetricsRetentionTest`, `RetentionScheduleTest` | | 10 | DNT `withHeader` vazava para o request Sec-GPC (P3) | `flushHeaders()` antes do GPC | `MetricsIngestionTest` | | 11 | E2E dependia da página 1 do ranking global e do relógio na virada UTC (P3) | Filtro `modulo=lgpd` + `utcToday()` capturado antes da visita | `tests/24-estatisticas.spec.ts` | | 12 | `?ordenar[]=`/`?direcao[]=`/`?relatorio[]=` → 500 (P3) | Leitura escalar + allowlist (`EstatisticasSortLinks::fromRequest`/`directionFrom`, `EstatisticasCsvExport::fromRequest`) | `EstatisticasCmsTest`, `EstatisticasExportTest` | | 13 | CSV não neutralizava TAB/CR (P3) | Regex `/^[=+\-@\t\r]/`, igual ao export de Dados Abertos | `EstatisticasExportTest` | | 14 | Linhas 81–83 da fila fora da tabela F7+ (P3) | Movidas para dentro da tabela, após o item 80 | revisão do `README.md` | | 15 | P4 do wiki ainda `planejado`; `INVENTARIO` dizia “não existe métrica” (P2/P3) | `em revisão` + ficha; inventário `FEITO (P4, em revisão)` | — | | 16 | Ficha com contagens erradas, comentário obsoleto do card, riscos não registrados (P3) | Este bloco; `PortalRequestsCard` documentado (sem link por divergência `painel.ver` × `estatisticas.ver`) | — | | 17 | Política publicava 400/90 literais enquanto a config é ajustável (P3) | View deriva os prazos de `config('metrics.')`; os 4 locales usam `:aggregate_days`/`:unique_days` | `LgpdTest` (4 locales, config-driven) | ### Decisões e riscos aceitos - Únicos por dia, não por rota: a ADR-047 não tem dimensão de rota para HLL; expor “únicos da rota” exigiria um HLL por rota (custo e cardinalidade) e uma emenda de ADR. Decisão: coluna diária global na visão geral/série, com nota explícita na tela e no CSV. - Fallback × métodos ≠ GET: mantido 405 (`POST`/`PUT`) e 200 (`OPTIONS`) para path inexistente, documentado e coberto. Trocar por catch-all quebraria o 405 de rota viva; um renderer de exceção cobriria só parte dos verbos. Risco residual: cliente de API que envie `OPTIONS` para URL desconhecida recebe 200 `Allow: GET, HEAD` em vez de 404. - Retenção/LGPD: os prazos publicados acompanham `config()`; se o deploy mudar `METRICS_RETENTION_DAYS`/`METRICS_UNIQUE_TTL_DAYS`, o texto muda junto (sem literal congelado). - Cache de relatório sem `throttle:` (achado transversal F2): chave de cache cresce com `de`/`ate`/`modulo`/`ordem`/`página`; só usuários com `estatisticas.ver` alcançam. Não implementado nesta correção — vira task de dívida (throttle/reuso do payload do export). - `BotClassifier`: marcadores genéricos (`bot`, `monitor`, `uptime`) foram estreitados — aparelho CUBOT e UA de navegador com a palavra “Monitor” deixam de ser bot; Googlebot, bingbot, crawlers e monitores conhecidos (UptimeRobot, Pingdom) continuam cobertos. - Export `paginas` sem cache (O1): mantido (decisão documentada da S5, linhas limitadas). ### Evidência (2026-10-25, após P4.FIX) - Prova do HLL real (`metrics.uniques.driver=valkey`, phpredis 6.3.0, Valkey 9, via `bootstrap/app.php`): `driver=Core\Internal\Metrics\ValkeyUniqueCounter`, três `add()` com dois hashes distintos → `count=2`, `ttl=7776000` (90 dias). O fake `RecordingRedisConnection` passou a validar a assinatura do cliente e rejeita `pfadd` escalar. - Suíte completa: `OK (1363 tests, 23077 assertions)`; cobertura `src/` = 93,92% (17.350/18.474), piso 90%. - `make check` 2× verde (24 OK · 0 FAIL · 9 SKIP e 22 OK · 0 FAIL · 11 SKIP) e `make check E2E=1` verde (24 OK · 0 FAIL · 9 SKIP; `e2e` 141 s, `perf` 62 s, `a11y` OK). - E2E: 132 testes — 131 passed + 1 skipped (`07-cms-shell`, opt-in); os dois casos da spec `24-estatisticas` verdes com o filtro `modulo=lgpd` no `cms-desktop`. - Gates estáticos: PHPStan `max` 0; Pint `PASS`; `arch-check`, `migration-check`, `name-check`, `docs-check`, `optimize-check`, `check-gates` OK. ## P4.FIX2 — `de[]`/`ate[]` não podem gerar 500 (`task_00epcj24`) A verificação independente do P4.FIX (recorte export/testes) encontrou que a regra cruzada `after_or_equal:de` faz o framework parsear o valor de `de`: com `?periodo=custom&de[]=x&ate=…` o `DateTime::createFromFormat()` do vendor recebia um array e o `TypeError` escapava do `parse()` — HTTP 500 nas telas de período e no export, em vez do fallback 200. | Achado | Correção | Teste | |---|---|---| | A1 (Baixo) `de[]`, `ate[]` e ambos, com e sem `custom`, respondiam 500 (o contrato “entrada inválida → fallback 200” era violado) | `EstatisticasFilterParser::refuseNonScalarDates()` roda antes de montar as regras: `de`/`ate` só passam como texto (ou ausente/`null`); tipo inesperado vira `ValidationException` localizada (`date_format`) e cai no fallback determinístico de 7 dias | `EstatisticasCmsTest::non_scalar_date_filters_never_break_the_screens` (6 formas × 4 telas) · `EstatisticasExportTest::non_scalar_date_filters_fall_back_instead_of_failing` (6 formas) | - Precedência preservada: a autorização (`estatisticas.ver`) continua no controller antes do parse; a recusa acontece dentro do `try` existente, então o `GET` nunca levanta erro de formulário. - As 5 rotas: `/estatisticas`, `/paginas`, `/modulos` e `/exportar` caem no fallback com aviso; `/conteudo` não usa o parser (contadores atuais, sem filtro de período) e simplesmente ignora a query, seguindo 200 — o teste cobre as cinco para provar que nenhuma responde 500. - Vermelho→verde: antes da correção o teste novo falhava com `DateTime::createFromFormat(): Argument #2 ($datetime) must be of type string, array given` (`Tests: 2, Assertions: 4, Failures: 2`); depois, `OK (2 tests, 56 assertions)`. - Docs: `MODULE.md` §Filtros fechados registra a recusa de data não escalar; contagens de teste atualizadas abaixo. ### Evidência (2026-10-25, após P4.FIX2) - Testes alvo: `EstatisticasCmsTest` 20 casos · `EstatisticasExportTest` 14 · `EstatisticasI18nTest` 3 · `MetricsRetentionTest` 7 · `RetentionScheduleTest` 4 · `LgpdTest` 21 — verdes. - Suíte completa: `OK (1365 tests, 23133 assertions)`; cobertura `src/` = 93,92% (17.357/18.481), piso 90%. - `make check` 2× verde (24 OK · 0 FAIL · 9 SKIP e 22 OK · 0 FAIL · 11 SKIP) e `make check E2E=1` verde (24 OK · 0 FAIL · 9 SKIP; `e2e` 143 s, `perf` 63 s, `a11y` OK). - E2E: 132 testes — 131 passed + 1 skipped (`07-cms-shell`, opt-in); a spec `24-estatisticas` (tela e export) verde nas duas rodadas. - Gates estáticos: PHPStan `max` 0; Pint `PASS`; `arch-check`, `migration-check`, `name-check`, `docs-check`, `optimize-check`, `check-gates` OK. ## Notas da revisão | Data | Revisor | Resultado | Observações | |---|---|---|---| | 2026-10-25 | revisão paralela (7 recortes) + P4.FIX | ✅ aprovado | 17 achados corrigidos com teste (seção `P4.FIX`); riscos aceitos registrados (únicos por dia global, 405/200 do fallback, cache de export sem throttle, `BotClassifier` estreitado). Verificação independente: nenhum achado sobrevivente. | | 2026-10-25 | verificação independente do export + P4.FIX2 | ✅ aprovado | A1 (`de[]`/`ate[]` → 500) corrigido com recusa de data não escalar antes das regras (seção `P4.FIX2`); teste vermelho→verde nas telas e no export; verificação final sem achados. |