This commit is contained in:
@@ -0,0 +1,19 @@
|
||||
# ADR-001 — Identidade, autorização e acesso anónimo
|
||||
|
||||
- Estado: Aceite para orientar contratos e novas alterações; não declara implementação completa.
|
||||
- Data: 2026-10-01
|
||||
- Contexto: Laravel 13, Fortify e sessões existentes; API pública versionada e páginas Inertia. Não foi encontrado emissor/verificador JWT configurado.
|
||||
|
||||
## Decisão
|
||||
|
||||
Usar a sessão Laravel como mecanismo primário para browser/Inertia e para operações privadas same-origin, com CSRF, verificação de email quando aplicável, MFA nas áreas já protegidas e autorização explícita por Policy/Gate para cada recurso. Endpoints anónimos são uma allowlist de leitura/submissão pública, com validação, limitação de pedidos e resposta mínima. A existência de uma rota sob `/api` não a torna pública. Não introduzir JWT nem bearer tokens sem consumidor externo, ciclo de vida, audiência, rotação e revogação contratados. Não confiar em IDs enviados pelo cliente para autorizar acesso.
|
||||
|
||||
## Alternativas consideradas
|
||||
|
||||
- JWT para toda a aplicação: rejeitado; não há necessidade demonstrada e duplicaria a sessão existente.
|
||||
- Um gate global de gestor: insuficiente para autorização por recurso; manter as verificações actuais como barreira adicional, com Policies por domínio.
|
||||
- Tornar toda a API pública: rejeitado; publicar só operações explicitamente inventariadas.
|
||||
|
||||
## Consequências e validação futura
|
||||
|
||||
Contratos devem declarar `security` por operação e casos anónimo/autenticado/negado. Privacidade SQL/RLS é decisão separada no ADR-007. Alterações futuras precisam de testes positivos e negativos. Esta ADR não converte o gate `manage-portal` em RBAC completo.
|
||||
@@ -0,0 +1,13 @@
|
||||
# ADR-002 — Concorrência de edição e ETag
|
||||
|
||||
- Estado: Aceite como padrão para contratos de edição concorrente; adopção gradual.
|
||||
- Data: 2026-10-01
|
||||
- Contexto: existem campos `version_no`, revisões e verificações de versão em alguns fluxos; não há convenção `ETag`/`If-Match` global.
|
||||
|
||||
## Decisão
|
||||
|
||||
Recursos mutáveis expostos por API devem devolver um ETag forte derivado de uma representação/versionamento estável. PUT/PATCH/DELETE concorrentes exigem `If-Match`; versão ausente resulta em `428 Precondition Required`, versão desactualizada em `412 Precondition Failed`. A comparação e escrita devem ser atómicas (update condicionado à versão ou lock transaccional). Respostas devolvem novo ETag. Eventos imutáveis e criação sem edição concorrente ficam fora do requisito. Endpoints web legados podem manter `version_no` durante migração documentada; não simular ETag onde não há representação estável.
|
||||
|
||||
## Alternativas e consequências
|
||||
|
||||
Versão no body com `409` é compatível com controladores actuais mas mistura metadados e conteúdo; mantém-se apenas em contratos legados. Lock pessimista isolado não protege clientes entre pedidos. Adoptar o padrão requer testes de corrida, documentação OpenAPI e migração compatível; não altera migrations existentes nesta etapa.
|
||||
@@ -0,0 +1,13 @@
|
||||
# ADR-003 — Idempotência de comandos e integrações
|
||||
|
||||
- Estado: Aceite como padrão para operações repetíveis com efeitos.
|
||||
- Data: 2026-10-01
|
||||
- Contexto: há recibos idempotentes territoriais, chaves em outbox e `insertOrIgnore` localizados, mas não contrato uniforme.
|
||||
|
||||
## Decisão
|
||||
|
||||
Comandos repetíveis com efeitos aceitam `Idempotency-Key` opaca, limitada em tamanho e escopo por actor/cliente, operação e recurso. Persistir chave, hash canónico dos parâmetros relevantes, estado e resultado mínimo por janela de retenção aprovada; a mesma chave e mesmo pedido reproduzem a resposta, a mesma chave com payload diferente produz conflito. A criação do recibo e a mutação de negócio pertencem à mesma transacção. Jobs e consumidores deduplicam por identificador de evento e guardam progresso sem reexecutar efeitos já confirmados. Não registar a chave em claro em logs; guardar apenas referência/hash adequado. Retenção não é fixada aqui.
|
||||
|
||||
## Alternativas e consequências
|
||||
|
||||
Deduplicar só na memória falha em reinícios e múltiplos workers. Usar só UUID do recurso não cobre criação repetida. Integrações externas exigem reconciliação e chave do destinatário; não se promete exactly-once, mas entrega pelo menos uma vez com consumidor idempotente. Cada API define respostas de replay e conflito.
|
||||
@@ -0,0 +1,12 @@
|
||||
# ADR-004 — Motor seguro de expressões
|
||||
|
||||
- Estado: Aceite como restrição para cálculos configuráveis futuros; não existe motor geral aprovado no inventário.
|
||||
- Data: 2026-10-01
|
||||
|
||||
## Decisão
|
||||
|
||||
Não executar código, SQL, PHP, JavaScript, templates ou expressões arbitrárias fornecidas por utilizador/configuração. Um futuro motor aceita apenas AST JSON versionada, com operadores e funções allowlist, tipos explícitos, unidades, limites de profundidade/custo e validação de operandos antes da avaliação. Sem reflexão, I/O, rede, acesso a relógio aleatório ou estado mutável. Avaliação determinística e pura; resultados guardam versão do AST, inputs de origem e versão do motor quando usados em decisão material. Invalidar entrada fora da gramática; sem fallback silencioso. Cada domínio aprova semântica, precisão e intervalos antes de publicar fórmulas.
|
||||
|
||||
## Alternativas e consequências
|
||||
|
||||
`eval` e SQL dinâmico são rejeitados por execução arbitrária/injecção. Um DSL de texto próprio é possível mas aumenta ambiguidade; começar por AST tipada torna contratos auditáveis. Este ADR não define fórmulas, taxas, limiares ou interpretação fiscal.
|
||||
@@ -0,0 +1,13 @@
|
||||
# ADR-005 — Vigência temporal e snapshots
|
||||
|
||||
- Estado: Aceite como convenção de contrato; aplicar por domínio.
|
||||
- Data: 2026-10-01
|
||||
- Contexto: schema usa `valid_from`/`valid_until`, `valid_to`, revisões e snapshots; não há convenção temporal única para todo o legado.
|
||||
|
||||
## Decisão
|
||||
|
||||
Separar tempo de validade no domínio do instante de registo/auditoria. Para novos intervalos de validade com datas, adoptar intervalo inclusivo no início e exclusivo no fim (`[valid_from, valid_to)`), `valid_from` obrigatório quando a regra de domínio o exigir e fim aberto representado por NULL; UTC/timestamptz para instantes e date para vigência civil. Snapshots imutáveis guardam versão do catálogo e IDs de origem quando resultado depende de dados versionados. Não reescrever semântica de colunas existentes (`valid_until`, `expires_at`, `published_at`) até migração contratual específica; documentar inclusividade em cada schema.
|
||||
|
||||
## Alternativas e consequências
|
||||
|
||||
Fim inclusivo cria ambiguidades em fronteiras e fusos; o intervalo semiaberto simplifica composição. Bitemporalidade integral foi adiada por não estar exigida em todas as entidades. Importações e correcções históricas preservam proveniência e não actualizam snapshots passados.
|
||||
@@ -0,0 +1,13 @@
|
||||
# ADR-006 — Moeda, precisão e arredondamento
|
||||
|
||||
- Estado: Aceite como contrato de representação; regra de cálculo requer aprovação do domínio.
|
||||
- Data: 2026-10-01
|
||||
- Contexto: valores exactos usam `numeric(20,2)` em partes do schema; moedas são códigos de 3 letras, mas a lista autorizada e políticas de arredondamento não estão completas.
|
||||
|
||||
## Decisão
|
||||
|
||||
Representar montante como decimal exacto em SQL e como string decimal no JSON/OpenAPI para evitar perda IEEE-754; transportar código monetário separadamente e exigir ambos ou nenhum nos campos emparelhados. `^[A-Z]{3}$` verifica formato, não validade ISO nem moeda permitida. Não converter moedas nem arredondar implicitamente. A escala, modo e momento de arredondamento dependem de regra aprovada pelo domínio e devem ser identificados em cada operação; resultados persistidos registam a moeda e, se aplicável, a regra/versão usada. Não inferir taxas fiscais, taxa de câmbio ou número de casas pela moeda.
|
||||
|
||||
## Alternativas e consequências
|
||||
|
||||
Float/double é rejeitado por erro binário. Inteiro em unidade mínima depende de escala monetária ainda não aprovada. É necessário decidir allowlist de moedas e regras específicas antes de cálculo financeiro público.
|
||||
@@ -0,0 +1,13 @@
|
||||
# ADR-007 — RLS e autorização SQL
|
||||
|
||||
- Estado: Aceite como gate de segurança; activação por tabela bloqueada até matriz de papéis e contexto aprovada.
|
||||
- Data: 2026-10-01
|
||||
- Contexto: baseline não encontrou `ENABLE/FORCE ROW LEVEL SECURITY` ou `CREATE POLICY`; permissões SQL e bypass não foram auditados. Decisões anteriores proíbem inventar roles/tenants.
|
||||
|
||||
## Decisão
|
||||
|
||||
Preservar Policies/Gates da aplicação como autorização obrigatória e não declarar RLS activo. Antes de expor dados protegidos a mais de um actor, aprovar matriz de papéis, fronteiras de isolamento/tenant, contas de runtime/migration e comportamento para jobs. Depois, aplicar RLS em tabelas e operações explicitamente mapeadas, usando papel runtime sem propriedade/`BYPASSRLS`, políticas `USING`/`WITH CHECK`, e `FORCE ROW LEVEL SECURITY` quando compatível com operações técnicas. Contexto por pedido deve ser transaccional e limpo ao devolver conexão ao pool. Garantir testes permitidos e negados, inclusive acesso SQL directo e papel privilegiado conforme ameaça.
|
||||
|
||||
## Alternativas e consequências
|
||||
|
||||
RLS genérico com tenant inventado é rejeitado; RLS desligado como se fosse controlo é igualmente rejeitado. Até a matriz e auditoria serem aprovadas, a cobertura permanece bloqueada e a aplicação não deve alegar isolamento na camada SQL. Sem alteração funcional nesta Etapa 1.
|
||||
@@ -0,0 +1,13 @@
|
||||
# ADR-008 — Outbox transaccional
|
||||
|
||||
- Estado: Aceite como padrão para integração assíncrona.
|
||||
- Data: 2026-10-01
|
||||
- Contexto: existem tabelas `outbox_events`/`inbox_events`, cliente SuiteCRM e emissão localizada; integração externa não está globalmente homologada.
|
||||
|
||||
## Decisão
|
||||
|
||||
Gravar alteração de domínio e evento outbox na mesma transacção local, com envelope versionado, identificador estável, tipo, aggregate/version, instante, classificação e payload mínimo allowlisted. Nunca incluir segredos, tokens ou PII desnecessária. Worker publica após commit, usa backoff configurado por operação, regista tentativas/erro sanitizado e marca sucesso; assumir entrega pelo menos uma vez. Consumidor valida schema/versão, deduplica por message/event ID via inbox e confirma efeito e recibo atomicamente. Falhas permanentes vão para estado de falha observável e exigem replay idempotente. Não prometer exactly-once entre sistemas.
|
||||
|
||||
## Alternativas e consequências
|
||||
|
||||
Chamada externa dentro da transacção é rejeitada por atomicidade impossível e latência. Dispatch directo após commit perde eventos em crash. Contratos e políticas de retenção/PII precisam validação por integração; existência das tabelas não significa operação activa.
|
||||
@@ -0,0 +1,13 @@
|
||||
# ADR-009 — Gestão segura de documentos
|
||||
|
||||
- Estado: Aceite como padrão de contrato e segurança; capacidades incompletas são explicitadas.
|
||||
- Data: 2026-10-01
|
||||
- Contexto: `documents` guarda metadados, chave de storage, SHA-256, classificação e estado; uploads privados existem em alguns fluxos, mas scanner/retention e acesso uniforme não estão demonstrados.
|
||||
|
||||
## Decisão
|
||||
|
||||
Separar metadados, blob privado e ligações tipadas. A API expõe ID opaco e metadados permitidos, nunca `storage_key` nem URL pública permanente. Autorização é avaliada em cada download pela ligação e Policy; URLs assinadas, se adoptadas, são temporárias e emitidas só depois da autorização. Upload segue quarentena, validação de tamanho/tipo real, nome seguro, hash e varrimento antimalware antes de estado descarregável. Versões são imutáveis; substituição cria nova versão, mantendo trilho. Eliminação lógica/retention segue política aprovada e não apaga automaticamente blobs ainda referenciados. Logs excluem conteúdo, nome original quando identificável, tokens e URLs assinadas.
|
||||
|
||||
## Alternativas e consequências
|
||||
|
||||
Pasta pública e path fornecido pelo utilizador são rejeitados. Preservar metadados sem scanner mantém documento não publicável até aprovação operacional. Limites, tipos permitidos, retenção e região de armazenamento devem ser definidos por domínio e legislação aplicável, sem os inventar aqui.
|
||||
Reference in New Issue
Block a user