Plataforma Completa para Avaliação, Prescrição e Controle de Treinos Físicos
- Introdução
- Visão Geral do Projeto
- Arquitetura do Sistema
- Tecnologias
- Início Rápido
- Estrutura do Projeto
- Comandos Disponíveis
- Funcionalidades Implementadas
- Deploy
- Troubleshooting
- Links Úteis
- Contribuindo
O APC FIT PRO é uma plataforma completa para prescrição, avaliação e controle de treinos físicos, unindo ciência e tecnologia para revolucionar a experiência de profissionais de educação física e alunos. Baseado no método "Avaliar, Planejar e Controlar" (APC), oferece avaliação detalhada, planejamento personalizado e controle preciso de carga em uma única solução. O grande diferencial está na personalização avançada, integração entre profissionais e alunos, e ajustes contínuos para otimizar resultados.
- Personalização Avançada: Algoritmos inteligentes para prescrição individualizada
- Integração Professor-Aluno: Fluxo colaborativo e comunicação em tempo real
- Método APC: Fundamentado em evidências científicas
- Interface Moderna: Design responsivo e acessível
- Escalabilidade: Arquitetura preparada para crescimento
- Objetivo: Oferecer avaliações detalhadas, planejamento personalizado e controle preciso de treinos, tudo em um só lugar, com base no método APC.
- Diferencial: Personalização avançada, integração entre profissionais e alunos, e ajustes contínuos para otimizar resultados.
- Público-Alvo: Profissionais de Educação Física e seus alunos
- Modalidade: Plataforma Web Progressive (PWA)er">
O sistema é dividido em duas grandes partes: Frontend e Backend.
- Função: Responsável pela comunicação assíncrona entre serviços do sistema, utilizando filas para processar eventos, tarefas e integrações de forma desacoplada.
- Integração: O backend (
apcpro-api) publica e consome mensagens via CloudAMQP, permitindo escalabilidade e maior resiliência no processamento de dados. - Tecnologia: CloudAMQP (RabbitMQ gerenciado na nuvem).
- Framework: Next.js (React)
- Componentes UI: Shadcn e Tailwind CSS
- Autenticação: NextAuth.js
- Linguagem: TypeScript
- Estrutura:
app/: Páginas e rotas do sistema (ex:/dashboard,/setup-profile)components/: Componentes reutilizáveis e de interfacelib/: Funções utilitárias e integração com APIservices/: Comunicação com o backendpublic/: Arquivos estáticos (imagens, ícones, etc.)
- Framework: Express (Node.js)
- ORM: Prisma (acesso ao banco de dados)
- Linguagem: TypeScript
- Estrutura:
controllers/: Recebem requisições HTTP e retornam respostasservices/: Lógica de negócio (ex: criação de perfis, regras de treino)repositories/: Acesso ao banco de dados via Prismamiddlewares/: Autenticação, validação, etc.models/: Tipos e interfaces do sistemaroutes.ts: Define os endpoints da API
- Utiliza o NextAuth.js tanto no frontend quanto no backend para autenticação segura, gerenciamento de sessões e integração com provedores OAuth (ex: Google).
- Armazenamento Persistente: Tabelas para usuários, treinos, avaliações, etc.
- Relacionamentos: Relacionamentos entre entidades.
- Usuário interage com a interface Next.js.
- Frontend faz requisição à API Node.js.
- API valida autenticação via Auth.js.
- Controller processa requisição e chama o Service apropriado.
- Service aplica regras de negócio e usa a Data Access Layer.
- Data Access Layer interage com o banco de dados PostgreSQL.
- Resposta retorna pelas camadas até o frontend.
- Next.js atualiza a interface com os dados recebidos.
- apcpro-api: Diretório do backend, desenvolvido com Node.js, Express e Prisma.
- apcpro-web: Diretório do frontend, desenvolvido com Next.js e Shadcn.
- CloudAMQP: Instância gerenciada de RabbitMQ utilizada para mensageria entre serviços (configuração via variáveis de ambiente).
.github/: Arquivos de configuração e workflows do GitHub Actions.README.md: Documentação principal do projeto.
src/: Código-fonte principal do backend.controllers/: Controladores para gerenciar requisições.services/: Lógica de negócios.repositories/: Acesso ao banco de dados com Prisma.middlewares/: Middlewares para autenticação e validação.models/: Interfaces e tipos do sistema.utils/: Funções utilitárias.routes.ts: Definição das rotas da API.
prisma/: Configuração do Prisma.schema.prisma: Esquema do banco de dados.migrations/: Migrações do banco de dados.
.env: Variáveis de ambiente.package.json: Dependências e scripts do backend.
src/: Código-fonte principal do frontend.app/: Estrutura de páginas do Next.js.dashboard/: Página principal do dashboard.setup-profile/: Página de configuração de perfil.
components/: Componentes reutilizáveis.ui/: Componentes de interface (ex.: botões, formulários).
lib/: Funções utilitárias e abstrações.services/: Comunicação com a API backend.
public/: Arquivos estáticos (imagens, ícones, etc.)..env: Variáveis de ambiente.package.json: Dependências e scripts do frontend.
A plataforma utiliza tecnologias modernas e robustas para garantir performance, escalabilidade e manutenibilidade:
- Next.js 14 - Framework React com App Router, SSR e SSG
- TypeScript - Tipagem estática para maior confiabilidade
- Tailwind CSS - Framework CSS utilitário para estilização rápida
- Shadcn/ui - Componentes UI acessíveis e reutilizáveis
- NextAuth.js - Autenticação segura e escalável
- Node.js - Runtime JavaScript para servidor
- Express.js - Framework web minimalista e flexível
- Prisma ORM - ORM moderno com tipagem automática
- PostgreSQL - Banco de dados relacional robusto
- TypeScript - Tipagem estática no backend
- CloudAMQP - Mensageria RabbitMQ gerenciada
- Azure - Plataforma de deploy e hospedagem
- Vercel - Deploy do frontend (alternativa)
- Node.js 18+
- npm ou yarn
- PostgreSQL 14+
- Git
# Navegue até o diretório desejado
cd C:\Projetos
# Clone o repositório
git clone https://alexsrs@dev.azure.com/alexsrs/APC%20PRO/_git/APC%20PRO apc-fit-pro
# Acesse o diretório
cd apc-fit-pro# Acesse o diretório da API
cd apcpro-api
# Instale as dependências
npm install
# Configure as variáveis de ambiente
copy .env.example .env
# Edite o arquivo .env com suas configurações
# Execute as migrações do banco
npx prisma migrate dev
# Inicie o servidor de desenvolvimento
npm run start:dev# Em outro terminal, acesse o diretório web
cd apcpro-web
# Instale as dependências
npm install
# Configure as variáveis de ambiente
copy .env.local.example .env.local
# Edite o arquivo .env.local com suas configurações
# Inicie o servidor de desenvolvimento
npm run dev- Frontend: http://localhost:3000
- API: http://localhost:3001
- Swagger: http://localhost:3001/api-docs
# Instalar PostgreSQL (Windows)
winget install PostgreSQL.PostgreSQL
# Criar banco de dados
createdb apc_fit_pro_dev
# String de conexão no .env
DATABASE_URL="postgresql://usuario:senha@localhost:5432/apc_fit_pro_dev"# Usar o compose fornecido
cd apcpro-bd
docker-compose up -d# Desenvolvimento
npm run start:dev # Inicia em modo desenvolvimento
npm run start:watch # Inicia com reload automático
npm run build # Compila o projeto
npm run start:dist # Executa a versão compilada
# Banco de Dados
npx prisma migrate dev # Aplica migrações em desenvolvimento
npx prisma migrate deploy # Aplica migrações em produção
npx prisma generate # Gera o cliente Prisma
npx prisma studio # Interface visual do banco
# Testes e Qualidade
npm run test # Executa testes
npm run test:watch # Testes em modo watch
npm run lint # Verifica código com ESLint
npm run format # Formata código com Prettier# Desenvolvimento
npm run dev # Inicia servidor de desenvolvimento
npm run build # Compila para produção
npm run start # Inicia servidor de produção
npm run preview # Preview da build
# Testes e Qualidade
npm run test # Executa testes
npm run test:ui # Interface de testes
npm run lint # Verifica código
npm run type-check # Verifica tipagem TypeScript
# Componentes
npx shadcn-ui add [component] # Adiciona componente ShadcnO APC FIT PRO já possui as seguintes funcionalidades plenamente desenvolvidas e testadas:
- ✅ Autenticação NextAuth.js: Login via Google OAuth e email/senha
- ✅ Gestão de Perfis: Criação e edição de perfis para professores e alunos
- ✅ Configuração Inicial: Setup Profile com escolha de papel (professor/aluno)
- ✅ Relacionamentos: Vinculação professor-aluno com convites por link
- ✅ Middleware de Autenticação: Proteção de rotas e validação JWT
- ✅ Questionário Automatizado: Identificação do objetivo principal (Controle de Doença, Saúde/Bem-estar, Estética/Hipertrofia, Alta Performance)
- ✅ Classificação Automática: Algoritmo de classificação baseado nas respostas
- ✅ Validação de Avaliação: Sistema para verificar se aluno possui avaliação válida
- ✅ Interface Modal: Modal específico para alunos com fluxo guiado
- ✅ Entrevista Aprofundada: Perguntas segmentadas por objetivo identificado
- ✅ Histórico Médico: Coleta de informações sobre lesões, limitações e condições de saúde
- ✅ Preferências e Logística: Análise de disponibilidade, preferências e comprometimento
- ✅ Integração com Triagem: Abertura automática após triagem (exceto para Alto Rendimento)
- ✅ Formulário Validado: Validação completa com feedback em tempo real
- ✅ Protocolo Específico: Avaliação diferenciada para atletas e esportistas
- ✅ Métricas Avançadas: Coleta de dados específicos para alta performance
- ✅ Integração Automática: Seleção baseada no resultado da triagem
- ✅ Coleta Completa: Peso, altura, circunferências (pescoço, cintura, quadril, membros)
- ✅ Cálculos Automáticos: IMC, RCQ, Circunferência Abdominal com classificações
- ✅ Interface Organizada: Divisão por regiões corporais (tronco, membros)
- ✅ Validação em Tempo Real: Feedback imediato com classificações
- ✅ Múltiplos Protocolos: Jackson & Pollock (3 e 7 dobras), Guedes, Petroski, Faulkner
- ✅ Cálculos Automáticos: Densidade corporal, percentual de gordura, massa gorda/magra
- ✅ Classificações por Gênero/Idade: Referências específicas para cada protocolo
- ✅ Interface Moderna: Componente avançado com validação e feedback
- ✅ API Robusta: Endpoints específicos para cada protocolo com documentação completa
- ✅ Controle de Status: Pendente, Aprovada, Reprovada, Vencida
- ✅ Gestão de Validade: Definição de prazo pelo professor (padrão 90 dias)
- ✅ Aprovação por Professor: Interface para aprovação/reprovação com motivos
- ✅ Verificação Automática: Detecção de avaliações vencidas
- ✅ Badges Visuais: Indicadores coloridos para cada status
- ✅ Histórico de Avaliações: Lista completa com status e validade
- ✅ Próxima Avaliação: Cálculo automático da data de reavaliação
- ✅ Evolução Física: Comparação entre avaliações com indicadores visuais
- ✅ Métricas de Progresso: Análise de peso, massa magra e gordura corporal
- ✅ Detalhamento Completo: Modal com visualização detalhada dos resultados
- ✅ Avaliações Pendentes: Painel específico para professores gerenciarem aprovações
- ✅ Mensageria CloudAMQP: Integração com RabbitMQ para notificações assíncronas
- ✅ Alertas Automáticos: Notificações geradas após cadastro de avaliações
- ✅ Alertas por Usuário: Sistema persistente para professores e alunos
- ✅ API de Alertas: Endpoints para consumo e gestão de notificações
- ✅ Gestão de Alunos: Lista, busca e visualização de alunos vinculados
- ✅ Métricas do Professor: Total de alunos, novos cadastros, alunos ativos
- ✅ Convite de Alunos: Sistema de convite via link com professorId
- ✅ Nova Avaliação: Modal completo para criar avaliações para alunos
- ✅ Avaliações Pendentes: Painel específico para aprovar/reprovar avaliações
- ✅ Detalhes do Aluno: Modal com histórico completo e informações detalhadas
- ✅ Alertas Inteligentes: Notificações específicas para o professor
- ✅ Métricas Pessoais: Treinos realizados, próxima avaliação, evolução física
- ✅ Abertura Automática: Modal de avaliação abre automaticamente se necessário
- ✅ Fluxo Guiado: Etapas sequenciais de avaliação com validação
- ✅ Histórico Completo: Lista de avaliações com status e validade
- ✅ Ações Rápidas: Acesso direto para diferentes tipos de avaliação
- ✅ Alertas Personalizados: Notificações relevantes para o aluno
- ✅ API RESTful Completa: 35+ endpoints documentados com Swagger
- ✅ Documentação Swagger: Interface interativa para testes da API
- ✅ Health Check: Monitoramento de status da aplicação
- ✅ Métricas do Sistema: Endpoints para monitoramento de performance
- ✅ CORS Configurado: Suporte para requisições cross-origin
- ✅ Deploy Azure: Configuração completa para produção no Azure
- ✅ Banco PostgreSQL: Schema Prisma com 30+ migrações aplicadas
- ✅ Design Responsivo: Interface adaptável para desktop, tablet e mobile
- ✅ Componentes Shadcn: UI moderna e acessível com sistema de design consistente
- ✅ Sidebar Dinâmica: Navegação adaptada por perfil (professor/aluno)
- ✅ Modais Padronizados: Sistema de modais reutilizáveis com ModalPadrao
- ✅ Loading States: Indicadores de carregamento em todas as operações
- ✅ Tratamento de Erros: Validação e feedback em tempo real
- ✅ Progress Indicators: Barras de progresso para fluxos multi-etapas
- ✅ Sistema de Badges: Indicadores visuais para status e classificações
- ✅ 80 Testes Implementados: Suite completa de testes unitários e de integração
- ✅ 100% de Aprovação: Todos os testes passando sem falhas
- ✅ Cobertura 80%+: Meta de cobertura atingida nos módulos críticos
- ✅ Testes Unitários: Utilitários, services, controllers e helpers
- ✅ Testes de Integração: APIs de avaliação e endpoints críticos
- ✅ Jest + TypeScript: Configuração moderna com ts-jest e supertest
- ✅ Mocks Inteligentes: Simulação realista do banco de dados e APIs
- ✅ Relatórios de Cobertura: Análise detalhada via
npm test -- --coverage
tests/
├── setup.ts # Configuração global
├── helpers/test-app.ts # Helper para testes de integração
├── unit/ # Testes unitários
│ ├── genero-converter.test.ts
│ ├── idade.test.ts
│ ├── avaliacaoMedidas.test.ts
│ ├── users-service.test.ts
│ ├── avaliacao-controller.test.ts
│ ├── dobras-cutaneas.test.ts
│ └── avaliacao-service.test.ts
└── integration/ # Testes de integração
├── avaliacoes.test.ts
└── avaliacoes-json.test.ts
# Executar todos os testes
npm test
# Executar com relatório de cobertura
npm test -- --coverage
# Executar testes específicos
npm test -- genero-converter- ✅ Código Limpo: Zero warnings de lint após refatoração completa
- ✅ TypeScript Strict: Tipagem estática em 100% do código
- ✅ Componentes Reutilizáveis: Biblioteca de componentes padronizados
- ✅ Utilitários Centralizados: Conversores e helpers sem duplicação
- ✅ Documentação Técnica: Guides e documentação para todos os componentes
- ✅ Testes de Build: Build automatizado sem erros de compilação
- Aluno Entra no Sistema → Verifica se possui avaliação válida
- Sem Avaliação Válida → Abre automaticamente a Triagem
- Triagem Concluída → Classifica objetivo e decide próximo passo
- Objetivo Não-Esportivo → Abre automaticamente a Anamnese
- Anamnese Concluída → Aluno pode acessar Medidas Corporais
- Medidas Corporais → Cálculos automáticos e classificações
- Histórico Completo → Todas as avaliações ficam disponíveis
- Evolução Física → Comparações automáticas entre avaliações
- Alertas Gerados → Professor recebe notificações via mensageria
Todo o fluxo é automatizado, seguro e baseado em evidências científicas, promovendo avaliações detalhadas e prescrições individualizadas.
# Configurar Azure CLI
az login
# Deploy do backend
cd apcpro-api
az webapp create --name apc-fit-pro-api --resource-group apc-fit-pro-rg
az webapp deployment source config --name apc-fit-pro-api --resource-group apc-fit-pro-rg --repo-url https://github.com/seu-usuario/apc-fit-pro
# Deploy do frontend
cd ../apcpro-web
npm run build
az storage blob upload-batch --source ./out --destination '$web' --account-name apcfitprostorage# Instalar Vercel CLI
npm install -g vercel
# Deploy do frontend
cd apcpro-web
vercel --prod# Conectar ao Railway
railway login
railway link
# Deploy
railway up- Configurar variáveis de ambiente
- Executar migrações do banco
- Configurar domínio personalizado
- Configurar SSL/TLS
- Configurar monitoramento
- Testar todas as funcionalidades
- Configurar backup do banco de dados
# Verificar se PostgreSQL está rodando
Get-Service postgresql*
# Testar conexão
psql -h localhost -U postgres -d apc_fit_pro_dev# Resetar migrações (apenas desenvolvimento)
npx prisma migrate reset
# Forçar aplicação das migrações
npx prisma db push# Limpar cache e reinstalar
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install# Verificar processos na porta 3000
netstat -ano | findstr :3000
# Finalizar processo (substitua PID)
taskkill /F /PID [PID]# Executar como administrador
# ou ajustar permissões de pasta
icacls "C:\Projetos\apc-fit-pro" /grant Users:F /TSe você encontrar problemas não listados aqui:
- Verifique os logs da aplicação
- Consulte a documentação das tecnologias utilizadas
- Abra uma issue no repositório com detalhes do erro
- Entre em contato com a equipe de desenvolvimento
- Documentação do Projeto - Documentação técnica completa
- API Swagger - Documentação interativa da API
- Guia de Contribuição - Como contribuir com o projeto
- Prisma Studio - Interface visual do banco de dados
- Next.js DevTools - Ferramentas de debug
- VS Code Extensions - Extensões recomendadas
- Next.js Documentation - Documentação oficial do Next.js
- Prisma Documentation - Documentação oficial do Prisma
- Tailwind CSS Documentation - Documentação oficial do Tailwind
- Shadcn/ui Documentation - Documentação dos componentes
- Azure Documentation - Documentação do Azure
- Vercel Documentation - Documentação do Vercel
- Railway Documentation - Documentação do Railway
- 80 testes automatizados implementados e funcionais
- 100% de aprovação em todos os testes
- Cobertura de 80%+ nos módulos críticos
- Estrutura robusta com Jest, TypeScript e Supertest
- Fluxo completo de avaliações físicas implementado
- Dobras cutâneas com múltiplos protocolos funcionais
- Conversão de gênero padronizada em todo o projeto
- Estrutura JSON validada para campo resultado
- Zero warnings de lint em todo o projeto
- Código limpo e bem documentado
- Utilitários centralizados eliminando duplicações
- Arquitetura sólida pronta para expansão
- 📄 Sistema de Relatórios PDF - Puppeteer + Templates
- 🧪 Novos Tipos de Avaliação - Testes funcionais, postural
- 📊 Dashboard Analytics - Métricas avançadas e evolução
- 💰 Pagamentos Stripe - Planos e cobrança recorrente
- 📱 App Mobile - React Native companion
- 🔄 Integração Wearables - Fitbit, Garmin
- 🤖 IA Avançada - Prescrição automática com OpenAI
- 🌐 Funcionalidades Sociais - Feed, ranking, grupos
- 📈 Business Intelligence - Analytics setorial
- ✅ 35+ endpoints da API documentados
- ✅ 30+ migrações do banco aplicadas
- ✅ 80 testes com 100% aprovação
- ✅ 4 tipos de avaliação implementados
- ✅ 2 dashboards específicos (professor/aluno)
🚀 O projeto está em excelente estado! Base sólida, testes robustos e pronto para as próximas funcionalidades estratégicas. 2025 será o ano do lançamento público! 💪✨
Contribuições são muito bem-vindas! Este projeto segue as melhores práticas de desenvolvimento colaborativo.
# Fork o repositório no GitHub
# Clone seu fork
git clone https://github.com/seu-usuario/apc-fit-pro.git
cd apc-fit-pro
# Adicione o repositório original como upstream
git remote add upstream https://github.com/alexsrs/apc-fit-pro.git# Crie uma branch para sua feature
git checkout -b feature/nova-funcionalidade
# Faça suas alterações
# Commit com mensagem descritiva
git commit -m "feat: adiciona nova funcionalidade X"
# Push para seu fork
git push origin feature/nova-funcionalidade
# Abra um Pull RequestUtilizamos Conventional Commits:
feat:- Nova funcionalidadefix:- Correção de bugdocs:- Alterações na documentaçãostyle:- Alterações de formataçãorefactor:- Refatoração de códigotest:- Adição ou correção de testeschore:- Tarefas de manutenção
- ✅ Código limpo e bem documentado
- ✅ Testes para novas funcionalidades
- ✅ TypeScript com tipagem adequada
- ✅ Responsividade para interfaces
- ✅ Acessibilidade seguindo padrões WCAG
- Automated Tests - Todos os testes devem passar
- Code Review - Pelo menos uma aprovação necessária
- Documentation - Atualizar docs se necessário
- Manual Testing - Testar funcionalidades impactadas
- 🐛 Bug Reports - Reporte problemas encontrados
- 💡 Feature Requests - Sugira novas funcionalidades
- 📝 Documentation - Melhore a documentação
- 🧪 Tests - Adicione ou melhore testes
- 🎨 UI/UX - Melhorias na interface
- 🔧 Performance - Otimizações de performance
Agradecemos por contribuir para o APC FIT PRO! �
Feito com 💙 por Alex Sandro R. de Souza
APC FIT PRO - Transformando a Educação Física com Tecnologia
