Tria/emaui
1
0
Fork 0
mirror of https://github.com/Tria-plc/emaui.git synced 2026-08-26 13:02:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: update exam stage actions and payment flow

Browse Source 
- 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.
This commit is contained in:
Nati
2026-08-20 12:41:46 +00:00
parent 558cfe20a1
commit 6901e985fc
14 changed files with 231 additions and 1154 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
apps/backoffice/src/app/features/license-review/config/actions.ts
View File

@@ -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',
},

6
apps/backoffice/src/app/features/license-review/pages/LicenseQueuePage/actions.tsx
View File

@@ -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

14
apps/backoffice/src/app/features/license-review/pages/LicenseQueuePage/index.tsx
View File

@@ -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;
});

76
apps/backoffice/src/app/features/license-review/pages/LicenseReviewPage/index.tsx
View File

@@ -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)}

32
apps/portal/src/app/features/certificates/pages/CertificatesPage.tsx
View File

@@ -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">

1094
apps/portal/src/app/features/certificates/pages/CoCApplicationPage.tsx
View File

File diff suppressed because it is too large Load Diff

53
apps/portal/src/app/features/licensing/components/ExamStageActions.tsx
View File

@@ -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>
);
}

9
apps/portal/src/app/features/licensing/pages/MyApplicationsPage/actions.tsx
View File

@@ -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

15
apps/portal/src/app/features/licensing/pages/MyApplicationsPage/index.tsx
View File

@@ -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}`),
}),

12
apps/portal/src/app/router.tsx
View File

@@ -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
{

2
libs/api/src/lib/base-api/mock-data.ts
View File

@@ -337,7 +337,7 @@ export const mockApplications: Record<string, any> = {
licenseType: { id: 'license-type-coc', key: 'CERTIFICATE_OF_COMPETENCY', name: { en: 'Certificate of Competency' } },
applicantUserId: 'user-mock-001',
kind: 'RENEWAL',
status: 'ELIGIBILITY_APPROVED',
status: 'ELIGIBILITY_PAID',
assignedOfficerId: 'officer-mock-002',
claimedAt: '2026-08-01T10:00:00.000Z',
formData: { account: { applicantName: 'Abebe Tesfaye' } },

31
libs/api/src/lib/features/licensing/licensing-api.ts
View File

@@ -494,9 +494,26 @@ export const licensingApi = baseApi
scheduleExam: builder.mutation<
LicenseApplication,
{ id: string; examId: string; admissionNumber?: string; examDate?: string }
>({
query: ({ id, examDate: _examDate, ...body }) => ({
// Matches the controller's `:id/exam-scheduled` route — `examDate`
// is UI-only context for the confirmation toast, not part of
// `MarkExamScheduledDto`, so it never goes on the wire.
url: `/license-application-review/${id}/exam-scheduled`,
method: 'POST',
body,
}),
invalidatesTags: (_r, error, { id }) =>
error ? [] : [itemTag('LicenseApplication', id), listTag('ApplicationQueue')],
}),
/** Records a published examination result (pass or fail). */
recordExamOutcome: builder.mutation<
LicenseApplication,
{ id: string; passed: boolean; score?: number }
>({
query: ({ id, ...body }) => ({
url: `/license-application-review/${id}/schedule-exam`,
url: `/license-application-review/${id}/exam-outcome`,
method: 'POST',
body,
}),
@@ -505,12 +522,13 @@ export const licensingApi = baseApi
}),
/**
* Raises the examination fee — after eligibility approval, or again when
* a failed candidate elects to resit.
* A failed candidate asks for another sitting. Re-opens the examination
* fee (EXAM_FAILED -> EXAM_PAYMENT_PENDING); eligibility was already
* assessed and paid for on the first attempt.
*/
requestExamPayment: builder.mutation<LicenseApplication, string>({
retakeExam: builder.mutation<LicenseApplication, string>({
query: (id) => ({
url: `/license-applications/${id}/request-exam-payment`,
url: `/license-applications/${id}/retake`,
method: 'POST',
}),
invalidatesTags: (_r, error, id) =>
@@ -864,7 +882,8 @@ export const {
useFinalApproveMutation,
useRejectApplicationMutation,
useScheduleExamMutation,
useRequestExamPaymentMutation,
useRecordExamOutcomeMutation,
useRetakeExamMutation,
useConfirmPaymentMutation,
useScheduleIssuanceMutation,
useIssueCertificateMutation,

12
libs/api/src/lib/features/licensing/licensing.helpers.ts
View File

@@ -74,7 +74,8 @@ export const STATUS_LABELS: Record<LicenseStatus, string> = {
SCHEDULED: 'Pickup Scheduled',
CERTIFICATE_ISSUED: 'Certificate Issued',
COMPLETED: 'Completed',
ELIGIBILITY_APPROVED: 'Eligible to Sit',
ELIGIBILITY_PAYMENT_PENDING: 'Eligibility Fee Due',
ELIGIBILITY_PAID: 'Eligibility Under Review',
EXAM_PAYMENT_PENDING: 'Exam Fee Due',
EXAM_PAID: 'Awaiting Exam Date',
EXAM_SCHEDULED: 'Exam Scheduled',
@@ -100,7 +101,8 @@ export const STATUS_COLORS: Record<LicenseStatus, string> = {
SCHEDULED: 'cyan',
CERTIFICATE_ISSUED: 'green',
COMPLETED: 'green',
ELIGIBILITY_APPROVED: 'teal',
ELIGIBILITY_PAYMENT_PENDING: 'yellow',
ELIGIBILITY_PAID: 'lime',
EXAM_PAYMENT_PENDING: 'yellow',
EXAM_PAID: 'lime',
EXAM_SCHEDULED: 'cyan',
@@ -135,7 +137,8 @@ export const STATUS_PROGRESS: Record<LicenseStatus, number> = {
REJECTED: 100,
// The exam leg sits between approval and the certificate fee, so these
// interleave with PAYMENT_PENDING (80) rather than running past it.
ELIGIBILITY_APPROVED: 60,
ELIGIBILITY_PAYMENT_PENDING: 52,
ELIGIBILITY_PAID: 56,
EXAM_PAYMENT_PENDING: 64,
EXAM_PAID: 68,
EXAM_SCHEDULED: 72,
@@ -149,6 +152,9 @@ export const APPLICANT_ACTION_STATUSES: LicenseStatus[] = [
'DRAFT',
'RESUBMIT_REQUIRED',
'PAYMENT_PENDING',
// Due the moment an examined application is submitted, before any officer
// looks at it.
'ELIGIBILITY_PAYMENT_PENDING',
// Both wait on the candidate: one to pay for a sitting, one to decide to
// sit again after a failure.
'EXAM_PAYMENT_PENDING',

8
libs/api/src/lib/features/licensing/licensing.types.ts
View File

@@ -41,9 +41,11 @@ export type LicenseStatus =
| "SCHEDULED"
| "CERTIFICATE_ISSUED"
| "COMPLETED"
// Examined certificates (CoC, some CoP): approval establishes eligibility,
// the candidate pays to sit, and the certificate fee falls due on a pass.
| "ELIGIBILITY_APPROVED"
// Examined certificates (CoC, some CoP): the eligibility assessment fee is
// due before review starts, then the candidate pays to sit, and the
// certificate fee falls due on a pass.
| "ELIGIBILITY_PAYMENT_PENDING"
| "ELIGIBILITY_PAID"
| "EXAM_PAYMENT_PENDING"
| "EXAM_PAID"
| "EXAM_SCHEDULED"