From 8eaf2ed0a03e300a53caa409fe70362305f80197 Mon Sep 17 00:00:00 2001 From: Hardik Date: Mon, 22 Jun 2026 04:58:22 +0530 Subject: [PATCH] docs: submitter view-all feature flag (read+export every PO, History) --- Environment-Variables.md | 7 +++++++ Feature-Catalogue.md | 4 +++- Pages-and-Navigation.md | 7 ++++--- Roles-and-Permissions.md | 32 ++++++++++++++++++++++++++++++++ 4 files changed, 46 insertions(+), 4 deletions(-) diff --git a/Environment-Variables.md b/Environment-Variables.md index 31c66f8..58cb9aa 100644 --- a/Environment-Variables.md +++ b/Environment-Variables.md @@ -31,6 +31,7 @@ Server-side env on pms1 lives in `~/pms/App/.env`; locally in `App/.env.local` | `FORGEJO_TOKEN` | optional | optional | Token scope `write:issue` | | `GST_SERVICE_URL` | optional | optional | GstService base (default `http://localhost:3003`) | | `NEXT_PUBLIC_INVENTORY_ENABLED` | optional | optional | Inventory flag — **off only when `"false"`** | +| `NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED` | optional | optional | Submitter view-all flag — **on only when `"true"`**. Lets TECHNICAL/MANNING read & export every PO and open History | | `NEXT_PUBLIC_ENV_LABEL` | optional | **unset** | When set, shows the non-prod banner (`EnvBanner`). Leave unset in production | | `PORT` | optional | optional | App port (default 3000; staging 3200; autofix 3100) | @@ -44,6 +45,12 @@ Server-side env on pms1 lives in `~/pms/App/.env`; locally in `App/.env.local` [File Storage](File-Storage) and [Notifications](Notifications). - **Inventory flag** — `INVENTORY_ENABLED = NEXT_PUBLIC_INVENTORY_ENABLED !== "false"`, i.e. enabled unless explicitly `"false"`. +- **Submitter view-all flag** — `SUBMITTER_VIEW_ALL_ENABLED = + NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED === "true"`, i.e. **off unless + explicitly `"true"`** (opt-in, since it widens read access). When on, submitter + roles (TECHNICAL/MANNING) can read & export **every** PO and reach the History + page; it grants no approval/payment/edit rights. See + [Roles and Permissions](Roles-and-Permissions#feature-flagged-access). - **Env banner** — `EnvBanner` renders nothing when `NEXT_PUBLIC_ENV_LABEL` is unset, so production is unaffected; staging sets it to the "INTERNAL DEV / STAGING - NOT PRODUCTION" string. diff --git a/Feature-Catalogue.md b/Feature-Catalogue.md index 56a9d46..4f24874 100644 --- a/Feature-Catalogue.md +++ b/Feature-Catalogue.md @@ -50,7 +50,9 @@ with the detail, or names the code that implements it. centre and by month (Recharts). - **In-app notification bell** with unread badge, plus email at every transition. - **History & export** — filter by date range, cost centre, and **multiple - statuses**; CSV/PDF export (up to ~200 rows). + statuses**; CSV/PDF export (up to ~200 rows). Open to `export_reports` holders; + **submitters get read+export access under the `NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED` + flag** (read-only). See [Roles and Permissions](Roles-and-Permissions#feature-flagged-access). - **Mobile experience** — manager/accounts get mobile cards + bottom nav; other roles see a "Desktop Required" overlay. - **PPMS rebrand** — login, sidebar, and title show "PPMS". diff --git a/Pages-and-Navigation.md b/Pages-and-Navigation.md index 7c05606..ebe9232 100644 --- a/Pages-and-Navigation.md +++ b/Pages-and-Navigation.md @@ -15,7 +15,8 @@ My Orders /my-orders ← TECH, MANNING, MANAGER, SUPERUSER Approvals /approvals ← MANAGER, SUPERUSER Import PO /po/import ← MANAGER, SUPERUSER, ADMIN Payments /payments ← ACCOUNTS (+ MANAGER, SUPERUSER) -History / Export /history ← MANAGER, SUPERUSER, ACCOUNTS, AUDITOR, ADMIN +History / Export /history ← MANAGER, SUPERUSER, AUDITOR, ADMIN + (+ TECHNICAL, MANNING when SUBMITTER_VIEW_ALL flag on) Vendors /inventory/vendors ← MANAGER, ACCOUNTS, ADMIN Items /inventory/items ← all (read-only catalogue) Cart /inventory/cart ← TECH, MANNING, MANAGER, SUPERUSER @@ -39,7 +40,7 @@ SuperUser Requests /admin/superuser-requests ← ADMIN | `/dashboard` | Dashboard | Role-specific stat cards + charts | | `/my-orders` | My Purchase Orders | Submitter's open & past POs (Closed list scoped by role) | | `/po/new` | New PO | Multi-section form (header, line items, T&C, documents) | -| `/po/[id]` | PO Detail | Read view; contextual action buttons by status/role; export | +| `/po/[id]` | PO Detail | Read view; contextual action buttons by status/role; export. Own PO always; any PO for `view_all_pos` holders (and submitters when the `SUBMITTER_VIEW_ALL` flag is on) | | `/po/[id]/edit` | Edit PO | DRAFT or EDITS_REQUESTED, owner/SUPERUSER; "Update & Resubmit" | | `/po/[id]/receipt` | Confirm Receipt | PAID_DELIVERED; upload receipt; full or partial | | `/po/import` | Import PO | Upload Pelagia-format Excel → CLOSED | @@ -47,7 +48,7 @@ SuperUser Requests /admin/superuser-requests ← ADMIN | `/approvals/[id]` | Approval Detail | Approve / Approve+Note / Reject / Request Edits / Request Vendor ID; inline line-item edit | | `/payments` | Payment Queue | MGR_APPROVED & SENT_FOR_PAYMENT cards; send/mark paid; partial | | `/payments/history` | Payment History | Completed payments (ACCOUNTS, MANAGER) | -| `/history` | History & Export | All POs; filter by date/cost centre/multiple statuses; CSV/PDF | +| `/history` | History & Export | All POs; filter by date/cost centre/multiple statuses; CSV/PDF. `export_reports` holders, plus submitters when the `SUBMITTER_VIEW_ALL` flag is on | | `/inventory/items` | Items (read-only) | Catalogue; expand for per-vendor prices; Cheapest/★Closest tags | | `/inventory/items/[id]` | Item Detail | Price comparison, site-distance sort, stock by site | | `/inventory/vendors` | Vendors | List with verified/active badges | diff --git a/Roles-and-Permissions.md b/Roles-and-Permissions.md index 626d3d2..ed32d4f 100644 --- a/Roles-and-Permissions.md +++ b/Roles-and-Permissions.md @@ -62,6 +62,38 @@ The exact `ROLE_PERMISSIONS` map in `lib/permissions.ts`. ✓ = granted. (`manage_users` plus the catalogue/`manage_*` permissions) and can view/export. - **AUDITOR is strictly read-only** (`view_*`, `export_reports`). +## Feature-flagged access + +### Submitter view-all (`NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED`) + +By default submitters (**TECHNICAL**, **MANNING**) only see the POs they raised. +When `NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED="true"` they gain **read-only** +access to every PO: + +- the **History** page (`/history`) and its CSV/PDF report export; +- any other user's **PO detail** page (`/po/[id]`); +- the **Export PDF / XLSX** buttons on those POs (approved & cancelled POs only, + same status gate as everyone else). + +It is a pure read widening — it grants **no** approval, payment, edit, cancel, or +admin rights, and does not change what non-submitter roles can do. The flag is +**opt-in** (off unless the value is exactly `"true"`). + +Implementation lives in `lib/permissions.ts`: + +| Helper | Meaning | +|---|---| +| `isSubmitterRole(role)` | `role ∈ {TECHNICAL, MANNING}` | +| `submitterCanViewAll(role)` | flag is on **and** `isSubmitterRole(role)` | +| `canViewAllPos(role)` | `hasPermission(role, "view_all_pos") \|\| submitterCanViewAll(role)` | + +`canViewAllPos` gates the PO detail page and the per-PO export route; +`submitterCanViewAll` is OR'd into the `export_reports` gate on the History page, +the report-export route, and the sidebar's History link. When the flag is off, +all of these collapse to the prior behaviour (view_all_pos holders only). The +`my-orders` "Closed Purchase Orders" list stays personal for submitters +regardless — History is the all-POs surface. + ## Business rules layered on top Beyond the permission map, server actions and the state machine enforce: