Server backup 2026-11-07 of uncommitted work in projects/pharma-web-celtic
Snapshot of the working tree on srv1071960 (branch main), taken during server cleanup. .env files, node_modules, builds, logs and media were excluded.
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
> **Deploying to a server?** Use [PRODUCTION.md](PRODUCTION.md) — the operator's guide (first deployment, real users, backups, updates, runbook). This README is for development.
|
||||
|
||||
Field-force reporting for a pharmaceutical sales team (Celtic Life Science Pvt Ltd): Medical Representatives (MRs) file **Daily Call Reports**, Area Managers (AMs) review and approve them (the General Manager has a read-only overview), and approved reports are locked and rendered as PDFs. Alongside the DCR, the system manages the company's paper forms — tour plans, fare charts, stock statements and more — and prints each one on its own PDF layout.
|
||||
Field-force reporting for a pharmaceutical sales team (Celtic Life Science Pvt Ltd): Medical Representatives (MRs) file **Daily Call Reports**, Area Business Managers (ABMs) review and approve them (the Assistant General Manager (AGM) has a read-only overview), and approved reports are locked and rendered as PDFs. Alongside the DCR, the system manages the company's paper forms — tour plans, fare charts, stock statements and more — and prints each one on its own PDF layout.
|
||||
|
||||
- **Backend:** FastAPI · SQLAlchemy 2 (async) · PostgreSQL 16 · Alembic
|
||||
- **PDFs:** Jinja2 templates rendered by WeasyPrint
|
||||
@@ -35,11 +35,11 @@ Deliberately **not** in scope: HR, payroll, attendance, distributor management,
|
||||
| Area | What it does |
|
||||
|---|---|
|
||||
| Daily Call Reports | MR records doctor and chemist calls per day; one report per MR per date |
|
||||
| Approval workflow | `DRAFT → PENDING_AM → APPROVED`, with a return-for-correction loop (the Area Manager is the final approver); approved reports are immutable |
|
||||
| Approval workflow | `DRAFT → PENDING_ABM → APPROVED`, with a return-for-correction loop (the Area Business Manager is the final approver); approved reports are immutable |
|
||||
| Audit trail | Append-only log of every state change; approval history is a view over it |
|
||||
| PDFs | Approved DCRs are stored as PDFs; company forms download as PDFs on demand |
|
||||
| Company forms | Ten form tables (tour plan, fare chart, stock statement, …) with per-form PDF layouts |
|
||||
| Masters | Users, headquarters, AM↔HQ mapping, doctors, chemists, products, with MR assignments |
|
||||
| Masters | Users, headquarters, ABM↔HQ mapping, doctors, chemists, products, with MR assignments |
|
||||
| Security | JWT with refresh-token rotation, argon2 password hashing, role **and** scope checks |
|
||||
|
||||
---
|
||||
@@ -181,7 +181,7 @@ cd web && npm install && npm run dev
|
||||
|
||||
**PDF rendering on a dev machine:** WeasyPrint needs Pango and HarfBuzz (`apt install libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz0b fonts-dejavu-core fonts-liberation fonts-crosextra-carlito` on Debian/Ubuntu). Without them the app still runs but produces plain-text PDFs and logs a warning; use the Docker image to see the real layout.
|
||||
|
||||
Seeded accounts (`scripts/seed.py`): `adm001@acmepharma.in` (System Admin), `gm001@acmepharma.in` (GM), `am001@acmepharma.in` (AM), `mr001@acmepharma.in` (MR) — one company, one headquarters (BBSR), 15 doctors (3 core) and 5 chemists assigned to the MR.
|
||||
Seeded accounts (`scripts/seed.py`): `adm001@acmepharma.in` (System Admin), `gm001@acmepharma.in` (AGM), `am001@acmepharma.in` (ABM), `mr001@acmepharma.in` (MR) — one company, one headquarters (BBSR), 15 doctors (3 core) and 5 chemists assigned to the MR.
|
||||
|
||||
---
|
||||
|
||||
@@ -245,7 +245,7 @@ web/src/
|
||||
└── styles/ tokens.css · base.css · layout.css · components.css
|
||||
```
|
||||
|
||||
Screens are role-aware: MR / AM / GM get a dashboard with counts and a "waiting on you" queue; the Administrator gets an organisation overview. Routes use hash URLs (`#/reports/<id>`), so every screen is linkable and the back button works behind any static file server. To add a page, create it under `pages/`, add a route in `App.tsx` and a menu entry in `lib/navigation.ts`.
|
||||
Screens are role-aware: MR / ABM / AGM get a dashboard with counts and a "waiting on you" queue; the Administrator gets an organisation overview. Routes use hash URLs (`#/reports/<id>`), so every screen is linkable and the back button works behind any static file server. To add a page, create it under `pages/`, add a route in `App.tsx` and a menu entry in `lib/navigation.ts`.
|
||||
|
||||
### Branding and theme
|
||||
|
||||
@@ -268,9 +268,9 @@ The UI uses the Celtic logo and the colours taken from it.
|
||||
| Role | Can do |
|
||||
|---|---|
|
||||
| **MR** | File and edit own DCRs while `DRAFT`/`RETURNED`; submit; edit company forms |
|
||||
| **AM** | Review DCRs of own headquarters: approve or return; sees only the approval forms (Tour Plan, Standard Tour Plan, Fare Chart) |
|
||||
| **GM** | Read-only: view reports, users and headquarters across the company; no approval step |
|
||||
| **ADMIN** | Provision users, headquarters and masters. **Cannot approve or read report content** |
|
||||
| **ABM** | Review DCRs of own headquarters: approve or return; sees only the approval forms (Tour Plan, Standard Tour Plan, Fare Chart) |
|
||||
| **AGM** | Read-only: view reports, users and headquarters across the company; no approval step |
|
||||
| **ADMIN** | Provision users, headquarters and masters; monitor and read Daily Call Reports across the company. **Cannot approve reports** |
|
||||
|
||||
Permissions are checked in two separate layers, because most RBAC bugs live in the gap between them:
|
||||
|
||||
@@ -282,7 +282,7 @@ current_user: User = Depends(require_role(Role.MR))
|
||||
await assert_can_view_dcr(db, current_user, dcr)
|
||||
```
|
||||
|
||||
"AM" is a role; "AM *of this headquarters*" is a scope. Both are mandatory on scoped endpoints, and each has a negative test asserting **403** — not 404 or an empty 200 — so a scope bug cannot hide behind an ambiguous response.
|
||||
"ABM" is the stored role code for an ABM; "ABM *of this headquarters*" is a scope. Both are mandatory on scoped endpoints, and each has a negative test asserting **403** — not 404 or an empty 200 — so a scope bug cannot hide behind an ambiguous response.
|
||||
|
||||
The System Administrator can never approve: `ADMIN` matches no transition in the state machine, so the audit trail stays evidence that a manager made the decision.
|
||||
|
||||
@@ -291,13 +291,13 @@ The System Administrator can never approve: `ADMIN` matches no transition in the
|
||||
## The approval workflow
|
||||
|
||||
```
|
||||
DRAFT ──submit(MR)──► PENDING_AM ──approve(AM)──► APPROVED (terminal, immutable)
|
||||
DRAFT ──submit(MR)──► PENDING_ABM ──approve(ABM)──► APPROVED (terminal, immutable)
|
||||
▲ │
|
||||
│ └──return(AM)──┐
|
||||
│ └──return(ABM)──┐
|
||||
└──────submit(MR)───── RETURNED ◄───────┘
|
||||
```
|
||||
|
||||
- `RETURNED` records who returned it in the `returned_by_role` column. There is no General Manager stage; the GM is a read-only role.
|
||||
- `RETURNED` records who returned it in the `returned_by_role` column. There is no AGM stage; the AGM is a read-only role.
|
||||
- `APPROVED` is both "finally approved" and "locked": immutability is a property of the state, enforced in one guard, so there is no window where a report is approved but still editable.
|
||||
- Managers change state and add comments; they never edit another person's call rows.
|
||||
- Returning a report requires a reason (`MIN_RETURN_REASON_LENGTH`).
|
||||
@@ -323,9 +323,9 @@ The `csv_data` module exposes the company's paper forms as editable tables, impo
|
||||
| Weekly Report | `weekly_report` | One page per saved report |
|
||||
| Daily Call Report (CSV) | `daily_call_report_csv` | Doctor and chemist sections (not exposed in the UI) |
|
||||
|
||||
¹ *Approval forms* — the AM can only see these, and their PDF carries the AM approval signature line.
|
||||
¹ *Approval forms* — the ABM can only see these, and their PDF carries the ABM approval signature line.
|
||||
|
||||
**Approval forms are per MR.** Tour Plan, Standard Tour Plan and Fare Chart rows belong to the MR who entered them (`owner_user_id`), each MR sees and numbers only their own, and the approval (`form_approval`) is kept per form *and* MR. A request goes only to the Area Manager who currently manages that MR's headquarters: any other Area Manager gets a 403 and never sees it in their list, and an MR whose headquarters has no Area Manager cannot send a form. Editing an MR's rows withdraws only that MR's approval. An admin fills a form in on behalf of one chosen MR and can never approve.
|
||||
**Approval forms are per MR.** Tour Plan, Standard Tour Plan and Fare Chart rows belong to the MR who entered them (`owner_user_id`), each MR sees and numbers only their own, and the approval (`form_approval`) is kept per form *and* MR. A request goes only to the Area Business Manager who currently manages that MR's headquarters: any other Area Business Manager gets a 403 and never sees it in their list, and an MR whose headquarters has no Area Business Manager cannot send a form. Editing an MR's rows withdraws only that MR's approval. An admin fills a form in on behalf of one chosen MR and can never approve.
|
||||
|
||||
**Monthly download.** Forms with a month (Sales Projection, Weekly Report, Field Activity Report, Core Doctor Call Conversion, Area Covered, Sales and Stock Statement) get a Month selector. The table and the PDF (`GET /csv-data/{form}/pdf?month=November`) then cover that month only; a month with no rows is refused rather than printed blank.
|
||||
|
||||
@@ -347,7 +347,7 @@ Base path `/api/v1`; interactive documentation at `/docs` and `/redoc`, schema a
|
||||
|---|---|---|
|
||||
| auth | `/auth` | Login, refresh (rotating tokens), logout, current user |
|
||||
| users | `/users` | User administration and the MR profile |
|
||||
| organization | `/headquarters` | Headquarters and AM↔HQ mapping |
|
||||
| organization | `/headquarters` | Headquarters and ABM↔HQ mapping |
|
||||
| doctors, chemists | `/doctors`, `/chemists` | Masters and MR assignment |
|
||||
| products | `/products` | Product master and stock inventory list |
|
||||
| reports | `/dcr` | DCR CRUD, calls, submit / return / approve, PDF |
|
||||
@@ -395,7 +395,7 @@ ALTER TABLE daily_call_report ADD CONSTRAINT uq_dcr_mr_date UNIQUE (mr_user_id,
|
||||
-- No duplicate doctor call within one report
|
||||
ALTER TABLE doctor_call ADD CONSTRAINT uq_call_dcr_doctor UNIQUE (dcr_id, doctor_id);
|
||||
|
||||
-- Exactly one active Area Manager per headquarters
|
||||
-- Exactly one active Area Business Manager per headquarters
|
||||
CREATE UNIQUE INDEX uq_active_am_per_hq ON am_headquarters (headquarters_id)
|
||||
WHERE effective_to IS NULL;
|
||||
```
|
||||
@@ -447,7 +447,7 @@ pytest tests/unit -q # state machine, PDF layouts — s
|
||||
|
||||
## Known limitations
|
||||
|
||||
- **Company-form approval is per form, not per row.** The tour plan, standard tour plan and fare chart each have one server-stored approval state (`draft → pending → approved`). The MR sends a form that has rows, the Area Manager approves it, and the PDF signature is decided by the server. Any change to the rows withdraws the approval.
|
||||
- **Company-form approval is per form, not per row.** The tour plan, standard tour plan and fare chart each have one server-stored approval state (`draft → pending → approved`). The MR sends a form that has rows, the Area Business Manager approves it, and the PDF signature is decided by the server. Any change to the rows withdraws the approval.
|
||||
- **`web/node_modules` and `web/dist` are committed** to the repository (with stale build output) and should be untracked; Docker builds the app from source.
|
||||
- The test suite needs a reachable PostgreSQL; some tests under `tests/unit` also need it.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user