Trilha de auditoria

A trilha de auditoria é uma coleção própria (auditLog) com um registro para cada criação, alteração e exclusão de plano, nota, pagamento e comentário (G-12). Excluir uma nota não apaga o que ela era: o registro da exclusão guarda a última versão.

O registro

Campo	Para quem interpreta
kind	O que foi alterado: plan, entry (nota), payment ou comment.
path	Caminho do documento alterado.
planId	Plano a que pertence.
entryId	Nota dona do registro (a própria nota, seus pagamentos e comentários). Vazio em plan.
op	create, update ou delete.
before	O documento inteiro antes da alteração. Vazio na criação.
after	O documento inteiro depois. Vazio na exclusão.
changedKeys	Só em update: os campos cujo valor mudou.
authType, authId	A credencial que fez a escrita, como o servidor a recebeu.
actorUid	A conta de quem fez a alteração. Ver “Como ler a autoria”.
memberUids	Quem pode ler este registro.
at	A hora do evento, no relógio do servidor.

Como o registro nasce

Quatro triggers (funções que o servidor dispara quando um documento é gravado) cobrem plano, nota, pagamento e comentário. Cada um grava o registro com o identificador do próprio evento como nome do documento, e a gravação só cria, nunca sobrescreve. O servidor pode entregar o mesmo evento mais de uma vez; a segunda entrega encontra o registro já criado e é ignorada. Essa propriedade, de que repetir a operação não duplica o resultado, chama-se idempotência. O app não escreve nesta coleção (G-13).

Como ler a autoria

O campo que diz quem fez é actorUid:

• Escrita feita pelo app. authType é api_key e actorUid é igual a authId: o código da conta conectada.
• Escrita feita pelo servidor a pedido de um membro (mudança na divisão, entrada e saída de membros, pedido de entrada, retirada de itens da divisão). authId é a credencial do servidor, e actorUid é o código de quem pediu, que a função anota no documento no momento da escrita.
• Escrita do servidor sem pedido de ninguém (por exemplo, a exclusão de planos em lote na exclusão de uma conta). actorUid é vazio; o relatório mostra “Sistema”.
• Registro anterior a 2026-10-14. Não tem actorUid. Vale o authId somente quando authType é api_key; as alterações feitas pelo servidor a pedido de um membro aparecem como do sistema (G-12).

O relatório aplica exatamente esta regra para preencher a coluna de autor da seção “Alterações registradas”.

O que não vira registro

• Atualização que não muda nenhum campo. Reenviar o mesmo documento não gera registro.
• No plano, as chaves de cache monthlyTotals, unreadByUid e memberSince. As duas primeiras são totais e contadores recalculados pelo app; memberSince é derivada das vigências da divisão, que já são registradas. Uma atualização que mude só essas chaves não gera registro.
• O marcador da conta que pediu a escrita (auditActor) não conta como campo alterado.

Por isso a ausência de registro nesses casos não é lacuna: o que importa (valor, divisão, membros, textos) está registrado quando muda.

Quem lê e quem escreve

Lê quem está na lista memberUids do próprio registro. Para plano, a lista é a união dos membros antes e depois da alteração; para nota, pagamento e comentário, é a lista de membros do plano lida quando o servidor grava o registro, instantes depois da escrita. Por isso quem saiu do plano lê o período em que participou e nada depois (G-14). A escrita é só dos triggers; o cliente não cria, altera nem apaga registro (G-13).

Ciclo de vida: quando a trilha é apagada

A trilha só é apagada quando a conta excluída é o único membro do plano (seja ou não a criadora), e só quando nenhuma outra pessoa aparece nos registros daquele plano (G-15). A exclusão tem carência de 7 dias e pode ser suspensa por ordem judicial.

flowchart TD
    A["Conta marcada para exclusão<br/>(carência de 7 dias)"] --> B{"Preservação por<br/>ordem judicial?"}
    B -->|sim| C["Exclusão suspensa"]
    B -->|não| D{"O plano tem<br/>outros membros?"}
    D -->|sim| E["Só sai da lista de membros<br/>trilha e arquivos ficam"]
    D -->|não| F["Plano apagado;<br/>expurgo agendado para 24 h depois"]
    F --> G{"Algum registro cita<br/>outra pessoa?"}
    G -->|sim| H["Nada é apagado<br/>trilha e arquivos ficam"]
    G -->|não| I["Apaga a trilha<br/>e os arquivos do plano"]

A espera de 24 horas existe porque a própria exclusão do plano dispara os triggers, que podem chegar depois e gravar registros da exclusão; apagar a trilha antes deixaria esses registros para trás.

O limite, dito claramente

O operador tem acesso administrativo ao banco de dados. Não há cadeia de hash entre os registros nem carimbo de tempo de terceiro: não existe como provar, só pela trilha, que ela não foi alterada por quem administra a infraestrutura. O que as garantias dizem é que nenhum usuário a altera (G-13). Ver Limites conhecidos.

Como ler uma alteração

Exemplo fictício: o autor de uma nota manual de R$ 100,00 a altera para R$ 150,00. A trilha tem, para esse documento, um registro create e um update. O update traz, abreviado:

Campo	Valor
kind	entry
op	update
changedKeys	amount
before	o documento inteiro, com amount = 100
after	o documento inteiro, com amount = 150
authType / actorUid	api_key / código da conta do autor
at	hora do servidor da alteração

Lê-se: naquela hora, a conta do autor mudou o valor de 100 para 150; todo o resto do documento era igual. O registro anterior (create) mostra o valor original. O relatório de prestação de contas traz essa linha na seção “Alterações registradas”.