Service Manager — Audit Logs UI & API¶

{
  path: 'system/logs',
  name: SYSTEM_NAV.SYSTEM_LOGS.routeName,           // 'system-logs'
  component: () => import('pages/system/LogsPage.vue'),
  beforeEnter: requirePermission('system.users', 'edit'),
  meta: {
    requiresAuth: true,
    note: 'System Admin - Audit logs viewer',
    breadcrumb: false,
    isSystem: true,
    title: 'Logs',
    icon: 'assignment',
    description: 'View, search, and export audit logs and user activity history for security auditing and troubleshooting.',
  },
},

SYSTEM_LOGS: {
  routeName: 'system-logs',
  description: 'system-logs-description',
  icon: 'o_list_alt',
},

GET /api/v1/audit/activity
  ?user_id=123                          # optional — filter by actor
  ?entity_type=DataEntry                # optional
  ?entity_id=456                        # optional — history of specific entity
  ?action=CREATE                        # optional — CREATE|READ|UPDATE|DELETE|ROLLBACK|TRANSFER
  ?date_from=2024-10-01T00:00:00Z       # optional ISO 8601
  ?date_to=2024-10-08T23:59:59Z         # optional ISO 8601
  ?search=sophie                        # optional — free-text on changed_by, change_reason, entity_type
  ?module=Auth                          # optional — filter by route_path prefix or entity_type group
  ?page=1
  ?page_size=25
  ?sort_by=changed_at                   # changed_at | entity_type | change_type | changed_by
  ?sort_desc=true

Response 200:
{
  "data": AuditLogEntry[],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "total": 1234
  }
}

GET /api/v1/audit/stats
  (same optional filters as above, excluding page/page_size/sort)

Response 200:
{
  "total_entries": 1200000,
  "creates": 800000,
  "reads": 350000,
  "updates": 45000,
  "deletes": 5000
}

GET /api/v1/audit/activity/{id}

Response 200: AuditLogEntry (full data_snapshot + data_diff, no truncation)

GET /api/v1/audit/export
  (same filters as query)
  ?format=csv                           # csv | json

Response: file download
Filename: audit_export_{YYYY-MM-DD}.{format}

from datetime import datetime
from typing import Any, Dict, List, Optional
from pydantic import BaseModel
from app.models.audit import AuditChangeTypeEnum


class AuditLogEntry(BaseModel):
    """Single audit log entry returned by the API."""
    id: int
    entity_type: str
    entity_id: int
    version: int
    change_type: AuditChangeTypeEnum
    change_reason: Optional[str]
    changed_by: str                     # email or 'system'
    changed_at: datetime                # ISO 8601
    handler_id: str                     # actor provider code
    handled_ids: List[str]              # affected user provider codes
    ip_address: str
    route_path: Optional[str]
    data_snapshot: Dict[str, Any]       # full JSON snapshot (detail only)
    data_diff: Optional[Dict[str, Any]] # JSON diff (detail only)
    message_summary: Optional[str]      # truncated human-readable summary (~80 chars)

    class Config:
        from_attributes = True


class AuditLogListResponse(BaseModel):
    """Paginated list of audit log entries."""
    data: List[AuditLogEntry]
    pagination: "PaginationMeta"


class PaginationMeta(BaseModel):
    page: int
    page_size: int
    total: int


class AuditStats(BaseModel):
    """Summary statistics for audit logs."""
    total_entries: int
    creates: int
    reads: int
    updates: int
    deletes: int


class AuditQueryParams(BaseModel):
    """Query parameters for filtering audit logs."""
    user_id: Optional[str] = None
    entity_type: Optional[str] = None
    entity_id: Optional[int] = None
    action: Optional[AuditChangeTypeEnum] = None
    date_from: Optional[datetime] = None
    date_to: Optional[datetime] = None
    search: Optional[str] = None
    module: Optional[str] = None
    page: int = 1
    page_size: int = 25
    sort_by: str = "changed_at"
    sort_desc: bool = True

from fastapi import APIRouter, Depends, Query, Request, Response
from app.db import get_session
from app.schemas.audit import (
    AuditLogEntry, AuditLogListResponse, AuditStats, AuditQueryParams
)

router = APIRouter(prefix="/audit", tags=["audit"])

@router.get("/activity", response_model=AuditLogListResponse)
async def list_audit_logs(...): ...

@router.get("/stats", response_model=AuditStats)
async def get_audit_stats(...): ...

@router.get("/activity/{log_id}", response_model=AuditLogEntry)
async def get_audit_log_detail(...): ...

@router.get("/export")
async def export_audit_logs(...): ...

async def query(
    self,
    filters: AuditQueryParams,
) -> tuple[list[AuditDocument], int]:
    """Paginated, filtered, sorted query. Returns (results, total_count)."""

async def count_by_change_type(
    self,
    filters: AuditQueryParams,
) -> dict[str, int]:
    """Count audit entries grouped by change_type, with same filters (minus pagination)."""

CREATE INDEX ix_audit_documents_changed_at ON audit_documents (changed_at DESC);
CREATE INDEX ix_audit_documents_changed_by ON audit_documents (changed_by);
CREATE INDEX ix_audit_documents_change_type ON audit_documents (change_type);
CREATE INDEX ix_audit_documents_composite ON audit_documents (entity_type, entity_id, changed_at DESC);

pages/system/LogsPage.vue                  ← orchestrator (replaces placeholder)
├── components/audit/
│   ├── AuditFilterBar.vue                 ← Action / Entity Type / Module / Date Range dropdowns
│   ├── AuditSearchBar.vue                 ← full-width search input + Search button + Export button
│   ├── AuditTable.vue                     ← dark-background data table
│   │   ├── AuditTableHeader.vue           ← sortable column headers
│   │   └── AuditTableRow.vue              ← single log row with status dot
│   ├── AuditPagination.vue                ← "Showing X–Y of Z | Rows per page" + page stepper
│   ├── AuditStatCards.vue                 ← summary cards (Total / Creates / Updates / Deletes)
│   └── AuditDetailDrawer.vue             ← side panel with full entry details + diff viewer
├── api/
│   └── audit.ts                           ← API calls using shared ky client
└── composables/
    └── useAuditLogs.ts                    ← fetch/filter/sort/pagination state

import { api } from "./http";
import type {
  AuditLogEntry,
  AuditLogListResponse,
  AuditStats,
  AuditQueryParams,
} from "@/types/audit";

export async function fetchAuditLogs(
  params: AuditQueryParams,
): Promise<AuditLogListResponse> {
  return api.get("audit/activity", { searchParams: params }).json();
}

export async function fetchAuditStats(
  params: Partial<AuditQueryParams>,
): Promise<AuditStats> {
  return api.get("audit/stats", { searchParams: params }).json();
}

export async function fetchAuditLogDetail(id: number): Promise<AuditLogEntry> {
  return api.get(`audit/activity/${id}`).json();
}

export async function exportAuditLogs(
  params: AuditQueryParams & { format: "csv" | "json" },
): Promise<Blob> {
  return api.get("audit/export", { searchParams: params }).blob();
}

export type AuditAction =
  | "CREATE"
  | "READ"
  | "UPDATE"
  | "DELETE"
  | "ROLLBACK"
  | "TRANSFER";

export interface AuditLogEntry {
  id: number;
  entity_type: string; // e.g. 'DataEntry', 'User', 'Factor'
  entity_id: number;
  version: number;
  change_type: AuditAction;
  change_reason: string | null;
  changed_by: string; // email or 'system'
  changed_at: string; // ISO 8601
  handler_id: string; // actor provider code
  handled_ids: string[]; // affected user provider codes
  ip_address: string;
  route_path: string | null;
  data_snapshot: Record<string, unknown>;
  data_diff: AuditDiff | null;
  message_summary: string | null; // truncated human-readable summary
}

export interface AuditDiff {
  added: Record<string, unknown>;
  removed: Record<string, unknown>;
  changed: Record<string, { old: unknown; new: unknown }>;
}

export interface AuditStats {
  total_entries: number;
  creates: number;
  reads: number;
  updates: number;
  deletes: number;
}

export interface AuditQueryParams {
  user_id?: string;
  entity_type?: string;
  entity_id?: number;
  action?: AuditAction;
  date_from?: string;
  date_to?: string;
  search?: string;
  module?: string;
  page: number;
  page_size: number;
  sort_by: string;
  sort_desc: boolean;
}

export interface PaginationMeta {
  page: number;
  page_size: number;
  total: number;
}

export interface AuditLogListResponse {
  data: AuditLogEntry[];
  pagination: PaginationMeta;
}

// Filter state
const actionFilter = ref<AuditAction | null>(null);
const entityTypeFilter = ref<string | null>(null);
const moduleFilter = ref<string | null>(null);
const dateRange = ref<{ from: string; to: string } | null>(null);
const searchQuery = ref("");

// Pagination state
const page = ref(1);
const pageSize = ref(25);
const totalEntries = ref(0);

// Table state
const logs = ref<AuditLogEntry[]>([]);
const isLoading = ref(false);
const sortBy = ref<string>("changed_at");
const sortDesc = ref(true);

// Stats (loaded independently)
const stats = ref<AuditStats>({
  total_entries: 0,
  creates: 0,
  reads: 0,
  updates: 0,
  deletes: 0,
});
const statsLoading = ref(false);

// Detail drawer
const selectedLog = ref<AuditLogEntry | null>(null);
const detailOpen = ref(false);

function buildParams(): AuditQueryParams {
  /* assemble from refs */
}

async function fetchLogs() {
  isLoading.value = true;
  try {
    const result = await fetchAuditLogs(buildParams());
    logs.value = result.data;
    totalEntries.value = result.pagination.total;
  } finally {
    isLoading.value = false;
  }
}

async function fetchStats() {
  statsLoading.value = true;
  try {
    stats.value = await fetchAuditStats(buildParams());
  } finally {
    statsLoading.value = false;
  }
}

function onSearch() {
  page.value = 1;
  fetchLogs();
  fetchStats();
}
function onFilterChange() {
  page.value = 1;
  fetchLogs();
  fetchStats();
}
function onSort(column: string) {
  if (sortBy.value === column) {
    sortDesc.value = !sortDesc.value;
  } else {
    sortBy.value = column;
    sortDesc.value = true;
  }
  fetchLogs();
}
function onPageSizeChange(n: number) {
  pageSize.value = n;
  page.value = 1;
  fetchLogs();
}
function onPageChange(n: number) {
  page.value = n;
  fetchLogs();
}

async function openDetail(id: number) {
  selectedLog.value = await fetchAuditLogDetail(id);
  detailOpen.value = true;
}

async function handleExport(format: "csv" | "json") {
  const blob = await exportAuditLogs({ ...buildParams(), format });
  const url = URL.createObjectURL(blob);
  const a = document.createElement("a");
  a.href = url;
  a.download = `audit_export_${new Date().toISOString().slice(0, 10)}.${format}`;
  a.click();
  URL.revokeObjectURL(url);
}

Before:                         After:
{                               {
  "name": "Old Name"    →         "name": "New Name"
}                               }

<template>
  <q-page>
    <NavigationHeader :item="SYSTEM_NAV.SYSTEM_LOGS" />
    <div class="q-my-xl q-px-xl">
      <div class="container full-width">
        <!-- Filter dropdowns row -->
        <AuditFilterBar
          v-model:action="actionFilter"
          v-model:entity-type="entityTypeFilter"
          v-model:module="moduleFilter"
          v-model:date-range="dateRange"
          @filter-change="onFilterChange"
        />

        <!-- Search + Export -->
        <AuditSearchBar
          v-model="searchQuery"
          @search="onSearch"
          @export="handleExport"
        />

        <!-- Table + pagination -->
        <div class="logs-table-container">
          <AuditTable
            :rows="logs"
            :loading="isLoading"
            :sort-by="sortBy"
            :sort-desc="sortDesc"
            @sort="onSort"
            @view="openDetail"
            @copy="copyEntry"
          />
          <AuditPagination
            :page="page"
            :page-size="pageSize"
            :total="totalEntries"
            @update:page="onPageChange"
            @update:page-size="onPageSizeChange"
          />
        </div>

        <!-- Summary stat cards -->
        <AuditStatCards :stats="stats" :loading="statsLoading" />

        <!-- Detail drawer -->
        <AuditDetailDrawer
          v-model="detailOpen"
          :entry="selectedLog"
          @copy="copyEntry"
        />
      </div>
    </div>
  </q-page>
</template>

<script setup lang="ts">
import { onMounted } from "vue";
import NavigationHeader from "@/components/organisms/backoffice/NavigationHeader.vue";
import { SYSTEM_NAV } from "@/constant/navigation";
import { useAuditLogs } from "@/composables/useAuditLogs";
// Import audit sub-components...

const {
  actionFilter,
  entityTypeFilter,
  moduleFilter,
  dateRange,
  searchQuery,
  page,
  pageSize,
  totalEntries,
  logs,
  isLoading,
  sortBy,
  sortDesc,
  stats,
  statsLoading,
  selectedLog,
  detailOpen,
  onSearch,
  onFilterChange,
  onSort,
  onPageChange,
  onPageSizeChange,
  openDetail,
  handleExport,
} = useAuditLogs();

function copyEntry(entry: AuditLogEntry) {
  navigator.clipboard.writeText(JSON.stringify(entry, null, 2));
  // show q-notify toast
}

onMounted(() => {
  onSearch();
});
</script>

beforeEnter: requirePermission("system.users", "edit");

const canExport = usePermission("system.logs", "export");

const canViewSensitive = usePermission("audit.logs", "view_sensitive");

┌──────────────────────────────────────────────────┐
│  No audit entries found                          │
│  Try adjusting your filters or search query.     │
└──────────────────────────────────────────────────┘

/system/logs?action=UPDATE&entity_type=DataEntry&date_from=2026-01-01&search=sophie