Logistiki.Audit (logistiki v0.1.0)

Copy Markdown View Source

The context for audit evidence.

Every important action in the accounting pipeline records an audit event so that the full chain — business event, rules, policy, template, journal, postings, ledger result — can be explained later.

Summary

Functions

list_audit_events(opts \\ [])

Lists audit events, optionally filtered.

record(attrs)

Records a single audit event.

record_evidence(evidence)

Records every stage in an Evidence struct as an audit event.

trail_for_event(event_id)

Returns the full audit trail for a business event.

trail_for_journal(journal_id)

Returns the full audit trail for a journal.

Functions

list_audit_events(opts \\ [])

(since 0.1.0) 
@spec list_audit_events(keyword()) :: [Logistiki.Audit.AuditEvent.t()]

Lists audit events, optionally filtered.

Arguments

  • opts — keyword() of options:
    • :event_id — String.t — filter by event id
    • :journal_id — integer() — filter by journal id
    • :action — String.t — filter by action (e.g. "journal_posted")

Returns

  • [AuditEvent.t()] — ordered by inserted_at descending.

Examples

iex> Logistiki.Audit.list_audit_events(event_id: "evt_001")
[%AuditEvent{action: "business_event_received", ...}, ...]

iex> Logistiki.Audit.list_audit_events(action: "journal_posted")
[%AuditEvent{action: "journal_posted", ...}]

record(attrs)

(since 0.1.0) 
@spec record(map()) ::
  {:ok, Logistiki.Audit.AuditEvent.t()} | {:error, Ecto.Changeset.t()}

Records a single audit event.

Arguments

  • attrs — map() of audit event attributes:
    • :action — String.t — required (e.g. "journal_posted")
    • :event_id — String.t — the originating event id
    • :journal_id — integer() — the related journal id
    • :resource_type — String.t
    • :resource_id — String.t
    • :explanation — map()
    • :metadata — map()

Returns

  • {:ok, %AuditEvent{}} — the persisted audit event.
  • {:error, %Ecto.Changeset{}} — validation failed.

Examples

iex> {:ok, event} = Logistiki.Audit.record(%{action: "journal_posted", event_id: "evt_1"})
iex> event.action
"journal_posted"

record_evidence(evidence)

(since 0.1.0) 
@spec record_evidence(Logistiki.Audit.Evidence.t()) :: :ok

Records every stage in an Evidence struct as an audit event.

Arguments

  • evidence — %Logistiki.Audit.Evidence{} — with stages, event_id, journal_id.

Returns

  • :ok — all stages were recorded.

Examples

iex> evidence = Logistiki.Audit.Evidence.build("evt_1", journal_id, stages, %{})
iex> Logistiki.Audit.record_evidence(evidence)
:ok

trail_for_event(event_id)

(since 0.1.0) 
@spec trail_for_event(String.t() | atom()) :: [Logistiki.Audit.AuditEvent.t()]

Returns the full audit trail for a business event.

Arguments

  • event_id — String.t() | atom() — the event id.

Returns

  • [AuditEvent.t()] — ordered by inserted_at ascending, showing the full pipeline trace.

Examples

iex> trail = Logistiki.Audit.trail_for_event("evt_001")
iex> Enum.map(trail, & &1.action)
["event_normalized", "business_event_received", "facts_generated", ...]

trail_for_journal(journal_id)

(since 0.1.0) 
@spec trail_for_journal(integer()) :: [Logistiki.Audit.AuditEvent.t()]

Returns the full audit trail for a journal.

Arguments

  • journal_id — integer() — the journal id.

Returns

  • [AuditEvent.t()] — ordered by inserted_at ascending.

Examples

iex> trail = Logistiki.Audit.trail_for_journal(1)
iex> Enum.map(trail, & &1.action)
["journal_built", "invariant_validation_succeeded", "journal_posted", ...]