Spec

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**

[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 );

---

## 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

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)