23 KiB

Raw Blame History

Story 6.10: Audit Log Viewer

Epic Reference

Epic 6: Admin Dashboard

User Story

As an admin, I want to view admin action history, So that I can maintain accountability and track changes.

Dependencies

Story 1.1: Project Setup & Database Schema (admin_logs table and AdminLog model)
Story 1.2: Authentication & Role System (admin auth middleware)
Story 6.1: Dashboard Overview & Statistics (admin layout, navigation patterns)

Accessible from admin dashboard sidebar/navigation
Route: /admin/audit-logs
Named route: admin.audit-logs

Background Context

What Gets Logged

The admin_logs table captures significant admin actions for accountability:

User Management: Create, update, delete, deactivate/reactivate users
Consultation Management: Approve, reject, mark complete, mark no-show, cancel bookings
Timeline Management: Create, update, archive timelines and timeline entries
Posts Management: Create, update, delete posts
Settings Changes: System configuration modifications

AdminLog Model Schema

Reference: PRD §16.1 Database Schema

admin_logs table:
- id: bigint (primary key)
- admin_id: bigint (nullable, foreign key to users - null for system actions)
- action: string (create, update, delete, approve, reject, etc.)
- target_type: string (user, consultation, timeline, timeline_update, post, setting)
- target_id: bigint (ID of the affected record)
- old_values: json (nullable - previous state for updates)
- new_values: json (nullable - new state for creates/updates)
- ip_address: string (IPv4/IPv6 address of admin)
- created_at: timestamp

Acceptance Criteria

Display Requirements

Paginated table of audit log entries (25 per page)
Each row displays:
- Timestamp (formatted per locale: d/m/Y H:i for AR, m/d/Y H:i for EN)
- Admin name (or "System" for automated actions)
- Action type badge (color-coded: green=create, blue=update, red=delete)
- Target type and ID (e.g., "User #123")
- IP address
- Details button to view old/new values

Filtering

Filter by action type (dropdown with available actions)
Filter by target type (dropdown with available targets)
Filter by date range (date pickers for from/to)
Filters apply without page reload (Livewire)
Reset filters button

Search

Search by target ID (exact match)
Search updates results in real-time with debounce

Modal displays full log entry details
Shows old values in readable format (JSON pretty-printed)
Shows new values in readable format
Highlights differences between old/new for updates
Bilingual labels

CSV Export

Export current filtered results to CSV
CSV includes all displayed columns
CSV filename includes export date
Bilingual column headers based on admin's language preference

Empty State

Friendly message when no logs exist
Friendly message when filters return no results

Technical Notes

Files to Create/Modify

resources/views/livewire/admin/audit-logs.blade.php - Main Volt component
app/Models/AdminLog.php - Eloquent model (if not already created in Story 1.1)
routes/web.php - Add admin route (or admin routes file)
lang/ar/audit.php - Arabic translations
lang/en/audit.php - English translations

AdminLog Model

class AdminLog extends Model
{
    protected $fillable = [
        'admin_id',
        'action',
        'target_type',
        'target_id',
        'old_values',
        'new_values',
        'ip_address',
    ];

    protected function casts(): array
    {
        return [
            'old_values' => 'array',
            'new_values' => 'array',
        ];
    }

    public function admin(): BelongsTo
    {
        return $this->belongsTo(User::class, 'admin_id');
    }
}

Volt Component Structure

<?php

use App\Models\AdminLog;
use Livewire\Volt\Component;
use Livewire\WithPagination;
use Symfony\Component\HttpFoundation\StreamedResponse;

new class extends Component {
    use WithPagination;

    public string $actionFilter = '';
    public string $targetFilter = '';
    public string $dateFrom = '';
    public string $dateTo = '';
    public string $search = '';
    public ?int $selectedLogId = null;

    public function updatedActionFilter(): void { $this->resetPage(); }
    public function updatedTargetFilter(): void { $this->resetPage(); }
    public function updatedDateFrom(): void { $this->resetPage(); }
    public function updatedDateTo(): void { $this->resetPage(); }
    public function updatedSearch(): void { $this->resetPage(); }

    public function resetFilters(): void
    {
        $this->reset(['actionFilter', 'targetFilter', 'dateFrom', 'dateTo', 'search']);
        $this->resetPage();
    }

    public function showDetails(int $logId): void
    {
        $this->selectedLogId = $logId;
        $this->dispatch('open-modal', name: 'log-details');
    }

    public function with(): array
    {
        return [
            'logs' => $this->getFilteredQuery()->paginate(25),
            'actionTypes' => AdminLog::distinct()->pluck('action'),
            'targetTypes' => AdminLog::distinct()->pluck('target_type'),
            'selectedLog' => $this->selectedLogId
                ? AdminLog::with('admin')->find($this->selectedLogId)
                : null,
        ];
    }

    public function exportCsv(): StreamedResponse
    {
        $logs = $this->getFilteredQuery()->get();

        return response()->streamDownload(function () use ($logs) {
            $handle = fopen('php://output', 'w');

            // Header row (bilingual based on locale)
            fputcsv($handle, [
                __('audit.timestamp'),
                __('audit.admin'),
                __('audit.action'),
                __('audit.target_type'),
                __('audit.target_id'),
                __('audit.ip_address'),
            ]);

            foreach ($logs as $log) {
                fputcsv($handle, [
                    $log->created_at->format('Y-m-d H:i:s'),
                    $log->admin?->name ?? __('audit.system'),
                    $log->action,
                    $log->target_type,
                    $log->target_id,
                    $log->ip_address,
                ]);
            }

            fclose($handle);
        }, 'audit-log-' . now()->format('Y-m-d') . '.csv');
    }

    private function getFilteredQuery()
    {
        return AdminLog::query()
            ->with('admin')
            ->when($this->actionFilter, fn($q) => $q->where('action', $this->actionFilter))
            ->when($this->targetFilter, fn($q) => $q->where('target_type', $this->targetFilter))
            ->when($this->dateFrom, fn($q) => $q->whereDate('created_at', '>=', $this->dateFrom))
            ->when($this->dateTo, fn($q) => $q->whereDate('created_at', '<=', $this->dateTo))
            ->when($this->search, fn($q) => $q->where('target_id', $this->search))
            ->latest();
    }
}; ?>

<div>
    <!-- Filters Section -->
    <!-- Table Section -->
    <!-- Pagination -->
    <!-- Detail Modal -->
</div>

Template Structure

<div class="space-y-6">
    {{-- Filters --}}
    <div class="flex flex-wrap gap-4">
        <flux:select wire:model.live="actionFilter" placeholder="{{ __('audit.filter_action') }}">
            <flux:select.option value="">{{ __('audit.all_actions') }}</flux:select.option>
            @foreach($actionTypes as $type)
                <flux:select.option value="{{ $type }}">{{ __("audit.action_{$type}") }}</flux:select.option>
            @endforeach
        </flux:select>

        <flux:select wire:model.live="targetFilter" placeholder="{{ __('audit.filter_target') }}">
            <flux:select.option value="">{{ __('audit.all_targets') }}</flux:select.option>
            @foreach($targetTypes as $type)
                <flux:select.option value="{{ $type }}">{{ __("audit.target_{$type}") }}</flux:select.option>
            @endforeach
        </flux:select>

        <flux:input type="date" wire:model.live="dateFrom" />
        <flux:input type="date" wire:model.live="dateTo" />
        <flux:input wire:model.live.debounce.300ms="search" placeholder="{{ __('audit.search_target_id') }}" />

        <flux:button wire:click="resetFilters" variant="ghost">{{ __('audit.reset') }}</flux:button>
        <flux:button wire:click="exportCsv">{{ __('audit.export_csv') }}</flux:button>
    </div>

    {{-- Table --}}
    @if($logs->isEmpty())
        <flux:callout>{{ __('audit.no_logs_found') }}</flux:callout>
    @else
        <table class="min-w-full">
            <thead>
                <tr>
                    <th>{{ __('audit.timestamp') }}</th>
                    <th>{{ __('audit.admin') }}</th>
                    <th>{{ __('audit.action') }}</th>
                    <th>{{ __('audit.target') }}</th>
                    <th>{{ __('audit.ip_address') }}</th>
                    <th></th>
                </tr>
            </thead>
            <tbody>
                @foreach($logs as $log)
                    <tr wire:key="log-{{ $log->id }}">
                        <td>{{ $log->created_at->translatedFormat(app()->getLocale() === 'ar' ? 'd/m/Y H:i' : 'm/d/Y H:i') }}</td>
                        <td>{{ $log->admin?->name ?? __('audit.system') }}</td>
                        <td>
                            <flux:badge
                                color="{{ match($log->action) {
                                    'create' => 'green',
                                    'update' => 'blue',
                                    'delete' => 'red',
                                    default => 'zinc'
                                } }}">
                                {{ __("audit.action_{$log->action}") }}
                            </flux:badge>
                        </td>
                        <td>{{ __("audit.target_{$log->target_type}") }} #{{ $log->target_id }}</td>
                        <td>{{ $log->ip_address }}</td>
                        <td>
                            <flux:button size="sm" wire:click="showDetails({{ $log->id }})">
                                {{ __('audit.details') }}
                            </flux:button>
                        </td>
                    </tr>
                @endforeach
            </tbody>
        </table>

        {{ $logs->links() }}
    @endif

    {{-- Detail Modal --}}
    <flux:modal name="log-details">
        @if($selectedLog)
            <flux:heading>{{ __('audit.log_details') }}</flux:heading>

            @if($selectedLog->old_values)
                <div>
                    <strong>{{ __('audit.old_values') }}:</strong>
                    <pre class="bg-zinc-100 p-2 rounded text-sm overflow-auto">{{ json_encode($selectedLog->old_values, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) }}</pre>
                </div>
            @endif

            @if($selectedLog->new_values)
                <div>
                    <strong>{{ __('audit.new_values') }}:</strong>
                    <pre class="bg-zinc-100 p-2 rounded text-sm overflow-auto">{{ json_encode($selectedLog->new_values, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE) }}</pre>
                </div>
            @endif
        @endif
    </flux:modal>
</div>

Action Badge Colors

Action	Color	Meaning
create	green	New record created
update	blue	Record modified
delete	red	Record removed
approve	green	Booking approved
reject	red	Booking rejected
archive	zinc	Timeline archived

Testing Requirements

Test Scenarios

// tests/Feature/Admin/AuditLogTest.php

test('audit log page requires admin authentication', function () {
    $this->get(route('admin.audit-logs'))
        ->assertRedirect(route('login'));
});

test('audit log page loads for admin', function () {
    $admin = User::factory()->admin()->create();

    $this->actingAs($admin)
        ->get(route('admin.audit-logs'))
        ->assertOk()
        ->assertSeeLivewire('admin.audit-logs');
});

test('audit logs display in table', function () {
    $admin = User::factory()->admin()->create();
    AdminLog::factory()->count(5)->create();

    Volt::test('admin.audit-logs')
        ->actingAs($admin)
        ->assertSee('audit.timestamp');
});

test('can filter by action type', function () {
    $admin = User::factory()->admin()->create();
    AdminLog::factory()->create(['action' => 'create']);
    AdminLog::factory()->create(['action' => 'delete']);

    Volt::test('admin.audit-logs')
        ->actingAs($admin)
        ->set('actionFilter', 'create')
        ->assertSee('create')
        ->assertDontSee('delete');
});

test('can filter by target type', function () {
    $admin = User::factory()->admin()->create();
    AdminLog::factory()->create(['target_type' => 'user']);
    AdminLog::factory()->create(['target_type' => 'consultation']);

    Volt::test('admin.audit-logs')
        ->actingAs($admin)
        ->set('targetFilter', 'user')
        ->assertSee('user');
});

test('can filter by date range', function () {
    $admin = User::factory()->admin()->create();
    AdminLog::factory()->create(['created_at' => now()->subDays(10)]);
    AdminLog::factory()->create(['created_at' => now()]);

    Volt::test('admin.audit-logs')
        ->actingAs($admin)
        ->set('dateFrom', now()->subDays(5)->format('Y-m-d'))
        ->set('dateTo', now()->format('Y-m-d'))
        ->assertViewHas('logs', fn($logs) => $logs->count() === 1);
});

test('can search by target id', function () {
    $admin = User::factory()->admin()->create();
    AdminLog::factory()->create(['target_id' => 123]);
    AdminLog::factory()->create(['target_id' => 456]);

    Volt::test('admin.audit-logs')
        ->actingAs($admin)
        ->set('search', '123')
        ->assertViewHas('logs', fn($logs) => $logs->count() === 1);
});

test('can view log details in modal', function () {
    $admin = User::factory()->admin()->create();
    $log = AdminLog::factory()->create([
        'old_values' => ['name' => 'Old Name'],
        'new_values' => ['name' => 'New Name'],
    ]);

    Volt::test('admin.audit-logs')
        ->actingAs($admin)
        ->call('showDetails', $log->id)
        ->assertSet('selectedLogId', $log->id);
});

test('can export filtered logs to csv', function () {
    $admin = User::factory()->admin()->create();
    AdminLog::factory()->count(3)->create();

    Volt::test('admin.audit-logs')
        ->actingAs($admin)
        ->call('exportCsv')
        ->assertFileDownloaded();
});

test('displays empty state when no logs', function () {
    $admin = User::factory()->admin()->create();

    Volt::test('admin.audit-logs')
        ->actingAs($admin)
        ->assertSee(__('audit.no_logs_found'));
});

test('pagination works correctly', function () {
    $admin = User::factory()->admin()->create();
    AdminLog::factory()->count(50)->create();

    Volt::test('admin.audit-logs')
        ->actingAs($admin)
        ->assertViewHas('logs', fn($logs) => $logs->count() === 25);
});

test('reset filters clears all filters', function () {
    $admin = User::factory()->admin()->create();

    Volt::test('admin.audit-logs')
        ->actingAs($admin)
        ->set('actionFilter', 'create')
        ->set('targetFilter', 'user')
        ->set('search', '123')
        ->call('resetFilters')
        ->assertSet('actionFilter', '')
        ->assertSet('targetFilter', '')
        ->assertSet('search', '');
});

Edge Cases & Error Handling

Empty state: Display friendly message when no logs exist or filters return nothing
Deleted admin: Show "System" or "Deleted User" if admin_id references deleted user
Large JSON values: Truncate display in table, show full in modal with scroll
IPv6 addresses: Ensure column width accommodates longer IP addresses
Missing target: Handle gracefully if target record was deleted (show ID only)
Pagination reset: Reset to page 1 when filters change

Definition of Done

Audit logs page accessible at /admin/audit-logs
Logs display with all required columns
All filters work correctly (action, target, date range)
Search by target ID works
Pagination displays 25 items per page
CSV export downloads with filtered data
Detail modal shows old/new values formatted
Empty state displays when appropriate
Bilingual support (AR/EN) complete
Admin-only access enforced
All tests pass
Code formatted with Pint

Estimation

Complexity: Medium | Effort: 3-4 hours

Dev Agent Record

Status

Ready for Review

Agent Model Used

Claude Opus 4.5 (claude-opus-4-5-20251101)

Completion Notes

AdminLog model already existed from Story 1.1 with correct structure (admin_id, action, target_type, target_id, old_values, new_values, ip_address, created_at)
AdminLogFactory already existed with useful test states
Created Volt component following existing admin patterns (consultations/index, timelines/index)
Implemented all filters: action type, target type, date range, target ID search
Pagination set to 25 items per page as specified
CSV export with bilingual headers based on locale
Detail modal shows JSON-formatted old/new values with proper dark mode styling
Empty states for no logs and no filter results
Locale-aware timestamp formatting (d/m/Y for AR, m/d/Y for EN)
Action badge colors: green (create/approve), blue (update), red (delete/reject), amber (archive)
25 comprehensive Pest tests covering all acceptance criteria
All tests pass, code formatted with Pint

File List

New Files:

resources/views/livewire/admin/audit-logs.blade.php - Volt component for audit log viewer
lang/en/audit.php - English translations for audit log feature
lang/ar/audit.php - Arabic translations for audit log feature
tests/Feature/Admin/AuditLogTest.php - Feature tests (25 tests)

Modified Files:

routes/web.php - Added admin.audit-logs route

Change Log

2025-12-28: Initial implementation of Story 6.10 Audit Log Viewer

QA Results

Review Date: 2025-12-28

Reviewed By: Quinn (Test Architect)

Risk Assessment

Review Depth: Standard - No auto-escalation triggers detected:

No auth/payment/security files touched (read-only audit viewer)
Tests added: 25 comprehensive tests
Diff size: ~400 lines (under 500 line threshold)
Story has 4 main acceptance criteria sections

Code Quality Assessment

Overall: Excellent

The implementation demonstrates high-quality, production-ready code:

Architecture: Clean Volt component following established project patterns (class-based, WithPagination trait)
Design Patterns: Proper separation of concerns with private methods (getFilteredQuery, getActionColor)
Query Optimization: Eager loading (with('admin')) prevents N+1 queries
UI/UX: Responsive design with mobile/desktop views, dark mode support, proper loading states
Bilingual: Complete AR/EN translations with locale-aware date formatting
Code Style: Follows project coding standards, proper type hints, clean formatting

Requirements Traceability

Acceptance Criteria	Test Coverage	Status
Display Requirements
AC: Paginated table (25/page)	`pagination works correctly with 25 items per page`	✓
AC: Row displays all fields	`audit logs display in table`, `displays system for logs without admin`	✓
AC: Action badges color-coded	Implemented in Blade template	✓
AC: Details button	`can view log details in modal`	✓
Filtering
AC: Filter by action type	`can filter by action type`	✓
AC: Filter by target type	`can filter by target type`	✓
AC: Filter by date range	`can filter by date range`	✓
AC: Filters without reload	Livewire wire:model.live	✓
AC: Reset filters button	`reset filters clears all filters`	✓
Search
AC: Search by target ID	`can search by target id`	✓
AC: Real-time with debounce	wire:model.live.debounce.300ms	✓
Detail Modal
AC: Shows old/new values	`modal displays old and new values`	✓
AC: Bilingual labels	Translation files verified	✓
CSV Export
AC: Export filtered results	`can export filtered logs to csv`, `csv export respects filters`	✓
AC: Filename includes date	`csv filename includes current date`	✓
AC: Bilingual headers	`__('audit.xxx')` in export headers	✓
Empty State
AC: No logs message	`displays empty state when no logs exist`	✓
AC: No filter results	`displays empty state when filters return no results`	✓
Access Control
AC: Admin-only access	`audit log page requires admin authentication`, `client cannot access audit logs page`	✓

Coverage: 100% - All acceptance criteria have corresponding tests

Refactoring Performed

None required - implementation is clean and follows project standards.

Compliance Check

Coding Standards: ✓ Class-based Volt component, Flux UI components, proper translations
Project Structure: ✓ Files in correct locations per coding-standards.md
Testing Strategy: ✓ 25 Pest tests covering all scenarios
All ACs Met: ✓ 100% acceptance criteria coverage

Improvements Checklist

All items handled - no outstanding issues:

Authentication tests (admin required, client forbidden)
Display tests (table rendering, sorting, pagination)
Filter tests (action, target, date range, search)
Modal tests (show details, close modal, old/new values)
Export tests (CSV download, filtered export, filename)
Locale tests (timestamp format per locale)
Empty state tests (no logs, no filter results)
Pagination reset on filter change

Security Review

Status: PASS

Route protected by auth, active, and admin middleware chain
No SQL injection risk (using Eloquent ORM with parameterized queries)
No XSS risk (using Blade escaping {{ }})
Read-only feature (audit logs cannot be modified through this interface)
No sensitive data exposure (audit log viewer displays data already accessible to admin)

Performance Considerations