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,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.