Logs e Auditoria — Definição (v1.0)
Documentos desta funcionalidade: 01 - Definição (v1.0) · 02 - Especificação (v1.0) · 03 - Protótipo (v1.0, código executável em 03 - Protótipo v1.0.html) · 04 - Mapeamento de Banco de Dados (v1.0) · Cenários de Teste (v1.0) · 05 - Registro de Decisões (v1.0)
Status: v1.0, rascunho para aprovação do solicitante. A rodada de Revisão por Dois Críticos (Skill Designer) ainda não foi executada. Tudo que não vem de decisão do solicitante, da Biblioteca de Schema (DDL), dos Requisitos SBIS ou de documentos do projeto está marcado [PROPOSTA] (invenção do Designer).
1.1 Objetivo
Dar ao Gemed 2.1 dois registros separados, com finalidades diferentes:
- Log de sistema: ajuda o suporte a achar anomalias, tanto de um usuário ou funcionalidade específicos (por exemplo, “o que aconteceu com a Maria às 14h?”) quanto em números gerais (taxa de erro, lentidão, falhas de banco).
- Trilha de auditoria: guarda quem fez o quê, quando e sobre qual registro, em todo o sistema, com ênfase no prontuário e nas funcionalidades coligadas. Serve à auditoria interna, à busca de responsáveis por decisões e ações, e à certificação (SBIS, ONA).
Os dois precisam ser simples de incorporar nas APIs e bibliotecas e, quando o desenvolvedor esquecer de incorporar, o próprio framework deve avisá-lo (falha de build ou de inicialização), e não o auditor, meses depois.
1.2 Contexto
O Gemed 2.1 é SaaS na nuvem do fornecedor, backend .NET (C#), banco por cliente mais bancos globais (IpSeguranca, IpTerminologia). A equipe opera Grafana, Loki e Prometheus em contêineres. Hoje existem apenas: o carimbo de 16 campos do framework (framework_pattern.md), que registra só a última ação sobre a linha e portanto não é trilha; o “log técnico” de tradução ausente (DT-011); e as tabelas Log e LogComplemento do IpSeguranca, de finalidade não confirmada. O caso de teste CT-AGM-API-08 (Agenda) já espera um mecanismo de auditoria que não existe.
1.3 Escopo
Dentro:
- Log de sistema estruturado, métricas e alertas (pacote
Gemed.Telemetry, nome [PROPOSTA]). - Trilha de auditoria de todo o sistema, em duas categorias (clínica e operacional) e dois repositórios (global e por cliente) (pacote
Gemed.Audit, nome [PROPOSTA]). - Tela do auditor: consulta cronológica com filtros e exportação.
- Salvaguardas para o desenvolvedor (atributos obrigatórios, analisador de código, verificação na inicialização, testes de arquitetura).
- Dashboards e regras de alerta iniciais para o suporte.
Fora (nesta versão):
- Selo em lote, cadeia de hash entre lotes e selo externo imutável (fase 2 e 3 da integridade; adiadas, D-LOG-009).
- Arquivamento em camada fria (só se o volume exigir, P-LOG-03).
- Tracing distribuído com Tempo (opcional).
- Telas de configuração de retenção (os prazos ficam em parâmetros de operação).
- Acesso de emergência (NGS1.11.07, estágio 3): apenas o evento fica reservado no catálogo.
1.4 Personas
| Persona | O que precisa | Como usa |
|---|---|---|
| Suporte | Reconstituir o que houve com um usuário; ver saúde geral | Pede o código de suporte (traceId) ao usuário; consulta dashboards “Um usuário” e “Saúde geral” no Grafana |
| Auditor (perfil novo, [PROPOSTA]) | Saber quem acessou ou alterou um registro; exportar evidências | Tela de auditoria: filtra por período, evento, usuário e registro afetado; exporta |
| Administrador do cliente | Acompanhar acessos indevidos e gestão de usuários | Mesma tela, com o direito de visualização concedido ao perfil |
| Desenvolvedor | Incorporar log e auditoria sem esforço e sem esquecer | Atributos [Audited]/[NotAudited], ILogger, template de projeto; recebe erro de build quando falta |
| DevOps | Operar Loki, Prometheus, Collector e o armazenamento | Parâmetros de retenção, alertas de infraestrutura |
| Usuário clínico | Não ser atrapalhado; ter um código para informar ao suporte | Vê apenas o código de suporte na mensagem de erro |
| Encarregado de proteção de dados / certificador | Evidência de conformidade | Recebe a exportação e a matriz de conformidade NGS1.07 |
1.5 Workflows e touchpoints
| Momento | Necessidade | O que oferece | Decisão de design |
|---|---|---|---|
| Usuário recebe erro | Falar com o suporte sem termos técnicos | Mensagem em linguagem simples com um código curto (traceId) | RN-LOG-004; ECF.17.19 |
| Suporte recebe o código | Ver a linha do tempo do usuário | Dashboard “Um usuário” (Grafana) filtrado por traceId ou userId | RN-LOG-002 |
| Pico de erros | Perceber antes do cliente | Alerta por taxa de erro e de falha de banco | RN-LOG-008 |
| Profissional abre prontuário | Rastro de leitura | Evento de auditoria clínico, uma vez por abertura | RN-LOG-019, 020 |
| Profissional altera dado | Rastro de escrita | Evento com nomes dos campos alterados, sem valores | RN-LOG-016 |
| Login falho, troca de senha, gestão de usuário | Rastro de segurança | Evento no repositório global (IpSeguranca) | RN-LOG-012 |
| Auditor investiga | Quem acessou o paciente X no período | Tela com filtros e linha do tempo; consulta global e do cliente juntas | RN-LOG-012, 023 |
| Auditor exporta | Evidência para certificador | Arquivo em formato aberto com identificação do software e da instituição | RN-LOG-024 |
| Desenvolvedor cria endpoint | Não esquecer a auditoria | Build falha sem [Audited] ou [NotAudited("motivo")] | RN-LOG-021 |
| Aplicação inicia sem o pacote | Não subir sem log/auditoria | Falha na inicialização com mensagem clara | RN-LOG-021 |
1.6 Regras de negócio
Log de sistema
RN-LOG-001 — Dois registros, duas finalidades. O log de sistema (suporte) e a trilha de auditoria (responsabilização) são distintos, têm armazenamento, retenção e acesso próprios, e nenhum substitui o outro. (Decidido pelo solicitante.)
RN-LOG-002 — Log estruturado com campos mínimos. Todo registro do log de sistema é JSON com: traceId, instante em UTC, nível, serviço, versão do software, código de evento, rota, resultado, tenant (ClienteBDId), clínica (ClienteEmpresa.Id) e usuário (GUID global de IpSeguranca.Usuario). (Decidido: tenant, clínica e usuário como campos; lista de campos [PROPOSTA] a partir do pedido.)
RN-LOG-003 — Sem dado clínico no log de sistema. O log de sistema não leva nome, CPF, número de prontuário nem valores clínicos. O coletor (OpenTelemetry Collector) aplica redação como segunda barreira. [PROPOSTA]
RN-LOG-004 — Código de suporte. Toda mensagem de erro mostrada ao usuário traz o traceId como código de suporte, em linguagem não técnica; o conteúdo técnico (exceção, SQL) nunca aparece (ECF.17.19). [PROPOSTA]
RN-LOG-005 — Eventos de log catalogados. Os eventos relevantes têm código no formato SYS-<área>-<nnn> (por exemplo SYS-TRD-001, tradução ausente, DT-011). Mensagens de log usam o gerador de código [LoggerMessage], evitando concatenação de texto. [PROPOSTA]
RN-LOG-006 — Rótulos do Loki. Só service, environment e level são rótulos; tenant, clínica e usuário são campos (metadados estruturados). (Decidido pelo solicitante, D-LOG-004.)
RN-LOG-007 — Granularidade das métricas. Métricas HTTP por endpoint, sem tenant; uma métrica enxuta com tenant (requisições e erros por classe de status); métricas da camada de banco com tenant (falhas de conexão, tempo de consulta, tempo esgotado). (Decidido pelo solicitante, D-LOG-004.)
RN-LOG-008 — Alertas. Regras do Alertmanager sobre taxa de erro, falha de banco e lentidão; limiares iniciais definidos após medir o volume. [PROPOSTA]
RN-LOG-009 — Retenção do log de sistema. Desejo de 1 a 2 anos de consulta, porque clientes pedem investigação do passado em funcionalidades fora do prontuário. O período por nível, o uso de armazenamento de objetos (MinIO/S3) e a necessidade de longo prazo para métricas (Mimir, Thanos ou VictoriaMetrics) serão decididos depois de medir o volume. (Decidido pelo solicitante: avaliar o volume; P-LOG-02.)
RN-LOG-010 — Falha do log de sistema não derruba a operação. Se o envio do log de sistema falhar, a operação do usuário continua, com buffer e reenvio. [PROPOSTA]
Trilha de auditoria
RN-LOG-011 — Uma trilha para o sistema todo, com categorias. Categoria clínica (ligada a paciente; escopo SBIS) e categoria operacional (restante do sistema). (Decidido pelo solicitante, D-LOG-005.)
RN-LOG-012 — Dois repositórios. Um global em IpSeguranca (tentativas de login, troca de senha, gestão de usuários e perfis: NGS1.07.03b/c) e um por cliente (eventos clínicos e operacionais). A tela do auditor consulta os dois e apresenta uma linha do tempo única. (Decidido pelo solicitante: processo de auditoria no Segurança; dois repositórios por consequência, D-LOG-005.)
RN-LOG-013 — Somente inclusão. A trilha não admite alteração nem exclusão por nenhum perfil da aplicação (NGS1.07.01/.02). O papel de banco da aplicação só tem permissão de inserir e consultar; o papel dono é separado. [PROPOSTA]
RN-LOG-014 — Mesma transação, falha fechada. O evento é gravado na mesma transação da operação; se a gravação falhar, a operação falha, nos eventos marcados como críticos no catálogo (todos os clínicos). Fila de saída (outbox) só se a trilha for para outro banco. [PROPOSTA]
RN-LOG-015 — Identificador opaco do paciente. O paciente é identificado na trilha por Paciente.IdPaciente (GescomClienteAlfa), nunca por nome, CPF ou NumProntuario. O identificador não pode ser reaproveitado; havendo unificação de pacientes, mantém-se a tabela de equivalência. (Decidido pelo solicitante, D-LOG-002.)
RN-LOG-016 — Sem valores clínicos. Para alterações, a trilha guarda os nomes dos campos alterados, não os valores (NGS1.07.06). A interpretação do requisito, em particular quanto ao PEPLog.NovoValor legado, será confirmada com o certificador (P-LOG-01). [PROPOSTA]
RN-LOG-017 — Campos do registro. Identificador único, data e hora (UTC), tipo de evento, componente e IP, usuário, identificador do registro afetado, informação complementar, tenant e categoria (NGS1.07.05).
RN-LOG-018 — Catálogo de eventos em código. Os eventos existem como enumeração AuditEventType, cada um com item NGS1.07.03/.04, gravidade, janela de supressão e sinalizador de falha fechada; a matriz de conformidade NGS1.07.03 é gerada a partir dela. [PROPOSTA]
RN-LOG-019 — Como capturar. Leitura: atributo [Audited(evento, recurso)] com comportamento de pipeline. Escrita: interceptador de gravação do EF Core (se a camada de dados não for EF, decorador do repositório ou da unidade de trabalho; P-LOG-05). Segurança: chamada explícita IAuditTrail.Record. [PROPOSTA]
RN-LOG-020 — Janela de supressão. Eventos repetitivos (por exemplo, o polling da Agenda) têm janela por tipo de evento: um registro por carga do dia e nenhum para atualização do mesmo dia, mais um por abertura do prontuário (CT-AGM-API-08). [PROPOSTA] a partir do teste existente.
RN-LOG-021 — O desenvolvedor não pode esquecer. Todo endpoint ou caso de uso declara [Audited(...)] ou [NotAudited("motivo")]; a falta é erro de build (analisador Roslyn), a varredura de endpoints na inicialização derruba a aplicação, e testes de arquitetura (NetArchTest) rodam no CI. A aplicação não inicia sem AddGemedAudit() e AddGemedTelemetry(). (Pedido do solicitante; mecanismos [PROPOSTA].)
RN-LOG-022 — Acesso à própria trilha. Só o perfil de auditor e o administrador consultam a trilha (NGS1.07.02); cada consulta e exportação vira evento de auditoria (NGS1.07.04, estágio 2). [PROPOSTA]
RN-LOG-023 — Visualização. Lista cronológica com filtros por período, evento, usuário e registro afetado (NGS1.07.07). Todos os registros ficam consultáveis, mesmo os antigos (NGS1.07.07b). (Requisito SBIS.)
RN-LOG-024 — Exportação. Formato aberto (CSV e JSON, [PROPOSTA]) com identificação do software e da instituição (nome, CNES, CNPJ) e instantes em RFC 3339 (NGS1.07.08, NGS1.09.02). Estágio 3.
RN-LOG-025 — Integridade, fase 1. Permissões só de inserção e hash SHA-256 por linha, calculado pela aplicação (independente do banco). Selo em lote e selo externo ficam para depois da conversa com o certificador sobre NGS1.07.02. (Decidido pelo solicitante, D-LOG-009.)
RN-LOG-026 — Armazenamento. Partições mensais por data do evento; modelo lógico neutro, com mapeamento para SQL Server e PostgreSQL (migração possível). Tudo online com compressão; camada de arquivamento só se o volume exigir. (Decidido pelo solicitante, D-LOG-008.)
RN-LOG-027 — Hora e relógio. Instantes em UTC; relógios de todos os componentes sincronizados (NGS1.08.06), com isso descrito no manual de operação.
RN-LOG-028 — Retenção da trilha. Nenhuma exclusão até o prazo legal e do certificador estar definido (P-LOG-04).
RN-LOG-029 — Acesso de emergência. O evento fica reservado no catálogo para quando NGS1.11.07 (estágio 3) for tratado.
1.7 Fluxo principal
- A requisição entra na API; o middleware abre o
traceIde o contexto (tenant, clínica, usuário). - O endpoint declara
[Audited]; o pipeline prepara o evento de leitura. - A operação roda; escritas passam pelo interceptador, que acumula os nomes dos campos alterados.
- Na mesma transação, o evento entra na trilha (cliente ou global, conforme o tipo) com hash da linha.
- O log de sistema sai pelo OpenTelemetry para o Collector (redação, buffer) e daí para Loki e Prometheus.
- O suporte consulta o Grafana; o auditor consulta a tela de auditoria.
1.8 Premissas
- Camada de dados em EF Core (a confirmar, P-LOG-05).
Paciente.IdPacienteé estável (RN-LOG-015).- Existe, ou será criado, o perfil “Auditor” no
IpSeguranca(não encontrado hoje). - Loki com suporte nativo a OTLP na versão adotada (a confirmar).
1.9 Dependências
Contexto Segurança (perfis, processos e direitos); Gestão do Sistema; DT-011; Agenda do Médico (CT-AGM-API-08); framework_pattern.md; ClienteEmpresa (CNPJ), Clinica.CNES (identificação na exportação).
1.10 Requisitos SBIS aplicáveis
NGS1.07.01 a .08 (núcleo); NGS1.02.13 (tentativas de login); NGS1.03.01 (acesso por autorização); NGS1.08.06 (relógio); NGS1.09.02 (RFC 3339 na exportação); NGS1.11.07 (emergência, estágio 3); ECF.17.19 (mensagens). Detalhe na Especificação (2.11).
1.11 Prioridade e complexidade
Prioridade alta: NGS1.07.01 a .07 são de estágio 1, obrigatórios. Complexidade alta (transversal a todos os serviços); recomenda-se entregar primeiro o pacote Gemed.Audit com o catálogo mínimo NGS1.07.03 e depois a telemetria.
1.12 Próximos passos
Aprovação do solicitante; rodada de Revisão por Dois Críticos; conversa com o certificador (P-LOG-01, 04, 06); medição de volume (P-LOG-02, 03); decisão EF Core x outra camada (P-LOG-05).
Histórico de Versões
- v1.0 (11/11/2026) — Criação, a partir das decisões do solicitante na conversa de arquitetura de logs (D-LOG-001 a 010).