feat(po): submitter view-all of POs + History + export (feature-flagged)

Gated behind NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED (opt-in, "true").
When on, submitter roles (TECHNICAL/MANNING) get read-only access to every
PO: the History page + report export, any other user's PO detail page, and
the per-PO Export PDF/XLSX buttons. No approval/payment/edit rights are added.

- lib/feature-flags.ts: SUBMITTER_VIEW_ALL_ENABLED flag
- lib/permissions.ts: isSubmitterRole / submitterCanViewAll / canViewAllPos
- po/[id] page + export route: gate via canViewAllPos
- history page + reports/export route: OR submitterCanViewAll into export_reports
- sidebar: show History to submitters when flag on
- tests: permission helpers, both flag states
- docs: .env.example, CLAUDE.md (wiki updated separately)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

App/.env.example

@@ -55,6 +55,13 @@ FORGEJO_URL=https://git.pelagiamarine.com
 FORGEJO_REPO=shad0w/pelagia-portal
 FORGEJO_TOKEN=
 
+# ── Feature flags (NEXT_PUBLIC_, available to client + server) ─
+# Inventory tracking (site stock / consumption). On unless explicitly "false".
+# NEXT_PUBLIC_INVENTORY_ENABLED=false
+# Let submitters (TECHNICAL/MANNING) read & export every PO and open the History
+# page (read-only). Opt-in — on only when exactly "true".
+# NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED=true
+
 # ── Non-production banner ─────────────────────────────────────
 # When set, a fixed "internal dev / staging" banner is shown (EnvBanner).
 # Leave UNSET in production. Staging sets this automatically.

App/CLAUDE.md

@@ -142,6 +142,7 @@ FORGEJO_URL, FORGEJO_REPO, FORGEJO_TOKEN
 
 GST_SERVICE_URL         # GstService microservice (defaults to localhost:3003)
 NEXT_PUBLIC_INVENTORY_ENABLED   # Inventory feature flag
+NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED  # Opt-in ("true"): submitters (TECHNICAL/MANNING) read & export every PO + History (read-only)
 NEXT_PUBLIC_ENV_LABEL   # When set, shows a non-prod banner (EnvBanner). Leave unset in prod.
 ```
 

App/app/(portal)/history/page.tsx

@@ -1,6 +1,6 @@
 import { auth } from "@/auth";
 import { db } from "@/lib/db";
-import { hasPermission } from "@/lib/permissions";
+import { hasPermission, submitterCanViewAll } from "@/lib/permissions";
 import { redirect } from "next/navigation";
 import Link from "next/link";
 import { formatCurrency, formatDate } from "@/lib/utils";
@@ -27,7 +27,14 @@ export default async function HistoryPage({ searchParams }: Props) {
   const session = await auth();
   if (!session?.user) redirect("/login");
 
-  if (!hasPermission(session.user.role, "export_reports")) redirect("/dashboard");
+  // Report-export holders see History; submitters get read+export access when the
+  // submitter-view-all feature flag is on.
+  if (
+    !hasPermission(session.user.role, "export_reports") &&
+    !submitterCanViewAll(session.user.role)
+  ) {
+    redirect("/dashboard");
+  }
 
   const { dateFrom, dateTo, approvedFrom, approvedTo, vesselId, status } = await searchParams;
 

App/app/(portal)/po/[id]/page.tsx

@@ -2,6 +2,7 @@ import { auth } from "@/auth";
 import { db } from "@/lib/db";
 import { notFound, redirect } from "next/navigation";
 import { PoDetail } from "@/components/po/po-detail";
+import { canViewAllPos } from "@/lib/permissions";
 import { VendorIdForm } from "./vendor-id-form";
 import type { Metadata } from "next";
 
@@ -39,11 +40,11 @@ export default async function PoDetailPage({ params }: Props) {
 
   if (!po) notFound();
 
-  // Submitters can only view their own POs (unless they have view_all_pos)
+  // Submitters can only view their own POs — unless they hold view_all_pos, or the
-  const canViewAll = ["ACCOUNTS", "MANAGER", "SUPERUSER", "AUDITOR", "ADMIN"].includes(
+  // submitter-view-all feature flag grants them read access to every PO.
-    session.user.role
+  if (!canViewAllPos(session.user.role) && po.submitterId !== session.user.id) {
-  );
+    redirect("/dashboard");
-  if (!canViewAll && po.submitterId !== session.user.id) redirect("/dashboard");
+  }
 
   const canProvideVendorId =
     po.status === "VENDOR_ID_PENDING" &&

App/app/api/po/[id]/export/route.ts

@@ -7,6 +7,7 @@ import { downloadBuffer } from "@/lib/storage";
 import { CANCELLED_WATERMARK_PNG_BASE64, CANCELLED_WATERMARK_W, CANCELLED_WATERMARK_H } from "@/lib/cancelled-watermark";
 import { getImageSize, scaleToBox } from "@/lib/image-size";
 import { signatoryLayout } from "@/lib/po-export-layout";
+import { canViewAllPos } from "@/lib/permissions";
 
 // ── Company fallback constants (used when no company is linked to a PO) ──────
 
@@ -66,8 +67,9 @@ export async function GET(request: NextRequest, { params }: Props) {
   });
   if (!po) return NextResponse.json({ error: "Not found" }, { status: 404 });
 
-  const canViewAll = ["ACCOUNTS", "MANAGER", "SUPERUSER", "AUDITOR", "ADMIN"].includes(session.user.role);
+  // view_all_pos holders, or submitters when the view-all feature flag is on, may export
-  if (!canViewAll && po.submitterId !== session.user.id) {
+  // any PO; everyone else only their own.
+  if (!canViewAllPos(session.user.role) && po.submitterId !== session.user.id) {
     return NextResponse.json({ error: "Forbidden" }, { status: 403 });
   }
 

App/app/api/reports/export/route.ts

@@ -1,6 +1,6 @@
 import { auth } from "@/auth";
 import { db } from "@/lib/db";
-import { hasPermission } from "@/lib/permissions";
+import { hasPermission, submitterCanViewAll } from "@/lib/permissions";
 import { NextRequest, NextResponse } from "next/server";
 import type { POStatus } from "@prisma/client";
 
@@ -16,7 +16,10 @@ export async function GET(request: NextRequest) {
   if (!session?.user) {
     return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
   }
-  if (!hasPermission(session.user.role, "export_reports")) {
+  if (
+    !hasPermission(session.user.role, "export_reports") &&
+    !submitterCanViewAll(session.user.role)
+  ) {
     return NextResponse.json({ error: "Forbidden" }, { status: 403 });
   }
 

App/components/layout/sidebar.tsx

@@ -2,7 +2,7 @@
 
 import { usePathname } from "next/navigation";
 import Link from "next/link";
-import { INVENTORY_ENABLED } from "@/lib/feature-flags";
+import { INVENTORY_ENABLED, SUBMITTER_VIEW_ALL_ENABLED } from "@/lib/feature-flags";
 import { cn } from "@/lib/utils";
 import {
   LayoutDashboard,
@@ -34,6 +34,13 @@ interface NavItem {
   roles?: Role[];
 }
 
+// History is open to all-PO viewers; when the submitter-view-all flag is on, submitters
+// (TECHNICAL / MANNING) get read+export access to it too.
+const HISTORY_ROLES: Role[] = [
+  "MANAGER", "SUPERUSER", "AUDITOR", "ADMIN",
+  ...(SUBMITTER_VIEW_ALL_ENABLED ? (["TECHNICAL", "MANNING"] as Role[]) : []),
+];
+
 const NAV_ITEMS: NavItem[] = [
   { href: "/dashboard",        label: "Dashboard",              icon: LayoutDashboard },
   { href: "/po/new",           label: "New PO",                 icon: Plus,        roles: ["TECHNICAL", "MANNING", "MANAGER", "SUPERUSER"] },
@@ -42,7 +49,7 @@ const NAV_ITEMS: NavItem[] = [
   { href: "/approvals",        label: "Approvals",              icon: CheckSquare, roles: ["MANAGER", "SUPERUSER"] },
   { href: "/payments",         label: "Payments",               icon: CreditCard,  roles: ["ACCOUNTS"] },
   { href: "/payments/history", label: "Payment History",        icon: Receipt,     roles: ["ACCOUNTS", "SUPERUSER"] },
-  { href: "/history",          label: "History",                icon: History,     roles: ["MANAGER", "SUPERUSER", "AUDITOR", "ADMIN"] },
+  { href: "/history",          label: "History",                icon: History,     roles: HISTORY_ROLES },
   { href: "/profile",          label: "My Profile",             icon: UserCircle },
 ];
 

App/lib/feature-flags.ts

@@ -4,7 +4,16 @@
  *
  * NEXT_PUBLIC_INVENTORY_ENABLED=false  →  hides inventory tracking (site qty/consumption)
  *   Vendor list, product catalogue, and cart remain available for PO creation regardless.
+ *
+ * NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED=true  →  lets submitters (TECHNICAL / MANNING)
+ *   read every PO (not just their own), open the History page, and use the export buttons.
+ *   Opt-in (off unless explicitly "true") because it widens read access. Submitters stay
+ *   read-only — it grants no approval, payment, or edit rights. See lib/permissions.ts
+ *   (canViewAllPos / submitterCanViewAll).
  */
 
 export const INVENTORY_ENABLED =
   process.env.NEXT_PUBLIC_INVENTORY_ENABLED !== "false";
+
+export const SUBMITTER_VIEW_ALL_ENABLED =
+  process.env.NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED === "true";

App/lib/permissions.ts

@@ -1,4 +1,5 @@
 import type { Role } from "@prisma/client";
+import { SUBMITTER_VIEW_ALL_ENABLED } from "./feature-flags";
 
 export type Permission =
   | "create_po"
@@ -92,3 +93,31 @@ export function requirePermission(role: Role, permission: Permission): void {
 export function getPermissions(role: Role): Permission[] {
   return ROLE_PERMISSIONS[role] ?? [];
 }
+
+// ── Submitter roles & feature-flagged view-all ────────────────────────────────
+// Submitters raise and track their own POs. The two "submitter" roles below hold
+// `view_own_pos` but not `view_all_pos`.
+
+export const SUBMITTER_ROLES: Role[] = ["TECHNICAL", "MANNING"];
+
+export function isSubmitterRole(role: Role): boolean {
+  return SUBMITTER_ROLES.includes(role);
+}
+
+/**
+ * Feature-flagged: when NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED=true, submitters may
+ * read & export every PO (not just their own) and reach the History page. This is a
+ * read-only widening — it does not grant approval, payment, or edit rights.
+ */
+export function submitterCanViewAll(role: Role): boolean {
+  return SUBMITTER_VIEW_ALL_ENABLED && isSubmitterRole(role);
+}
+
+/**
+ * Whether a role may view/export any PO, not just the ones they submitted.
+ * True for `view_all_pos` holders (ACCOUNTS, MANAGER, SUPERUSER, AUDITOR, ADMIN) and,
+ * when the feature flag is on, for submitters too.
+ */
+export function canViewAllPos(role: Role): boolean {
+  return hasPermission(role, "view_all_pos") || submitterCanViewAll(role);
+}

App/tests/unit/permissions.test.ts

@@ -1,5 +1,11 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi, afterEach } from "vitest";
-import { hasPermission, requirePermission } from "@/lib/permissions";
+import {
+  hasPermission,
+  requirePermission,
+  isSubmitterRole,
+  submitterCanViewAll,
+  canViewAllPos,
+} from "@/lib/permissions";
 
 describe("Permissions", () => {
   describe("hasPermission", () => {
@@ -99,6 +105,64 @@ describe("Permissions", () => {
     });
   });
 
+  // ── Submitter view-all (feature-flagged) ──────────────────────────────────
+  describe("isSubmitterRole", () => {
+    it("is true for the two submitter roles", () => {
+      expect(isSubmitterRole("TECHNICAL")).toBe(true);
+      expect(isSubmitterRole("MANNING")).toBe(true);
+    });
+
+    it("is false for every other role", () => {
+      for (const role of ["ACCOUNTS", "MANAGER", "SUPERUSER", "AUDITOR", "ADMIN"] as const) {
+        expect(isSubmitterRole(role)).toBe(false);
+      }
+    });
+  });
+
+  describe("canViewAllPos / submitterCanViewAll — flag OFF (default)", () => {
+    it("submitters cannot view all POs", () => {
+      expect(canViewAllPos("TECHNICAL")).toBe(false);
+      expect(canViewAllPos("MANNING")).toBe(false);
+      expect(submitterCanViewAll("TECHNICAL")).toBe(false);
+    });
+
+    it("view_all_pos holders can still view all POs", () => {
+      for (const role of ["ACCOUNTS", "MANAGER", "SUPERUSER", "AUDITOR", "ADMIN"] as const) {
+        expect(canViewAllPos(role)).toBe(true);
+      }
+    });
+  });
+
+  describe("canViewAllPos / submitterCanViewAll — flag ON", () => {
+    afterEach(() => {
+      vi.unstubAllEnvs();
+      vi.resetModules();
+    });
+
+    it("submitters gain view-all when NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED=true", async () => {
+      vi.resetModules();
+      vi.stubEnv("NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED", "true");
+      const perms = await import("@/lib/permissions");
+
+      expect(perms.submitterCanViewAll("TECHNICAL")).toBe(true);
+      expect(perms.submitterCanViewAll("MANNING")).toBe(true);
+      expect(perms.canViewAllPos("TECHNICAL")).toBe(true);
+      expect(perms.canViewAllPos("MANNING")).toBe(true);
+    });
+
+    it("does not widen non-submitter roles, and is read-only (no approve/edit)", async () => {
+      vi.resetModules();
+      vi.stubEnv("NEXT_PUBLIC_SUBMITTER_VIEW_ALL_ENABLED", "true");
+      const perms = await import("@/lib/permissions");
+
+      expect(perms.submitterCanViewAll("MANAGER")).toBe(false);
+      expect(perms.canViewAllPos("ACCOUNTS")).toBe(true); // unchanged
+      // The flag grants read access only — no approval or edit rights.
+      expect(perms.hasPermission("TECHNICAL", "approve_po")).toBe(false);
+      expect(perms.hasPermission("TECHNICAL", "view_all_pos")).toBe(false);
+    });
+  });
+
   describe("requirePermission", () => {
     it("does not throw when permission is granted", () => {
       expect(() => requirePermission("MANAGER", "approve_po")).not.toThrow();