📚 Especificações Técnicas

🗂️ Índice

1. Visão Geral
2. Estrutura do Projeto
3. Tecnologias Utilizadas
4. Arquitetura
5. Banco de Dados
6. Autenticação
7. APIs
8. Middlewares
9. Guia de Desenvolvimento
10. Suporte

---

🔎 Visão Geral

O Saúde na Sua Casa é um sistema de gestão de atendimento médico domiciliar, focado em facilitar o trabalho dos Agentes Comunitários de Saúde (ACS) e médicos no atendimento à população. Permite agendamento e gestão de consultas, monitoramento de sinais vitais, notificações para pacientes e profissionais de saúde e gerenciamento de recursos do sistema.

A API segue o padrão RESTful, utiliza JSON e autenticação JWT (exceto login). Todas as funcionalidades são acessadas via endpoints protegidos.

---

🏗️ Estrutura do Projeto

O projeto segue uma arquitetura limpa (Clean Architecture) com Next.js, utilizando TypeScript. A estrutura de diretórios é organizada da seguinte forma:

/src
/app              # Rotas da API (Next.js App Router)
/config           # Configurações do sistema
/controllers      # Controladores das APIs
/interfaces       # Interfaces TypeScript
/lib             # Bibliotecas e utilitários
/middlewares     # Middlewares da aplicação
/models          # Modelos de dados
/pages           # Páginas Next.js (incluindo API routes)
/routes          # Definições de rotas
/services        # Camada de serviços
/types           # Tipos TypeScript
/utils           # Funções utilitárias

---

💻 Tecnologias Utilizadas

• Next.js: Framework React para desenvolvimento full-stack
• TypeScript: Linguagem principal
• Prisma: ORM para banco de dados
• MySQL: Banco de dados relacional
• JWT: Autenticação baseada em tokens
• Zod: Validação de schemas
• Swagger/OpenAPI: Documentação da API

---

🧩 Arquitetura

O sistema segue uma arquitetura em camadas:

1. Routes/Controllers: Recebem as requisições HTTP e validam os inputs
2. Services: Implementam a lógica de negócio
3. Models: Representam as entidades do sistema
4. Prisma: Camada de acesso ao banco de dados

🔄 Fluxo de Dados

Request → Middleware → Controller → Service → Model → Database
Response ← Controller ← Service ← Model ← Database

---

🗄️ Banco de Dados

O sistema utiliza MySQL com Prisma ORM. As principais entidades são:

• User: Profissionais (Admin, Coordenador, Médico, ACS, Farmacêutico)
• Patient: Pacientes cadastrados
• Consultation: Consultas médicas
• VitalSigns: Sinais vitais dos pacientes
• Notification: Sistema de notificações
• Equipment: Equipamentos utilizados pela equipe

---

🔗 APIs

📌 Endpoints Principais

Autenticação

• POST /api/auth/login: Login de usuário

Pacientes

• GET /api/patients: Lista todos os pacientes
• GET /api/patients/{id}: Busca paciente por ID
• POST /api/patients: Cadastra novo paciente
• PUT /api/patients/{id}: Atualiza dados do paciente
• DELETE /api/patients/{id}: Remove paciente

Consultas

• GET /api/consultations: Lista todas as consultas
• POST /api/consultations: Agenda nova consulta
• GET /api/consultations/{id}: Busca consulta por ID
• PUT /api/consultations/{id}: Atualiza consulta
• DELETE /api/consultations/{id}: Cancela consulta

Sinais Vitais

• GET /api/vital-signs: Lista registros de sinais vitais
• POST /api/vital-signs: Registra novos sinais vitais
• GET /api/vital-signs/{id}: Busca registro por ID

Usuários

• GET /api/users: Lista todos os usuários
• POST /api/users: Cadastra novo usuário
• GET /api/users/{id}: Busca usuário por ID
• PUT /api/users/{id}: Atualiza usuário
• DELETE /api/users/{id}: Desativa usuário

---

🔒 Autenticação e Autorização

O sistema utiliza JWT (JSON Web Tokens) para autenticação. O fluxo é:

1. Usuário faz login com email/senha
2. Sistema valida credenciais e gera token JWT
3. Token deve ser enviado no header Authorization: Bearer {token}
4. Middleware auth.middleware.ts valida o token em cada requisição protegida

👤 Roles de Usuário

• ADMIN: Acesso total ao sistema
• COORDINATOR: Gestão de equipes e relatórios
• DOCTOR: Atendimento médico e prontuários
• ACS: Agendamento e pré-consultas
• PHARMACIST: Gestão de medicamentos

---

🛡️ Middlewares

🛡️ auth.middleware.ts

• Valida token JWT
• Verifica permissões do usuário
• Injeta informações do usuário na requisição

🌐 cors.middleware.ts

• Configura CORS para a API
• Permite requisições de origens específicas
• Configura métodos HTTP permitidos

---

📝 Guia de Desenvolvimento

⚙️ Configuração do Ambiente

1. Clone o repositório
2. Instale as dependências:

   npm install

3. Configure as variáveis de ambiente:

   DATABASE_URL="mysql://user:password@localhost:3306/database"
   JWT_SECRET="seu-secret-aqui"
   

4. Execute as migrações do banco:

   npx prisma migrate dev

5. Inicie o servidor de desenvolvimento:

   npm run dev

✅ Boas Práticas

1. TypeScript

   • Use tipos explícitos
   • Evite any
   • Mantenha interfaces atualizadas

2. API

   • Valide inputs com Zod
   • Use try/catch para tratamento de erros
   • Mantenha a documentação Swagger atualizada

3. Banco de Dados

   • Use transações quando necessário
   • Mantenha índices atualizados
   • Faça migrações para alterações no schema

4. Segurança

   • Nunca exponha senhas ou dados sensíveis
   • Sempre valide permissões
   • Use HTTPS em produção

🔁 Fluxo de Trabalho Recomendado

1. Crie uma nova branch para cada feature
2. Implemente os testes necessários
3. Mantenha a documentação atualizada
4. Faça code review antes de mergear
5. Siga o padrão de commits convencional

📄 Documentação Adicional

• Prisma Documentation
• Next.js Documentation
• TypeScript Documentation

---

💬 Suporte

Para dúvidas ou suporte, entre em contato com a equipe de desenvolvimento ou abra uma issue no repositório.