spec

name	Spec
description	Fase 2 - Specification Protocol. Le PRD.md, aplica S.D.A completo (mapeia TODAS dependencias), define mudancas cirurgicas linha por linha e gera Spec.md. Preserva logica existente, mudancas minimas focadas.

FASE 2: SPECIFICATION (SURGICAL PLANNING)

Objetivo

Transformar PRD em especificacao tecnica precisa com mudancas cirurgicas linha por linha.

---

INPUT OBRIGATORIO

Carregar PRD

# Localizar PRD gerado na Fase 1
ls -la .claude/docs/PRD-*.md

# Ler PRD completo
cat .claude/docs/PRD-[nome-tarefa].md

---

PROTOCOLO S.D.A COMPLETO

FASE 1: SOLICITACAO (Arquivos Originais)

1.1 Solicitar Todos os Arquivos do PRD

# Para cada arquivo listado no PRD, solicitar COMPLETO
# (Nunca trabalhar com snippets)

# Exemplo do PRD:
# "Arquivos a modificar: controllers/extratoController.js"

cat controllers/extratoController.js  # VER TUDO

1.2 Analisar Linha por Linha

• Identificar funcoes principais
• Mapear variaveis usadas
• Entender fluxo de dados
• Detectar dependencias internas

FASE 2: MAPEAMENTO DE DEPENDENCIAS

2.1 Links Diretos (HTML)

grep -r "href=.*[nome-arquivo]" . --include="*.html"

2.2 JavaScript Imports

grep -r "require.*[nome-arquivo]\|import.*[nome-arquivo]" . --include="*.js"

2.3 IDs e Classes CSS

grep -r "#[id-elemento]" . --include="*.js" --include="*.css"
grep -r "\.[classe]" . --include="*.js" --include="*.css"

2.4 Formularios e Rotas

grep -r "fetch.*[endpoint]\|action=.*[endpoint]" public/

FASE 3: VERIFICACAO CRUZADA

3.1 Solicitar Arquivos Dependentes

# Para cada dependencia encontrada, solicitar arquivo
cat [arquivo-que-importa].js
cat [arquivo-com-link].html

3.2 Documentar Impactos

• Arquivo A usa funcao X -> Precisa atualizar importacao
• Arquivo B tem link para Y -> Precisa ajustar href

FASE 4: IMPLEMENTACAO SEGURA

4.1 Propor Alteracoes Minimas

// ERRADO: Reescrever funcao inteira
async function calcularSaldo() {
  // ... 50 linhas de codigo novo
}

// CORRETO: Mudanca cirurgica
async function calcularSaldo() {
  // ... [codigo existente preservado]

  // [LINHA 45] ADICIONAR:
  const saldoAcertos = await calcularSaldoAcertos(participanteId);

  // ... [restante do codigo preservado]
  return saldoTotal + saldoAcertos; // [LINHA 78] MODIFICAR
}

---

GERAR SPEC.MD

Estrutura Obrigatoria

# SPEC - [Nome da Funcionalidade]

**Data:** [data atual]
**Baseado em:** PRD-[nome].md
**Status:** Especificacao Tecnica

---

## Resumo da Implementacao
[1 paragrafo: O que sera feito tecnicamente]

---

## Arquivos a Modificar (Ordem de Execucao)

### 1. [Arquivo Principal] - Mudanca Primaria

**Path:** `[caminho completo]`
**Tipo:** Modificacao | Criacao | Delecao
**Impacto:** Alto | Medio | Baixo
**Dependentes:** [Arquivo X, Y, Z]

#### Mudancas Cirurgicas:

**Linha [num]: ADICIONAR**
```javascript
[codigo a adicionar]

Motivo: [Explicacao]

Linha [num]: MODIFICAR

// ANTES:
[codigo antigo]

// DEPOIS:
[codigo novo]

Motivo: [Explicacao]

---

2. [Arquivo Dependente] - Ajuste de Integracao

Path: [caminho completo] Tipo: Modificacao Impacto: Baixo

Mudancas Cirurgicas:

Linha [num]: ATUALIZAR IMPORTACAO

// ANTES:
import { funcaoAntiga } from './modulo';

// DEPOIS:
import { funcaoAntiga, funcaoNova } from './modulo';

---

Mapa de Dependencias

Arquivo Principal (controllers/extratoController.js)
    |-> routes/extrato-routes.js [MODIFICAR linha 23]
    |-> public/js/extrato/core.js [MODIFICAR linha 45]
    |-> public/participante/fronts/extrato.html [ADICIONAR botao]

---

Validacoes de Seguranca

Multi-Tenant

• Todas queries incluem liga_id
• Verificado isolamento entre ligas

Queries Afetadas:

// [Arquivo] - Linha [num]
Model.find({
  liga_id: ligaId,  // VALIDADO
  // ...
});

Autenticacao

• Rotas protegidas com middleware
• Verificacao de permissoes

Middlewares Aplicados:

router.post('/endpoint',
  verificarAdmin,        // Protecao
  validarLigaId,         // Multi-tenant
  controller.acao
);

---

Validacoes de Performance

Queries MongoDB

• Queries de leitura usam .lean() (sem overhead do Mongoose)
• Sem N+1 queries (carregar lista e depois buscar cada item em loop)
• Indices adequados para os campos filtrados na feature

Queries a verificar:

// CORRETO — leitura com .lean()
Model.find({ liga_id: ligaId, temporada }).lean()

// ERRADO — N+1 query
const times = await Time.find({ liga_id });
for (const time of times) {
  time.extrato = await Extrato.findOne({ time_id: time.id }); // N queries!
}

// CORRETO — buscar tudo de uma vez
const extratos = await Extrato.find({ liga_id, time_id: { $in: timeIds } }).lean();

Indices Necessarios

• Listar indices que a feature exige (campos em .find())
• Verificar se ja existem em produção ou precisam ser criados

// Exemplo: se a feature filtra por liga_id + temporada + time_id
// o indice composto deve existir:
db.collection.createIndex({ liga_id: 1, temporada: 1, time_id: 1 });

Volume de Dados

• Queries com potencial de retornar > 100 documentos tem .limit() ou paginacao
• Agregacoes pesadas tem .allowDiskUse(true) se necessario

---

Casos de Teste

Teste 1: [Cenario Positivo]

Setup: [Condicao inicial] Acao: [Passo a passo] Resultado Esperado: [O que deve acontecer]

Teste 2: [Cenario Negativo]

Setup: [Condicao inicial] Acao: [Passo a passo com erro] Resultado Esperado: [Tratamento de erro]

---

Rollback Plan

Em Caso de Falha

Passos de Reversao:

1. Reverter commit: git revert [hash]
2. Restaurar banco (se aplicavel)
3. Limpar cache

---

Checklist de Validacao

Antes de Implementar

• Todos os arquivos dependentes identificados
• Mudancas cirurgicas definidas linha por linha
• Impactos mapeados
• Testes planejados
• Rollback documentado

---

Ordem de Execucao (Critico)

1. Backend primeiro:

   • Models (schema)
   • Controllers (logica)
   • Routes (endpoints)

2. Frontend depois:

   • JS (logica cliente)
   • HTML (UI)
   • CSS (estilos)

3. Testes:

   • Unitarios (se existirem)
   • Integracao
   • E2E (manual)

---

Proximo Passo

Comando para Fase 3:

LIMPAR CONTEXTO e executar:
/code .claude/docs/SPEC-[nome].md

---

Gerado por: Spec Protocol v1.0

### Onde Salvar
```bash
path=".claude/docs/SPEC-[nome-tarefa-kebab-case].md"

---

Checklist S.D.A (Verificacao Final)

Arquivos Solicitados

• Arquivo original completo (nao snippet)
• Todos os dependentes identificados
• Arquivos relacionados analisados

Dependencias Mapeadas

• JavaScript imports verificados
• Links HTML checados
• IDs e classes CSS validados
• Formularios e rotas mapeados

Mudancas Documentadas

• Linha por linha especificada
• Codigo antes/depois claramente definido
• Motivo de cada mudanca explicado
• Impacto documentado

Seguranca e Validacoes

• Multi-tenant validado (liga_id)
• Autenticacao verificada
• Rollback plan documentado
• Testes planejados

---

Anti-Patterns (NAO FAZER)

Modificar Sem Ver Original

ERRADO: "Vou adicionar linha 45 sem ver o arquivo"

CORRETO: cat [arquivo].js primeiro
         Analisar contexto da linha 45
         Garantir que mudanca nao quebra logica adjacente

Ignorar Dependencias

ERRADO: "Modifico apenas o controller, o resto se resolve"

CORRETO: Mapear TODOS os arquivos que usam o controller
         Ajustar rotas, frontend, testes
         Verificar importacoes

Reescrever Tudo

ERRADO: function novaFuncao() { /* 100 linhas novas */ }

CORRETO: Preservar funcao existente
         Adicionar apenas 2-3 linhas necessarias
         Manter compatibilidade

---

STATUS: SPEC PROTOCOL - SURGICAL & PRECISE Versao: 1.0 (High Senior Edition)