# Shell Publico, Roteamento e Consumo da API

**Status:** normativo para o baseline desacoplado  
**Ultima revisao:** 2026-06-19

## 1. Objetivo

Definir como o `front-end/` publica a experiencia web indexavel sem depender do runtime do `cms/`, preservando tres invariantes:

- a superficie publica e servida a partir de `front-end/public/`;
- toda navegacao publica depende apenas de `/api/v1`;
- o consumo da API passa por um unico cliente que entende o envelope `data/meta/error`.

## 2. Shell publico

O shell publico e uma SPA leve com server fallback para `index.html`.

### 2.1 Responsabilidades

- montar cabecalho, navegacao principal, area de conteudo e rodape;
- resolver rotas publicas via History API;
- carregar dados globais do site (`/site` e `/menus/primary`);
- atualizar `title`, `description`, canonical e metadados sociais a partir do payload atual;
- exibir estados de `loading`, `empty`, `error` e `not_found` sem expor detalhes internos.

### 2.2 Estrutura de arquivos

```text
front-end/
  config/
    api.config.js
  public/
    index.html
    router.php
    config/
      api.config.js
    assets/
      css/main.css
      js/main.js
```

- `front-end/config/api.config.js` e a unica fonte de verdade para configuracao publica.
- `front-end/public/config/api.config.js` apenas reexporta a configuracao para o shell executado no browser.
- `front-end/public/router.php` existe para dev local com `php -S` e documenta o fallback que a hospedagem final precisa reproduzir.

## 3. Rotas publicas

As rotas canônicas do shell sao:

| Rota | Uso | Fonte primaria |
|---|---|---|
| `/` | home/listagem principal | `GET /api/v1/site`, `GET /api/v1/posts`, `GET /api/v1/menus/primary` |
| `/categoria/{slug}` | listagem filtrada por categoria | `GET /api/v1/categories`, `GET /api/v1/posts?category={slug}` |
| `/tag/{slug}` | listagem filtrada por tag | `GET /api/v1/tags`, `GET /api/v1/posts?tag={slug}` |
| `/post/{slug}` | detalhe de post | `GET /api/v1/posts/{slug}` |
| `/pagina/{slug}` | pagina estatica | `GET /api/v1/pages/{slug}` |

Regras:

- o CMS nao participa da resolucao dessas rotas;
- a navegacao do menu deve apontar para URLs publicas canônicas, nao para paths internos do admin;
- qualquer rota desconhecida entra em `not_found` no shell, com `404` assumido no contexto visual;
- o deploy HTTP precisa reescrever requisicoes sem arquivo fisico para `front-end/public/index.html`.

## 4. Padrao de consumo da API

### 4.1 Cliente unico

Todo acesso HTTP deve passar por um unico cliente JS com estas obrigacoes:

- prefixar requests com `API_CONFIG.baseUrl`;
- aplicar timeout com `AbortController`;
- enviar `X-Public-Key` apenas quando `API_CONFIG.publicKey` existir;
- validar o envelope `data/meta/error`;
- normalizar erros de transporte, timeout e contrato em uma mesma hierarquia de excecoes.

### 4.2 Repositorio do shell

O shell nao deve montar URLs soltas em componentes. O padrao e expor metodos explicitos:

- `getSite()`
- `getPrimaryMenu()`
- `getPosts(filters)`
- `getPostBySlug(slug)`
- `getPageBySlug(slug)`
- `getCategories()`
- `getTags()`

Beneficios:

- desacopla a interface do formato bruto de query string;
- concentra compatibilidade com `/api/v1`;
- reduz breaking change acidental em componentes de tela.

### 4.3 Sanitizacao e renderizacao

- HTML vindo de `content` continua nao confiavel ate passar por sanitizacao.
- O shell pode renderizar um subconjunto seguro de tags sem permitir `script`, `style`, handlers inline ou URLs `javascript:`.
- Campos textuais simples (`title`, `excerpt`, `name`) devem usar `textContent`, nunca HTML.

## 5. Regras de SEO e navegacao

- o shell atualiza `document.title`, `<meta name="description">`, canonical e metadados `og:*`/`twitter:*` a cada transicao de rota;
- fallback sem SEO especifico usa `site.seo.default_title`, `site.seo.default_description` e `site.url`;
- links internos navegam via router; links externos ou com `target` diferente de `_self` usam comportamento nativo;
- o shell precisa suportar acesso direto por URL, refresh e navegacao por `back/forward`.

## 6. Estados obrigatorios por tela

Cada rota publica deve prever:

- `loading`: placeholder visivel durante fetch;
- `empty`: ausencia legitima de conteudo sem erro;
- `error`: falha de rede, timeout ou contrato;
- `not_found`: slug inexistente ou recurso nao publicado.

Esses estados sao parte do baseline. Nao sao melhorias futuras.

## 7. Verificacao minima

Para considerar esta definicao atendida, o baseline precisa provar:

1. `front-end/public/index.html` sobe sozinho como shell publico;
2. o fallback local via `router.php` funciona para rotas como `/post/...`;
3. a home carrega `site`, `menu` e `posts` via `/api/v1`;
4. as rotas de categoria, tag, post e pagina usam apenas o cliente centralizado;
5. o shell trata `loading`, `error` e `not_found` sem quebrar a navegacao.