Fluxos Principais do Sistema¶

Este documento descreve os principais fluxos do Billings Ease, desde autenticação até análise de ciclos.

1. Autenticação¶

1.1. Registro de Usuário¶

sequenceDiagram
    participant C as Cliente (Web/Mobile)
    participant B as Backend API
    participant DB as PostgreSQL
    participant E as Email Service

    C->>B: POST /api/auth/register
    Note over C,B: { email, password, name, user_type }
    B->>B: Validar dados
    B->>DB: Verificar se email já existe
    DB-->>B: Resultado
    B->>B: Hash da senha
    B->>DB: Criar usuário
    DB-->>B: Usuário criado
    B->>E: Enviar email de verificação
    E-->>B: Email enviado
    B-->>C: 201 Created + { user, message }

Endpoints: - POST /api/auth/register - Registro inicial - POST /api/auth/verify-email - Verificar email - POST /api/auth/resend-verification - Reenviar email

Fluxo: 1. Usuário preenche formulário de registro 2. Backend valida dados e verifica se email já existe 3. Senha é hasheada (bcrypt) 4. Usuário é criado com email_verified = false 5. Email de verificação é enviado (via SendGrid) 6. Usuário clica no link do email 7. Backend marca email_verified = true

sequenceDiagram
    participant C as Cliente
    participant B as Backend API
    participant DB as PostgreSQL

    C->>B: POST /api/auth/login
    Note over C,B: { email, password }
    B->>DB: Buscar usuário por email
    DB-->>B: Usuário encontrado
    B->>B: Verificar senha (bcrypt)
    B->>B: Gerar JWT token
    B->>B: Gerar refresh token
    B-->>C: 200 OK + { token, refresh_token, user }
    C->>C: Armazenar tokens (localStorage/SecureStore)

Endpoint: POST /api/auth/login

Resposta:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "Nome",
    "user_type": "client"
  }
}

Armazenamento: - Web: localStorage.setItem('token', token) - Mobile: SecureStore.setItemAsync('token', token)

1.3. Refresh Token¶

sequenceDiagram
    participant C as Cliente
    participant B as Backend API

    C->>B: POST /api/auth/refresh
    Note over C,B: { refresh_token }
    B->>B: Validar refresh token
    B->>B: Gerar novo JWT token
    B-->>C: 200 OK + { token }

Endpoint: POST /api/auth/refresh

Quando usar: - Token JWT expirou (24 horas) - Cliente ainda tem refresh token válido (7 dias)

1.4. Recuperação de Senha¶

sequenceDiagram
    participant C as Cliente
    participant B as Backend API
    participant E as Email Service

    C->>B: POST /api/auth/forgot-password
    Note over C,B: { email }
    B->>B: Gerar token de reset
    B->>B: Salvar token no banco
    B->>E: Enviar email com link
    E-->>B: Email enviado
    B-->>C: 200 OK + { message }

    Note over C: Usuário clica no link do email

    C->>B: POST /api/auth/reset-password
    Note over C,B: { token, new_password }
    B->>B: Validar token
    B->>B: Atualizar senha
    B-->>C: 200 OK + { message }

Endpoints: - POST /api/auth/forgot-password - Solicitar reset - POST /api/auth/reset-password - Redefinir senha

2. Registro Diário do Ciclo¶

2.1. Criar Observação Diária¶

sequenceDiagram
    participant C as Cliente
    participant B as Backend API
    participant S as Fertility Service
    participant DB as PostgreSQL

    C->>B: POST /api/observations
    Note over C,B: { date, symbol_id, sensation_id, appearance_id, ... }
    B->>B: Validar dados
    B->>DB: Verificar ciclo ativo
    DB-->>B: Ciclo encontrado
    B->>DB: Verificar se já existe observação no dia
    DB-->>B: Não existe
    B->>DB: Criar observação
    DB-->>B: Observação criada
    B->>S: Calcular status de fertilidade
    S->>S: Aplicar regras do Método Billings
    S-->>B: { is_fertile, intercourse_status, ... }
    B-->>C: 201 Created + { observation, fertility_status }

Endpoint: POST /api/observations

Payload:

{
  "date": "2024-01-15",
  "symbol_id": 1,
  "sensation_id": 2,
  "appearance_id": 3,
  "had_intercourse": false,
  "is_first_day_of_menstruation": false
}

Validações: - Apenas uma observação por dia por usuário - Deve existir ciclo ativo - Símbolo deve ser permitido para o dia do ciclo

2.2. Atualizar Observação¶

Endpoint: PUT /api/observations/:id

Fluxo similar ao criar, mas: - Atualiza observação existente - Recalcula status de fertilidade - Mantém constraint de uma observação por dia

3. Análise de Ciclo¶

3.1. Visualizar Status de Fertilidade¶

sequenceDiagram
    participant C as Cliente
    participant B as Backend API
    participant S as Fertility Service
    participant DB as PostgreSQL

    C->>B: GET /api/client/fertility-status?date=2024-01-15
    B->>DB: Buscar ciclo ativo
    DB-->>B: Ciclo encontrado
    B->>DB: Buscar observações do ciclo
    DB-->>B: Observações
    B->>S: GetFertilityStatus(user_id, date)
    S->>S: Aplicar regras do Método Billings
    Note over S: - Verificar sangramento<br/>- Verificar primeiros 15 dias<br/>- Verificar ápice<br/>- Aplicar regras por objetivo
    S-->>B: FertilityStatus
    B-->>C: 200 OK + { fertility_status }

Endpoint: GET /api/client/fertility-status?date=2024-01-15

Resposta:

{
  "is_fertile": false,
  "intercourse_status": "allowed_no_risk",
  "days_after_peak": null,
  "has_bleeding": false,
  "peak_date": null
}

Valores de intercourse_status: - "not_allowed" - Relação não permitida - "allowed_with_risk" - Permitida, mas com risco de gravidez - "allowed_no_risk" - Permitida, sem risco

3.2. Dashboard do Cliente¶

Endpoint: GET /api/client/statistics

Retorna: - Status de fertilidade do dia atual - Informações do ciclo ativo - Estatísticas gerais - Mensagens do dashboard

4. Pagamentos e Assinaturas¶

4.1. Criar Assinatura¶

sequenceDiagram
    participant C as Cliente
    participant B as Backend API
    participant DB as PostgreSQL

    C->>B: POST /api/subscriptions
    Note over C,B: { plan_id, payment_method }
    B->>DB: Buscar plano
    DB-->>B: Plano encontrado
    B->>B: Validar dados
    B->>DB: Criar assinatura
    B->>DB: Criar registro de pagamento
    DB-->>B: Dados criados
    B-->>C: 201 Created + { subscription, payment }

Endpoint: POST /api/subscriptions

Validações: - Usuário deve ser do tipo client - Plano deve existir e estar ativo - Não pode ter assinatura ativa simultânea

4.2. Listar Planos (Público)¶

Endpoint: GET /api/plans (público, não requer autenticação)

Retorna: Lista de planos disponíveis com preços e features

5. Comunicação Profissional ↔ Paciente¶

5.1. Vincular Paciente a Profissional¶

sequenceDiagram
    participant C as Cliente
    participant B as Backend API
    participant DB as PostgreSQL

    C->>B: POST /api/client/link-professional
    Note over C,B: { professional_id }
    B->>B: Validar profissional existe e está aprovado
    B->>DB: Criar vínculo ProfessionalPatient
    DB-->>B: Vínculo criado
    B-->>C: 201 Created + { professional_patient }

Endpoint: POST /api/client/link-professional

Validações: - Profissional deve existir - Profissional deve ter perfil aprovado - Cliente não pode estar vinculado a outro profissional (ou deve desvincular primeiro)

5.2. Enviar Mensagem¶

sequenceDiagram
    participant C as Cliente/Profissional
    participant B as Backend API
    participant DB as PostgreSQL

    C->>B: POST /api/messages
    Note over C,B: { recipient_id, content }
    B->>B: Validar destinatário existe
    B->>B: Validar relacionamento (se necessário)
    B->>DB: Criar mensagem
    DB-->>B: Mensagem criada
    B-->>C: 201 Created + { message }

Endpoint: POST /api/messages

Validações: - Cliente só pode enviar para profissional vinculado - Profissional só pode enviar para pacientes vinculados - Admin pode enviar para qualquer um

5.3. Visualizar Conversas¶

Endpoint: GET /api/messages/conversations

Retorna: Lista de conversas do usuário autenticado

5.4. Comentário Profissional em Ciclo¶

Endpoint: POST /api/cycles/:cycle_id/comments

Validações: - Apenas profissionais podem comentar - Profissional deve estar vinculado ao paciente do ciclo - Profissional deve ter perfil aprovado

6. Sincronização (Mobile)¶

6.1. Push (Enviar Dados do Mobile)¶

sequenceDiagram
    participant M as Mobile
    participant B as Backend API
    participant DB as PostgreSQL

    M->>B: POST /api/sync/push
    Note over M,B: { cycles: [...], observations: [...] }
    B->>B: Validar dados
    B->>DB: Criar/atualizar ciclos
    B->>DB: Criar/atualizar observações
    DB-->>B: Dados sincronizados
    B-->>M: 200 OK + { synced_count, conflicts }

Endpoint: POST /api/sync/push

Payload:

{
  "cycles": [
    { "sync_id": "...", "start_date": "...", ... }
  ],
  "observations": [
    { "sync_id": "...", "date": "...", ... }
  ]
}

6.2. Pull (Buscar Atualizações)¶

Endpoint: GET /api/sync/pull?last_sync=2024-01-01T00:00:00Z

Retorna: Dados atualizados desde a última sincronização

7. Perfil Profissional¶

7.1. Criar/Atualizar Perfil¶

Endpoint: POST /api/profile ou PUT /api/profile

Validações: - Apenas usuários do tipo professional - Alguns campos são obrigatórios - Perfil fica pendente até aprovação de admin

7.2. Verificar Status do Perfil¶

Endpoint: GET /api/profile/status

Retorna:

{
  "has_profile": true,
  "is_approved": false,
  "status": "pending"
}

Status possíveis: - "pending" - Aguardando aprovação - "approved" - Aprovado - "rejected" - Rejeitado

Diagramas de Fluxo Simplificados¶

Fluxo Completo: Registro Diário → Análise¶

1. Cliente acessa página de registro diário
2. Cliente seleciona símbolo, sensação, aparência
3. Cliente submete formulário
4. Backend valida dados
5. Backend cria/atualiza observação
6. Backend calcula status de fertilidade
7. Cliente visualiza resultado no dashboard

Fluxo: Onboarding de Cliente¶

1. Cliente se registra
2. Cliente verifica email
3. Cliente faz login
4. Cliente completa perfil (objetivo, etc.)
5. Cliente cria primeiro ciclo
6. Cliente começa a registrar observações

Fluxo: Onboarding de Profissional¶

1. Profissional se registra
2. Profissional verifica email
3. Profissional faz login
4. Profissional cria perfil profissional
5. Admin aprova perfil
6. Profissional pode receber pacientes