# Task 25 — Audit Logs

## Goal
Build the Audit Logs module to record important system actions for traceability and accountability.
This task focuses on tracking create, update, delete, and key workflow actions across the ERP.

---

## Scope

This task covers:
- audit log storage
- audit log listing UI
- reusable logging service or package integration

This task does NOT cover:
- advanced security SIEM integration
- external log shipping
- full field-level change diff for every model unless supported by implementation choice

---

## Database

Preferred approach:
- use activity log package or custom `activity_logs` table

Custom table option: `activity_logs`

Fields:
- id
- log_name (nullable string)
- subject_type (nullable string)
- subject_id (nullable unsignedBigInteger)
- causer_type (nullable string)
- causer_id (nullable unsignedBigInteger)
- event (nullable string)
- description (nullable text)
- properties (json, nullable)
- ip_address (nullable string)
- created_at
- updated_at

Indexes:
- index subject_type + subject_id
- index causer_type + causer_id
- index event
- index log_name

---

## Relations

Audit log records may refer to:
- subject model (e.g., Branch, JournalEntry, Invoice)
- causer model (usually Admin)

---

## Business Rules

1. Audit logs must be append-only.
2. Dashboard users with permission can view audit logs.
3. Important events should be loggable from services later.
4. Properties JSON can store before/after values or metadata.
5. Logs should be filterable by event, causer, and subject.

---

## Files

### Model
- app/Models/System/ActivityLog.php (if custom table used)

### Service
- app/Services/System/AuditLogService.php

### Controller
- app/Http/Controllers/Admin/System/AuditLogController.php

### Requests
- app/Http/Requests/Admin/System/AuditLogFilterRequest.php

### Views
- resources/views/dashboard/system/audit_logs/index.blade.php

### Lang files
- lang/ar/system.php
- lang/en/system.php

---

## Permissions

- system.audit_logs.view

---

## UI

Views path:
`resources/views/dashboard/system/audit_logs/`

### Filter fields
- event
- causer
- subject_type
- date range

### Table columns
- created_at
- event
- description
- causer
- subject
- ip_address

---

## Lang Keys

Suggested keys:
- audit_logs
- audit_log
- event
- description
- causer
- subject
- ip_address
- created_at
- filter
- no_data_found

---

## Seeder

Update RolePermissionSeeder with:
- system.audit_logs.view

---

## Steps

### Step 1
Create or confirm audit log storage strategy.

### Step 2
Create model if using custom table.

### Step 3
Create `AuditLogService`.

### Step 4
Create `AuditLogFilterRequest`.

### Step 5
Create `AuditLogController`.

### Step 6
Add routes in `routes/admin.php`.

### Step 7
Create audit logs view.

### Step 8
Create lang files.

### Step 9
Update `RolePermissionSeeder`.

---

## Notes for AI

- Follow docs/ai/AI_MASTER_PROJECT.md
- Follow docs/ai/ARCHITECTURE_RULES.md
- Follow docs/ai/MODULE_STRUCTURE.md
- Execute one step at a time
- Do not modify unrelated files
- Do not generate tests in this task
- Wait for confirmation after each step