vitepress-template

Appearance

Audit and Compliance ​

**Referenced Files in This Document** - [[log.proto]](file/bi-sys/api/sys/v1/log.proto) - [[log.go (biz)]](file/bi-sys/internal/biz/log.go) - [[log.go (data)]](file/bi-sys/internal/data/log.go) - [[log.go (service)]](file/bi-sys/internal/service/log.go) - [[architecture-bi-sys.md]](file/bi-sys/docs/architecture-bi-sys.md) - [[page.tsx (Admin Logs Page)]](file/ui-web-admin/src/app/dashboard)/system/logs/page.tsx)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction ​

This document describes the Audit and Compliance features within the Admin Panel, focusing on the audit trail management interface and related backend services. It covers:

  • Audit trail management: login logs and operation logs, including viewing, filtering, deletion, clearing, and exporting.
  • Compliance reporting and governance: leveraging the audit trail for regulatory reporting and policy enforcement via the Admin Panel.
  • User activity monitoring and system access logging: real-time visibility into who accessed the system and what operations were performed.
  • Data change tracking: operational logs capture module, operation type, request metadata, and outcomes.
  • Integration points: gRPC/HTTP APIs exposed by the system management service and consumed by the Admin Panel.
  • Retention and privacy considerations: configurable retention aligned with compliance needs and secure handling of sensitive data.
  • Examples of common compliance tasks: generating audit reports, investigating security incidents, and maintaining regulatory documentation.

Project Structure ​

The Audit and Compliance features are implemented across:

  • Protocol definitions for audit log APIs (login and operation logs).
  • Business logic encapsulating use cases for log operations.
  • Data access layer implementing persistence and query building.
  • Service layer exposing gRPC/HTTP endpoints for the Admin Panel.
  • Admin Panel UI route for viewing and managing audit logs.

Diagram sources

Section sources

Core Components ​

  • Login Log Service: Provides listing, retrieval, deletion, batch deletion, clearing, and export of login events.
  • Operation Log Service: Provides listing, retrieval, deletion, batch deletion, clearing, and export of operation events.
  • LogUsecase: Encapsulates business logic for log operations, including pagination defaults and validation.
  • LogRepo: Implements persistence and query construction for login and operation logs, including filters and ordering.
  • Admin Panel Logs Page: Presents the UI for browsing, filtering, and exporting audit logs.

Key capabilities:

  • Filtering by username, IP, status, and time range.
  • Pagination with configurable page number and page size.
  • Export to downloadable file format.
  • Deletion and bulk deletion for maintenance and privacy requests.
  • Clearing entire log sets for compliance retention resets.

Section sources

Architecture Overview ​

The audit trail feature follows a layered architecture:

  • Presentation/UI: Admin Panel renders the logs page and triggers API calls.
  • Service: gRPC/HTTP services translate requests into use cases.
  • Business: Usecases enforce defaults and orchestrate repositories.
  • Data: Repositories handle persistence and query building with filters and pagination.
  • Storage: Database tables for login and operation logs.

Diagram sources

Detailed Component Analysis ​

Login Log Management ​

  • API surface: list, get, delete, batch delete, clear, export.
  • Filters: username (partial match), IP (partial match), status, begin_time, end_time.
  • Pagination: page_num and page_size with sensible defaults enforced in usecase.
  • Export: returns a download URL for exported records.

Diagram sources

Section sources

Operation Log Management ​

  • API surface: list, get, delete, batch delete, clear, export.
  • Filters: username (partial match), module (partial match), operation (partial match), status, begin_time, end_time.
  • Pagination: page_num and page_size with defaults.
  • Export: returns a download URL for exported records.

Diagram sources

Section sources

Admin Panel Logs Page ​

  • Route: system/logs page in the Admin Panel.
  • Responsibilities: render filter controls, display paginated results, trigger export, and manage deletion actions.
  • Integration: consumes the LoginLogService and OperationLogService endpoints defined in the protocol.

Section sources

Data Model and Persistence ​

  • Login logs: include identity, device/OS info, location, status, and timestamps.
  • Operation logs: include module, operation type, request metadata, response/result, IP/location, status, error messages, and cost time.
  • Query builder pattern: supports LIKE, EQ, GTE/LTE conditions, ordering, and pagination.
  • ID generation: uses a snowflake generator for log identifiers.

Diagram sources

Section sources

Dependency Analysis ​

  • Protocol-driven design: APIs defined in protobuf enable gRPC/HTTP gateway interoperability.
  • Layered dependencies: service depends on biz, which depends on data, which depends on the database.
  • Admin Panel depends on service endpoints for rendering and performing actions.

Diagram sources

Section sources

Performance Considerations ​

  • Pagination defaults: usecases set safe defaults for page_num and page_size to avoid heavy queries.
  • Query builder: efficient filtering with LIKE, EQ, and range conditions; descending sort by time for recent-first views.
  • Export: offloads heavy work to a background process returning a download URL to reduce latency.
  • Indexing: ensure database indexes on frequently filtered columns (username, ip, timestamps) for optimal query performance.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

Common issues and resolutions:

  • Empty results despite existing logs:
    • Verify time range filters and ensure begin_time/end_time are correctly formatted.
    • Confirm pagination parameters are set appropriately.
  • Export returns no data:
    • Check filters applied during export; remove restrictive conditions.
    • Validate that export endpoint returns a valid download URL.
  • Deletion failures:
    • Ensure log IDs exist and are within allowed ranges.
    • Confirm batch sizes adhere to configured limits.
  • UI not reflecting updates:
    • Refresh the logs page after bulk actions or clears.
    • Confirm network connectivity to the bi-sys service.

Section sources

Conclusion ​

The Audit and Compliance features provide a robust foundation for monitoring and governing system access and operations. The Admin Panel integrates seamlessly with bi-sys services to deliver:

  • Comprehensive audit trails for login and operation events.
  • Powerful filtering, pagination, and export capabilities.
  • Secure deletion and clearing mechanisms aligned with retention and privacy requirements.
  • A clear pathway for compliance reporting and incident investigation.

[No sources needed since this section summarizes without analyzing specific files]

Appendices ​

Compliance Task Examples ​

  • Generating audit reports:
    • Use the export endpoints for login and operation logs to produce downloadable reports for a selected period and filters.
  • Investigating security incidents:
    • Filter by IP address and time range to isolate suspicious login attempts or failed operations.
    • Review operation logs for high-risk modules and operations to identify unauthorized or anomalous activities.
  • Maintaining regulatory documentation:
    • Schedule periodic exports and store them per organizational retention policies.
    • Combine login and operation logs to demonstrate access control and change tracking.

[No sources needed since this section provides general guidance]