# Fluxos Principais

## 1. Convenções

Cada fluxo indica actor, pré-condições, sequência, excepções e resultado. Toda mudança de estado guarda data, actor e motivo quando aplicável.

## 2. Registo de paciente

**Actor:** recepcionista ou utilizador autorizado.  
**Pré-condição:** sessão activa e permissão `patients.create`.

1. Informar dados mínimos, contactos e responsável quando aplicável.
2. Pesquisar automaticamente possíveis duplicados.
3. Se houver correspondência forte, abrir o registo existente ou confirmar criação excepcional com motivo.
4. Registar consentimentos apresentados e decisão do paciente.
5. Gerar número clínico único.
6. Guardar auditoria e apresentar ficha do paciente.

**Excepções:** emergência pode permitir dados provisórios; o registo fica sinalizado para regularização.  
**Resultado:** paciente activo, sem apagar eventuais alertas de duplicidade.

## 3. Configuração da disponibilidade

1. Gestor configura serviço, duração e preço vigente.
2. Regista horário recorrente do profissional.
3. Regista pausas, férias, indisponibilidades e feriados.
4. Sistema calcula vagas sem sobreposição.
5. Alteração futura não move marcações existentes; conflitos resultantes são apresentados para resolução.

## 4. Marcação

**Actor:** recepcionista ou paciente no portal.

1. Seleccionar paciente, serviço e preferência de profissional/data.
2. Sistema apresenta somente vagas válidas.
3. Seleccionar vaga; o sistema volta a validar concorrência antes de guardar.
4. Calcular preço e política de pré-pagamento.
5. Criar como `a_aguardar_pagamento` quando exigido; caso contrário, `agendada`.
6. Registar origem e histórico.
7. Enfileirar confirmação/notificação autorizada.

**Excepção:** conflito autorizado exige `schedules.override_conflict` e motivo.  
**Resultado:** marcação única e rastreável.

## 5. Estados da marcação

```text
pendente -> a_aguardar_pagamento -> agendada -> confirmada
pendente --------------------------> agendada
agendada/confirmada -> reagendada -> agendada ou a_aguardar_pagamento
agendada/confirmada -> cancelada
confirmada -> chegada_registada -> em_atendimento -> concluida
agendada/confirmada/chegada_registada -> falta
```

Regras:

- `cancelada`, `concluida` e `falta` são estados finais.
- `reagendada` encerra a ocorrência anterior e liga a uma nova data.
- `em_atendimento` cria ou activa a consulta clínica.
- saltos exigem uma transição explicitamente autorizada; não se actualiza estado directamente na base de dados.

## 6. Confirmação de pagamento e marcação

1. Registar pagamento como pendente ou confirmado conforme origem.
2. Validar montante, método e referência.
3. Alocar valor à factura.
4. Quando o mínimo de pré-pagamento for atingido, mover marcação para `agendada`.
5. Emitir recibo apenas pelo valor confirmado.
6. Auditar operação e enfileirar notificação.

Falha ou pagamento insuficiente mantém saldo e estado pendentes. Confirmação manual exige permissão própria.

## 7. Chegada e triagem

1. Recepção confirma identidade e regista chegada.
2. Enfermeiro chama paciente atribuído.
3. Confirma alertas e regista sinais vitais com unidades.
4. Regista queixa inicial e observações permitidas.
5. Finaliza triagem sem apagar medições anteriores.
6. Médico visualiza a triagem no atendimento.

## 8. Consulta clínica

1. Médico abre a marcação atribuída.
2. Sistema valida identidade, permissão e estado.
3. Médico inicia atendimento; é criada a consulta.
4. Consulta histórico, alergias e sinais vitais.
5. Regista anamnese, exame, diagnósticos e plano.
6. Emite prescrição/documentos quando necessário.
7. Confirma campos mínimos e conclui.
8. Sistema bloqueia edição comum, regista auditoria e publica apenas documentos autorizados.

**Correcção posterior:** criar adenda com motivo, conteúdo, autor e data; o original permanece visível.

## 9. Facturação e pagamento

1. Criar factura provisória a partir do serviço e itens adicionais.
2. Aplicar desconto apenas com permissão e aprovação quando exigida.
3. Emitir factura, fixando numeração e valores.
4. Registar pagamento e referência.
5. Confirmar pagamento e alocar à factura dentro de uma transacção.
6. Actualizar saldo: `pendente`, `parcial` ou `paga`.
7. Emitir recibo do valor confirmado.
8. Incluir movimento no fecho diário.

**Estorno/reembolso:** solicitar, aprovar, criar movimento inverso, actualizar saldo e emitir documento de correcção; nunca apagar o original.

## 10. Cancelamento e reagendamento

1. Localizar marcação e verificar estado.
2. Registar motivo e solicitante.
3. Calcular eventual multa, crédito ou reembolso segundo política.
4. Para cancelamento, libertar vaga e encerrar como `cancelada`.
5. Para reagendamento, escolher nova vaga válida, encerrar ocorrência anterior como `reagendada` e ligar ambas.
6. Registar auditoria e notificar.

Não é permitido cancelar ou reagendar uma consulta concluída.

## 11. Falta

1. Depois do horário e tolerância configurada, utilizador autorizado marca falta.
2. Sistema regista actor, momento e observação.
3. Aplica política financeira configurada sem apagar o pagamento.
4. Notifica o paciente quando autorizado.

## 12. Portal do paciente

1. Paciente autentica-se por conta vinculada.
2. Sistema determina paciente/dependentes autorizados.
3. Portal mostra apenas dados próprios e documentos publicados.
4. Nova marcação segue disponibilidade e pagamento normais.
5. Pedido de alteração sensível cria solicitação para validação.
6. Visualizações e downloads clínicos ficam auditados.

## 13. Suspensão de utilizador

1. Administrador abre a conta e informa motivo.
2. Sistema impede auto-suspensão quando deixaria o sistema sem administrador activo.
3. Suspende a conta e termina sessões/tokens.
4. Preserva autoria histórica de todos os registos.
5. Regista auditoria.

## 14. Acesso clínico de emergência

1. Profissional sem atribuição solicita acesso excepcional.
2. Informa motivo obrigatório e confirma aviso de auditoria.
3. Sistema concede acesso temporário e limitado.
4. Evento recebe destaque para revisão do gestor clínico.
5. Expiração remove o acesso sem afectar os registos criados legitimamente.

## 15. Validações transversais

- Revalidar autorização e estado no servidor em cada acção.
- Usar transacção em marcação concorrente, facturação e pagamentos.
- Mostrar erro claro sem expor dados técnicos ou sensíveis.
- Impedir submissão duplicada por clique repetido.
- Guardar auditoria antes de apresentar sucesso em operação crítica.