Merge branch 'master' into feat/delivery-locations

App/.env.example

@@ -62,6 +62,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

@@ -112,6 +112,8 @@ Structured format: **`COMPANY/VESSEL/PO_ID/FY`** — e.g. `PMS/HNR1/9000/2024-25
 
 When Accounts records a payment, a **compulsory payment date** is captured (`PurchaseOrder.paymentDate`) — the input defaults to today and rejects future dates (validated in `processPaymentSchema` and `markPaid`). There is also an editable **`poDate`** field; the exported PO "Date" shows `poDate ?? approvedAt ?? createdAt` (i.e. the approval date once approved, not creation).
 
+**Advance payment (issue #92):** the approving Manager sets how much of the PO is paid first via a 0–100% slider on the approval card (`approval-actions.tsx`, default 100%). The slider is convenience only — the resolved **absolute amount** is stored on `PurchaseOrder.suggestedAdvancePayment` (`Decimal(12,2)`, nullable; null = no explicit advance ⇒ full payment). `approvePo()` clamps it to `[0, totalAmount]` and records it on the `APPROVED` audit row; it is **set once at approval and never edited after**. Accounts sees it on the payment queue + PO detail, and it **prefills the first payment's amount** (`payment-actions.tsx`, only when nothing is paid yet and the advance is a true partial); the balance then runs through the normal `PARTIALLY_PAID` loop. It does **not** appear on the exported PO/invoice.
+
 ### Vendors
 
 `Vendor` carries `isVerified`, `gstin`, `pincode` + `latitude`/`longitude` (geocoded for vendor-distance sorting from a Site), and a `VendorContact[]` list. **Submitters can create vendors** (permission `create_vendor`) but they are created **unverified**; a vendor becomes verified when a PO is closed/paid with it, on import, or when a Manager/Accounts/Admin runs `verifyVendor`. Only `manage_vendors` holders may assign a `vendorId` (the formal verified code).
@@ -238,6 +240,7 @@ FORGEJO_URL, FORGEJO_REPO, FORGEJO_TOKEN
 GST_SERVICE_URL         # GstService microservice (defaults to localhost:3003)
 EPFO_SERVICE_URL        # EpfoService microservice for UAN lookup (defaults to localhost:3004)
 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_CREWING_ENABLED     # Crewing module feature flag (opt-in "true"; off by default)
 NEXT_PUBLIC_ENV_LABEL   # When set, shows a non-prod banner (EnvBanner). Leave unset in prod.
 ```

App/app/(portal)/admin/crew/admin-crew-manager.tsx

@@ -15,7 +15,6 @@ const SECONDARY = "rounded-lg border border-neutral-300 px-4 py-2 text-sm font-m
 
 const STATUSES: CrewStatus[] = ["PROSPECT", "CANDIDATE", "EMPLOYEE", "EX_HAND", "BLACKLISTED"];
 const SOURCES: CandidateSource[] = ["CAREERS", "EX_HAND", "WALK_IN", "REFERRAL", "OTHER"];
-const TYPES: CandidateType[] = ["NEW", "EX_HAND"];
 const label = (s: string) => s.replace(/_/g, " ").toLowerCase().replace(/\b\w/g, (m) => m.toUpperCase());
 
 type Opt = { id: string; name: string };
@@ -132,7 +131,10 @@ function CrewFormButton({ ranks, editing, open, onOpenChange }: { ranks: RankOpt
             <input className={INPUT} placeholder="Name" value={f.name} onChange={(e) => setF({ ...f, name: e.target.value })} required />
             <select className={INPUT} value={f.status} onChange={(e) => setF({ ...f, status: e.target.value as CrewStatus })}>{STATUSES.map((s) => <option key={s} value={s}>{label(s)}</option>)}</select>
             <select className={INPUT} value={f.source} onChange={(e) => setF({ ...f, source: e.target.value as CandidateSource })}>{SOURCES.map((s) => <option key={s} value={s}>{label(s)}</option>)}</select>
-            <select className={INPUT} value={f.type} onChange={(e) => setF({ ...f, type: e.target.value as CandidateType })}>{TYPES.map((s) => <option key={s} value={s}>{label(s)}</option>)}</select>
+            <label className="flex items-center gap-2 px-1 text-sm text-neutral-700">
+              <input type="checkbox" className="h-4 w-4 rounded border-neutral-300 text-primary-600 focus:ring-primary-500/30" checked={f.type === "EX_HAND"} onChange={(e) => setF({ ...f, type: e.target.checked ? "EX_HAND" : "NEW" })} />
+              Ex-hand (returning crew)
+            </label>
             <select className={INPUT} value={f.appliedRankId} onChange={(e) => setF({ ...f, appliedRankId: e.target.value })}><option value="">Rank applied…</option>{ranks.map((r) => <option key={r.id} value={r.id}>{r.code} — {r.name}</option>)}</select>
             <select className={INPUT} value={f.currentRankId} onChange={(e) => setF({ ...f, currentRankId: e.target.value })}><option value="">Rank held…</option>{ranks.map((r) => <option key={r.id} value={r.id}>{r.code} — {r.name}</option>)}</select>
             <input className={INPUT} placeholder="Email" value={f.email} onChange={(e) => setF({ ...f, email: e.target.value })} />

App/app/(portal)/approvals/[id]/actions.ts

@@ -3,6 +3,7 @@
 import { auth } from "@/auth";
 import { db } from "@/lib/db";
 import { canPerformAction } from "@/lib/po-state-machine";
+import { approvePoSchema } from "@/lib/validations/po";
 import { notify } from "@/lib/notifier";
 import { revalidatePath } from "next/cache";
 
@@ -12,14 +13,21 @@ export async function approvePo({
   poId,
   note,
   withNote = false,
+  suggestedAdvancePayment,
 }: {
   poId: string;
   note?: string;
   withNote?: boolean;
+  // Absolute advance the Manager wants paid first (issue #92). Whole amount,
+  // resolved from the approval slider client-side. Omitted ⇒ full payment.
+  suggestedAdvancePayment?: number;
 }): Promise<ActionResult> {
   const session = await auth();
   if (!session?.user) return { error: "Unauthorized" };
 
+  const parsed = approvePoSchema.safeParse({ note, suggestedAdvancePayment });
+  if (!parsed.success) return { error: parsed.error.errors[0]?.message ?? "Validation failed" };
+
   const po = await db.purchaseOrder.findUnique({
     where: { id: poId },
     include: { submitter: true, lineItems: true },
@@ -35,17 +43,28 @@ export async function approvePo({
     return { error: "A vendor must be assigned before approving this PO." };
   }
 
+  // Resolve the advance: clamp to [0, total]. Undefined ⇒ no explicit advance
+  // (full payment, current default behaviour). The slider always sends a value,
+  // but a malformed/over-total amount is clamped rather than rejected.
+  const total = Number(po.totalAmount);
+  const advance =
+    parsed.data.suggestedAdvancePayment === undefined
+      ? null
+      : Math.min(Math.max(parsed.data.suggestedAdvancePayment, 0), total);
+
   await db.purchaseOrder.update({
     where: { id: poId },
     data: {
       status: "MGR_APPROVED",
       approvedAt: new Date(),
       managerNote: note ?? null,
+      suggestedAdvancePayment: advance,
       actions: {
         create: {
           actionType: withNote ? "APPROVED_WITH_NOTE" : "APPROVED",
           note: note ?? null,
           actorId: session.user.id,
+          metadata: advance !== null ? { suggestedAdvancePayment: advance } : undefined,
         },
       },
     },

App/app/(portal)/approvals/[id]/approval-actions.tsx

@@ -3,21 +3,38 @@
 import { useState } from "react";
 import { useRouter } from "next/navigation";
 import { approvePo, rejectPo, requestEdits, requestVendorId } from "./actions";
+import { formatCurrency } from "@/lib/utils";
 import type { POStatus } from "@prisma/client";
 
+// Resolve the slider percent (whole number) into an absolute advance amount.
+// 100% is the exact total (no rounding loss on paise); partial advances are
+// rounded to whole rupees — the slider is convenience, the amount is the record.
+function advanceAmount(total: number, percent: number): number {
+  if (percent >= 100) return total;
+  if (percent <= 0) return 0;
+  return Math.round((total * percent) / 100);
+}
+
 export function ApprovalActions({
   poId,
   poStatus,
+  totalAmount = 0,
+  currency = "INR",
 }: {
   poId: string;
   poStatus: POStatus;
+  totalAmount?: number;
+  currency?: string;
 }) {
   const router = useRouter();
   const [note, setNote] = useState("");
+  const [advancePercent, setAdvancePercent] = useState(100);
   const [activeAction, setActiveAction] = useState<string | null>(null);
   const [pending, setPending] = useState<string | null>(null);
   const [error, setError] = useState("");
 
+  const advance = advanceAmount(totalAmount, advancePercent);
+
   async function dispatch(action: string, requireNote = false) {
     if (requireNote && !note.trim()) {
       setError("A note is required for this action.");
@@ -26,8 +43,10 @@ export function ApprovalActions({
     setPending(action);
     setError("");
     let result: { ok: true } | { error: string } | undefined;
-    if (action === "approve") result = await approvePo({ poId, note });
-    else if (action === "approve_note") result = await approvePo({ poId, note, withNote: true });
+    // Approvals carry the Manager's advance decision (resolved amount, not %).
+    if (action === "approve") result = await approvePo({ poId, note, suggestedAdvancePayment: advance });
+    else if (action === "approve_note")
+      result = await approvePo({ poId, note, withNote: true, suggestedAdvancePayment: advance });
     else if (action === "reject") result = await rejectPo({ poId, note });
     else if (action === "request_edits") result = await requestEdits({ poId, note });
     else if (action === "request_vendor_id") result = await requestVendorId({ poId });
@@ -45,6 +64,37 @@ export function ApprovalActions({
     <div className="rounded-lg border border-neutral-200 bg-white p-4 md:p-6">
       <h3 className="text-base font-semibold text-neutral-900 mb-4">Decision</h3>
 
+      {/* Advance payment (issue #92) — Manager decides how much Accounts pays
+          first. 100% = full payment; lower values seed the first part-payment. */}
+      <div className="mb-5 rounded-lg border border-neutral-200 bg-neutral-50 p-3.5">
+        <div className="flex items-center justify-between mb-2">
+          <label htmlFor="advance-slider" className="text-sm font-medium text-neutral-700">
+            Advance payment
+          </label>
+          <span className="text-sm font-semibold text-neutral-900 tabular-nums">
+            {advancePercent}% · {formatCurrency(advance, currency)}
+          </span>
+        </div>
+        <input
+          id="advance-slider"
+          type="range"
+          min={0}
+          max={100}
+          step={1}
+          value={advancePercent}
+          onChange={(e) => setAdvancePercent(Number(e.target.value))}
+          className="w-full accent-primary-600"
+        />
+        <p className="mt-1.5 text-xs text-neutral-500">
+          {advancePercent >= 100
+            ? "Full payment — Accounts will be prompted to pay the whole PO value."
+            : `Accounts will be prompted to pay ${formatCurrency(advance, currency)} first; the balance of ${formatCurrency(
+                Math.max(totalAmount - advance, 0),
+                currency
+              )} follows the usual part-payment flow.`}
+        </p>
+      </div>
+
       {(activeAction === "reject" || activeAction === "request_edits" || activeAction === "approve_note") && (
         <div className="mb-4">
           <label className="block text-sm font-medium text-neutral-700 mb-1.5">

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

@@ -107,7 +107,12 @@ export default async function ApprovalDetailPage({ params }: Props) {
 
       <div className="mt-4 md:mt-6">
         {hasSignature ? (
-          <ApprovalActions poId={po.id} poStatus={po.status} />
+          <ApprovalActions
+            poId={po.id}
+            poStatus={po.status}
+            totalAmount={Number(po.totalAmount)}
+            currency={po.currency}
+          />
         ) : (
           <div className="rounded-lg border border-warning-200 bg-warning-50 p-4 md:p-5 flex items-start gap-3">
             <span className="text-warning-500 text-xl leading-none mt-0.5">✎</span>

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

@@ -51,13 +51,13 @@ export default async function CandidateDetailPage({ params }: { params: Promise<
         <div className="flex items-center gap-3">
           <h1 className="text-2xl font-semibold text-neutral-900">{c.name}</h1>
           <Badge variant={STATUS_VARIANT[c.status]}>{STATUS_LABEL[c.status]}</Badge>
-          {c.source === "EX_HAND" && (
+          {c.type === "EX_HAND" && (
             <span className="rounded-full bg-purple-100 text-purple-700 px-2.5 py-0.5 text-xs font-medium">Returning crew</span>
           )}
         </div>
       </div>
 
-      {c.source === "EX_HAND" && (
+      {c.type === "EX_HAND" && (
         <div className="mb-6 rounded-lg border border-purple-200 bg-purple-50 px-4 py-3 text-sm text-purple-800">
           <strong>Returning crew.</strong> The interview may be waived with Manager approval.{" "}
           {c.experienceRecords.length === 0 && c.documents.length === 0 ? (

App/app/(portal)/crewing/candidates/actions.ts

@@ -50,13 +50,6 @@ function parse(formData: FormData) {
   });
 }
 
-// An EX_HAND source means a returning crew member; everyone else is NEW. The
-// CrewStatus follows: ex-hands sit in the pool as EX_HAND, the rest as CANDIDATE.
-function derive(source: CandidateSource) {
-  const isExHand = source === "EX_HAND";
-  return { type: isExHand ? "EX_HAND" : "NEW", status: isExHand ? "EX_HAND" : "CANDIDATE" } as const;
-}
-
 // Store an optional CV upload and return its storage key (null if none).
 async function storeCv(formData: FormData, crewMemberId: string): Promise<string | null> {
   const file = formData.get("cv");
@@ -74,53 +67,53 @@ export async function addCandidate(formData: FormData): Promise<ActionResult> {
   const parsed = parse(formData);
   if (!parsed.success) return { error: parsed.error.errors[0]?.message ?? "Validation failed" };
   const d = parsed.data;
-  const { type, status } = derive(d.source);
 
   // B3 AC1 — ex-hand recognition: a returning person re-entered as a fresh
-  // candidate (not already tagged EX_HAND) is matched to their existing EX_HAND
-  // pool record by a stable key — email when given, else an exact name match —
-  // and the SAME row is reused (so their tour history, documents and bank stay on
-  // file) rather than creating a duplicate. (Heuristic: with no DOB on file a
+  // candidate is matched to their existing EX_HAND pool record by a stable key —
+  // email when given, else an exact name match — and the SAME row is reused (so
+  // their tour history, documents and bank stay on file) rather than creating a
+  // duplicate. (Ex-hand is set by the office on the admin crew record; the
+  // candidate form never tags it directly. Heuristic: with no DOB on file a
   // name-only match can in theory collide; email is preferred when available.)
-  if (d.source !== "EX_HAND") {
-    const match = await db.crewMember.findFirst({
-      where: {
-        status: "EX_HAND",
-        ...(d.email
-          ? { email: { equals: d.email, mode: "insensitive" } }
-          : { name: { equals: d.name, mode: "insensitive" } }),
+  const match = await db.crewMember.findFirst({
+    where: {
+      status: "EX_HAND",
+      ...(d.email
+        ? { email: { equals: d.email, mode: "insensitive" } }
+        : { name: { equals: d.name, mode: "insensitive" } }),
+    },
+    select: { id: true, appliedRankId: true, currentRankId: true, email: true, phone: true, notes: true, experienceMonths: true, vesselTypeExperience: true },
+  });
+  if (match) {
+    const updated = await db.crewMember.update({
+      where: { id: match.id },
+      data: {
+        // Keep EX_HAND type/status; refresh the application's details, never
+        // discarding prior history (take the larger recorded experience).
+        appliedRankId: d.appliedRankId || match.appliedRankId,
+        currentRankId: d.currentRankId || match.currentRankId,
+        email: d.email || match.email,
+        phone: d.phone || match.phone,
+        notes: d.notes || match.notes,
+        experienceMonths: Math.max(d.experienceMonths, match.experienceMonths),
+        vesselTypeExperience: d.vesselTypeExperience || match.vesselTypeExperience,
+        actions: { create: { actionType: "CANDIDATE_UPDATED", actorId: g.userId, metadata: { exHandRecognized: true } } },
       },
-      select: { id: true, appliedRankId: true, currentRankId: true, email: true, phone: true, notes: true, experienceMonths: true, vesselTypeExperience: true },
     });
-    if (match) {
-      const updated = await db.crewMember.update({
-        where: { id: match.id },
-        data: {
-          // Keep EX_HAND type/status; refresh the application's details, never
-          // discarding prior history (take the larger recorded experience).
-          appliedRankId: d.appliedRankId || match.appliedRankId,
-          currentRankId: d.currentRankId || match.currentRankId,
-          email: d.email || match.email,
-          phone: d.phone || match.phone,
-          notes: d.notes || match.notes,
-          experienceMonths: Math.max(d.experienceMonths, match.experienceMonths),
-          vesselTypeExperience: d.vesselTypeExperience || match.vesselTypeExperience,
-          actions: { create: { actionType: "CANDIDATE_UPDATED", actorId: g.userId, metadata: { exHandRecognized: true } } },
-        },
-      });
-      const cvKey = await storeCv(formData, updated.id);
-      if (cvKey) await db.crewMember.update({ where: { id: updated.id }, data: { cvKey } });
-      revalidatePath(LIST_PATH);
-      return { ok: true, id: updated.id };
-    }
+    const cvKey = await storeCv(formData, updated.id);
+    if (cvKey) await db.crewMember.update({ where: { id: updated.id }, data: { cvKey } });
+    revalidatePath(LIST_PATH);
+    return { ok: true, id: updated.id };
   }
 
   const candidate = await db.crewMember.create({
     data: {
       name: d.name,
       source: d.source,
-      type,
-      status,
+      // The candidate form always intakes a fresh NEW candidate. Ex-hand status
+      // is an office/admin designation set on the crew record, not here.
+      type: "NEW",
+      status: "CANDIDATE",
       appliedRankId: d.appliedRankId || null,
       currentRankId: d.currentRankId || null,
       experienceMonths: d.experienceMonths,
@@ -149,7 +142,6 @@ export async function updateCandidate(formData: FormData): Promise<ActionResult>
   const parsed = parse(formData);
   if (!parsed.success) return { error: parsed.error.errors[0]?.message ?? "Validation failed" };
   const d = parsed.data;
-  const { type, status } = derive(d.source);
 
   const existing = await db.crewMember.findUnique({ where: { id }, select: { status: true } });
   if (!existing) return { error: "Candidate not found" };
@@ -161,9 +153,8 @@ export async function updateCandidate(formData: FormData): Promise<ActionResult>
     data: {
       name: d.name,
       source: d.source,
-      // Don't downgrade an onboarded employee back to a candidate via an edit.
-      type,
-      status: existing.status === "EMPLOYEE" ? existing.status : status,
+      // type/status are left untouched — ex-hand / employee designation is owned
+      // by the office (admin crew record + sign-off), never by a candidate edit.
       appliedRankId: d.appliedRankId || null,
       currentRankId: d.currentRankId || null,
       experienceMonths: d.experienceMonths,

App/app/(portal)/crewing/candidates/candidate-form.tsx

@@ -5,7 +5,7 @@ import { useRouter } from "next/navigation";
 import type { CandidateSource } from "@prisma/client";
 import { AdminDialog } from "@/components/ui/admin-dialog";
 import { addCandidate, updateCandidate } from "./actions";
-import { SOURCE_OPTIONS, SOURCE_LABEL } from "./candidate-ui";
+import { FORM_SOURCE_OPTIONS, SOURCE_LABEL } from "./candidate-ui";
 
 const INPUT =
   "w-full rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:border-primary-500 focus:outline-none focus:ring-2 focus:ring-primary-500/20";
@@ -46,7 +46,7 @@ function CandidateFields({
         <div>
           <label className="block text-xs font-medium text-neutral-700 mb-1">Source</label>
           <select className={INPUT} value={state.source} onChange={(e) => set("source", e.target.value as CandidateSource)}>
-            {SOURCE_OPTIONS.map((s) => (
+            {FORM_SOURCE_OPTIONS.map((s) => (
               <option key={s} value={s}>{SOURCE_LABEL[s]}</option>
             ))}
           </select>
@@ -64,7 +64,7 @@ function CandidateFields({
           </select>
         </div>
         <div>
-          <label className="block text-xs font-medium text-neutral-700 mb-1">Rank held (ex-hands)</label>
+          <label className="block text-xs font-medium text-neutral-700 mb-1">Rank held</label>
           <select className={INPUT} value={state.currentRankId} onChange={(e) => set("currentRankId", e.target.value)}>
             <option value="">—</option>
             {ranks.map((r) => (
@@ -131,7 +131,9 @@ function emptyState(): FieldState {
 function stateFrom(c: EditableCandidate): FieldState {
   return {
     name: c.name,
-    source: c.source,
+    // Ex-hand is an admin-only designation; the candidate form only edits origin.
+    // Legacy rows may carry the EX_HAND source — show a sensible origin instead.
+    source: c.source === "EX_HAND" ? "CAREERS" : c.source,
     appliedRankId: c.appliedRankId ?? "",
     currentRankId: c.currentRankId ?? "",
     experienceMonths: String(c.experienceMonths),

App/app/(portal)/crewing/candidates/candidate-ui.ts

@@ -13,6 +13,11 @@ export const SOURCE_LABEL: Record<CandidateSource, string> = {
 
 export const SOURCE_OPTIONS: CandidateSource[] = ["CAREERS", "EX_HAND", "WALK_IN", "REFERRAL", "OTHER"];
 
+// Ex-hand is now its own checkbox (not a source) — the Add/Edit form offers only
+// the real origins. EX_HAND stays in the enum/label for legacy rows created
+// before the split.
+export const FORM_SOURCE_OPTIONS: CandidateSource[] = ["CAREERS", "WALK_IN", "REFERRAL", "OTHER"];
+
 export const STATUS_LABEL: Record<CrewStatus, string> = {
   PROSPECT: "Prospect",
   CANDIDATE: "Candidate",

App/app/(portal)/crewing/candidates/candidates-manager.tsx

@@ -2,7 +2,7 @@
 
 import { useMemo, useState } from "react";
 import Link from "next/link";
-import type { CandidateSource, CrewStatus } from "@prisma/client";
+import type { CandidateSource, CandidateType, CrewStatus } from "@prisma/client";
 import { Badge } from "@/components/ui/badge";
 import { RowActionsMenu, RowActionsItem } from "@/components/ui/row-actions-menu";
 import { AddCandidateButton, EditCandidateButton, type EditableCandidate } from "./candidate-form";
@@ -12,6 +12,7 @@ type CandidateRow = {
   id: string;
   name: string;
   source: CandidateSource;
+  type: CandidateType;
   status: CrewStatus;
   appliedRankId: string | null;
   appliedRank: string | null;
@@ -54,13 +55,12 @@ function CandidateRowView({ c, ranks }: { c: CandidateRow; ranks: RankOpt[] }) {
     <tr className="border-b border-neutral-100 last:border-0 hover:bg-neutral-50">
       <td className="px-4 py-3">
         <Link href={`/crewing/candidates/${c.id}`} className="font-medium text-neutral-900 hover:text-primary-700">{c.name}</Link>
+        {c.type === "EX_HAND" && (
+          <span className="ml-2 rounded-full bg-purple-100 text-purple-700 px-2 py-0.5 text-[10px] font-medium align-middle">Ex-hand</span>
+        )}
         {c.hasCv && <span className="ml-2 text-xs text-neutral-400">CV</span>}
       </td>
-      <td className="px-4 py-3">
-        <span className={c.source === "EX_HAND" ? "text-purple-700 font-medium text-sm" : "text-neutral-600 text-sm"}>
-          {SOURCE_LABEL[c.source]}
-        </span>
-      </td>
+      <td className="px-4 py-3 text-neutral-600 text-sm">{SOURCE_LABEL[c.source]}</td>
       <td className="px-4 py-3 text-neutral-600 text-sm">{c.currentRank ?? "—"}</td>
       <td className="px-4 py-3 text-neutral-600 text-sm">{c.appliedRank ?? "—"}</td>
       <td className="px-4 py-3 text-neutral-600 text-sm">{experienceLabel(c.experienceMonths)}</td>

App/app/(portal)/crewing/candidates/page.tsx

@@ -33,6 +33,7 @@ export default async function CandidatesPage() {
     id: c.id,
     name: c.name,
     source: c.source,
+    type: c.type,
     status: c.status,
     appliedRankId: c.appliedRankId,
     appliedRank: c.appliedRank?.name ?? null,

App/app/(portal)/crewing/crew/actions.ts

@@ -304,10 +304,13 @@ export async function signOffCrew(assignmentId: string, signOffDate: string, rem
         source: "internal",
       },
     });
-    // Same entity: flip EMPLOYEE → EX_HAND; they reappear in Candidates as a returning hand.
+    // Same entity: flip EMPLOYEE → EX_HAND; they reappear in Candidates as a
+    // returning hand. The ex-hand flag lives on type/status — their original
+    // source (how they were first recruited) is preserved. currentRank (rank
+    // held) is refreshed to the tour they just signed off from.
     await tx.crewMember.update({
       where: { id: assignment.crewMemberId },
-      data: { status: "EX_HAND", type: "EX_HAND", source: "EX_HAND", currentRankId: assignment.rankId },
+      data: { status: "EX_HAND", type: "EX_HAND", currentRankId: assignment.rankId },
     });
     await tx.crewAction.create({
       data: { actionType: "CREW_SIGNED_OFF", actorId: g.userId, crewMemberId: assignment.crewMemberId, note: remarks?.trim() || null },

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)/payments/page.tsx

@@ -98,12 +98,25 @@ export default async function PaymentsPage() {
                       Paid {formatCurrency(Number(po.paidAmount), po.currency)} of {formatCurrency(Number(po.totalAmount), po.currency)}
                     </span>
                   )}
+                  {/* Manager's advance decision (issue #92) — shown until the first payment lands. */}
+                  {po.status === "SENT_FOR_PAYMENT" &&
+                    po.paidAmount == null &&
+                    po.suggestedAdvancePayment != null &&
+                    Number(po.suggestedAdvancePayment) < Number(po.totalAmount) && (
+                      <span className="text-xs text-primary-700">
+                        Advance requested: {formatCurrency(Number(po.suggestedAdvancePayment), po.currency)} of{" "}
+                        {formatCurrency(Number(po.totalAmount), po.currency)}
+                      </span>
+                    )}
                 </div>
                 <PaymentActions
                   poId={po.id}
                   poStatus={po.status}
                   totalAmount={Number(po.totalAmount)}
                   paidAmount={po.paidAmount != null ? Number(po.paidAmount) : 0}
+                  suggestedAdvancePayment={
+                    po.suggestedAdvancePayment != null ? Number(po.suggestedAdvancePayment) : null
+                  }
                 />
               </div>
             </div>

App/app/(portal)/payments/payment-actions.tsx

@@ -10,6 +10,9 @@ interface Props {
   poStatus: POStatus;
   totalAmount?: number;
   paidAmount?: number;
+  // Manager's advance decision (issue #92) — absolute amount. Prefills the FIRST
+  // payment's amount field; ignored once any payment has been recorded.
+  suggestedAdvancePayment?: number | null;
 }
 
 // Today's date as a local yyyy-mm-dd string (for <input type="date"> default + max)
@@ -19,15 +22,33 @@ function todayLocal(): string {
   return new Date(d.getTime() - off * 60_000).toISOString().slice(0, 10);
 }
 
-export function PaymentActions({ poId, poStatus, totalAmount = 0, paidAmount = 0 }: Props) {
+export function PaymentActions({
+  poId,
+  poStatus,
+  totalAmount = 0,
+  paidAmount = 0,
+  suggestedAdvancePayment = null,
+}: Props) {
   const router = useRouter();
+  const remaining = totalAmount - paidAmount;
+
+  // Prefill the first payment with the Manager's advance, when it's a genuine
+  // partial of the (untouched) total. Nothing paid yet ⇒ first payment; a full
+  // (>= total) advance leaves the field blank so "Confirm Full Payment" is used.
+  const advancePrefill =
+    paidAmount === 0 &&
+    suggestedAdvancePayment != null &&
+    suggestedAdvancePayment > 0 &&
+    suggestedAdvancePayment < remaining
+      ? String(suggestedAdvancePayment)
+      : "";
+
   const [ref, setRef] = useState("");
-  const [amount, setAmount] = useState<string>("");
+  const [amount, setAmount] = useState<string>(advancePrefill);
   const [paymentDate, setPaymentDate] = useState<string>(todayLocal());
   const [pending, setPending] = useState(false);
   const [error, setError] = useState("");
 
-  const remaining = totalAmount - paidAmount;
   const today = todayLocal();
 
   async function handleProcessPayment() {
@@ -120,6 +141,11 @@ export function PaymentActions({ poId, poStatus, totalAmount = 0, paidAmount = 0
             className="w-full sm:w-36 rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:border-primary-500 focus:outline-none focus:ring-2 focus:ring-primary-500/20"
           />
         </div>
+        {advancePrefill && (
+          <span className="text-xs text-primary-700">
+            Manager set an advance of {Number(suggestedAdvancePayment).toFixed(2)} — prefilled below; adjust if needed.
+          </span>
+        )}
         {error && <span className="text-xs text-danger-700">{error}</span>}
         <div className="flex gap-2 justify-end">
           {isPartialPayment && (

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)
-  const canViewAll = ["ACCOUNTS", "MANAGER", "SUPERUSER", "AUDITOR", "ADMIN"].includes(
-    session.user.role
-  );
-  if (!canViewAll && po.submitterId !== session.user.id) redirect("/dashboard");
+  // Submitters can only view their own POs — unless they hold view_all_pos, or the
+  // submitter-view-all feature flag grants them read access to every PO.
+  if (!canViewAllPos(session.user.role) && 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);
-  if (!canViewAll && po.submitterId !== session.user.id) {
+  // view_all_pos holders, or submitters when the view-all feature flag is on, may export
+  // 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

@@ -3,7 +3,7 @@
 import { useEffect, useState } from "react";
 import { usePathname } from "next/navigation";
 import Link from "next/link";
-import { INVENTORY_ENABLED, CREWING_ENABLED } from "@/lib/feature-flags";
+import { INVENTORY_ENABLED, SUBMITTER_VIEW_ALL_ENABLED, CREWING_ENABLED } from "@/lib/feature-flags";
 import { cn } from "@/lib/utils";
 import {
   LayoutDashboard,
@@ -46,6 +46,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"] },
@@ -54,7 +61,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/components/po/po-detail.tsx

@@ -25,6 +25,7 @@ type PoWithRelations = {
   paymentRef: string | null;
   paymentDate?: Date | null;
   paidAmount?: import("@prisma/client").Prisma.Decimal | null;
+  suggestedAdvancePayment?: import("@prisma/client").Prisma.Decimal | null;
   piQuotationNo?: string | null;
   piQuotationDate?: Date | null;
   requisitionNo?: string | null;
@@ -290,6 +291,21 @@ export async function PoDetail({ po, currentUserId, currentRole, readOnly = fals
         </div>
       )}
 
+      {/* Manager's advance-payment decision (issue #92) — a partial advance set
+          at approval. Shown to Accounts/Manager from approval through payment. */}
+      {po.suggestedAdvancePayment != null &&
+        Number(po.suggestedAdvancePayment) < Number(po.totalAmount) &&
+        ["MGR_APPROVED", "SENT_FOR_PAYMENT", "PARTIALLY_PAID"].includes(po.status) && (
+          <div className="rounded-lg border border-primary-100 bg-primary-50 px-4 py-3">
+            <p className="text-sm font-medium text-primary-700 mb-0.5">Advance payment requested</p>
+            <p className="text-sm text-primary-700">
+              Pay {formatCurrency(Number(po.suggestedAdvancePayment), po.currency)} first (of{" "}
+              {formatCurrency(Number(po.totalAmount), po.currency)}). The balance follows the usual
+              part-payment flow.
+            </p>
+          </div>
+        )}
+
       {/* Submitter changes banner — shown to managers when PO is resubmitted after edits */}
       {resubmitSnapshot &&
         po.status === "MGR_REVIEW" &&

App/lib/feature-flags.ts

@@ -5,6 +5,12 @@
  * 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).
+ *
  * NEXT_PUBLIC_CREWING_ENABLED=true  →  exposes the Crewing module (crew/ranks/requisitions
  *   etc.). Opt-in (off unless explicitly "true") because the feature is built incrementally;
  *   keeping it dark by default leaves production unchanged. See lib/permissions.ts (§6 matrix)
@@ -14,5 +20,8 @@
 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";
+
 export const CREWING_ENABLED =
   process.env.NEXT_PUBLIC_CREWING_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"
@@ -241,3 +242,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/lib/validations/po.ts

@@ -53,6 +53,13 @@ export const createPoSchema = z.object({
 
 export const approvePoSchema = z.object({
   note: z.string().optional(),
+  // Absolute advance amount the Manager wants paid first (issue #92). The UI
+  // slider works in whole percent of totalAmount; the resolved amount is what we
+  // persist. Validated against the PO total in the action. Omitted ⇒ full payment.
+  suggestedAdvancePayment: z.coerce
+    .number()
+    .nonnegative("Advance payment cannot be negative")
+    .optional(),
 });
 
 export const rejectPoSchema = z.object({

App/prisma/migrations/20260624120000_po_suggested_advance_payment/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "PurchaseOrder" ADD COLUMN     "suggestedAdvancePayment" DECIMAL(12,2);

App/prisma/schema.prisma

@@ -530,6 +530,17 @@ model PurchaseOrder {
   paymentRef         String?
   paymentDate        DateTime?
   paidAmount         Decimal?  @db.Decimal(12, 2)
+  // Advance the approving Manager wants paid first (absolute amount, not %).
+  // The approval slider (0–100% of totalAmount) is convenience only — the
+  // resolved amount is stored here. Null on legacy/pre-feature POs ⇒ no explicit
+  // advance, so Accounts defaults to the full remaining balance. Set once at
+  // approval and not edited afterwards (issue #92).
+  //
+  // NOTE (issue #91): this IS the "exact sum due for payment" for an ADVANCE/PART
+  // request. When the structured payment-request lane (payment-term enum +
+  // separate approval) is built, reuse this column for the requested amount
+  // rather than adding a parallel "exact sum" field.
+  suggestedAdvancePayment Decimal? @db.Decimal(12, 2)
   piQuotationNo      String?
   piQuotationDate    DateTime?
   requisitionNo      String?

App/tests/integration/approval-actions.test.ts

@@ -119,6 +119,46 @@ describe("M-02 — approve PO", () => {
   });
 });
 
+// ── #92: Advance payment decided at approval ─────────────────────────────────
+
+describe("issue #92 — advance payment on approval", () => {
+  it("persists the manager's advance amount and records it on the audit row", async () => {
+    const poId = await createSubmittedPo(`${PREFIX}Advance`);
+    vi.mocked(auth as unknown as () => Promise<unknown>).mockResolvedValue(makeSession(managerId, "MANAGER"));
+    const before = await db.purchaseOrder.findUniqueOrThrow({ where: { id: poId } });
+    const half = Math.round(Number(before.totalAmount) / 2);
+
+    const result = await approvePo({ poId, suggestedAdvancePayment: half });
+    expect(result).toEqual({ ok: true });
+
+    const po = await db.purchaseOrder.findUniqueOrThrow({ where: { id: poId } });
+    expect(po.status).toBe("MGR_APPROVED");
+    expect(Number(po.suggestedAdvancePayment)).toBe(half);
+
+    const action = await db.pOAction.findFirst({ where: { poId, actionType: "APPROVED" } });
+    expect((action?.metadata as { suggestedAdvancePayment?: number } | null)?.suggestedAdvancePayment).toBe(half);
+  });
+
+  it("defaults to null (full payment) when no advance is provided", async () => {
+    const poId = await createSubmittedPo(`${PREFIX}AdvanceNone`);
+    vi.mocked(auth as unknown as () => Promise<unknown>).mockResolvedValue(makeSession(managerId, "MANAGER"));
+    await approvePo({ poId });
+    const po = await db.purchaseOrder.findUniqueOrThrow({ where: { id: poId } });
+    expect(po.suggestedAdvancePayment).toBeNull();
+  });
+
+  it("clamps an advance above the PO total down to the total", async () => {
+    const poId = await createSubmittedPo(`${PREFIX}AdvanceClamp`);
+    vi.mocked(auth as unknown as () => Promise<unknown>).mockResolvedValue(makeSession(managerId, "MANAGER"));
+    const before = await db.purchaseOrder.findUniqueOrThrow({ where: { id: poId } });
+    const total = Number(before.totalAmount);
+
+    await approvePo({ poId, suggestedAdvancePayment: total + 5000 });
+    const po = await db.purchaseOrder.findUniqueOrThrow({ where: { id: poId } });
+    expect(Number(po.suggestedAdvancePayment)).toBe(total);
+  });
+});
+
 // ── M-03: Reject ──────────────────────────────────────────────────────────────
 
 describe("M-03 — reject PO", () => {

App/tests/integration/candidates.test.ts

@@ -33,6 +33,21 @@ const SS_EMAIL = "sitestaff@itcand.local";
 const as = (userId: string, role: Role) =>
   vi.mocked(auth as unknown as () => Promise<unknown>).mockResolvedValue(makeSession(userId, role));
 
+// Ex-hand is an office/admin designation (set on the admin crew record, not the
+// candidate form) — seed such rows directly for the recognition tests.
+const seedExHand = (data: { name: string; email?: string; experienceMonths?: number }) =>
+  db.crewMember.create({
+    data: {
+      name: data.name,
+      type: "EX_HAND",
+      status: "EX_HAND",
+      source: "CAREERS",
+      email: data.email ?? null,
+      experienceMonths: data.experienceMonths ?? 0,
+      actions: { create: { actionType: "CANDIDATE_ADDED", actorId: managerId } },
+    },
+  });
+
 beforeAll(async () => {
   managerId = (await getSeedUser("manager@pelagia.local")).id;
   const ss = await db.user.upsert({
@@ -71,12 +86,14 @@ describe("addCandidate", () => {
     expect(c.actions[0].actorId).toBe(managerId);
   });
 
-  it("an EX_HAND source yields type EX_HAND and status EX_HAND", async () => {
+  it("candidate intake always creates a NEW candidate — ex-hand is admin-only", async () => {
     as(managerId, "MANAGER");
-    await addCandidate(fd({ name: "Returning Ravi", source: "EX_HAND" }));
+    // Even if an ex-hand hint is smuggled into the form data, intake stays
+    // NEW/CANDIDATE; ex-hand is set only on the admin crew record.
+    await addCandidate(fd({ name: "Returning Ravi", source: "CAREERS", isExHand: "true" }));
     const c = await db.crewMember.findFirstOrThrow();
-    expect(c.type).toBe("EX_HAND");
-    expect(c.status).toBe("EX_HAND");
+    expect(c.type).toBe("NEW");
+    expect(c.status).toBe("CANDIDATE");
   });
 
   it("requires a name", async () => {
@@ -98,8 +115,7 @@ describe("addCandidate", () => {
 describe("ex-hand recognition + ordering (B3)", () => {
   it("recognizes a returning hand by email and reuses the same row (AC1)", async () => {
     as(managerId, "MANAGER");
-    await addCandidate(fd({ name: "Ravi Old", source: "EX_HAND", email: "ravi@ex.com", experienceMonths: "120" }));
-    const exhand = await db.crewMember.findFirstOrThrow({ where: { status: "EX_HAND" } });
+    const exhand = await seedExHand({ name: "Ravi Old", email: "ravi@ex.com", experienceMonths: 120 });
 
     // Re-applies as a fresh careers candidate with the same email → recognized.
     const res = await addCandidate(fd({ name: "Ravi Returning", source: "CAREERS", email: "ravi@ex.com", appliedRankId: rankId }));
@@ -115,16 +131,15 @@ describe("ex-hand recognition + ordering (B3)", () => {
 
   it("recognizes a returning hand by exact name when no email is given (AC1)", async () => {
     as(managerId, "MANAGER");
-    await addCandidate(fd({ name: "Returning Ravi", source: "EX_HAND" }));
+    const exhand = await seedExHand({ name: "Returning Ravi" });
     const res = await addCandidate(fd({ name: "returning ravi", source: "REFERRAL" })); // case-insensitive
-    const exhand = await db.crewMember.findFirstOrThrow({ where: { status: "EX_HAND" } });
     expect("ok" in res && res.id).toBe(exhand.id);
     expect(await db.crewMember.count()).toBe(1);
   });
 
   it("does not match a different person → creates a new candidate", async () => {
     as(managerId, "MANAGER");
-    await addCandidate(fd({ name: "Ex One", source: "EX_HAND", email: "one@ex.com" }));
+    await seedExHand({ name: "Ex One", email: "one@ex.com" });
     await addCandidate(fd({ name: "Brand New", source: "CAREERS", email: "new@ex.com" }));
     expect(await db.crewMember.count()).toBe(2);
   });
@@ -132,7 +147,7 @@ describe("ex-hand recognition + ordering (B3)", () => {
   it("lists ex-hands above new candidates by default (AC2)", async () => {
     as(managerId, "MANAGER");
     await addCandidate(fd({ name: "New First", source: "CAREERS" }));
-    await addCandidate(fd({ name: "Ex Second", source: "EX_HAND" }));
+    await seedExHand({ name: "Ex Second" });
     const el = (await CandidatesPage()) as unknown as { props: { candidates: Array<{ name: string; status: string }> } };
     expect(el.props.candidates[0].status).toBe("EX_HAND");
     expect(el.props.candidates[0].name).toBe("Ex Second");

App/tests/unit/permissions.test.ts

@@ -1,5 +1,11 @@
-import { describe, it, expect } from "vitest";
-import { hasPermission, requirePermission } from "@/lib/permissions";
+import { describe, it, expect, vi, afterEach } from "vitest";
+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();