feat: update exam stage actions and payment flow

- Refactor ExamStageActions component to handle eligibility payment and retake exam actions. - Update MyApplicationsPage to use new retakeExam mutation instead of requestExamPayment. - Modify licensing API to include retakeExam mutation for handling exam fee requests for failed candidates. - Adjust mock data to reflect new application statuses and ensure consistency in eligibility and exam payment states. - Update licensing helpers to include new status labels and colors for eligibility payment states. - Revise licensing types to replace ELIGIBILITY_APPROVED with ELIGIBILITY_PAYMENT_PENDING and ELIGIBILITY_PAID for clarity in application status flow.
2026-08-26 19:12:50 +00:00 · 2026-08-20 12:41:46 +00:00
parent 558cfe20a1
commit 6901e985fc
14 changed files with 231 additions and 1154 deletions
--- a/apps/backoffice/src/app/features/license-review/config/actions.ts
+++ b/apps/backoffice/src/app/features/license-review/config/actions.ts
@@ -29,6 +29,7 @@ export type ActionId =
  | 'request-adjustment'
  | 'reject'
  | 'schedule-exam'
+  | 'record-exam-outcome'
  | 'confirm-payment'
  | 'schedule-issuance'
  | 'issue-certificate'
@@ -68,7 +69,9 @@ export const ACTIONS: ActionDefinition[] = [
    id: 'claim',
    tier: 'workflow',
    labelKey: 'review.actions.claim',
-    from: ['SUBMITTED'],
+    // Mirrors the CLAIM transition's `from` list: an examined cert (CoC/CoP)
+    // sits in ELIGIBILITY_PAID once its eligibility fee clears, not SUBMITTED.
+    from: ['SUBMITTED', 'ELIGIBILITY_PAID'],
    permissions: ['can:claim:license-application'],
    emphasis: 'light',
  },
@@ -198,7 +201,21 @@ export const ACTIONS: ActionDefinition[] = [
    // Only after the examination fee clears — scheduling an unpaid candidate
    // is what the EXAM_PAID gate exists to prevent.
    from: ['EXAM_PAID'],
-    permissions: ['can:schedule:exam-candidate'],
+    // Matches the controller's guard on `:id/exam-scheduled`
+    // (`LICENSE_PERMISSIONS.MANAGE_EXAMS`) — the previous string didn't
+    // correspond to any real permission constant, so this button could never
+    // actually be granted to anyone.
+    permissions: ['can:manage:exams'],
+    emphasis: 'filled',
+    color: 'cyan',
+  },
+  {
+    id: 'record-exam-outcome',
+    tier: 'primary',
+    labelKey: 'review.actions.recordExamOutcome',
+    // Only once the candidate has actually sat the exam.
+    from: ['EXAM_SCHEDULED'],
+    permissions: ['can:publish:exam-result'],
    emphasis: 'filled',
    color: 'cyan',
  },
--- a/apps/backoffice/src/app/features/license-review/pages/LicenseQueuePage/actions.tsx
+++ b/apps/backoffice/src/app/features/license-review/pages/LicenseQueuePage/actions.tsx
@@ -22,7 +22,11 @@ export function licenseQueueActionsColumn(
    cell: ({ row }) =>
      handlers.claimable !== false &&
      row.original.assignedOfficerId === null &&
-      row.original.status === "SUBMITTED" ? (
+      // Mirrors the CLAIM transition's `from` list: an examined cert
+      // (CoC/CoP) sits in ELIGIBILITY_PAID once its eligibility fee clears,
+      // not SUBMITTED.
+      (row.original.status === "SUBMITTED" ||
+        row.original.status === "ELIGIBILITY_PAID") ? (
        <RequirePermission
          anyOf={[LICENSE_PERMISSIONS.CLAIM_APPLICATION]}
          hideOnly
--- a/apps/backoffice/src/app/features/license-review/pages/LicenseQueuePage/index.tsx
+++ b/apps/backoffice/src/app/features/license-review/pages/LicenseQueuePage/index.tsx
@@ -87,6 +87,17 @@ const STANDARD_ONLY_STATUSES: LicenseStatus[] = [
  "INSPECTION_COMPLETED",
 ];

+/** Statuses only an examined cert (CoC, or a CoP with requiresExamination) reaches. */
+const EXAM_ONLY_STATUSES: LicenseStatus[] = [
+  "ELIGIBILITY_PAYMENT_PENDING",
+  "ELIGIBILITY_PAID",
+  "EXAM_PAYMENT_PENDING",
+  "EXAM_PAID",
+  "EXAM_SCHEDULED",
+  "EXAM_PASSED",
+  "EXAM_FAILED",
+];
+
 const ALL_STATUSES: LicenseStatus[] = [
  "SUBMITTED",
  "UNDER_REVIEW",
@@ -96,9 +107,11 @@ const ALL_STATUSES: LicenseStatus[] = [
  "INSPECTION_COMPLETED",
  "ON_HOLD",
  "APPROVED",
+  ...EXAM_ONLY_STATUSES,
  "PAYMENT_PENDING",
  "PAID",
  "PAYMENT_CONFIRMED",
+  "SCHEDULED",
  "CERTIFICATE_ISSUED",
  "COMPLETED",
  "REJECTED",
@@ -117,6 +130,7 @@ function statusesFor(type: LicenseType | undefined): LicenseStatus[] {
    if (status === "INSPECTION_PENDING" || status === "INSPECTION_COMPLETED") {
      return type.inspectionRequired;
    }
+    if (EXAM_ONLY_STATUSES.includes(status)) return Boolean(type.requiresExamination);
    if (status === "CERTIFICATE_ISSUED") return type.issuesCertificate;
    return true;
  });
--- a/apps/backoffice/src/app/features/license-review/pages/LicenseReviewPage/index.tsx
+++ b/apps/backoffice/src/app/features/license-review/pages/LicenseReviewPage/index.tsx
@@ -44,6 +44,7 @@ import {
  useScheduleIssuanceMutation,
  useIssueCertificateMutation,
  useScheduleExamMutation,
+  useRecordExamOutcomeMutation,
  useEscalateApplicationMutation,
  useFinalApproveMutation,
  useGetApplicationForReviewQuery,
@@ -209,6 +210,7 @@ export function LicenseReviewPage() {
  const [issueCertificate] = useIssueCertificateMutation();
  const [scheduleExam, { isLoading: schedulingExam }] =
    useScheduleExamMutation();
+  const [recordExamOutcome] = useRecordExamOutcomeMutation();
  const [holdApplication] = useHoldApplicationMutation();
  const [resumeApplication] = useResumeApplicationMutation();
  const [escalateApplication] = useEscalateApplicationMutation();
@@ -234,6 +236,8 @@ export function LicenseReviewPage() {
  const [issuanceDate, setIssuanceDate] = useState("");
  const [resultOpen, setResultOpen] = useState(false);
  const [scheduleExamOpen, setScheduleExamOpen] = useState(false);
+  const [examOutcomeOpen, setExamOutcomeOpen] = useState(false);
+  const [examScore, setExamScore] = useState<number | undefined>();
  const [findings, setFindings] = useState("");
  const [checklist, setChecklist] = useState<
    Record<string, "PASS" | "FAIL" | "NEEDS_CORRECTION">
@@ -490,6 +494,11 @@ export function LicenseReviewPage() {
      case "schedule-exam":
        setScheduleExamOpen(true);
        return;
+      // Pass/fail plus an optional score, same reasoning as schedule-exam:
+      // needs its own inputs before anything is sent.
+      case "record-exam-outcome":
+        setExamOutcomeOpen(true);
+        return;
      case "copy-link":
        navigator.clipboard.writeText(window.location.href);
        notifications.show({
@@ -1173,6 +1182,73 @@ export function LicenseReviewPage() {
        }}
      />

+      <Modal
+        opened={examOutcomeOpen}
+        onClose={() => setExamOutcomeOpen(false)}
+        title={t("review.actions.recordExamOutcome", "Record exam outcome")}
+      >
+        <Stack>
+          <Text size="sm" c="dimmed">
+            {t(
+              "review.examOutcome.intro",
+              "Record the published result. A pass makes the certificate fee due; a fail leaves the application open for a retake.",
+            )}
+          </Text>
+          <NumberInput
+            label={t("review.examOutcome.score", "Score (optional)")}
+            value={examScore}
+            onChange={(v) => setExamScore(typeof v === "number" ? v : undefined)}
+            min={0}
+          />
+          <ModalFooter grow>
+            <ActionIcon
+              variant="light"
+              color="teal"
+              size="lg"
+              aria-label={t("review.passed", "Passed")}
+              onClick={() =>
+                run(
+                  async () => {
+                    await recordExamOutcome({
+                      id,
+                      passed: true,
+                      score: examScore,
+                    }).unwrap();
+                    setExamOutcomeOpen(false);
+                    setExamScore(undefined);
+                  },
+                  t("review.done.examPassed", "Exam result recorded — passed"),
+                )
+              }
+            >
+              <IconCheck size={18} />
+            </ActionIcon>
+            <ActionIcon
+              variant="light"
+              color="red"
+              size="lg"
+              aria-label={t("review.failed", "Failed")}
+              onClick={() =>
+                run(
+                  async () => {
+                    await recordExamOutcome({
+                      id,
+                      passed: false,
+                      score: examScore,
+                    }).unwrap();
+                    setExamOutcomeOpen(false);
+                    setExamScore(undefined);
+                  },
+                  t("review.done.examFailed", "Exam result recorded — not passed"),
+                )
+              }
+            >
+              <IconX size={18} />
+            </ActionIcon>
+          </ModalFooter>
+        </Stack>
+      </Modal>
+
      <Modal
        opened={inspectionOpen}
        onClose={() => setInspectionOpen(false)}
--- a/apps/portal/src/app/features/certificates/pages/CertificatesPage.tsx
+++ b/apps/portal/src/app/features/certificates/pages/CertificatesPage.tsx
@@ -72,7 +72,8 @@ const STATUS_COLOR: Record<string, string> = {
  RESUBMIT_REQUIRED: 'orange',
  INSPECTION_PENDING: 'grape',
  INSPECTION_COMPLETED: 'grape',
-  ELIGIBILITY_APPROVED: 'teal',
+  ELIGIBILITY_PAYMENT_PENDING: 'orange',
+  ELIGIBILITY_PAID: 'blue',
  EXAM_PAYMENT_PENDING: 'orange',
  EXAM_PAID: 'blue',
  EXAM_SCHEDULED: 'indigo',
@@ -220,14 +221,25 @@ export function CertificatesPage() {
          {/* Tooltip needs a hoverable child even while the button itself is
              disabled, so the reason still shows on hover. */}
          <span>
-            <Button
-              leftSection={<IconShieldCheck size={15} />}
-              rightSection={<IconArrowRight size={15} />}
-              onClick={() => navigate('/certificates/apply')}
-              disabled={!canApply}
-            >
-              Apply for CoC / CoP
-            </Button>
+            <Group gap="xs">
+              <Button
+                leftSection={<IconShieldCheck size={15} />}
+                rightSection={<IconArrowRight size={15} />}
+                onClick={() => navigate('/licensing/CERTIFICATE_OF_COMPETENCY/apply')}
+                disabled={!canApply}
+              >
+                Apply for CoC
+              </Button>
+              <Button
+                variant="light"
+                leftSection={<IconShieldCheck size={15} />}
+                rightSection={<IconArrowRight size={15} />}
+                onClick={() => navigate('/licensing/CERTIFICATE_OF_PROFICIENCY/apply')}
+                disabled={!canApply}
+              >
+                Apply for CoP
+              </Button>
+            </Group>
          </span>
        </Tooltip>
      </Group>
@@ -269,7 +281,7 @@ export function CertificatesPage() {
        <Text fw={700} mb="md">My Applications</Text>
        {applications.length === 0 ? (
          <Alert variant="light" color="gray" icon={<IconInfoCircle size={15} />}>
-            No active CoC/CoP applications. Click "Apply for CoC / CoP" to start.
+            No active CoC/CoP applications. Click "Apply for CoC" or "Apply for CoP" to start.
          </Alert>
        ) : (
          <Table highlightOnHover fz="sm" verticalSpacing="sm">
--- a/apps/portal/src/app/features/certificates/pages/CoCApplicationPage.tsx
+++ b/apps/portal/src/app/features/certificates/pages/CoCApplicationPage.tsx
--- a/apps/portal/src/app/features/licensing/components/ExamStageActions.tsx
+++ b/apps/portal/src/app/features/licensing/components/ExamStageActions.tsx
@@ -7,12 +7,13 @@ interface Props {
  t: TFunction;
  requesting: boolean;
  paying: boolean;
-  onRequestExamFee: (app: LicenseApplication) => void;
+  onRetakeExam: (app: LicenseApplication) => void;
  onPay: (app: LicenseApplication) => void;
 }

 /**
- * What the candidate can do while an examined certificate is in its exam leg.
+ * What the candidate can do while an examined certificate is in its
+ * eligibility or exam leg.
 *
 * Kept apart from the general actions column because these statuses only ever
 * occur on types that examine — folding them into that column would put five
@@ -26,24 +27,50 @@ export function ExamStageActions({
  t,
  requesting,
  paying,
-  onRequestExamFee,
+  onRetakeExam,
  onPay,
 }: Props) {
-  // Eligible but not yet committed to sitting, or sat and not passed: both are
-  // the same decision — ask for the fee that buys a sitting.
-  if (app.status === 'ELIGIBILITY_APPROVED' || app.status === 'EXAM_FAILED') {
-    const retake = app.status === 'EXAM_FAILED';
+  // The eligibility fee is invoiced the moment the application is submitted —
+  // there is no separate "request" step, so this is a pay button, exactly
+  // like EXAM_PAYMENT_PENDING below.
+  if (app.status === 'ELIGIBILITY_PAYMENT_PENDING') {
    return (
      <Button
        size="xs"
        variant="filled"
-        color={retake ? 'orange' : 'teal'}
-        loading={requesting}
-        onClick={() => onRequestExamFee(app)}
+        color="yellow"
+        loading={paying}
+        onClick={() => onPay(app)}
      >
-        {retake
-          ? t('applications.actions.bookRetake', 'Book a resit')
-          : t('applications.actions.bookExam', 'Book exam')}
+        {t('applications.actions.payEligibilityFee', {
+          defaultValue: 'Pay eligibility fee ({{amount}} {{currency}})',
+          amount: Number(app.feeAmount ?? 0).toLocaleString(),
+          currency: app.feeCurrency,
+        })}
+      </Button>
+    );
+  }
+
+  // Paid — queued for backoffice review. Nothing for the candidate to do.
+  if (app.status === 'ELIGIBILITY_PAID') {
+    return (
+      <Button size="xs" variant="subtle" disabled>
+        {t('applications.actions.eligibilityUnderReview', 'Under review')}
+      </Button>
+    );
+  }
+
+  // Failed a sitting: the only decision left is whether to pay for another.
+  if (app.status === 'EXAM_FAILED') {
+    return (
+      <Button
+        size="xs"
+        variant="filled"
+        color="orange"
+        loading={requesting}
+        onClick={() => onRetakeExam(app)}
+      >
+        {t('applications.actions.bookRetake', 'Book a resit')}
      </Button>
    );
  }
--- a/apps/portal/src/app/features/licensing/pages/MyApplicationsPage/actions.tsx
+++ b/apps/portal/src/app/features/licensing/pages/MyApplicationsPage/actions.tsx
@@ -8,7 +8,8 @@ import { ExamStageActions } from '../../components/ExamStageActions';

 /** Statuses whose primary action is supplied by {@link ExamStageActions}. */
 const EXAM_STAGE_STATUSES = [
-  'ELIGIBILITY_APPROVED',
+  'ELIGIBILITY_PAYMENT_PENDING',
+  'ELIGIBILITY_PAID',
  'EXAM_PAYMENT_PENDING',
  'EXAM_PAID',
  'EXAM_SCHEDULED',
@@ -23,12 +24,12 @@ export function applicationActionsColumn(
    bypassEnabled: boolean;
    bypassing: boolean;
    isPaying: boolean;
-    /** True while the exam fee is being raised for a booking or a resit. */
+    /** True while a resit is being requested. */
    requestingExamFee: boolean;
    onBypass: (app: LicenseApplication) => void;
    onCertificate: (app: LicenseApplication) => void;
    onPay: (app: LicenseApplication) => void;
-    onRequestExamFee: (app: LicenseApplication) => void;
+    onRetakeExam: (app: LicenseApplication) => void;
    onOpen: (app: LicenseApplication) => void;
  },
 ): AdvancedColumn<LicenseApplication> {
@@ -46,7 +47,7 @@ export function applicationActionsColumn(
            t={t}
            requesting={deps.requestingExamFee}
            paying={deps.isPaying}
-            onRequestExamFee={deps.onRequestExamFee}
+            onRetakeExam={deps.onRetakeExam}
            onPay={deps.onPay}
          />
          {/* Both fee stops are bypassable — an examined certificate is
--- a/apps/portal/src/app/features/licensing/pages/MyApplicationsPage/index.tsx
+++ b/apps/portal/src/app/features/licensing/pages/MyApplicationsPage/index.tsx
@@ -46,7 +46,7 @@ import {
  useGetMyApplicationsQuery,
  useGetMyLicensesQuery,
  useGetPaymentCapabilitiesQuery,
-  useRequestExamPaymentMutation,
+  useRetakeExamMutation,
  type LicenseStatus,
 } from '@ema-platform/api';
 import {
@@ -99,8 +99,7 @@ export function MyApplicationsPage() {
  const { data: capabilities } = useGetPaymentCapabilitiesQuery();
  const { data: licences, isFetching: isFetchingLicences } = useGetMyLicensesQuery();
  const [bypassPayment, { isLoading: bypassing }] = useBypassPaymentMutation();
-  const [requestExamPayment, { isLoading: requestingExamFee }] =
-    useRequestExamPaymentMutation();
+  const [retakeExam, { isLoading: requestingExamFee }] = useRetakeExamMutation();
  const [getCertificateUrl] = useGetCertificateUrlMutation();
  const { renewLicense, isRenewing } = useRenewLicense();
  const [isDownloadingCert, setIsDownloadingCert] = useState(false);
@@ -135,15 +134,15 @@ export function MyApplicationsPage() {
  }

  /**
-   * Raises the examination fee, for a first sitting or a resit.
+   * Re-opens the examination fee for a failed candidate.
   *
-   * Payment is a separate step: this only moves the application to
+   * Payment is a separate step: this only moves the application back to
   * EXAM_PAYMENT_PENDING, and the Pay button that then appears hands off to
   * the provider the same way every other fee does.
   */
-  async function requestExamFee(applicationId: string) {
+  async function retakeExamFee(applicationId: string) {
    try {
-      await requestExamPayment(applicationId).unwrap();
+      await retakeExam(applicationId).unwrap();
      notifications.show({
        color: 'teal',
        title: t('applications.examFeeRequested', 'Exam fee ready'),
@@ -281,7 +280,7 @@ export function MyApplicationsPage() {
      onBypass: (app) => handleBypass(app.id),
      onCertificate: (app) => openCertificateForApplication(app.id),
      onPay: (app) => pay(app.id),
-      onRequestExamFee: (app) => requestExamFee(app.id),
+      onRetakeExam: (app) => retakeExamFee(app.id),
      onOpen: (app) =>
        navigate(`/licensing/${app.licenseType?.key ?? 'FREIGHT_FORWARDER'}/applications/${app.id}`),
    }),
--- a/apps/portal/src/app/router.tsx
+++ b/apps/portal/src/app/router.tsx
@@ -38,7 +38,6 @@ import { NotificationsPage } from "./features/notifications/pages/NotificationsP

 // Phase 2 — CoC / CoP
 import { CertificatesPage } from "./features/certificates/pages/CertificatesPage";
-import { CoCApplicationPage } from "./features/certificates/pages/CoCApplicationPage";

 // Phase 3 — Endorsement
 import { EndorsementPage } from "./features/endorsement/pages/EndorsementPage";
@@ -266,14 +265,9 @@ export const router = createBrowserRouter([
          </RequirePermission>
        ),
      },
-      {
-        path: "/certificates/apply",
-        element: (
-          <RequirePermission anyOf={[P.VIEW_OWN_CERTIFICATES]}>
-            <CoCApplicationPage />
-          </RequirePermission>
-        ),
-      },
+      // CoC/CoP applications go through the generic license wizard —
+      // /licensing/CERTIFICATE_OF_COMPETENCY/apply and
+      // /licensing/CERTIFICATE_OF_PROFICIENCY/apply, wired below.

      // Phase 3 — Endorsement
      {