From c3977897b7551f0efa0c8c2a614cea745dc7334c Mon Sep 17 00:00:00 2001
From: Nati <natinigussie7@gmail.com>
Date: Fri, 21 Aug 2026 19:10:01 +0000
Subject: [PATCH] Add rankKey support to certification forms and exams

- Introduced rankKey field in Certification interface and payloads.
- Updated CertificationForm to handle rankKey input.
- Enhanced ScheduleExamModal to filter exams based on rank.
- Added getEligibleExams API query to fetch exams relevant to the application's rank.
- Updated related components and types to accommodate new rankKey functionality.
---
 .../DocumentRequirementEditorDrawer.tsx       |  2 +-
 .../pages/CertificationPage/columns.tsx       |  9 ++++++
 .../pages/CertificationPage/index.tsx         | 28 ++++++++++++++-----
 .../certification/types/certification.ts      | 22 +++++++++++++++
 .../components/ScheduleExamModal.tsx          | 16 +++++++----
 .../pages/LicenseReviewPage/index.tsx         |  1 +
 .../lib/features/licensing/licensing-api.ts   | 11 ++++++++
 .../lib/features/licensing/licensing.types.ts | 10 +++++++
 8 files changed, 85 insertions(+), 14 deletions(-)

diff --git a/apps/backoffice/src/app/features/certificate-requirements/components/DocumentRequirementEditorDrawer.tsx b/apps/backoffice/src/app/features/certificate-requirements/components/DocumentRequirementEditorDrawer.tsx
index 6d59af5f6..733334b8e 100644
--- a/apps/backoffice/src/app/features/certificate-requirements/components/DocumentRequirementEditorDrawer.tsx
+++ b/apps/backoffice/src/app/features/certificate-requirements/components/DocumentRequirementEditorDrawer.tsx
@@ -167,7 +167,7 @@ export function DocumentRequirementEditorDrawer({
           <>
             <Divider label={t('certReq.condition.title', 'Condition')} labelPosition="left" />
             <ConditionBuilder
-              value={(draft.conditionExpression ?? null) as ConditionValue | null}
+              value={(draft.conditionExpression ?? { field: '', equals: '' }) as ConditionValue}
               onChange={(v) => setDraft((d) => ({ ...d, conditionExpression: v ?? undefined }))}
               targets={conditionTargets}
               palette={palette}
diff --git a/apps/backoffice/src/app/features/certification/pages/CertificationPage/columns.tsx b/apps/backoffice/src/app/features/certification/pages/CertificationPage/columns.tsx
index 4a56ea6d0..47649d27f 100644
--- a/apps/backoffice/src/app/features/certification/pages/CertificationPage/columns.tsx
+++ b/apps/backoffice/src/app/features/certification/pages/CertificationPage/columns.tsx
@@ -16,6 +16,15 @@ export function certificationColumns(
       header: t('certification.columns.description'),
       cell: ({ row }) => <Text fz="sm" lineClamp={2} maw={250}>{row.original.description[locale]}</Text>,
     },
+    {
+      header: t('certification.columns.rank', 'Rank'),
+      cell: ({ row }) =>
+        row.original.rankKey ? (
+          <Badge size="sm" variant="outline" color="violet">{row.original.rankKey}</Badge>
+        ) : (
+          <Text fz="sm" c="dimmed">—</Text>
+        ),
+    },
     {
       header: t('certification.columns.status'),
       cell: ({ row }) => (
diff --git a/apps/backoffice/src/app/features/certification/pages/CertificationPage/index.tsx b/apps/backoffice/src/app/features/certification/pages/CertificationPage/index.tsx
index 717311b65..e3f9ed214 100644
--- a/apps/backoffice/src/app/features/certification/pages/CertificationPage/index.tsx
+++ b/apps/backoffice/src/app/features/certification/pages/CertificationPage/index.tsx
@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import {Stack, Button, Modal, Text, TextInput, Textarea, Card} from '@mantine/core';
+import {Stack, Button, Modal, Text, TextInput, Textarea, Select, Card} from '@mantine/core';
 import { useDisclosure } from '@mantine/hooks';
 import { useTranslation } from 'react-i18next';
 import {IconPlus} from '@tabler/icons-react';
@@ -10,7 +10,7 @@ import {
   useUpdateCertificationMutation,
   useDeleteCertificationMutation,
 } from '../../api/certification-api';
-import type { Certification } from '../../types/certification';
+import { RANK_KEY_OPTIONS, type Certification } from '../../types/certification';
 import { certificationColumns } from './columns';
 import { certificationActionsColumn } from './actions';
 
@@ -22,7 +22,7 @@ function CertificationForm({
 }: {
   editing: Certification | null;
   isSubmitting: boolean;
-  onSubmit: (values: { nameEn: string; nameAm: string; descEn: string; descAm: string }, isEdit: boolean) => void;
+  onSubmit: (values: { nameEn: string; nameAm: string; descEn: string; descAm: string; rankKey: string | null }, isEdit: boolean) => void;
   onCancel: () => void;
 }) {
   const { t } = useTranslation();
@@ -30,6 +30,7 @@ function CertificationForm({
   const [nameAm, setNameAm] = useState(editing?.name?.am ?? '');
   const [descEn, setDescEn] = useState(editing?.description?.en ?? '');
   const [descAm, setDescAm] = useState(editing?.description?.am ?? '');
+  const [rankKey, setRankKey] = useState<string | null>(editing?.rankKey ?? null);
 
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
@@ -37,7 +38,7 @@ function CertificationForm({
       notify.error('Name fields are required');
       return;
     }
-    onSubmit({ nameEn, nameAm, descEn, descAm }, !!editing);
+    onSubmit({ nameEn, nameAm, descEn, descAm, rankKey }, !!editing);
   };
 
   return (
@@ -48,6 +49,17 @@ function CertificationForm({
           <TextInput label={t('certification.form.nameAm')} placeholder={t('certification.form.nameAmPlaceholder')} value={nameAm} onChange={(e) => setNameAm(e.currentTarget.value)} size="sm" required />
           <Textarea label={t('certification.form.descEn')} placeholder={t('certification.form.descEnPlaceholder')} value={descEn} onChange={(e) => setDescEn(e.currentTarget.value)} size="sm" autosize minRows={2} />
           <Textarea label={t('certification.form.descAm')} placeholder={t('certification.form.descAmPlaceholder')} value={descAm} onChange={(e) => setDescAm(e.currentTarget.value)} size="sm" autosize minRows={2} />
+          <Select
+            label={t('certification.form.rankKey', 'STCW rank (for exam scheduling)')}
+            description={t('certification.form.rankKeyHint', 'Leave blank if this certification is not part of the examined CoC/CoP ladder.')}
+            placeholder={t('certification.form.rankKeyPlaceholder', 'Not rank-specific')}
+            data={RANK_KEY_OPTIONS as unknown as { value: string; label: string }[]}
+            value={rankKey}
+            onChange={setRankKey}
+            size="sm"
+            clearable
+            searchable
+          />
           <ModalFooter>
             <Button variant="default" onClick={onCancel} size="sm">{t('certification.cancel')}</Button>
             <Button type="submit" size="sm" loading={isSubmitting}>{editing ? t('certification.update') : t('certification.create')}</Button>
@@ -80,15 +92,17 @@ export function CertificationPage() {
     setShowForm(false);
   };
 
-  const handleSubmit = async (values: { nameEn: string; nameAm: string; descEn: string; descAm: string }, isEdit: boolean) => {
+  const handleSubmit = async (values: { nameEn: string; nameAm: string; descEn: string; descAm: string; rankKey: string | null }, isEdit: boolean) => {
     const name = { en: values.nameEn, am: values.nameAm };
     const description = { en: values.descEn, am: values.descAm };
     try {
       if (isEdit && editing) {
-        await updateCert({ id: editing.id, name, description }).unwrap();
+        // null clears a previously-set rank; undefined would leave it
+        // untouched server-side, so the two are not interchangeable here.
+        await updateCert({ id: editing.id, name, description, rankKey: values.rankKey }).unwrap();
         notify.success(t('certification.updated'));
       } else {
-        await createCert({ name, description }).unwrap();
+        await createCert({ name, description, rankKey: values.rankKey ?? undefined }).unwrap();
         notify.success(t('certification.created'));
       }
       resetForm();
diff --git a/apps/backoffice/src/app/features/certification/types/certification.ts b/apps/backoffice/src/app/features/certification/types/certification.ts
index b89b4f328..a3298f5af 100644
--- a/apps/backoffice/src/app/features/certification/types/certification.ts
+++ b/apps/backoffice/src/app/features/certification/types/certification.ts
@@ -3,11 +3,30 @@ export interface LocalePair {
   am: string;
 }
 
+/**
+ * STCW rank an exam certification is for — the join that lets the
+ * schedule-exam picker offer only sittings valid for an application's rank.
+ * Matches `LicenseApplication.formData.certificate.rank` / `rankEngine` /
+ * `proficiency` on the backend. Not every certification is on the examined
+ * ladder, so this stays a plain optional string rather than a required enum.
+ */
+export const RANK_KEY_OPTIONS = [
+  { value: 'OOW_DECK', label: 'Officer of the Watch (Deck)' },
+  { value: 'CHIEF_MATE', label: 'Chief Mate' },
+  { value: 'MASTER', label: 'Master' },
+  { value: 'OOW_ENGINE', label: 'Officer of the Watch (Engine)' },
+  { value: 'SECOND_ENGINEER', label: 'Second Engineer' },
+  { value: 'CHIEF_ENGINEER', label: 'Chief Engineer' },
+  { value: 'ABLE_SEAFARER_DECK', label: 'Able Seafarer Deck' },
+  { value: 'ABLE_SEAFARER_ENGINE', label: 'Able Seafarer Engine' },
+] as const;
+
 export interface Certification {
   id: string;
   name: LocalePair;
   description: LocalePair;
   isActive: boolean;
+  rankKey: string | null;
   createdAt: string;
   updatedAt: string;
 }
@@ -20,6 +39,7 @@ export interface ListResponse<T> {
 export interface CreateCertificationPayload {
   name: LocalePair;
   description: LocalePair;
+  rankKey?: string;
 }
 
 export interface UpdateCertificationPayload {
@@ -27,4 +47,6 @@ export interface UpdateCertificationPayload {
   name?: LocalePair;
   description?: LocalePair;
   isActive?: boolean;
+  /** Omit to leave unchanged, null to clear a previously-set rank. */
+  rankKey?: string | null;
 }
diff --git a/apps/backoffice/src/app/features/license-review/components/ScheduleExamModal.tsx b/apps/backoffice/src/app/features/license-review/components/ScheduleExamModal.tsx
index 25210ad5c..b68de8778 100644
--- a/apps/backoffice/src/app/features/license-review/components/ScheduleExamModal.tsx
+++ b/apps/backoffice/src/app/features/license-review/components/ScheduleExamModal.tsx
@@ -3,10 +3,11 @@ import { Alert, Button, Modal, Select, Stack, Text, TextInput } from '@mantine/c
 import { IconCalendarEvent } from '@tabler/icons-react';
 import { useTranslation } from 'react-i18next';
 import { ModalFooter } from '@ema-platform/ui';
-import { useGetExamsQuery } from '../../exam/api/exam-api';
+import { useGetEligibleExamsQuery } from '@ema-platform/api';
 
 interface Props {
   opened: boolean;
+  applicationId: string;
   applicantName: string;
   loading: boolean;
   onClose: () => void;
@@ -22,27 +23,30 @@ interface Props {
  *
  * Sessions are picked from the exam calendar rather than typed, because the
  * candidate joins a scheduled sitting — this is an assignment, not the creation
- * of a per-candidate appointment.
+ * of a per-candidate appointment. Scoped to sittings whose certification
+ * matches this application's rank, so a Chief Mate candidate cannot be seated
+ * into an OOW Deck sitting by accident.
  */
 export function ScheduleExamModal({
   opened,
+  applicationId,
   applicantName,
   loading,
   onClose,
   onConfirm,
 }: Props) {
   const { t } = useTranslation();
-  const { data: exams, isLoading } = useGetExamsQuery(undefined, { skip: !opened });
+  const { data: exams, isLoading } = useGetEligibleExamsQuery(applicationId, { skip: !opened });
   const [examId, setExamId] = useState<string | null>(null);
   const [admissionNumber, setAdmissionNumber] = useState('');
 
-  const options = (exams?.items ?? []).map((exam) => ({
+  const options = (exams ?? []).map((exam) => ({
     value: exam.id,
     label: [exam.title?.en ?? exam.title?.am ?? t('exam.untitled', 'Untitled exam'), exam.date]
       .filter(Boolean)
       .join(' — '),
   }));
-  const selected = exams?.items?.find((exam) => exam.id === examId);
+  const selected = exams?.find((exam) => exam.id === examId);
 
   function confirm() {
     if (!examId) return;
@@ -72,7 +76,7 @@ export function ScheduleExamModal({
           <Alert color="orange" icon={<IconCalendarEvent size={16} />}>
             {t(
               'review.scheduleExam.noSessions',
-              'No exam sessions exist yet. Create one in the Exams area first.',
+              'No exam sessions for this rank exist yet. Create one in the Exams area first.',
             )}
           </Alert>
         ) : (
diff --git a/apps/backoffice/src/app/features/license-review/pages/LicenseReviewPage/index.tsx b/apps/backoffice/src/app/features/license-review/pages/LicenseReviewPage/index.tsx
index d29871597..c26ec2cc8 100644
--- a/apps/backoffice/src/app/features/license-review/pages/LicenseReviewPage/index.tsx
+++ b/apps/backoffice/src/app/features/license-review/pages/LicenseReviewPage/index.tsx
@@ -1162,6 +1162,7 @@ export function LicenseReviewPage() {
 
       <ScheduleExamModal
         opened={scheduleExamOpen}
+        applicationId={id}
         applicantName={
           app.companyName ||
           applicantFullName ||
diff --git a/libs/api/src/lib/features/licensing/licensing-api.ts b/libs/api/src/lib/features/licensing/licensing-api.ts
index ac0fa0b02..6a960d0fa 100644
--- a/libs/api/src/lib/features/licensing/licensing-api.ts
+++ b/libs/api/src/lib/features/licensing/licensing-api.ts
@@ -21,6 +21,7 @@ import type {
   AssignableOfficer,
   DocumentDecision,
   DocumentReview,
+  EligibleExam,
   ExportResult,
   LicenseTemplate,
   Paginated,
@@ -565,6 +566,15 @@ export const licensingApi = baseApi
           error ? [] : [itemTag('LicenseApplication', id), listTag('ApplicationQueue')],
       }),
 
+      /**
+       * Exam sittings valid for this application's rank — what the
+       * schedule-exam picker offers, instead of every exam in the system.
+       */
+      getEligibleExams: builder.query<EligibleExam[], string>({
+        query: (id) => ({ url: `/license-application-review/${id}/eligible-exams` }),
+        providesTags: (_r, _e, id) => [itemTag('LicenseApplication', id)],
+      }),
+
       /** Places a candidate who has paid the examination fee into a sitting. */
       scheduleExam: builder.mutation<
         LicenseApplication,
@@ -963,6 +973,7 @@ export const {
   useApproveDocumentsMutation,
   useFinalApproveMutation,
   useRejectApplicationMutation,
+  useGetEligibleExamsQuery,
   useScheduleExamMutation,
   useRecordExamOutcomeMutation,
   useRetakeExamMutation,
diff --git a/libs/api/src/lib/features/licensing/licensing.types.ts b/libs/api/src/lib/features/licensing/licensing.types.ts
index 029f45f92..22bef0df4 100644
--- a/libs/api/src/lib/features/licensing/licensing.types.ts
+++ b/libs/api/src/lib/features/licensing/licensing.types.ts
@@ -690,3 +690,13 @@ export interface IssuedLicense {
   verificationCode: string;
   certificateFileKey: string | null;
 }
+
+/** One sitting offered to a claimed examined-certificate application, scoped to its rank. */
+export interface EligibleExam {
+  id: string;
+  title: { en: string; am: string };
+  date: string;
+  venue: string;
+  status: string;
+  certification?: { id: string; name: { en: string; am: string }; rankKey: string | null };
+}