Passa al contenuto principale

📚 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)​

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

Tempo: 4-6 horas

Para Novos Desenvolvedores (1ª vez)​

  1. Ler primeiro:

  2. Durante implementação:

  3. 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:

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

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

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

Solução:

  1. Ler PADRAO-ARQUITETURAL.md - Secção "Erros Comuns"
  2. Verificar: Renderização condicional está DENTRO de children?
  3. Código correto: 
    <AdminSectionLayout ...>
      {activeRightId === 'list' && <ListTab />}  // ✅ DENTRO
    </AdminSectionLayout>
  4. 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:

  1. Ler DIAGRAMA-VISUAL-PADRAO.md (10 min visualização)
  2. Ler PADRAO-ARQUITETURAL.md (20 min padrão)
  3. Explorar código:
    • LocationsPage.tsx (exemplo completo)
    • TestingCenterPage.tsx (implementado recentemente)
  4. 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:

  1. Ler PADRAO-ARQUITETURAL.md - Secção "Troubleshooting"
  2. Verificar:
    • Schema Pydantic: campos required vs optional
    • Frontend: dados enviados correspondem ao schema
  3. 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​

FaseGuia RecomendadoTempo
OnboardingDIAGRAMA-VISUAL-PADRAO.md + PADRAO-ARQUITETURAL.md30 min
ImplementaçãoCHECKLIST-NOVA-FEATURE.md + PADRAO-ARQUITETURAL.md (templates)4-6h
DebuggingPADRAO-ARQUITETURAL.md (erros comuns) + DIAGRAMA-VISUAL-PADRAO.md (fluxo)15-60 min
ReviewCHECKLIST-NOVA-FEATURE.md (Fase 6: Validação)30 min

Por Tipo de Problema​

ProblemaGuiaSecção
Sidebar não troca abasPADRAO-ARQUITETURAL.mdErros Comuns → Erro 1
State não atualizaPADRAO-ARQUITETURAL.mdErros Comuns → Erro 2
Backend 422PADRAO-ARQUITETURAL.mdTroubleshooting
TypeScript errorsPADRAO-ARQUITETURAL.mdTroubleshooting
Entender fluxo de dadosDIAGRAMA-VISUAL-PADRAO.mdFluxo de Dados
Como estruturar backendPADRAO-ARQUITETURAL.mdTemplate 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:

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

Materiais:

📞 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​

  1. Editar ficheiro correspondente
  2. Atualizar data no topo: "Data: DD de mmm de 2026"
  3. Adicionar nota de changelog no fim (se mudança significativa)
  4. 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

Ultimo aggiornamento il da CI Governance Bot