--- id: MOD-PUBLICACOES-NOTICIAS-ROTAS tipo: modulo onda: 4 status: concluido unidades: [MOD-PUBLICACOES-NOTICIAS] fontes: - V2/Modules/Publicacoes/Noticias/ depende_de: [CORE-BOOT, CORE-AUTH, CORE-CMS, CORE-RUNTIME, MOD-CONEXOES-UNIDADEREGIONAL] consumidores: [UI-CMS, UI-PORTAL, MOD-LAYOUTS-HOMEPAGE] criticidade: alta dono: NoticiasA --- # Publicações/Notícias — rotas > Anexo do [`spec.md`](spec.md). Vinte e quatro endpoints e três declarações de grupo em > dois arquivos (20 endpoints CMS, 4 públicos — `/noticias`, `/noticia/{slug}`, > `/noticia/{slug}/preview` e `/news-sitemap.xml`); nenhum endpoint de API no módulo. Telas em > [`cms.md`](cms.md) e [`portal.md`](portal.md). ## 0. Ficha de identidade | Campo | Valor | |---|---| | Efeito primário | Expõe o CRUD editorial em `cms/noticias/*` e a publicação em `/noticias`, `/noticia/{slug}` e `/news-sitemap.xml`. | | Entrada | HTTP GET/POST/PUT/DELETE; parâmetros de query na lista CMS; `{id}` e `{slug}` na URI. | | Saída | HTML (views `v2-noticias::`), JSON (tags, categorias, destaque), XML (sitemap), redirects `302` com flash. | | Efeitos colaterais | Escrita em `v2_news` e pivôs; auditoria; índice de busca; feed; purga de page cache; log estruturado. | | Particularidade central | O grupo nacional-only (`RegionalRestrictMiddleware`) cobre 13 rotas; duas rotas `POST /categorias` colidem e a primeira é engolida pelo `RouteCollection`. | | Como se integra | `Routes/cms.php` recebe `web`+`module.active:Noticias` do provider e `CmsAuthenticate` do próprio arquivo; `Routes/web.php` recebe `web`+maintenance+`page.cache`+`public.cache`. | | Se removido, quebra | Menu do CMS, portal de notícias, sitemap do Google News, widgets da Homepage. | | Superfície pública | As rotas da tabela §2. | ## 1. Efeito ### 1.1 Mapa de efeito por rota As rotas CMS mudam dados (exceto as três de leitura: `index`, `create`, `edit`, `preview-iframe`, `archived`, `categories`, `categories/json`, `tags.index`). As rotas públicas só leem — nunca criam sessão, nunca gravam. ### 1.2 O que muda no sistema por requisição | Requisição | Banco | Outros efeitos | |---|---|---| | `POST /cms/noticias/novo` | 1 `INSERT v2_news` + pivôs | auditoria `created`, busca, feed (se publicado), page cache purgado, `Log::info` | | `PUT/POST /cms/noticias/editar/{id}` | 1 `UPDATE v2_news` + `sync` de tags/galeria | auditoria `updated`, busca, feed, cache, log | | `DELETE /cms/noticias/{id}` | `deleted_at` | auditoria `archived`, remoção do índice público/feed, cache, log | | `POST /cms/noticias/{id}/restaurar` | `deleted_at=NULL`, `status=draft` | auditoria `restored`, busca, cache | | `POST /cms/noticias/{id}/toggle-highlight` | toggle `is_highlighted` | auditoria `highlight_toggled`, cache | | `POST /cms/noticias/set-super-highlight` | `UPDATE ... SET false` em todas + `true` em uma | auditoria `super_highlight_set`, cache | | `POST /cms/noticias/{id}/seo` | `metadata->seo` | auditoria `seo_updated`, cache | | `POST /cms/noticias/tags` | `firstOrCreate v2_news_tags` | nenhum log de auditoria | | `DELETE /cms/noticias/tags/{id}` | `DELETE` físico da tag (model sem `SoftDeletes`); pivôs ficam órfãos | nenhum log | | `POST /cms/noticias/categorias` | `INSERT v2_news_categories` | auditoria `category_created` | | `PUT/POST /cms/noticias/categorias/{id}` | `UPDATE` (bloqueado se `is_system`) | auditoria `category_updated` | | `DELETE /cms/noticias/categorias/{id}` | `category_id=NULL` nas notícias + `DELETE` físico da categoria; filhas ficam com `parent_id` órfão | auditoria `category_deleted` | | `GET /noticias`, `/noticia/{slug}`, `/news-sitemap.xml` | somente leitura | cache de página (Redis) e/ou cache próprio do sitemap | ### 1.3 O que **não** acontece - Rotas CMS **não** são cacheadas: `cms*` está na lista `except` do `PageCacheMiddleware` (`V2/Core/Middleware/PageCacheMiddleware.php:16-23`). - Não há throttle próprio, CSRF explícito no módulo (vem do grupo `web`) nem versionamento de API. - Não há rota de aprovação, rejeição ou preview com token funcional. - Não há redirect de `POST /categorias` para a página de categorias (retorna JSON). ## 2. Abordagem ### 2.1 Como as rotas são registradas `V2ServiceProvider::mapModuleRoutes` aplica o namespace `V2\Modules\Publicacoes\Noticias\Controllers` e, conforme o arquivo: | Arquivo | Middleware do provider | Efeito | |---|---|---| | `Routes/cms.php` | `web`, `module.active:Noticias` | rotas de administração; o arquivo adiciona `CmsAuthenticate` e o subgrupo `RegionalRestrictMiddleware` | | `Routes/web.php` | `web`, `MaintenanceMiddleware`, `page.cache`, `public.cache` | rotas públicas; o arquivo declara `web` de novo — `Route::gatherMiddleware()` aplica `array_unique`, então `web` roda uma vez | Fonte: `V2/Core/Providers/V2ServiceProvider.php:290-313`; `V2/Core/Middleware/PageCacheMiddleware.php:74-91`; `vendor/laravel/framework/src/Illuminate/Routing/Route.php:744-760`. ```mermaid flowchart LR A[Request] --> B{prefixo cms?} B -- sim --> C[web + module.active:Noticias] C --> D[CmsAuthenticate: Sentinel + roles] D --> E[V2PermissionMiddleware: Noticias read/write] E --> F{rota nacional-only?} F -- sim --> G[RegionalRestrictMiddleware] F -- não --> H[Controller] G --> H B -- não --> I[web + maintenance + page.cache + public.cache] I --> J[Controller público] ``` ### 2.2 Ordem de declaração e colisões 1. O grupo `cms/noticias` declara `GET /`, `GET|POST /novo`, `GET|PUT|POST /editar/{id}`, `GET /preview-iframe/{id}` e `DELETE /{id}` **antes** do subgrupo nacional-only. 2. `DELETE /cms/noticias/{id}` aceita qualquer segmento (inclusive `tags` ou `categorias`), mas `DELETE /tags/{id}` e `DELETE /categorias/{id}` têm dois segmentos e não colidem. 3. `POST /cms/noticias/categorias` é declarado **duas vezes** com nomes diferentes (`categories.index` e `categories.store`). O `RouteCollection` indexa por método+URI (`$this->routes[$method][$domainAndUri] = $route`), então a segunda sobrescreve a primeira; `refreshNameLookups()` no boot reconstrói a lista de nomes só com as rotas vivas, e `v2.noticias.cms.categories.index` deixa de existir. 4. `GET /cms/noticias/categorias` (página) e `GET /cms/noticias/categorias/json` convivem sem conflito. ### 2.3 Trechos de código pivô ```php // V2/Modules/Publicacoes/Noticias/Routes/cms.php:10-13 — o grupo CMS. Route::group([ 'middleware' => [\V2\Core\Middleware\CmsAuthenticate::class], 'prefix' => 'cms/noticias', ], function () { Route::get('/', [ 'as' => 'v2.noticias.cms.index', 'uses' => 'NoticiasCmsController@index', ]); ``` **Efeito.** Toda rota do arquivo herda autenticação; o prefixo não é aplicado pelo provider, é declarado aqui. O namespace do controller vem do provider. ```php // V2/Modules/Publicacoes/Noticias/Routes/cms.php:52-54,111-119 — subgrupo nacional-only // e a dupla declaração de POST /categorias. Route::group([ 'middleware' => [\V2\Core\Middleware\RegionalRestrictMiddleware::class], ], function () { // ... 13 rotas (destaques, arquivadas, SEO, tags, categorias) }); Route::get('/categorias/json', ['as' => 'v2.noticias.cms.categories.json', 'uses' => '...@categoriesIndex']); Route::post('/categorias', ['as' => 'v2.noticias.cms.categories.index', 'uses' => '...@categoriesIndex']); Route::post('/categorias', ['as' => 'v2.noticias.cms.categories.store', 'uses' => '...@categoriesStore']); ``` **Efeito.** A segunda declaração vence; criar categoria funciona, e o nome `categories.index` desaparece do roteador. A ausência de `active_pattern` específico não importa: o RBAC já resolveu o módulo pelo prefixo `cms/noticias*`. ```php // V2/Modules/Publicacoes/Noticias/Routes/web.php:10-37 — rotas públicas. Route::group(['middleware' => ['web']], function () { Route::get('/noticias', ['as' => 'v2.noticias.portal.index', 'uses' => 'NoticiasPortalController@index']); Route::get('/noticia/{slug}', ['as' => 'v2.noticias.portal.show', 'uses' => 'NoticiasPortalController@show']); Route::get('/noticia/{slug}/preview', ['as' => 'v2.noticias.portal.preview', 'uses' => 'NoticiasPortalController@preview']); Route::get('/news-sitemap.xml', ['as' => 'v2.noticias.sitemap.news', 'uses' => 'NoticiasSitemapController@index']); }); ``` **Efeito.** `/noticia/{slug}` e `/noticia/{slug}/preview` são registradas antes do catch-all `/{slug}` do Core; o fallback não as captura. Qualquer slug (`[a-z0-9-]+` não é imposto aqui) é aceito pelo parâmetro. ```php // V2/Modules/Publicacoes/Noticias/Controllers/NoticiasSitemapController.php:23-38 — cache // próprio do sitemap, independente do page cache. $currentHour = (int) date('H'); $currentMinute = (int) date('i'); if ($currentHour === 3 && $currentMinute <= 10) { Cache::forget('v2_news_sitemap_xml'); } $xml = Cache::remember('v2_news_sitemap_xml', 360, function () { return $this->generateSitemap(); }); return response($xml, 200)->header('Content-Type', 'application/xml'); ``` **Efeito.** O XML é recalculado a cada 6 h (360 min) e purgado na janela 03:00–03:10 (a cada requisição nessa janela). Como a rota é pública, `page.cache` também pode servir o XML por 5 min. ### 2.4 Decisões de design e por quê - **Rotas públicas fora de prefixo** `[C]`: `/noticias` e `/noticia/{slug}` são URLs de SEO consolidadas; o fallback do Core é registrado depois justamente para não capturá-las. - **CMS sem prefixo de módulo na URI** `[C]`: o prefixo é `cms/noticias`, não `cms/publicacoes/noticias`; a permissão usa `Noticias` (nome do diretório). - **Nacional-only como middleware de grupo** `[C]`: destaques, arquivadas, SEO, tags e categorias são administração nacional; regionais editam apenas o próprio conteúdo. - **Sem endpoint de API** `[C]`: não há `Routes/api.php`; a API de notícias regionais vive em `Conexoes/UnidadeRegional`, e a importação em `Support/NoticiasImport`. ### 2.5 Parâmetros, filtros e paginação **`GET /cms/noticias`** (`Controllers/NoticiasCmsController.php:62-126`): | Parâmetro | Tipo | Efeito | |---|---|---| | `status` | string | filtro exato; valor fora de `News::$validStatuses` é ignorado | | `category_id` | uuid | `where('category_id', ...)` | | `tag_id` | uuid | `whereHas('tags', ...)` | | `search` | string | `ILIKE %termo%` em `title`, `subtitle`, `summary` + `whereHas` em `category.name` e `tags.name` | | `page` | int | paginação de 15, ordenação `created_at desc` | O escopo regional (`RegionalScopeService::applyScope`) é aplicado **depois** dos filtros; os contadores também são escopados (`scopedStats`). **`GET /cms/noticias/arquivadas`**: sem filtros; `onlyTrashed()->orderBy('deleted_at','desc')->paginate(15)`; **não** aplica escopo regional (rota nacional-only) e usa `News::getStatsByStatus()` sem escopo (`:146-160`). **`GET /noticias`** (público): o controller ignora a query string. Parâmetros como `?categoria=`, `?regional=`, `?q=` aparecem na URL e são lidos **apenas** pelo JS da view; o servidor devolve sempre todas as publicadas (`NoticiasPortalController.php:62-91`). Não há paginação. **`GET /noticia/{slug}`**: `{slug}` é livre; `firstOrFail()` com `published()`; `404` quando não existe ou não está publicado. **`GET /news-sitemap.xml`**: sem parâmetros; limite 1.000, janela de 6 meses, ordenação `published_at desc`. ## 3. Particularidades ### 3.1 O que só existe aqui - **A única rota pública de detalhe é por slug**, não por id — e o slug é imutável (ver [`spec.md`](spec.md) RN-NOTICIAS-01). - **A rota de preview pública existe e está quebrada**: `GET /noticia/{slug}/preview` chama `News::isAccessible($token)`, método inexistente (`NoticiasPortalController.php:156`); qualquer requisição resulta em `500`. O preview usado pelo editor é `GET /cms/noticias/preview-iframe/{id}`. - **Cache duplo no sitemap**: `page.cache` (5 min, chave `page:`) + `Cache::remember('v2_news_sitemap_xml', 360)`. ### 3.2 Invariantes e regras não óbvias | ID | Regra | Efeito | Fonte | |---|---|---|---| | RN-NOTICIAS-R01 | Rotas CMS passam por `CmsAuthenticate`, que delega ao `V2PermissionMiddleware`. | Sem permissão `Noticias` → `403 Forbidden. Access denied for this module.`; `read` bloqueia POST/PUT/DELETE com `403 Forbidden. Write actions are not allowed for your profile.` | `V2/Core/Middleware/CmsAuthenticate.php:44`; `V2PermissionMiddleware.php:84-127` | | RN-NOTICIAS-R02 | Rotas nacional-only retornam `403` (AJAX/JSON) ou `302` ao dashboard. | Operador regional não vê arquivadas/tags/categorias. | `RegionalRestrictMiddleware.php:34-48` | | RN-NOTICIAS-R03 | `module.active:Noticias` desativado → `404 Modulo desativado.` (HTML) e `404` JSON para AJAX/API; não há redirect ao dashboard. | Módulo desligado some do CMS. | `ModuleAccessMiddleware.php:38-61` | | RN-NOTICIAS-R04 | O `DELETE /{id}` declara `{id}` sem `where`, aceitando qualquer string. | `DELETE /cms/noticias/qualquer` → `404` do `findOrFail`. | `Routes/cms.php:46-49` | | RN-NOTICIAS-R05 | `POST /cms/noticias/categorias` resolve para `categoriesStore`; o nome `.index` não existe. | Chamar `route('v2.noticias.cms.categories.index')` lança exceção. | `Routes/cms.php:111-119`; `Routes/cms.php:111-114` (rota sobrescrita); `RouteCollection.php:65-77,120-129` | | RN-NOTICIAS-R06 | `seo-update` exige `seo.title` (`required|max:255`); os demais campos são opcionais. | `302` com erros de validação quando falta o título. | `NoticiasCmsController.php:647-681` | | RN-NOTICIAS-R07 | `tags.store` exige `name` (`required|max:100`) e responde o model JSON, inclusive em conflito (usa `firstOrCreate`). | Repetir o nome devolve a tag existente com `200`. | `NoticiasCmsController.php:703-719` | | RN-NOTICIAS-R08 | `toggle-highlight` responde JSON e **não** valida existência prévia. | Id inexistente → `404` de `findOrFail`. | `NoticiasCmsController.php:588-607` | | RN-NOTICIAS-R09 | O sitemap não é excluído do `page.cache`. | XML pode ficar 5 min atrás do banco, além das 6 h do cache próprio. | `PageCacheMiddleware.php:16-23,85-91` | | RN-NOTICIAS-R10 | Rotas públicas não têm throttle nem rate limit. | Scraping não é limitado pelo módulo. | `Routes/web.php:10-37` | ### 3.3 Casos-limite 1. **`GET /noticia/{slug}/preview`** → `500` (método inexistente), mesmo com `?token=`. 2. **`GET /noticia/{slug}` de notícia agendada** (`published_at > now()`) → `200`, apesar de não aparecer em `/noticias`. 3. **`POST /cms/noticias/novo` com `status=pending_approval`** → aceito e persistido; a notícia não aparece no portal. 4. **`POST /cms/noticias/categorias` por operador regional** → bloqueado pelo grupo nacional-only (403/redirect), mesmo que o RBAC permita `write` em Notícias. 5. **`GET /cms/noticias/tags` por operador regional** → também bloqueado (rota dentro do subgrupo nacional-only), embora o editor use tags ao criar notícias. 6. **`PUT` sem `_method`** → o formulário precisa de `@method('PUT')`; `POST` na mesma URI também é aceito (`Route::match(['PUT','POST'])`). 7. **Slug com caracteres fora de `[a-z0-9-]`** → nenhuma restrição de rota; o valor chega literal ao `where('slug', ...)`. 8. **`news-sitemap.xml` com `titulo_site` indisponível** → fallback silencioso para `config('app.name')` (`NoticiasSitemapController.php:48-55`). ### 3.4 Armadilhas de reimplementação 1. **Recriar `POST /categorias` duas vezes** achando que ambos os nomes existirão: no Laravel 5.5 o segundo vence e o primeiro nome morre no boot. 2. **Aplicar `PageCacheMiddleware` nas rotas CMS** "por simetria": o CMS precisa ser fresco; o middleware já exclui `cms*`. 3. **Esperar que `/noticias` honre `?categoria=`**: o filtro é client-side; testes do legado apenas conferem que o HTML contém os cartões. 4. **Trocar a ordem dos grupos** (nacional-only antes do CRUD): muda a precedência de `DELETE /{id}` e de `POST /{id}/...`; manter a ordem do arquivo. 5. **Assumir que o `slug` da rota é validado**: não há `where`; URLs com barra não casam, mas qualquer outro caractere chega ao banco. ### 3.5 Divergências documentação × código | Ponto | Afirma | Realidade | |---|---|---| | `NoticiasPortalController.php:150-152` | "Preview de notícia com token de rascunho" | Sem token funcional; 500 por método ausente. | | `Routes/cms.php:106-119` | Rotas de categorias com `index`, `json` e `store` | `POST /categorias` duplicado; `.index` morto. | | `Views/cms/index.blade.php:204` | Link de preview via `getPreviewUrl()` | Método inexistente (guardado por `draft_token`, sempre nulo). | ## 4. Integrabilidade ### 4.1 Superfície pública | Símbolo | Tipo | Assinatura | Precondição | Consumidores | |---|---|---|---|---| | `route('v2.noticias.cms.index')` | nome | — | módulo ativo + permissão | sidebar, redirects | | `route('v2.noticias.cms.create')` | nome | — | idem | sidebar, botão "criar" | | `route('v2.noticias.cms.edit', ['id'=>...])` | nome | — | idem | listagem, redirects de update/restore | | `route('v2.noticias.cms.archived')` | nome | — | nacional | sidebar (submenu) | | `route('v2.noticias.cms.categories')` | nome | — | nacional | sidebar (submenu) | | `route('v2.noticias.cms.preview-iframe', ['id'=>...])` | nome | — | idem | editor (iframe) | | `route('v2.noticias.portal.show', ['slug'=>...])` | nome | — | notícia publicada | `News::getPublicUrl()`, feed, views | | `route('v2.noticias.portal.index')` | nome | — | — | JSON-LD do portal, menus | | `route('v2.noticias.sitemap.news')` | nome | — | — | `robots.txt`/sitemap index (externo) | ### 4.2 Contrato de UI/JS (quando aplicável) - Endpoints AJAX usados pelas telas: `GET /cms/noticias/tags` (lista), `POST /cms/noticias/tags` (`{name}`), `DELETE /cms/noticias/tags/{id}`, `GET /cms/noticias/categorias/json`, `POST /cms/noticias/categorias`, `PUT/POST /cms/noticias/categorias/{id}`, `DELETE /cms/noticias/categorias/{id}`, `POST /cms/noticias/{id}/toggle-highlight`. Todos retornam JSON e exigem o cookie de sessão + token CSRF do grupo `web`. - Formulários de notícia são submissões clássicas (`POST`/`PUT` com redirect), não AJAX. - `preview-iframe` é carregada em `