VdcScoreLive/docs/06-agent-handoff.md

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

// 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)