# Padrão de Relatórios Hard Court — Norma Editorial v1

> **Status:** norma ativa · criada em 15/04/2026
>
> **Origem:** derivada da LEI FUNDAMENTAL declarada pelo JP em 15/04/2026 (ver `feedback_lei_fundamental_publicacao.md` no memory) e da pesquisa em `docs/PADROES_INSTITUCIONAIS_REFERENCIA.md` (IBGE, BACEN, EIA, Itaú Research).
>
> **Propósito:** documento operacional que define o MÍNIMO ACEITÁVEL para qualquer publicação pública ou privada do Hard Court Brasil. Meta: jornalistas citem o HC, acadêmicos extraiam ciência da base, marcas/federações confiem pra decisão.
>
> **Regra de uso:** leitura OBRIGATÓRIA antes de qualquer agente (humano ou IA) produzir texto com dado. Conflito entre esta norma e qualquer outro arquivo → este doc prevalece.

---

## 0. Lei Fundamental (recap)

> "As pessoas precisam ver as nossas informações e confiar nelas. Precisamos ser referência e guia de planejamento. Jornalistas devem olhar pro nosso banco e ter uma referência confiável para suas publicações. Acadêmicos precisam olhar para a nossa base e tentar extrair ciência dela. Não podemos permitir que sejamos menos que isso." — JP, 15/04/2026

**Referências-padrão mínimo aceitável:** IBGE · BACEN · EIA · Rystad · PSR · Infosys · BTG Pactual · Itaú.

**Mistura de estilo adotada pelo HC:** esqueleto BACEN/EIA (rigor visível) + camada Itaú (orientação à decisão) + disciplina de revisão IBGE (nota técnica datada por mudança).

---

## 1. Checklist do mínimo aceitável (todo output tem que ter)

Todo relatório, página, email, post, card ou documento **público ou B2B** do HC deve ter os 8 elementos abaixo. A ausência de qualquer um é motivo de bloqueio de publicação.

| # | Elemento | Onde | Obrigatório |
|---|---|---|---|
| 1 | **Ficha técnica** | Footer canônico ou topo da página | ✅ Sempre |
| 2 | **Recorte temporal** explícito | Próximo a cada número/tabela | ✅ Sempre |
| 3 | **Universo declarado** | Próximo a cada número de coorte | ✅ Sempre |
| 4 | **Comparáveis** (média, topo, posição) | Ao lado de toda afirmação de "melhoria/gap" | ✅ Sempre que houver julgamento |
| 5 | **Fonte dos dados** | Rodapé das tabelas + footer | ✅ Sempre |
| 6 | **Nota de revisão** | Topo do relatório quando houver mudança | ✅ Quando aplicável |
| 7 | **Glossário / siglas expandidas** | Primeira ocorrência de cada seção | ✅ Sempre |
| 8 | **Tratamento de incerteza** | Junto a qualquer projeção/benchmark | ✅ Sempre que projetar |

---

## 2. Posicionamento da ficha técnica — padrão institucional

**Onde a ficha técnica fica:** ao FINAL do relatório, antes do rodapé institucional. Padrão observado em IBGE, BACEN, EIA, Itaú — todos expõem metodologia/anexo/glossário/disclaimer no **final** do documento. Topo fica reservado apenas para edição + data curtas (1-2 linhas) integradas à capa.

**Não usar:**
- Ficha técnica em `<details>` no topo — intrusivo, redundante com capa
- Bloco expandido logo após o hero — pesa visualmente e duplica o footer

**Usar:**
- Capa: edição, série e data (texto curto, integrado ao design)
- Corpo: texto analítico limpo, tabelas com notas de rodapé inline quando necessário
- **Final (antes do rodapé institucional):** bloco "Ficha Técnica" completa com todos os campos obrigatórios
- Rodapé institucional: marca + linha de identificação da edição

**Quem quer auditar rola até o fim** — é o comportamento esperado de leitor de relatório de dados, replicado em todas as 4 referências.

---

## 3. Footer canônico — template pronto pra uso

Este bloco deve aparecer no FINAL de **toda página pública** do HC (antes do rodapé institucional). Copiar e adaptar pelos placeholders:

```html
<footer class="hc-ficha-tecnica">
  <div class="ficha-linha-1">
    <strong>Hard Court Brasil — Inteligência de Tênis</strong>
    <span class="edicao">Edição: HC-{{PRODUTO}} v{{VERSAO}} — {{DATA_EDICAO_ISO}}</span>
  </div>
  <div class="ficha-linha-2">
    Dados até: <strong>{{DATA_CORTE_BR}} {{HORA}} BRT</strong>
    · Próxima atualização prevista: {{PROXIMA_ATUALIZACAO_BR}}
  </div>
  <div class="ficha-linha-3">
    Fonte: base HC (Tenis Integrado + CBT + ITF)
    · N={{TAMANHO_AMOSTRA}}
    · Escopo: {{ESCOPO}}
  </div>
  <div class="ficha-linha-4">
    Correções: <a href="mailto:hardcourtbrasil@gmail.com">hardcourtbrasil@gmail.com</a>
    · Metodologia: <a href="/docs/notas">/docs/notas</a>
  </div>
</footer>
```

**Exemplo preenchido** (Panorama RJ 2026):
```
Hard Court Brasil — Inteligência de Tênis
Edição: HC-Panorama-RJ v1.2 — 2026-04-15
Dados até: 15/04/2026 12:00 BRT · Próxima atualização prevista: 15/05/2026
Fonte: base HC (Tenis Integrado + CBT + ITF) · N=223 atletas ativos · Escopo: estadual RJ
Correções: hardcourtbrasil@gmail.com · Metodologia: /docs/notas/2026-04-15-panorama-estadual.md
```

---

## 3. Regras por tipo de output

### 3.1. Raio X do Atleta (Premium individual)

**Ficha técnica obrigatória no rodapé:**
- Edição: `HC-RaioX v{N.M} — {AAAA-MM-DD}`
- Data de corte: última sync com TI (DD/MM/AAAA HH:MM)
- Universo do atleta: "Partidas oficiais de simples do atleta {NOME} na base TI, com fase identificada, excluídas duplas e WOs quando indicado. N={X} partidas entre {DATA_INICIO} e {DATA_CORTE}."
- Coortes de comparação: "Comparáveis: {N} atletas com mesma faixa etária, mesmo UF e categoria ativa em 2026."

**Tratamento de revisão:** se uma edição anterior do Raio X deste atleta existir e um número mudou (ex: Score, WR, ranking), incluir bloco "Revisão desta edição" no topo: "Campo X: de A (ed. anterior) para B (esta ed.), motivo: {novos dados de Y partidas}."

**Boxes metodológicos numerados:** referenciar em `/docs/notas/` cada métrica crítica (Score, SoS, VPL, Similar Players). Ex: `2026-04-15-metodologia-score.md`.

### 3.2. Panorama Estadual / Clube (B2B)

**Capa obrigatória** (padrão BACEN RPM):
- Volume/Número/Data
- Autoria
- Data de corte explícita
- ISSN-like (identificador permanente)

**Seção 01 — Resumo executivo:**
- Máximo 5 bullets
- Cada bullet com número + comparável (média BR / topo / posição)
- Zero adjetivo sem base ("6º maior mercado" sim, "grande mercado" não)

**Cada número de "ponto de melhoria"** precisa trazer:
- Valor do alvo (RJ, Pinheiros, etc.)
- Média da base relevante (BR, média de clubes equivalentes)
- Topo (quem lidera e com quanto)
- Posição (Xº de N)

**Seção final obrigatória — Metodologia e fontes:**
- Universo da pesquisa
- Período de referência
- Método de cálculo por métrica
- Limitações declaradas
- Link para nota metodológica detalhada em `/docs/notas/`

### 3.3. Raio X do Tênis Brasileiro (macro público)

**Acima do hero:** badge com "Dados exclusivos · {MÊS/AAAA}" e "Base {ANO_INICIO}–{ANO_ATUAL} · Fonte primária: {FONTE}".

**Por KPI:**
- Valor
- Recorte temporal (YTD, histórico acumulado, parcial)
- Universo
- Comparação quando possível (ex: "1 em cada 13 atletas IJ do país")

**Funil numérico (47k→29k→741):** cada etapa com definição explícita do filtro.

### 3.4. Radar (Rede HC)

**Por atleta listado:**
- Consentimento parental ativo (flag verificado no banco)
- Nome, cidade, faixa etária, clube creditado
- Status: "Ativo {ANO}" com data do último jogo
- Link pra Raio X completo (gated)

**Rodapé do Radar público:** ficha técnica + declaração LGPD + link de revogação.

### 3.5. Similar Players (dentro do Raio X Premium)

**Cada espelho (Similar Player):**
- Nome anonimizado (se menor) ou nome (se consent ativo)
- Faixa etária + UF
- Trajetória: X → Y → Z (com datas)
- Desfecho real (college / pro / ativo / parou)
- **Similaridade declarada:** "Match por idade±1, WR dentro de ±5pp, mesmo UF"

**Tratamento de incerteza:**
- N da coorte de candidatos
- Quando N < 10: aviso visível "Amostra pequena, confiança baixa"
- Nunca projetar pontualmente — sempre faixa

### 3.6. Emails / Newsletters / Push

**Assunto:** `HC · {Produto} · {Data}`

**Corpo:**
- Abrir com **data de referência**
- Cada número citado com fonte inline (ex: "{N} partidas · dados até {DATA}")
- CTA com link que leva pra relatório público com footer canônico completo
- Rodapé do email: link de descadastro + política de privacidade

### 3.7. Cards compartilháveis (PNG/story)

- Marca d'água "Hard Court Brasil" + data da edição
- QR code ou URL curto apontando pra relatório full
- Disclaimer mínimo: "Dado de base {DATA}. Contexto completo no relatório."

---

## 4. Processo obrigatório antes de publicar qualquer dado novo

Sequência inviolável:

1. **Rodar a query SQL** do dado sobre a base atual
2. **Declarar explicitamente** no código/doc:
   - Universo (WHERE clauses)
   - Janela temporal (período)
   - Método (contagem, média, distinct, etc.)
   - Fonte (tabela canônica — ver `TABELAS_CANONICAS.md`)
3. **Rodar query de benchmark** — mesma métrica pra base comparável (todas UFs, todos clubes equivalentes, coorte de atletas similares)
4. **Calcular posição relativa** do alvo (Xº de N, percentil)
5. **Escrever texto começando pelo contexto**, só depois o número do alvo
6. **Incluir ficha técnica** (footer canônico ou box)
7. **Se houver revisão** de dado anterior — incluir nota explicativa no topo
8. **Glossário:** verificar se todos os termos técnicos têm definição canônica em `GLOSSARIO_HC.md`
9. **Rodar `hc_auditor.py`** antes de commit

---

## 5. Regra do t0 (lançamento oficial) — inviolável

**Princípio:** o histórico de revisões e o bloco "Revisão desta edição" **só existem pro público a partir do lançamento oficial**. Iterações pré-lançamento (cozinha interna: versões de staging, correções descobertas durante auditoria própria, ajustes editoriais antes da estreia) **NÃO viram entradas públicas de revisão**.

**Por quê:**
- Toda produção até o t0 é construção, não revisão. Registrar "corrigimos o que descobrimos que estava errado antes de publicar" é ruído — passa a impressão de instabilidade em vez de rigor.
- A credibilidade institucional se constrói a partir da **primeira publicação estável**. Essa é a v1.0, ponto de partida citável.
- A partir de v1.0 pública, TODA correção vira entrada pública de revisão (regra do §6 abaixo).

**Operação:**
- **Antes de t0:** correções de cozinha são registradas apenas no `DIARIO_PROJETO.md` e no `PENDENCIAS_ATIVAS.md`. **Não** aparecem em `/docs/notas/` nem em bloco "Revisão" na página pública.
- **No t0:** toda página nasce em **v1.0** com nota metodológica `/docs/notas/AAAA-MM-DD-<slug>.md` descrevendo a versão de lançamento. Histórico da nota começa em: "AAAA-MM-DD (v1.0): versão de lançamento."
- **Pós-t0:** qualquer alteração de dado ou narrativa vira entrada nova no histórico da nota metodológica **e** bloco "Revisão desta edição" no topo do relatório público.

**Quando é t0:** o momento exato do lançamento oficial do produto/página para público externo (marca, clube, federação, jornalista, pai). Antes disso, HC está em construção — o rigor de documentação interna (diário, pendências) é alto, mas a cronologia pública de revisão começa no dia 1.

---

## 6. Regras de revisão pós-t0 (nunca revisar silenciosamente)

### Quando:
- Número muda entre edições (novo dado, correção)
- Metodologia muda (novo cálculo, novo filtro)
- Universo muda (fonte adicional, exclusão de outlier)

### Como:
- **Nota técnica datada** em `/docs/notas/AAAA-MM-DD-<slug>.md` **antes** da edição afetada ir ao ar
- **Bloco "Revisão" no topo** do relatório: "Nesta edição, o campo X foi atualizado de A (ed. anterior) para B. Motivo: {explicação}. Detalhes: {link pra nota}."
- **Coluna "Anterior × Atual"** em tabelas quando a revisão afetar projeções (padrão Itaú)
- **Se afetar jornalistas/parceiros** que já citaram a edição anterior: comunicação direta por email/WhatsApp

### Quando pode NÃO divulgar:
- **Correção de erro tipográfico ou formatação** (não afeta dado)
- **Enriquecimento de contexto** sem mudar números (adicionar mais bullets)

---

## 6. Padrão de nota metodológica — estrutura de `/docs/notas/`

Todo box metodológico numerado deve viver como markdown citável em `/docs/notas/`. Estrutura:

```markdown
# Nota Metodológica — {TÍTULO}

**Slug:** AAAA-MM-DD-{tema}
**Data:** AAAA-MM-DD
**Produto afetado:** HC-{Produto}
**Versão:** v{N.M}
**Autor:** Hard Court Brasil
**Substitui:** {slug da nota anterior se houver}

## Resumo
{1 parágrafo descrevendo a métrica/mudança}

## Definição
{definição formal, sem ambiguidade}

## Método de cálculo
```sql
-- Query canônica
```

## Universo
{quem entra, quem fica de fora}

## Janela temporal
{período de referência}

## Fonte primária
{tabela canônica + origem externa}

## Limitações conhecidas
- Limitação 1
- Limitação 2

## Histórico de revisões
- AAAA-MM-DD: primeira versão
- AAAA-MM-DD: revisão (motivo)

## Referências
{links, papers, outras notas HC}
```

---

## 7. Regras de notação (aplicáveis a todo output)

### Datas
- **Metadados / APIs / filenames:** ISO `AAAA-MM-DD` (ex: `2026-04-15`)
- **Texto corrido:** BR `DD/MM/AAAA` (ex: `15/04/2026`)
- **Timestamps:** sempre declarar fuso `BRT` (UTC-3). Nunca usar UTC no produto público

### Números
- **Formato BR:** ponto milhar, vírgula decimal (ex: `461.003`, `25,6%`)
- **Em código:** `toLocaleString('pt-BR')` ou equivalente no Python
- **Em texto curto (cards, tweets):** pode usar "k" ou "mil" (ex: `461k`, `60 mil`) — mas com dado exato acessível no link de detalhes

### Percentuais
- **Números grandes (>10%):** 1 decimal (ex: `25,6%`, `69,4%`)
- **Números pequenos (<10%):** 1 decimal ou 2 decimais (ex: `0,28%`, `1,55%`) — consistência dentro do mesmo relatório
- **Variação:** com sinal explícito (ex: `+22%`, `-3,5p.p.`)
- **p.p.** (pontos percentuais) quando for diferença entre percentuais; **%** quando for razão

### Moeda
- **Real:** `R$ 235,00` (símbolo + espaço + valor BR)
- **Dólar:** `US$ 1,5 milhão` ou `$1.5M` (explicitar referência)
- **Valores históricos:** sempre declarar data-base (ex: `R$ 297 (base: abril/2026)`)

### Unidades
- **Explicitar sempre:** km, partidas, atletas, meses, R$, WTN
- **Evitar abreviações ambíguas:** "12m" pode ser 12 meses ou 12 milhões; sempre desambiguar

### Siglas
- **Expandir na primeira ocorrência** de cada seção
- **Lista canônica:** `GLOSSARIO_HC.md`
- **Exemplos:** WTN (World Tennis Number), UTR (Universal Tennis Rating), WR (Win Rate), SoS (Strength of Schedule), CBT (Confederação Brasileira de Tênis), FTERJ (Federação de Tênis do Estado do Rio de Janeiro)

---

## 8. Regras de tratamento de incerteza

Toda projeção, predição ou benchmark comparativo deve declarar:

### N (tamanho da amostra)
- Ex: "Comparáveis: N=247 atletas com idade ±1, WR dentro de ±5pp, mesmo UF."
- Se N < 10: aviso visível "Amostra pequena, confiança baixa — use com cautela."
- Se N < 30: aviso "Amostra moderada — resultados indicativos, não conclusivos."

### Faixa (não-pontual)
- Quando possível, dar faixa: "WR esperado dos 14 aos 16 anos: 45%–62% (mediana 54%)."
- Para Similar Players: dar os 3 desfechos possíveis com N de cada

### Limitação qualitativa
- "Não substitui avaliação técnica de treinador"
- "Modelo assume continuidade do padrão histórico"
- "Base de atletas do circuito CBT — comportamento de atletas de fora do circuito pode diferir"

### Fan chart (aspiracional, quando N permitir)
- Intervalos de 10%, 30%, 50%, 70%, 90% em torno da projeção central (padrão BACEN)
- Aplicável quando houver ≥100 observações com variância mensurável

---

## 9. Glossário obrigatório (pointer)

Todo termo técnico do HC tem definição canônica em **`docs/GLOSSARIO_HC.md`** (a criar). Regras:

- Cada termo tem definição única, não-ambígua
- Siglas expandidas na primeira ocorrência
- Quando o termo for usado no relatório, linkar quando possível: `[WTN](/docs/GLOSSARIO_HC.md#wtn)`
- Se o glossário tiver 2 definições conflitantes em locais diferentes do projeto, é BUG — resolver antes de publicar

Termos-chave que DEVEM estar no glossário:
- WTN, UTR, WR, WR Lifetime vs WR 2026
- SoS (Strength of Schedule)
- Score HC
- Gap Analysis
- VPL / VPL Sunk Cost
- Hit Rate
- Fase (Final, Semi, Quartas, Rodada)
- Similar Players / Similar Players Live
- Radar / Rede HC
- Atleta Ativo (e variantes: Kids ativo, Juvenil ativo, Premium)
- Torneio Programado vs Realizado vs Finalizado
- Categoria (Kids, Sub-12, Sub-14, Sub-16, Sub-18, etc.)
- Benchmark NCAA (D1, D2, D3, NAIA)

---

## 10. Exemplo prático — antes × depois

### ANTES (violação da norma)
> "Com apenas 5 torneios em 2026, o RJ precisa dobrar o calendário pra crescer."

**Problemas:**
- ❌ "Apenas 5" sem comparação (falso: é o 2º maior do BR)
- ❌ Recorte temporal ambíguo (é até hoje? programados? realizados?)
- ❌ Universo não declarado
- ❌ Afirmação de "precisa dobrar" sem base
- ❌ Zero benchmark

### DEPOIS (aderente à norma)
> "O RJ tem **18 torneios programados em 2026** (2º maior calendário do país, atrás só de SP com 20 — média BR: 5 torneios/UF), dos quais **5 já foram realizados até 15/04/2026**. O ritmo de execução está alinhado à capacidade histórica.
>
> O gap real do RJ, medido contra a média BR e o topo, não está no número de torneios (competitivo), mas em:
> - **Base ativa:** 223 atletas ativos (6º BR, abaixo da média de 255; SP tem 1.492).
> - **Densidade:** 2,24 partidas/atleta (6º, ACIMA da média 2,03; topo PA com 3,15).
> - **Participação feminina:** 25,6% (**17º de 18 UFs**; média BR 29,6%; topo MS com 37%)."

**Aderência:**
- ✅ Valor do alvo + média + topo + posição em cada afirmação
- ✅ Recorte temporal ancorado (programados vs realizados, data explícita)
- ✅ Universo (UFs com dados)
- ✅ Contextualização da afirmação antes do número
- ✅ Zero adjetivo sem base

---

## 11. Consequências da não-aderência

1. **Bloqueio de deploy** — `hc_auditor.py` flagará output sem ficha técnica, sem benchmark, sem universo declarado.
2. **Revisão editorial** — toda produção passa por checklist antes de ir ao ar.
3. **Custo reputacional** — jornalista/acadêmico que pegar um número furado nunca mais cita. Perda permanente.
4. **Custo comercial** — marca/federação que desconfiar do dado cancela contrato/não fecha.

---

## 12. Aplicação e retrofit

### Produção NOVA
Esta norma vale imediatamente. Qualquer output produzido daqui em diante — Raio X, Panorama, Radar, Similar Players, email, card, post — deve aderir integralmente.

### Retrofit das páginas existentes
Cronograma sugerido (ordem de prioridade = risco reputacional):
1. **Panoramas** (B2B — clube/marca/federação pagam esperando rigor institucional): RJ, SP, Pinheiros
2. **Raio X do Tênis Brasileiro** (macro público de autoridade)
3. **Raio X do Atleta** (template + 3 Premium existentes)
4. **Radar** (landing + 156 perfis de treinador)
5. **Vitrine** (B2B)
6. **Páginas institucionais** (sobre, guia, planos)

Cada retrofit vira entry no `DIARIO_PROJETO.md` com snapshot antes/depois.

### Auditor
`hc_auditor.py` deve ser estendido (Sprint 5) pra checar presença de:
- Footer canônico completo (regex dos 4 campos obrigatórios)
- Nota metodológica linkada
- Número sem contexto (heurística: número grande isolado sem "média", "topo", "% de", "Xº de")

---

## 13. Próximas versões desta norma

**v1.1 (planejado):** após pesquisa das 4 instituições restantes (Rystad, PSR, Infosys, BTG), incorporar padrões específicos que essas instituições trazem.

**v2 (futuro):** auditoria visual automática (screenshots desktop/mobile + diff entre páginas).

**v3 (visão):** certificação externa — se algum dia jornalista acadêmico de peso aceitar revisar a norma HC, publicar como "padrão aberto" citável por outros produtos de dados de esporte no BR.

---

## Glossário desta norma

- **Ficha técnica:** bloco estruturado com edição, data, autoria, fonte, universo, contato.
- **Footer canônico:** template HTML padronizado pro rodapé de toda página pública.
- **Nota metodológica:** documento em `/docs/notas/{slug}.md` descrevendo formalmente uma métrica.
- **Revisão silenciosa:** alterar número sem anunciar — PROIBIDO.
- **Box metodológico:** seção dentro de um relatório com metodologia específica (padrão BACEN RPM).
- **Retrofit:** aplicar esta norma em páginas que já existiam antes dela.

---

**Última atualização:** 2026-04-15
**Próxima revisão:** após v1.1 da pesquisa institucional + 1ª aplicação prática em Panorama retrofit.