# 06 — Guia de Agent Handoff

> Este documento existe para garantir que qualquer sessão de desenvolvimento pode ser retomada sem perda de contexto.

---

## Para o Agente que está a Retomar

### Passo 1: Lê o estado atual
Abre `docs/07-progress-tracker.md` e identifica:
- O que está feito ✅
- O que está em progresso 🔄
- O que é o próximo passo ⏭️

### Passo 2: Entende o contexto
- **O projeto é:** Painel de administração para gerir uma liga de futebol
- **A app cliente:** Já existe, só lê dados da Firebase
- **Este site:** É o único que escreve na Firebase
- **A funcionalidade mais importante:** Live Score Editor (atualização de resultados em tempo real)

### Passo 3: Verifica a estrutura de ficheiros
Confirma que a estrutura em `docs/02-tech-stack.md` foi seguida. Se houver desvios, atualiza a documentação.

### Passo 4: Atualiza o progress tracker
Ao terminar a sessão, atualiza `docs/07-progress-tracker.md` com o que foi feito.

---

## Princípios de Desenvolvimento a Seguir

### 1. Firebase primeiro
- Antes de criar qualquer componente de UI, confirma o schema Firebase em `docs/08-firebase-schema.md`
- Qualquer alteração ao schema deve ser documentada imediatamente
- Usar sempre TypeScript types que espelhem o schema

### 2. Real-time por defeito
- Usar `onSnapshot` em vez de `getDoc` sempre que possível
- O utilizador nunca deve precisar de fazer refresh manual

### 3. Transações para operações compostas
- Sempre que uma ação modifica múltiplos documentos (ex: marcar golo), usar `runTransaction`
- Nunca fazer writes paralelos sem transação — risco de inconsistência

### 4. UX do Live Editor é sagrada
- O Live Score Editor deve funcionar com latência mínima
- Botões grandes (min 48px de toque)
- Feedback visual imediato (antes mesmo da Firebase confirmar)
- Otimistic updates: atualiza UI localmente, reverte se Firebase falhar

### 5. Não breaking changes no schema
- A app cliente já está a ler dados. Qualquer alteração ao schema pode quebrar a app cliente.
- Adicionar campos novos é seguro (additive changes)
- Renomear ou remover campos exige coordenação com a app cliente

---

## Convenções de Código

### Nomeação
```
Ficheiros:    PascalCase para componentes (GameCard.tsx)
              camelCase para hooks, utils, stores (useGames.ts)
Variáveis:    camelCase
Constantes:   UPPER_SNAKE_CASE
Types/Types:  PascalCase (Game, Club, Player)
Firestore:    camelCase nas keys (homeScore, awayScore)
```

### Estrutura de um Hook Firebase
```typescript
// Padrão obrigatório para todos os hooks de dados
export function useGames(options?: { jornadaId?: string }) {
  const [games, setGames] = useState<Game[]>([])
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState<Error | null>(null)

  useEffect(() => {
    const unsubscribe = onSnapshot(query, 
      (snap) => {
        setGames(snap.docs.map(parseGame))
        setLoading(false)
      },
      (err) => {
        setError(err)
        setLoading(false)
      }
    )
    return unsubscribe  // cleanup obrigatório
  }, [options?.jornadaId])

  // Funções de mutação
  const createGame = async (data: CreateGameInput) => { ... }
  const updateGame = async (id: string, data: Partial<Game>) => { ... }
  const deleteGame = async (id: string) => { ... }

  return { games, loading, error, createGame, updateGame, deleteGame }
}
```

### Commits (se usar Git)
```
feat: adicionar live score editor
fix: corrigir cálculo de standings após golo
docs: atualizar schema Firebase
style: ajustar layout do sidebar
refactor: extrair lógica de golo para hook
```

---

## Perguntas Frequentes

**Q: Onde está o schema da Firebase?**  
A: `docs/08-firebase-schema.md`

**Q: Qual o design system a seguir?**  
A: `docs/04-design-system.md` — usa as CSS variables definidas lá

**Q: Posso mudar a stack tecnológica?**  
A: Não sem atualizar `docs/02-tech-stack.md` e ter uma boa razão documentada

**Q: A app cliente vai quebrar se eu alterar o schema?**  
A: Possivelmente. Adicionar campos novos é seguro. Remover/renomear requer coordenação.

**Q: Como sei se o Live Editor está a funcionar?**  
A: Abre a app cliente em paralelo. A alteração deve aparecer em menos de 2 segundos.

---

## Contactos / Dependências Externas

- **Firebase Project:** [preencher com o project ID]
- **Firebase Console:** https://console.firebase.google.com
- **App Cliente:** [link para o repositório ou descrição]
- **Design Mockup:** `mockup/index.html` (abrir no browser)