# Audit_Firm_v2.0.3.4 — Phase 3 (Audit Trail)

This phase adds a reusable audit logging layer across the core admin flows.

## Added
- `app/modules/core/audit/models.py`
- `app/modules/core/audit/service.py`
- `app/modules/core/audit/templates/logs.html`
- enhanced `app/modules/core/audit/ui.py`

## Included capabilities
- audit log table: `audit_logs`
- automatic creation of audit table on startup if missing
- audit entries for:
  - user create/update (UI + API)
  - tenant create/update
  - branch create/update
  - role create
  - permission create
  - role-permission update
  - login success/failure/lockout/logout
  - OTP success/failure/OTP-required
  - token success/failure/refresh/logout
- actor context captured:
  - user id
  - email
  - tenant
  - branch
  - IP address
  - user agent
- target context captured:
  - target tenant
  - target branch
- before/after snapshots for update actions
- permission-based Audit Logs menu and screen

## Permission added
- `audit.view`

## Default role mapping
- System Admin → audit.view
- Firm Admin → audit.view
- Partner → audit.view
- Branch Manager → audit.view

## Notes
- current implementation uses `details_json` text storage for maximum SQLite/Postgres compatibility
- logs are shown with scope filtering:
  - System Admin → all audit logs
  - tenant scoped roles → same tenant
  - branch scoped roles → same tenant + same branch