criação do website
This commit is contained in:
135
docs/06-agent-handoff.md
Normal file
135
docs/06-agent-handoff.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user