Prepare ERP source for Gitea deployment

documents/PHASE_v2.0.3.3_NOTES.md

@@ -0,0 +1,51 @@
+# 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