Referral MVP — Documentação

Documentação do projeto referral-mvp — explicação do sistema, fluxos, endpoints, diagramas (Mermaid), passos para rodar, testes e próximos passos.

1. Visão Geral

O Referral MVP é um sistema para gerenciar encaminhamentos (referrals) entre indicadores, profissionais e usuários/pacientes. Ele inclui cadastro de usuários, criação de referrals, agendamento, status do encaminhamento e integração com notificações/agenda.

Objetivos principais:

Registrar encaminhamentos com status (PENDING, SCHEDULED, COMPLETED).
Permitir que profissionais e administradores visualizem e atualizem o status.
Expor API RESTful para frontend (Next.js/React) e possivelmente microservices.
Facilitar autenticação via JWT/Cognito (ou outro provedor).

2. Principais entidades (modelo lógico)

Abaixo está o modelo de dados em alto nível (ER). Ajuste os nomes conforme seu schema.prisma.

3. Enumerações sugeridas

enum Role { ADMIN, INDICATOR, PROFESSIONAL }
enum ReferralStatus { PENDING, SCHEDULED, COMPLETED }

4. Endpoints principais (API REST)

Autenticação

POST /auth/login — recebe email/senha ou token do provedor, retorna { accessToken, refreshToken, idToken }.
POST /auth/refresh — troca refresh token por novo access token.

Usuários

GET /users — (admin) lista usuários.
GET /users/:id — detalhes do usuário.
POST /users — cria usuário.

Professionals

GET /professionals
POST /professionals

Referrals

GET /referrals — lista com filtros (status, indicatorId, professionalId, createdFrom, createdTo).
GET /referrals/:id — detalhes.
POST /referrals — cria referral.
PUT /referrals/:id — atualiza campos (status, scheduledAt, notes).
DELETE /referrals/:id — remove (soft-delete preferível).

Exemplo: criar referral

Request POST /referrals

{
  "patientId": "uuid",
  "indicatorId": "uuid",
  "professionalId": "uuid",
  "notes": "Observações",
}

Response 201

{
  "id": "uuid",
  "code": "REF-2025-0001",
  "status": "PENDING",
  "createdAt": "2025-10-06T..."
}

5. Fluxos principais (Mermaid)

5.1 Fluxo de criação de referral

5.2 Fluxo de agendamento

5.3 Autenticação com JWT (fluxo)

6. Arquitetura recomendada

Notas:

Use Redis para cache e rate-limiting.
Use filas (RabbitMQ / SQS) para tarefas que enviam notificações e criam eventos no calendário.
Use testes unitários e integração com Jest/Playwright.

7. Configuração e execução local

Requisitos

Node.js >= 18
pnpm/yarn/npm
PostgreSQL 14+
Docker (opcional: executar postgres em container)

Variáveis de ambiente (exemplo `.env`)

DATABASE_URL=postgresql://admin:password@localhost:5432/referraldb
JWT_SECRET=uma_chave_secreta
PORT=4000
COGNITO_POOL_ID=...
NOTIFICATION_URL=http://localhost:9000

Scripts úteis

# instalar
pnpm install
# rodar migrations (Prisma)
npx prisma migrate dev --name init
# gerar client prisma
npx prisma generate
# rodar em dev
pnpm dev
# rodar testes
pnpm test

8. Observabilidade e monitoramento

Logs estruturados (JSON) — Winston/Pino.
Métricas — Prometheus + Grafana.
Tracing — OpenTelemetry.
Alertas para filas atrasadas, erros 5xx, latência alta.

9. Segurança

Tudo via HTTPS em produção.
Validar e sanitizar inputs.
Rate limit nos endpoints sensíveis.
Armazenar refresh tokens com segurança (httpOnly cookies) ou em DB com expirations.
Proteção contra RBAC: checar Role antes de ações administrativas.

10. Testes e QA

Unit tests para services e controllers (Jest).
Integration tests para endpoints (supertest).
E2E para fluxos críticos (Playwright).

11. Estrutura de pastas sugerida

/referral-mvp
  /apps
    /api
    /web
  /packages
    /db (Prisma schema)
    /auth
    /shared (types, utils)
  docker-compose.yml
  .env.example
  README.md

12. CI/CD (sugestão)

GitHub Actions pipeline:
1. Lint (ESLint + Prettier)
2. Test (unit + integration)
3. Build
4. Deploy (staging -> production) usando Terraform/CloudFormation ou serverless deploy

Referral MVP