# Logs e Auditoria — Definição (v1.0) **Documentos desta funcionalidade:** 01 - Definição (v1.0) · [02 - Especificação](./02%20-%20Especifica%C3%A7%C3%A3o%20v1.0.md) (v1.0) · [03 - Protótipo](./03%20-%20Prot%C3%B3tipo%20v1.0.md) (v1.0, código executável em `03 - Protótipo v1.0.html`) · [04 - Mapeamento de Banco de Dados](./04%20-%20Mapeamento%20de%20Banco%20de%20Dados%20v1.0.md) (v1.0) · [Cenários de Teste](./Cen%C3%A1rios%20de%20Teste%20v1.0.md) (v1.0) · [05 - Registro de Decisões](./05%20-%20Registro%20de%20Decis%C3%B5es%20v1.0.md) (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: 1. **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). 2. **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>-` (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 1. A requisição entra na API; o middleware abre o `traceId` e o contexto (tenant, clínica, usuário). 2. O endpoint declara `[Audited]`; o pipeline prepara o evento de leitura. 3. A operação roda; escritas passam pelo interceptador, que acumula os nomes dos campos alterados. 4. Na mesma transação, o evento entra na trilha (cliente ou global, conforme o tipo) com hash da linha. 5. O log de sistema sai pelo OpenTelemetry para o Collector (redação, buffer) e daí para Loki e Prometheus. 6. 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).