# Modelo Conceptual da Base de Dados

## 1. Estado do documento

Modelo conceptual inicial para validar entidades, propriedade e relações. Os campos exactos, tipos, índices e migrations serão detalhados antes da implementação de cada módulo.

O detalhamento físico está em `esquema-base-de-dados.md`.

## 2. Convenções

- chaves primárias internas: `id`;
- entidades white-label relevantes: `organization_id` obrigatório;
- datas técnicas: `created_at`, `updated_at` e, quando permitido, `deleted_at`;
- estados: enums controlados no código e validados na base quando adequado;
- dinheiro: `decimal` com moeda explícita;
- datas/hora armazenadas em UTC;
- documentos clínicos e financeiros consolidados não usam eliminação física;
- chaves visíveis, como número clínico e factura, são separadas do `id`.

## 3. Organizações e configuração

### `organizations`

Identidade e estado da organização: nome comercial, nome jurídico, NUIT, locale, moeda, fuso horário e estado.

### `organization_branding`

Logótipos, ícone e cores semânticas. Pode guardar versões publicadas.

### `organization_domains`

Domínios verificados, tipo, estado e datas de verificação.

### `organization_settings`

Preferências simples tipadas por chave. Configurações críticas permanecem em tabelas próprias.

### `organization_features`

Módulos disponíveis, estado e período de activação.

### `units`

Unidades físicas, endereço, contactos, fuso e estado.

## 4. Identidade e autorização

### `users`

Autenticação, nome, email/telefone verificados, estado, primeiro acesso e último acesso. Não guarda dados clínicos ou profissionais específicos.

### `organization_user`

Vínculo do utilizador à organização, estado e unidade padrão.

### `roles`, `permissions`, `role_user`, `permission_role`

Perfis e capacidades. O vínculo do perfil deve incluir organização quando o perfil não for global da instalação.

### `emergency_access_grants`

Acesso clínico excepcional: requerente, paciente, motivo, início, expiração e revisão.

## 5. Pacientes

### `patients`

Número clínico por organização, nome, nascimento/idade estimada, sexo clínico quando necessário, estado e dados administrativos.

### `patient_identifiers`

Tipo, número, país emissor, validade e verificação.

### `patient_contacts`

Telefone, email, endereço, preferência e verificação.

### `patient_representatives`

Responsáveis/dependentes, relação, período de validade e poderes autorizados.

### `patient_consents`

Tipo, versão, decisão, momento, origem, responsável e revogação.

### `allergies`, `chronic_conditions`

Alertas clínicos estruturados, estado, severidade, observação, autor e datas.

## 6. Profissionais e catálogo

### `staff_profiles`

Dados funcionais de colaboradores, cargo, unidade e estado.

### `professionals`

Dados regulatórios dos profissionais de saúde, número de ordem, estado e utilizador associado.

### `specialties`, `professional_specialty`

Especialidades e vínculo dos profissionais.

### `services`

Serviços, código, nome, duração, preço, política de pagamento e estado.

### `service_prices`

Histórico de preços por serviço, unidade, moeda e período de vigência.

## 7. Agenda

### `schedules`

Disponibilidade recorrente por profissional, unidade, dia e intervalo.

### `schedule_breaks`

Pausas recorrentes.

### `unavailabilities`

Férias, bloqueios e outras indisponibilidades com início, fim e motivo.

### `holidays`

Feriados globais ou por unidade.

### `appointments`

Paciente, profissional, serviço, unidade, início/fim, estado, origem, preço previsto e política aplicada.

### `appointment_status_history`

Estado anterior/novo, actor, momento e motivo.

### `appointment_links`

Relação entre marcação original e nova em reagendamento.

## 8. Processo clínico

### `consultations`

Ligação à marcação, paciente, médico, início, conclusão, estado e versão.

### `triages`

Queixa inicial, prioridade, autor e momento.

### `vital_signs`

Medições tipadas, valor, unidade, autor e momento.

### `consultation_notes`

Secções clínicas, conteúdo, autor, versão e estado.

### `diagnoses`

Diagnóstico, código de classificação quando usado, tipo, estado e autor.

### `consultation_addenda`

Adendas imutáveis com motivo, conteúdo, autor e momento.

### `prescriptions`, `prescription_items`

Prescrição emitida e respectivos medicamentos, dosagem, frequência, via, duração e instruções.

### `clinical_attachments`

Metadados de ficheiros privados, tipo, checksum, autor e ligação clínica.

## 9. Facturação

### `invoices`

Organização, unidade, paciente, série, número, emissão, moeda, totais, saldo e estado.

### `invoice_items`

Descrição preservada, quantidade, preço unitário, desconto, imposto e total.

### `payments`

Pagador, método, valor, moeda, referência, estado e responsável.

### `payment_allocations`

Valor de um pagamento aplicado a uma factura.

### `payment_transactions`

Movimentos de confirmação, falha, estorno e ajuste, sempre imutáveis.

### `refunds`

Pedido, aprovação, valor, motivo e movimento relacionado.

### `receipts`

Série, número, pagamento/alocações, total e versão do documento.

### `cash_sessions`

Abertura, movimentos, valor esperado, valor contado, diferença e fecho.

## 10. Documentos e notificações

### `document_templates`, `document_template_versions`

Modelos seguros, versões, identidade e estado de publicação.

### `documents`

Documento emitido, número, versão do modelo, entidade de origem, armazenamento, checksum e publicação no portal.

### `notification_templates`

Modelo por evento, canal, idioma e versão.

### `notifications`, `notification_attempts`

Destinatário, canal, estado, consentimento, tentativas e erros higienizados.

## 11. Auditoria

### `audit_logs`

Organização, actor, acção, entidade, identificador, valores permitidos, IP, agente, correlação e momento.

### `data_exports`

Solicitante, finalidade, filtros, ficheiro temporário, estado e expiração.

## 12. Restrições essenciais

- número clínico único por organização;
- documento do paciente único por organização, tipo, país e número;
- email/telefone autenticável normalizado conforme âmbito definido;
- número de factura e recibo únicos por organização, série e unidade aplicável;
- referência de pagamento única por organização e prestador quando preenchida;
- intervalos positivos e fim posterior ao início;
- valores financeiros não negativos, salvo movimento de correcção explicitamente tipado;
- alocações não excedem pagamento confirmado nem saldo permitido;
- relações entre entidades exigem a mesma organização;
- uma consulta pertence no máximo a uma marcação e mantém paciente consistente.

## 13. Índices iniciais

- todas as chaves estrangeiras;
- `(organization_id, status)` em entidades operacionais;
- paciente por número clínico, nome normalizado, telefone e documento;
- marcações por profissional/início, paciente/início e unidade/início;
- consultas por paciente/data e médico/data;
- facturas por número, paciente/data e estado;
- pagamentos por referência, data e estado;
- auditoria por organização/data, actor/data e entidade/identificador.

Índices serão confirmados com consultas reais; não indexar indiscriminadamente textos clínicos sensíveis.

## 14. Eliminação e retenção

- dados de referência podem ser inactivados;
- rascunhos sem efeitos podem admitir eliminação controlada;
- processos clínicos, documentos emitidos e movimentos financeiros não são eliminados;
- dados pessoais seguem política de retenção e eventual anonimização juridicamente validada;
- auditoria possui retenção própria e acesso restrito.

## 15. Sequência de implementação

1. organizações, unidades e utilizadores;
2. perfis, permissões e auditoria;
3. pacientes, contactos, representantes e consentimentos;
4. profissionais, especialidades, serviços e preços;
5. agenda e marcações;
6. processo clínico;
7. facturação e pagamentos;
8. documentos, notificações e relatórios.

## 16. Decisões ainda necessárias

- estratégia definitiva de identificadores públicos;
- pacote ou implementação de permissões;
- campos clínicos obrigatórios por especialidade;
- regras fiscais e séries documentais;
- retenção legal;
- base partilhada ou separada numa futura versão multi-organização;
- mecanismo de pesquisa e eventual encriptação de campos pesquisáveis.