# Arquitectura do Sistema

## 1. Contexto

Aplicação web Laravel 12, inicialmente monolítica e modular, com MySQL. O monólito reduz custo operacional e mantém transacções clínicas e financeiras consistentes. Separação em serviços só será considerada quando existir necessidade comprovada.

## 2. Princípios

- modularidade por domínio;
- autorização no servidor e negação por padrão;
- regras de negócio fora de controllers e views;
- dados clínicos e financeiros imutáveis após consolidação;
- transacções para operações compostas;
- auditoria como requisito transversal;
- configurações tipadas e versionadas;
- filas para trabalho externo;
- testes centrados em riscos;
- preparação white-label sem complexidade SaaS prematura.

## 3. Domínios

- Organização e configurações.
- Identidade, autenticação e autorização.
- Pacientes, responsáveis e consentimentos.
- Profissionais, especialidades e serviços.
- Agenda e marcações.
- Processo clínico.
- Facturação e pagamentos.
- Documentos.
- Notificações.
- Relatórios e auditoria.
- Portal do paciente.

## 4. Camadas

### Interface

Rotas, controllers, requests, views/componentes e recursos de resposta. Recebe dados, chama casos de uso e apresenta resultados; não decide regras críticas.

### Aplicação

Casos de uso como criar marcação, concluir consulta ou confirmar pagamento. Coordena autorização contextual, transacções, eventos e auditoria.

### Domínio

Modelos, estados, políticas, regras, objectos de valor e transições. Não depende da apresentação.

### Infra-estrutura

Base de dados, ficheiros, email, filas, pagamentos e integrações. Implementações externas ficam atrás de contratos quando houver mais de um fornecedor ou necessidade de testes.

## 5. Organização Laravel prevista

```text
app/
├── Actions/
├── Enums/
├── Events/
├── Exceptions/
├── Http/
│   ├── Controllers/
│   ├── Middleware/
│   └── Requests/
├── Jobs/
├── Models/
├── Notifications/
├── Policies/
├── Providers/
├── Services/
└── Support/
```

Não criar abstrações vazias antecipadamente. Uma Action representa um caso de uso relevante; Services agrupam lógica coesa que não pertence a um único modelo.

## 6. Autenticação e autorização

- autenticação baseada nos mecanismos seguros do Laravel;
- policies para entidades e permissões para capacidades;
- perfis agregam permissões;
- contexto restringe a organização e o registo atribuído;
- acesso clínico de emergência é temporário e auditado;
- administrador técnico não recebe acesso clínico implícito.

## 7. Contexto organizacional

Após autenticação, middleware resolve a organização permitida e disponibiliza um contexto imutável para a requisição. Models pertencentes a organizações aplicam filtros e validações consistentes. Jobs recebem o identificador explicitamente e reconstroem o contexto antes de trabalhar.

Filtros automáticos ajudam, mas não substituem policies, constraints e testes.

## 8. Estados e transições

Estados usam enums e serviços/actions específicos. Nenhum controller deve atribuir livremente um texto de estado.

Cada transição:

- valida estado de origem;
- verifica permissão e contexto;
- valida pré-condições;
- executa em transacção quando necessário;
- grava histórico e auditoria;
- publica evento depois do commit.

## 9. Dinheiro

- valores em `DECIMAL`, representados no código por objecto de valor ou unidades menores controladas;
- moeda explícita;
- totais calculados no servidor;
- facturas emitidas preservam itens e preços;
- pagamentos e estornos são movimentos imutáveis;
- alocações ligam pagamentos a facturas;
- reconciliação nunca depende apenas de um campo `status`.

## 10. Processo clínico

- marcação e consulta são entidades diferentes;
- consulta só existe quando o atendimento começa;
- notas concluídas recebem adendas, não sobrescrita;
- alergias e alertas activos são destacados;
- leitura e exportação são auditadas;
- anexos usam armazenamento privado e links temporários autorizados.

## 11. Configurações e cache

Configurações críticas usam tabelas especializadas; preferências simples podem usar catálogo tipado. A aplicação lê por um serviço central que aplica padrão, âmbito e cache. Alterações invalidam apenas chaves relacionadas.

Nunca usar `.env` para valores que administradores precisam alterar na interface. Usar `.env` para segredos e parâmetros da instalação.

## 12. Eventos, filas e notificações

Eventos internos representam factos concluídos. Envios externos e geração pesada de documentos usam filas. Jobs devem ser idempotentes, possuir tentativas limitadas e registar falhas sem duplicar pagamentos ou mensagens.

Eventos dependentes de dados gravados só são enviados depois do commit da transacção.

## 13. Ficheiros

- armazenamento privado por padrão;
- caminhos separados por organização e tipo;
- nomes físicos imprevisíveis;
- metadados e checksum na base;
- tipo e tamanho validados;
- downloads por controller/policy ou URL temporária;
- ficheiros públicos limitados a identidade visual aprovada.

## 14. Auditoria e logs

Auditoria de negócio é separada dos logs técnicos. Guarda actor, organização, acção, entidade, momento, origem e alterações permitidas. Palavras-passe, tokens, dados completos de cartões e segredos são sempre removidos.

## 15. Relatórios

Relatórios usam consultas dedicadas e índices, respeitando o mesmo contexto de autorização. Exportações grandes usam filas e ficheiros temporários com expiração. Totais financeiros devem ser conciliáveis com movimentos de origem.

## 16. Testes

- unitários para cálculos e transições;
- feature para casos de uso e autorização;
- integração para base de dados, filas e fornecedores simulados;
- isolamento entre organizações;
- concorrência de vagas e pagamentos idempotentes;
- regressão para processo clínico e financeiro.

## 17. Ambientes

- local: desenvolvimento e dados fictícios;
- homologação: demonstração com dados fictícios e configuração semelhante à produção;
- produção: dados reais, HTTPS, backups, monitorização e acesso restrito.

Cada ambiente possui chaves, base de dados, armazenamento e fornecedores separados.

## 18. Decisões adiadas

- pacote específico de perfis/permissões;
- interface Blade/Livewire ou alternativa;
- fornecedor de armazenamento externo;
- fornecedores de SMS/WhatsApp e pagamentos;
- base partilhada versus base por organização em futura oferta SaaS;
- motor de geração de PDFs;
- pesquisa avançada.

Essas decisões serão tomadas antes do módulo que delas dependa, com registo de decisão arquitectural.