# Modelo operacional de SEO por site e por pagina

## Objetivo

Definir como o CMS deve expor configuracoes editoriais de SEO em tres niveis complementares:

- site: identidade, defaults e politicas compartilhadas por todas as rotas publicas de um destino;
- destino: regras reutilizaveis por tipo de pagina, secao ou template publico;
- pagina: override pontual para cada pagina, post ou taxonomia publicada.

O objetivo nao e dar liberdade total em cada campo. O objetivo e manter consistencia editorial, reduzir configuracao repetida e garantir que o frontend sempre receba um payload final de SEO coerente.

## Principios operacionais

- Heranca primeiro: cada pagina deve nascer pronta a partir de defaults do site e do destino.
- Override explicito: o editor so altera campos locais quando precisa fugir da regra.
- Payload final unico: API e frontend nao devem reconstruir regra de negocio; devem receber a versao efetiva do SEO da rota.
- Multi-site nativo: cada site possui configuracoes, ownership e fallback proprios.
- Guardrails editoriais: limites de caracteres, presets de robots e previas reduzem erro manual.

## Hierarquia de decisao

### 1. SEO por site

Configuracoes mantidas em `Configuracoes > SEO` para cada site.

Responsabilidades:

- definir `site_name`, `default_title`, `title_separator` e `default_description`;
- definir `default_og_image` e handles sociais globais;
- definir politica padrao de indexacao do site publico;
- definir `canonical_base_url` do destino;
- definir se sitemap, robots publicos e metadados sociais estao habilitados por padrao.

Campos minimos:

| Campo | Uso |
|---|---|
| `default_title` | Base do titulo quando a pagina nao sobrescreve |
| `title_separator` | Separador entre titulo local e marca do site |
| `default_description` | Fallback de descricao |
| `canonical_base_url` | Base para canonicals absolutos |
| `default_robots` | Preset inicial, ex. `index,follow,max-image-preview:large` |
| `default_og_image_id` | Imagem social padrao |
| `social.twitter` | Handle para `twitter:site` |
| `social.facebook` | URL institucional usada em compartilhamento |

### 2. SEO por destino

Destino e a camada intermediaria entre o site e a pagina individual. Ela evita reconfigurar o mesmo comportamento em toda rota equivalente.

Destinos esperados nesta fase:

- home;
- pagina estatica;
- post;
- categoria;
- tag;
- listagem paginada;
- pagina 404;
- paginas especiais futuras, como busca e autor.

Cada destino deve permitir:

- padrao de titulo com placeholders, ex. `{page_title} | {site_name}`;
- padrao de description quando houver resumo, ex. `{excerpt}`;
- preset de robots;
- canonical strategy, ex. self-canonical, canonical do primeiro item ou sem override;
- imagem social padrao do destino;
- ligacao com schema futuro, sem obrigar configuracao agora.

Regra de UX: o editor escolhe o destino da pagina apenas quando ele nao puder ser inferido automaticamente pelo tipo de conteudo.

### 3. SEO por pagina

Configuracoes disponiveis na tela de edicao de pagina, post ou taxonomia, em um painel lateral ou secao dedicada de SEO.

Cada campo local deve ter dois estados:

- `inherit`: usa o valor efetivo vindo do destino/site;
- `custom`: habilita valor proprio daquela pagina.

Campos locais minimos:

| Campo | Comportamento |
|---|---|
| `seo_title` | Override do titulo final |
| `seo_description` | Override da meta description |
| `canonical_url` | Override manual do canonical |
| `robots_mode` | `inherit` ou preset local |
| `og_title` | Opcional; default e o titulo efetivo |
| `og_description` | Opcional; default e a description efetiva |
| `og_image_id` | Override da imagem social |
| `exclude_from_sitemap` | Ajuste pontual, normalmente herdado |

Nao expor campos livres para tudo. `robots` deve ser selecionado por preset, nao por texto arbitrario.

Presets minimos de robots:

- `index_follow`
- `noindex_follow`
- `noindex_nofollow`

## Resolucao final do payload

Toda rota publica deve produzir um objeto `seo` ja resolvido pela ordem:

1. override da pagina, quando existir;
2. configuracao do destino;
3. fallback global do site.

O frontend consome apenas o resultado final. A API administrativa pode expor metadados de heranca, mas a API publica deve priorizar simplicidade.

Estrutura alvo do payload publico:

```json
{
  "seo": {
    "title": "Titulo resolvido",
    "description": "Descricao resolvida",
    "canonical": "https://site.com/rota",
    "robots": "index,follow,max-image-preview:large",
    "og": {
      "title": "Titulo de compartilhamento",
      "description": "Descricao de compartilhamento",
      "image": {
        "id": 10,
        "url": "/uploads/og.jpg",
        "alt": "Imagem de compartilhamento"
      }
    },
    "twitter": {
      "card": "summary_large_image",
      "site": "@handle"
    }
  }
}
```

## Regras de consistencia editorial

- Se `seo_title` estiver vazio em modo `custom`, a publicacao deve falhar com erro inline.
- `canonical_url` manual precisa ser URL absoluta e do mesmo site, salvo override explicitamente permitido para consolidacao.
- `noindex` deve sugerir automaticamente `exclude_from_sitemap`.
- Paginacao publica nao deve reutilizar o mesmo canonical da pagina 1 por acidente; a estrategia precisa ser definida no destino.
- Quando a pagina usar imagem social local, o CMS deve exigir `alt` do asset ou herdar o melhor texto alternativo disponivel.

## Modelo de interface no CMS

### Configuracao por site

- Uma tela por site, com cards claros para identidade, indexacao e compartilhamento.
- Campos raros ficam em secoes colapsaveis; defaults criticos ficam visiveis sem scroll longo.

### Configuracao por destino

- Tabela simples com um registro por destino e acao de editar.
- Preview textual do pattern de titulo e do preset de robots antes de entrar no detalhe.

### Edicao por pagina

- Painel de SEO com preview de snippet e compartilhamento social.
- Cada campo mostra o valor herdado antes do override.
- Contadores e alertas devem orientar, mas nao bloquear arbitrariamente quando a decisao editorial for valida.

## Multi-site e governanca

- Cada site possui configuracao global propria e nao compartilha defaults implicitamente.
- O modulo de SEO deve respeitar o contexto do site atual em toda listagem, edicao e fallback.
- Usuarios com escopo editorial de um site podem sobrescrever pagina; configuracao global por site deve exigir permissao mais alta.

## Impacto esperado em API e frontend

- `GET /api/v1/site` continua retornando defaults globais do site.
- `GET /api/v1/posts/{slug}` e `GET /api/v1/pages/{slug}` devem retornar o `seo` efetivo da rota, nao apenas os campos crus preenchidos pelo editor.
- Rotas de taxonomia e listagem devem seguir o mesmo contrato final quando forem implementadas.
- O frontend deve sobrescrever placeholders estaticos com o payload resolvido e nao inventar fallback proprio alem do HTML baseline.

## Fora de escopo desta decisao

- geracao automatica de schema.org detalhado;
- experimentos de IA para sugestao de titulos e descricoes;
- automacoes de auditoria e relatarios de performance;
- internacionalizacao/locale por pagina, que pode adicionar outra camada de heranca depois.