---
id: SVC-<NOME>
tipo: servico
onda: <1|2>
status: pendente
unidades: [SVC-<NOME>]
fontes:
  - V2/Services/<Nome>/
depende_de: []
consumidores: []
criticidade: <alta|media|baixa>
dono:
---

# Serviço <Nome>

> Guia: substituir todo texto entre `>` por conteúdo citado. Não manter marcadores.
> Serviços de UI (`CONTENTRICHEDITOR`, `LANDINGSECTIONSEDITOR`, `GALLERY`, `MEDIA`,
> `SEO`, `SEARCH`, `EXCELIMPORTER`) têm também `ui-contrato.md`; este arquivo cobre o
> núcleo lógico e a integração.

## 0. Ficha de identidade

| Campo | Valor |
|---|---|
| Efeito primário | |
| Entrada | |
| Saída | |
| Efeitos colaterais | |
| Particularidade central | |
| Como se integra | |
| Se removido, quebra | |
| Superfície pública | classes, métodos, componentes, rotas |

## 1. Efeito

### 1.1 Transformação que o serviço realiza
> Entrada concreta → saída concreta (ex.: "recebe upload → grava original, gera
> variantes, registra metadados e devolve `GalleryMedia`"). Sem rótulos vagos.

### 1.2 Efeitos sobre dados e sistema
| Efeito | Recurso afetado | Ponto no código | Fonte |
|---|---|---|---|
> Inclui tabelas, disco/S3, cache, índice de busca, e-mail, logs, eventos.

### 1.3 Contrato observável
> Assinaturas públicas com tipos, retornos, exceções e estados inválidos.

### 1.4 O que o serviço deliberadamente NÃO faz
> Ex.: "não autoriza", "não grava se o disco falhar", "não envia e-mail".

## 2. Abordagem

### 2.1 Estratégia e por quê
> Padrão adotado (strategy, registry, repository, DTO, adapter), motivação observável.

### 2.2 Mecânica passo a passo
> Fluxo interno com classes/métodos reais.

### 2.3 Trechos de código pivô
```php
// V2/Services/.../Arquivo.php:10-24 — o que mostra
```
> Explicação do mecanismo e do efeito.

### 2.4 Algoritmos e custos
> Complexidade, consultas, I/O, concorrência, cache, limites.

## 3. Particularidades

### 3.1 O que é exclusivo deste serviço
> O conceito que ele é dono (ex.: "única implementação de assinatura visual", "única
> fonte de índice público"). Comparar com serviços/módulos semelhantes.

### 3.2 Invariantes e regras não óbvias
| ID | Regra | Efeito | Fonte |
|---|---|---|---|

### 3.3 Casos-limite
> Arquivo inválido, certificado expirado, storage indisponível, índice ausente, etc.

### 3.4 Armadilhas de reimplementação
> Ordem de chamada, dependência circular, estado global, timezone/locale, permissões.

### 3.5 Dívidas e divergências

## 4. Integrabilidade

### 4.1 API pública
| Símbolo | Assinatura | Retorno | Exceções | Consumidores |
|---|---|---|---|---|

### 4.2 Componentes Blade e contrato de UI
> Nome do componente, namespace, props, slots, variáveis obrigatórias, classes CSS,
> atributos `data-*`, IDs de DOM, eventos emitidos, eventos escutados.

### 4.3 JS e ciclo de vida
> Arquivo, função de init, eventos, storage, teardown, dependências (jQuery, Tiptap,
> Cropper), comportamento sem JS.

### 4.4 Ordem de inicialização e registro
> Provider, rotas, views, migrations, comandos; o que precisa existir antes.

### 4.5 Receitas de uso
> 2–5 exemplos canônicos (PHP, Blade, HTTP) com resultado esperado.

### 4.6 Anti-uso
> O que não fazer e o efeito da violação.

### 4.7 Custos e limites
> Quotas, throttling, tamanho, performance, cache.

## 5. Rotas e endpoints

| Método | URI | Nome | Middleware | Controller@ação | Permissão | Efeito | Fonte |
|---|---|---|---|---|---|---|---|

## 6. Dados e migrations

> Tabelas próprias, colunas, índices, FKs, soft delete, UUID, modelos, quem escreve.

## 7. Configuração e permissões

> Chaves de config/env, defaults, efeito; permissões e middleware; flags.

## 8. Observabilidade e erros

> Logs, auditoria, exceções, códigos HTTP, mensagens exatas, fail-open/closed.

## 9. Consumidores (mapa de integração)

| Consumidor | O que usa | Como usa | Risco de quebra |
|---|---|---|---|

## 10. Lacunas

## 11. Checklist de paridade

- [ ] `PC-...-01` — ...

## 12. Evidências consultadas