Prepare ERP source for Gitea deployment

2026-06-20 15:01:44 +05:30
commit 5c75eb6bd9
450 changed files with 67698 additions and 0 deletions
@@ -0,0 +1,16 @@
+
+Audit_Firm_v2.0.3.1
+
+Phase: Scope Hardening
+
+Key additions:
+- Scope guard utilities for tenant and branch validation
+- Intended to be used by IAM, RBAC and System Settings modules
+- Prevents cross-tenant and cross-branch operations
+
+Next planned phases:
+v2.0.3.2  Permission Guards
+v2.0.3.4  Audit Trail
+v2.0.3.4  User Lifecycle Controls
+v2.0.3.5  Invite / Password Reset Flows
+v2.0.3.6  Service Layer Refactor + UI Improvements
@@ -0,0 +1,9 @@
+# Audit_Firm_v2.0.3.2
+
+Phase 2 adds permission guards on top of v2.0.3.1:
+- central permission registry
+- reusable permission guard for UI and API
+- permission-aware sidebar/menu
+- UI route protection for Users, RBAC, and System Settings
+- FastAPI dependencies now raise HTTP 403 instead of generic PermissionError
+- template helper functions for button and menu visibility
@@ -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
@@ -0,0 +1,10 @@
+# Audit_Firm_v2.0.3.4 — Phase 4: User Lifecycle Controls
+
+Included in this phase:
+- user lifecycle fields: allow_login, is_locked, locked_at_utc, deleted_at
+- lifecycle helpers for activate/deactivate, login enable/disable, lock/unlock, soft delete/restore
+- UI lifecycle actions on the user management screen
+- API lifecycle endpoints for the same actions
+- audit logging for lifecycle actions
+- startup guard to add missing lifecycle columns on existing databases
+- auth/session checks updated to respect login-disabled, locked, and soft-deleted users
@@ -0,0 +1,6 @@
+Phase 5: Invite and password flows
+- invite token model and service
+- forgot/reset password flows
+- accept invite flow
+- must_change_password enforcement
+- invite generation from user list and user create form
@@ -0,0 +1,9 @@
+# Phase v2.0.3.6 - Service Layer Refactor + UI Cleanup
+
+Included in this phase:
+- introduced service modules for IAM, RBAC, and tenancy listing/filtering/pagination
+- reduced route-level query assembly in UI handlers
+- standardized reusable Tailwind UI macros for alerts, badges, search bars, empty states, and pagination
+- added search + pagination for users, roles, permissions, tenants, branches, and audit logs
+- corrected the broken branches list screen and replaced it with a proper directory view
+- updated version markers to Audit_Firm_v2.0.3.6
@@ -0,0 +1,102 @@
+# Audit Firm v2 — Full Baseline (Tailwind CDN + HTML + API + Security + System Settings)
+
+This baseline is designed to be a **stable v2 foundation** before adding other modules.
+
+## What’s included
+- FastAPI app with **HTML + API** side-by-side
+- Tailwind CSS via **CDN**
+- Modular templates: `app/ui/templates/modules/<module>/...`
+- System Settings module (super-admin UI):
+  - Tenants
+  - Branches
+  - Branch policies (identity, holidays, email policy, storage policy, security policy)
+- Security (built-in):
+  - Password hashing (bcrypt via passlib)
+  - Session auth (browser UI) + CSRF protection for HTML forms
+  - Secure cookie options (configurable) + security headers + CSP (Tailwind CDN allowed)
+  - RBAC (roles/permissions) with default roles seeded:
+    - System Admin, Firm Admin, Partner, Branch Manager, Staff, Client, Consultant
+  - Login lockout policy (attempts + lockout minutes) enforced
+  - Session expiry policy enforced (minutes)
+  - OTP step (dev mode): OTP code is printed to console (placeholder for SMS/Email provider)
+
+- DB:
+  - Common DB via SQLAlchemy (SQLite now; Postgres later)
+  - Tables are created on startup using `metadata.create_all()` to keep install smooth.
+    (Next step: replace with Alembic common + year.)
+
+- Tools:
+  - Local Storage Agent generator (`tools/storage_agent/`)
+
+## Quick start (Windows)
+```bat
+python -m venv venv
+venv\Scripts\activate
+pip install -r requirements.txt
+copy .env.example .env
+
+uvicorn app.main:app --reload
+```
+
+Open:
+- http://127.0.0.1:8000/health
+- http://127.0.0.1:8000/login
+- http://127.0.0.1:8000/system-settings
+
+Bootstrap admin (first run):
+- Uses `BOOTSTRAP_ADMIN_EMAIL` and `BOOTSTRAP_ADMIN_PASSWORD` from `.env`
+
+## OTP (dev placeholder)
+If OTP is required for your role (see Branch Settings → Security Policy),
+the app will show an OTP page after password login and print the OTP code in the console logs.
+
+## JWT (API authentication)
+Endpoints:
+- POST `/api/auth/token`
+- POST `/api/auth/refresh`
+- POST `/api/auth/logout`
+- GET  `/api/auth/me` (debug helper)
+
+Notes:
+- Access token is JWT (HS256) signed using `SECRET_KEY`
+- Refresh token is opaque and stored hashed (sha256) in DB with rotation
+
+## Template structure refactor
+Templates are now organized as:
+- `app/modules/system_settings/templates/...`
+- `app/modules/core/iam/templates/...`
+- `app/modules/core/audit/templates/...`
+- shared base remains at `app/ui/templates/base/layout.html`
+
+The Jinja loader resolves from `app/`, so module templates can safely extend:
+`ui/templates/base/layout.html`
+
+## Alembic added to baseline
+This baseline now uses **Alembic for the Common DB from the beginning**.
+
+### First-time setup
+1. Create virtual environment and install requirements
+2. Copy `.env.example` to `.env`
+3. Run:
+   `alembic upgrade head`
+4. Start app:
+   `uvicorn app.main:app --reload`
+
+### Create a new migration
+`alembic revision --autogenerate -m "message"`
+
+### Apply migrations
+`alembic upgrade head`
+
+### Downgrade one step
+`alembic downgrade -1`
+
+### Windows helper scripts
+- `scripts\migrate_up.bat`
+- `scripts\new_migration.bat "message"`
+
+### Important
+- App startup no longer creates schema automatically.
+- Schema must be migrated using Alembic first.
+- This baseline adds **Common DB Alembic only**.
+- `alembic_year/` for year databases can be added next.