📚 Guias de Desenvolvimento - Índice

Booking Management System
Data: 26 de fevereiro de 2026
Status: Validated & Production-Ready

🎯 Visão Geral

Esta pasta contém todos os guias práticos para desenvolvimento no sistema de gestão de reservas. Todos os padrões documentados aqui foram validados em produção nas features Locations e Testing Center.

📖 Guias Disponíveis

🏛️ 1. Padrão Arquitetural Completo

Ficheiro: PADRAO-ARQUITETURAL.md
Propósito: Guia rápido de referência para implementar novas secções
Leia quando: Antes de implementar qualquer nova feature

Conteúdo:

✅ Checklist rápido: Nova secção (frontend + backend + DB + tests)
✅ Templates de código prontos a copiar
✅ Exemplos: Page Component, Tab Component, Backend Module, E2E Test
✅ Erros comuns e como evitar
✅ Design System (cores, layout, estilos)
✅ Validação final (QA checklist)
✅ Referências para código validado

Tempo de leitura: 15-20 minutos
Referência rápida: Sempre aberto durante implementação

✅ 2. Checklist de Nova Feature

Ficheiro: CHECKLIST-NOVA-FEATURE.md
Propósito: Checklist interativa passo-a-passo para implementar feature completa
Leia quando: Durante implementação de nova feature (usar como TODO list)

Conteúdo:

📋 Fase 1: Database (30 min) - Migration Alembic
🐍 Fase 2: Backend (90 min) - FastAPI module completo
⚛️ Fase 3: Frontend (60 min) - React components + Page
🧪 Fase 4: Tests E2E (60 min) - Playwright tests
📖 Fase 5: Documentação (30 min) - User guides
✅ Fase 6: Validação (30 min) - QA checklist completo
🚀 Fase 7: Deploy (15 min) - Commit + PR

Tempo total: 4-6 horas (1 desenvolvedor, CRUD completo)
Como usar: Imprimir ou abrir em aba separada, marcar checkboxes à medida que completa

🎨 3. Diagrama Visual do Padrão

Ficheiro: DIAGRAMA-VISUAL-PADRAO.md
Propósito: Visualização em ASCII art de toda a arquitetura
Leia quando: Para entender visualmente como componentes interagem

Conteúdo:

📊 Visão geral: Hierarquia de componentes
🔄 Fluxo de dados: State management
🎯 Fluxo de interação: User click → State update → Re-render
🏗️ Arquitetura backend: API → Database
📦 Estrutura de módulos: Dependências
🎨 Layout responsivo: Grid system (desktop, tablet, mobile)
🚦 Estado do botão: Visual feedback
🔄 Ciclo de vida completo: Create → List

Tempo de leitura: 10-15 minutos
Referência visual: Útil para onboarding de novos devs

📘 4. Plano Completo de Onboarding & E2E

Ficheiro: ../PLANO-ONBOARDING-E2E-DOCUMENTACAO.md
Propósito: Documento estratégico completo do projeto
Leia quando: Para contexto geral do projeto e roadmap

Destaques:

Secção 2.8: Padrão Arquitetural Completo (versão extendida)
Secção 2.7: Testing Center Architecture (exemplo real)
Roadmap completo (Admin → Staff → Gestor → Cliente)
CI/CD pipeline setup
Geração automática de documentação

Tempo de leitura: 60-90 minutos (documento completo)
Consulta: Quando precisar de detalhes aprofundados

🚀 Quick Start: Implementar Nova Feature

Para Desenvolvedores Experientes (conhecem o padrão)

Abrir PADRAO-ARQUITETURAL.md
Copiar templates de código
Substituir {feature} pelo nome da feature
Implementar seguindo estrutura
Rodar testes: npm run test:e2e
Commit

Tempo: 4-6 horas

Para Novos Desenvolvedores (1ª vez)

Ler primeiro:
- DIAGRAMA-VISUAL-PADRAO.md - entender visualmente
- PADRAO-ARQUITETURAL.md - aprender padrão
Durante implementação:
- Abrir CHECKLIST-NOVA-FEATURE.md
- Seguir fase por fase
- Marcar checkboxes à medida que completa
Referências durante dev:
- Código validado: LocationsPage.tsx, TestingCenterPage.tsx
- Sempre constultar PADRAO-ARQUITETURAL.md para dúvidas

Tempo: 6-8 horas (incluindo aprendizado)

📚 Ordem de Leitura Recomendada

🎓 Onboarding (Novo Dev no Projeto)

1️⃣ DIAGRAMA-VISUAL-PADRAO.md          (10 min) - Visão geral visual
    ↓
2️⃣ PADRAO-ARQUITETURAL.md             (20 min) - Padrão completo
    ↓
3️⃣ PLANO-ONBOARDING... (Secção 2.8)   (30 min) - Detalhes aprofundados
    ↓
4️⃣ Código validado:
   - frontend/src/pages/admin/locations/LocationsPage.tsx
   - frontend/src/pages/admin/testing/TestingCenterPage.tsx
   - frontend/src/components/layout/AdminSectionLayout.tsx
    ↓
5️⃣ CHECKLIST-NOVA-FEATURE.md          (ao implementar) - Passo a passo

Tempo total onboarding: 1-2 horas

🔧 Implementação (Nova Feature)

1️⃣ CHECKLIST-NOVA-FEATURE.md          (abrir em aba)
    ↓
2️⃣ PADRAO-ARQUITETURAL.md             (consulta rápida de templates)
    ↓
3️⃣ Implementar seguindo checklist fase por fase
    ↓
4️⃣ Validar com QA checklist (Fase 6 do checklist)
    ↓
5️⃣ Commit + PR (Fase 7 do checklist)

Tempo: 4-6 horas

🐛 Debugging (Problema em Feature Existente)

1️⃣ Identificar sintoma
    ↓
2️⃣ PADRAO-ARQUITETURAL.md (Secção "Erros Comuns")
    ↓
3️⃣ DIAGRAMA-VISUAL-PADRAO.md (entender fluxo)
    ↓
4️⃣ Comparar com código validado (Locations/Testing Center)
    ↓
5️⃣ Fix + test

🎯 Casos de Uso

Caso 1: "Preciso implementar módulo de Serviços (CRUD completo)"

Solução:

Abrir CHECKLIST-NOVA-FEATURE.md
Preencher:
- Feature: services
- Data início: hoje
- Desenvolvedor: seu nome
Seguir todas as 7 fases marcando checkboxes
Templates de código em PADRAO-ARQUITETURAL.md

Resultado: Feature completa em 4-6 horas (frontend + backend + DB + tests + docs)

Solução:

Ler PADRAO-ARQUITETURAL.md - Secção "Erros Comuns"
Verificar: Renderização condicional está DENTRO de children?

Código correto:

<AdminSectionLayout ...>
  {activeRightId === 'list' && <ListTab />}  // ✅ DENTRO
</AdminSectionLayout>

Comparar com LocationsPage.tsx (referência validada)

Tempo de fix: 5-15 minutos

Caso 3: "Novo dev no projeto, por onde começar?"

Solução:

Ler DIAGRAMA-VISUAL-PADRAO.md (10 min visualização)
Ler PADRAO-ARQUITETURAL.md (20 min padrão)
Explorar código:
- LocationsPage.tsx (exemplo completo)
- TestingCenterPage.tsx (implementado recentemente)
Implementar feature simples seguindo CHECKLIST-NOVA-FEATURE.md

Tempo de onboarding: 1-2 horas + 6-8 horas implementação 1ª feature

Caso 4: "Backend 422 ao criar item, não sei o que está errado"

Solução:

Ler PADRAO-ARQUITETURAL.md - Secção "Troubleshooting"
Verificar:
- Schema Pydantic: campos required vs optional
- Frontend: dados enviados correspondem ao schema

Exemplo:

# Backend
class CreateDto(BaseModel):
    name: str = Field(...)  # required

# Frontend deve enviar
{ name: "Test" }  // ✅ string
{ name: null }    // ❌ null não aceito

Tempo de fix: 10-30 minutos

🔗 Navegação Rápida

Por Fase de Desenvolvimento

Fase	Guia Recomendado	Tempo
Onboarding	DIAGRAMA-VISUAL-PADRAO.md + PADRAO-ARQUITETURAL.md	30 min
Implementação	CHECKLIST-NOVA-FEATURE.md + PADRAO-ARQUITETURAL.md (templates)	4-6h
Debugging	PADRAO-ARQUITETURAL.md (erros comuns) + DIAGRAMA-VISUAL-PADRAO.md (fluxo)	15-60 min
Review	CHECKLIST-NOVA-FEATURE.md (Fase 6: Validação)	30 min

Por Tipo de Problema

Problema	Guia	Secção
Sidebar não troca abas	PADRAO-ARQUITETURAL.md	Erros Comuns → Erro 1
State não atualiza	PADRAO-ARQUITETURAL.md	Erros Comuns → Erro 2
Backend 422	PADRAO-ARQUITETURAL.md	Troubleshooting
TypeScript errors	PADRAO-ARQUITETURAL.md	Troubleshooting
Entender fluxo de dados	DIAGRAMA-VISUAL-PADRAO.md	Fluxo de Dados
Como estruturar backend	PADRAO-ARQUITETURAL.md	Template Backend Module

📋 Ficheiros de Referência (Código Validado)

Frontend

frontend/src/pages/admin/
├── locations/LocationsPage.tsx         ✅ REFERÊNCIA PRINCIPAL
│                                          (padrão completo, CRUD funcionando)
│
├── testing/TestingCenterPage.tsx       ✅ EXEMPLO RECENTE
                                           (implementado 26 fev 2026)

frontend/src/components/layout/
├── AdminSectionLayout.tsx              ✅ WRAPPER REUTILIZÁVEL
                                           (grid, sidebar, rightMenu)

frontend/src/components/locations/
├── LocationForm.tsx                    ✅ Exemplo Form Component
├── LocationCard.tsx                    ✅ Exemplo Card Component

frontend/src/components/testing/
├── TestingOverviewTab.tsx              ✅ Exemplo Tab Component (stateless)
├── TestingImagesTab.tsx                ✅ Exemplo Tab Component (gallery)

Backend

backend/src/modules/locations/
├── routes.py                           ✅ FastAPI endpoints (CRUD completo)
├── models.py                           ✅ SQLAlchemy model
├── schemas.py                          ✅ Pydantic validation
├── service.py                          ✅ Business logic

Tests E2E

frontend/tests/e2e/
├── 00-auth-login/login.spec.ts         ✅ Login test
├── 02-locations-list/list.spec.ts      ✅ List test
├── 03-locations-create/create.spec.ts  ✅ Create test
├── helpers/
    └── login.helper.ts                 ✅ Reusable helper

🎓 Materiais de Formação

Workshop Interno: "Implementar Nova Feature em 4 Horas"

Agenda:

30 min - Apresentação do padrão (DIAGRAMA-VISUAL-PADRAO.md)
30 min - Code walkthrough (LocationsPage, AdminSectionLayout)
180 min - Hands-on: Implementar feature simples (CRUD de Tags)
30 min - Review + Q&A

Materiais:

Slides: (TBD - criar apresentação visual)
Código base: Template de feature vazia
Checklist: CHECKLIST-NOVA-FEATURE.md

📞 Suporte

Dúvidas Frequentes

Q: Qual guia ler primeiro?
A: DIAGRAMA-VISUAL-PADRAO.md (10 min visual) → PADRAO-ARQUITETURAL.md (20 min padrão)

Q: Quanto tempo leva implementar feature completa?
A: 4-6 horas (dev experiente) ou 6-8 horas (novo dev)

Q: Sidebar não funciona, o que fazer?
A: PADRAO-ARQUITETURAL.md - "Erros Comuns" - Erro 1

Q: Como validar que feature está completa?
A: CHECKLIST-NOVA-FEATURE.md - Fase 6: Validação Final

Q: Posso desviar do padrão?
A: ❌ Não. Desvios causam inconsistência e bugs. Seguir padrão estritamente.

🔄 Manutenção destes Guias

Quando Atualizar

Atualizar documentação quando:

✅ Padrão arquitetural muda (nova versão validada)
✅ Novos componentes reutilizáveis criados
✅ Novos erros comuns identificados
✅ Feedback de devs: documentação confusa

Como Atualizar

Editar ficheiro correspondente
Atualizar data no topo: "Data: DD de mmm de 2026"
Adicionar nota de changelog no fim (se mudança significativa)
Commit: docs: update {guide-name} - {brief description}

📊 Métricas de Sucesso

Objetivo: Todos os devs seguem padrão consistentemente

KPIs:

✅ 100% features novas seguem padrão (verificar em PR)
✅ < 15 min tempo de onboarding para entender padrão
✅ < 6h tempo médio implementação CRUD completo
✅ 0 bugs relacionados a sidebar não funcionar (erro comum #1)
✅ 100% testes E2E passam em CI/CD

Meta Q1 2026: 5 features novas implementadas (Services, Staff, Bookings, Products, Reports)

🎯 Conclusão

Estes guias são a fonte única de verdade para desenvolvimento no projeto. Seguir estes padrões garante:

✅ Consistência - Código previsível, fácil manutenção
✅ Velocidade - Templates prontos, não reinventar a roda
✅ Qualidade - Padrões validados em produção
✅ Escalabilidade - Adicionar 10 features = mesmo padrão 10x
✅ Onboarding - Novos devs produtivos em < 1 dia

Próximo passo: Escolher um guia e começar! 🚀

Última atualização: 26 de fevereiro de 2026
Validado por: Testing Center (26 fev) + Locations (production)
Mantido por: Equipa de Desenvolvimento

🎯 Visão Geral​

📖 Guias Disponíveis​

🏛️ 1. Padrão Arquitetural Completo​

✅ 2. Checklist de Nova Feature​

🎨 3. Diagrama Visual do Padrão​

📘 4. Plano Completo de Onboarding & E2E​

🚀 Quick Start: Implementar Nova Feature​

Para Desenvolvedores Experientes (conhecem o padrão)​

Para Novos Desenvolvedores (1ª vez)​

📚 Ordem de Leitura Recomendada​

🎓 Onboarding (Novo Dev no Projeto)​

🔧 Implementação (Nova Feature)​

🐛 Debugging (Problema em Feature Existente)​

🎯 Casos de Uso​

Caso 1: "Preciso implementar módulo de Serviços (CRUD completo)"​

Caso 2: "Sidebar buttons não estão trocando conteúdo"​

Caso 3: "Novo dev no projeto, por onde começar?"​

Caso 4: "Backend 422 ao criar item, não sei o que está errado"​

🔗 Navegação Rápida​

Por Fase de Desenvolvimento​

Por Tipo de Problema​

📋 Ficheiros de Referência (Código Validado)​

Frontend​

Backend​

Tests E2E​

🎓 Materiais de Formação​

Workshop Interno: "Implementar Nova Feature em 4 Horas"​

📞 Suporte​

Dúvidas Frequentes​

🔄 Manutenção destes Guias​

Quando Atualizar​

Como Atualizar​

📊 Métricas de Sucesso​

🎯 Conclusão​

🎯 Visão Geral

📖 Guias Disponíveis

🏛️ 1. Padrão Arquitetural Completo

✅ 2. Checklist de Nova Feature

🎨 3. Diagrama Visual do Padrão

📘 4. Plano Completo de Onboarding & E2E

🚀 Quick Start: Implementar Nova Feature

Para Desenvolvedores Experientes (conhecem o padrão)

Para Novos Desenvolvedores (1ª vez)

📚 Ordem de Leitura Recomendada

🎓 Onboarding (Novo Dev no Projeto)

🔧 Implementação (Nova Feature)

🐛 Debugging (Problema em Feature Existente)

🎯 Casos de Uso

Caso 1: "Preciso implementar módulo de Serviços (CRUD completo)"

Caso 2: "Sidebar buttons não estão trocando conteúdo"

Caso 3: "Novo dev no projeto, por onde começar?"

Caso 4: "Backend 422 ao criar item, não sei o que está errado"

🔗 Navegação Rápida

Por Fase de Desenvolvimento

Por Tipo de Problema

📋 Ficheiros de Referência (Código Validado)

Frontend

Backend

Tests E2E

🎓 Materiais de Formação

Workshop Interno: "Implementar Nova Feature em 4 Horas"

📞 Suporte

Dúvidas Frequentes

🔄 Manutenção destes Guias

Quando Atualizar

Como Atualizar

📊 Métricas de Sucesso

🎯 Conclusão