feat: add inspection rescheduling workflow and unlock dependencies for flagged document sections

2026-09-03 16:43:40 +00:00 · 2026-08-28 06:46:06 +00:00
parent 4317e3cb89
commit 51627f9918
9 changed files with 295 additions and 63 deletions
--- a/apps/backoffice/src/app/features/license-review/config/actions.ts
+++ b/apps/backoffice/src/app/features/license-review/config/actions.ts
@@ -28,6 +28,7 @@ export type ActionId =
  | 'complete-review'
  | 'approve-documents'
  | 'schedule-inspection'
+  | 'reschedule-inspection'
  | 'record-inspection'
  | 'final-approve'
  | 'request-adjustment'
@@ -200,6 +201,17 @@ export const ACTIONS: ActionDefinition[] = [
    permissions: ['can:create:inspection'],
    emphasis: 'filled',
  },
+  {
+    id: 'reschedule-inspection',
+    tier: 'primary',
+    labelKey: 'review.actions.rescheduleInspection',
+    from: ['INSPECTION_PENDING', 'INSPECTION_FAILED'],
+    // Either permission: the team leader who booked the visit holds CREATE,
+    // the inspector who has to attend holds UPDATE, and both have a reason to
+    // move it. The server guards the same pair.
+    permissions: ['can:create:inspection', 'can:update:inspection'],
+    emphasis: 'light',
+  },
  {
    id: 'record-inspection',
    tier: 'primary',
@@ -441,6 +453,12 @@ export function resolveActions(ctx: ResolveContext): ResolvedAction[] {
      // one applies depends on whether an inspection is already booked.
      if (action.id === 'schedule-inspection' && ctx.hasPendingInspection) return [];
      if (action.id === 'record-inspection' && !ctx.hasPendingInspection) return [];
+      // The mirror of the scheduling gate: there is nothing to move until a
+      // visit is booked, and once one is, moving it is the officer's only
+      // option until the day arrives.
+      if (action.id === 'reschedule-inspection' && !ctx.hasPendingInspection) {
+        return [];
+      }

      // The transition table doesn't know which types need an inspection, so
      // `availableEvents` lists approve-documents at UNDER_EVALUATION even for
--- a/apps/backoffice/src/app/features/license-review/pages/LicenseReviewPage/index.tsx
+++ b/apps/backoffice/src/app/features/license-review/pages/LicenseReviewPage/index.tsx
@@ -32,6 +32,7 @@ import {
  IconLayoutSidebarRightCollapse,
  IconLayoutSidebarRightExpand,
  IconPaperclip,
+  IconPencil,
  IconQuestionMark,
  IconX,
 } from "@tabler/icons-react";
@@ -70,6 +71,7 @@ import {
  useRequestAdjustmentMutation,
  useResumeApplicationMutation,
  useScheduleInspectionMutation,
+  useRescheduleInspectionMutation,
  useGetCertificateUrlForOfficerMutation,
  uploadDocument,
  type RemarkTargetType,
@@ -218,6 +220,7 @@ export function LicenseReviewPage() {
  const [finalApprove] = useFinalApproveMutation();
  const [rejectApplication] = useRejectApplicationMutation();
  const [scheduleInspection] = useScheduleInspectionMutation();
+  const [rescheduleInspection] = useRescheduleInspectionMutation();
  const [recordResult] = useRecordInspectionResultMutation();
  const [confirmPayment] = useConfirmPaymentMutation();
  const [scheduleIssuance] = useScheduleIssuanceMutation();
@@ -261,6 +264,9 @@ export function LicenseReviewPage() {
  const [inspectionTimeSlot, setInspectionTimeSlot] = useState<"MORNING" | "AFTERNOON">(
    "MORNING",
  );
+  /** The booking modal moves an existing visit rather than creating one. */
+  const [rescheduling, setRescheduling] = useState(false);
+  const [rescheduleReason, setRescheduleReason] = useState("");
  const [issuanceOpen, setIssuanceOpen] = useState(false);
  const [issuanceDate, setIssuanceDate] = useState("");
  const [resultOpen, setResultOpen] = useState(false);
@@ -311,10 +317,14 @@ export function LicenseReviewPage() {

  const pendingInspection = inspections.find((i) => i.status === 'SCHEDULED');
  // A visit cannot have an outcome before it happens — mirror of the server's
-  // inspection_not_yet_due guard, compared instant-to-instant.
+  // inspection_not_yet_due guard. The column holds a calendar day, so the
+  // comparison is between day strings in the authority's timezone: parsing
+  // "2026-08-28" as a Date would read it as UTC midnight, i.e. 03:00 in Addis.
  const inspectionNotYetDue = Boolean(
    pendingInspection?.scheduledDate &&
-      new Date(pendingInspection.scheduledDate) > new Date(),
+      new Intl.DateTimeFormat("en-CA", { timeZone: "Africa/Addis_Ababa" }).format(
+        new Date(),
+      ) < pendingInspection.scheduledDate.slice(0, 10),
  );

  const { data: findingsEvidence = [], refetch: refetchFindingsEvidence } =
@@ -558,12 +568,29 @@ export function LicenseReviewPage() {
    }
  }

+  /** Opens the booking modal seeded with the visit already on the books. */
+  function openReschedule() {
+    if (!pendingInspection) return;
+    setRescheduling(true);
+    setInspectionDate(pendingInspection.scheduledDate ?? "");
+    setInspectionTimeSlot(pendingInspection.timeSlot ?? "MORNING");
+    setRescheduleReason("");
+    setInspectionOpen(true);
+  }
+
  /** Actions with their own dedicated form open that; the rest confirm. */
  function handleAction(action: ResolvedAction) {
    switch (action.id) {
      case "schedule-inspection":
+        setRescheduling(false);
+        setInspectionDate("");
+        setInspectionTimeSlot("MORNING");
+        setRescheduleReason("");
        setInspectionOpen(true);
        return;
+      case "reschedule-inspection":
+        openReschedule();
+        return;
      case "schedule-issuance":
        setIssuanceOpen(true);
        return;
@@ -1246,21 +1273,48 @@ export function LicenseReviewPage() {
                            </Text>
                          )}
                        </div>
-                        <Badge
-                          variant="light"
-                          color={
-                            inspection.result === "FAILED" ? "red" : "teal"
-                          }
-                        >
-                          {inspection.result === "PASSED"
-                            ? t("review.passed", "Passed")
-                            : inspection.result === "FAILED"
-                              ? t("review.failed", "Failed")
-                              : t(
-                                  `review.inspectionStatus.${inspection.status}`,
-                                  inspection.status,
+                        <Group gap="xs">
+                          {inspection.status === "SCHEDULED" &&
+                            inspection.id === pendingInspection?.id &&
+                            can([
+                              "can:create:inspection",
+                              "can:update:inspection",
+                            ]) && (
+                              <Tooltip
+                                label={t(
+                                  "review.actions.rescheduleInspection",
+                                  "Reschedule inspection",
                                )}
-                        </Badge>
+                              >
+                                <ActionIcon
+                                  variant="subtle"
+                                  size="sm"
+                                  aria-label={t(
+                                    "review.actions.rescheduleInspection",
+                                    "Reschedule inspection",
+                                  )}
+                                  onClick={openReschedule}
+                                >
+                                  <IconPencil size={16} />
+                                </ActionIcon>
+                              </Tooltip>
+                            )}
+                          <Badge
+                            variant="light"
+                            color={
+                              inspection.result === "FAILED" ? "red" : "teal"
+                            }
+                          >
+                            {inspection.result === "PASSED"
+                              ? t("review.passed", "Passed")
+                              : inspection.result === "FAILED"
+                                ? t("review.failed", "Failed")
+                                : t(
+                                    `review.inspectionStatus.${inspection.status}`,
+                                    inspection.status,
+                                  )}
+                          </Badge>
+                        </Group>
                      </Group>
                    ))}
                  </Stack>
@@ -1430,7 +1484,11 @@ export function LicenseReviewPage() {
      <Modal
        opened={inspectionOpen}
        onClose={() => setInspectionOpen(false)}
-        title={t("review.actions.scheduleInspection", "Schedule inspection")}
+        title={
+          rescheduling
+            ? t("review.actions.rescheduleInspection", "Reschedule inspection")
+            : t("review.actions.scheduleInspection", "Schedule inspection")
+        }
      >
        <Stack>
          <AmharicDatePicker
@@ -1446,36 +1504,72 @@ export function LicenseReviewPage() {
              { value: "AFTERNOON", label: t("review.afternoon", "Afternoon") },
            ]}
          />
+          {rescheduling && (
+            <Textarea
+              label={t("review.rescheduleReason", "Why is it moving?")}
+              description={t(
+                "review.rescheduleReasonHint",
+                "Kept in the audit trail and sent to the applicant.",
+              )}
+              value={rescheduleReason}
+              onChange={(e) => setRescheduleReason(e.currentTarget.value)}
+              autosize
+              minRows={2}
+            />
+          )}
          <ModalFooter>
+            {/* Mantine strips pointer events from a disabled control, so the
+                tooltip wraps a span — same trick as DecisionBar's ActionButton;
+                a disabled button must still say why. */}
            <Tooltip
              label={t("review.pickDate", "Pick a date first")}
              disabled={Boolean(inspectionDate)}
            >
-              <span>
-                <button type="button" hidden aria-hidden />
-              </span>
-            </Tooltip>
+              <span style={{ display: "inline-flex" }}>
            <ActionIcon
              variant="filled"
              size="lg"
              disabled={!inspectionDate}
-              aria-label={t("review.schedule", "Schedule")}
+              aria-label={
+                rescheduling
+                  ? t("review.reschedule", "Reschedule")
+                  : t("review.schedule", "Schedule")
+              }
              onClick={() =>
                run(
                  async () => {
-                    await scheduleInspection({
-                      applicationId: id,
-                      scheduledDate: inspectionDate,
-                      timeSlot: inspectionTimeSlot,
-                    }).unwrap();
+                    if (rescheduling) {
+                      // Guarded by the action's own gate, which only offers
+                      // rescheduling while a booking exists.
+                      if (!pendingInspection) return;
+                      await rescheduleInspection({
+                        inspectionId: pendingInspection.id,
+                        applicationId: id,
+                        scheduledDate: inspectionDate,
+                        timeSlot: inspectionTimeSlot,
+                        ...(rescheduleReason.trim()
+                          ? { reason: rescheduleReason.trim() }
+                          : {}),
+                      }).unwrap();
+                    } else {
+                      await scheduleInspection({
+                        applicationId: id,
+                        scheduledDate: inspectionDate,
+                        timeSlot: inspectionTimeSlot,
+                      }).unwrap();
+                    }
                    setInspectionOpen(false);
                  },
-                  t("review.done.scheduled", "Inspection scheduled"),
+                  rescheduling
+                    ? t("review.done.rescheduled", "Inspection rescheduled")
+                    : t("review.done.scheduled", "Inspection scheduled"),
                )
              }
            >
              <IconCheck size={18} />
            </ActionIcon>
+              </span>
+            </Tooltip>
          </ModalFooter>
        </Stack>
      </Modal>
@@ -1492,34 +1586,36 @@ export function LicenseReviewPage() {
            onChange={setIssuanceDate}
          />
          <ModalFooter>
+            {/* Span-wrapped like DecisionBar's ActionButton — Mantine strips
+                pointer events from a disabled control, and a disabled button
+                must still say why. */}
            <Tooltip
-              label={t("review.pickDate", "Pick a date and time first")}
+              label={t("review.pickDate", "Pick a date first")}
              disabled={Boolean(issuanceDate)}
            >
-              <span>
-                <button type="button" hidden aria-hidden />
+              <span style={{ display: "inline-flex" }}>
+                <ActionIcon
+                  variant="filled"
+                  size="lg"
+                  disabled={!issuanceDate}
+                  aria-label={t("review.schedule", "Schedule")}
+                  onClick={() =>
+                    run(
+                      async () => {
+                        await scheduleIssuance({
+                          id,
+                          scheduledDate: issuanceDate,
+                        }).unwrap();
+                        setIssuanceOpen(false);
+                      },
+                      t("review.done.scheduleIssuance", "Pickup scheduled"),
+                    )
+                  }
+                >
+                  <IconCheck size={18} />
+                </ActionIcon>
              </span>
            </Tooltip>
-            <ActionIcon
-              variant="filled"
-              size="lg"
-              disabled={!issuanceDate}
-              aria-label={t("review.schedule", "Schedule")}
-              onClick={() =>
-                run(
-                  async () => {
-                    await scheduleIssuance({
-                      id,
-                      scheduledDate: issuanceDate,
-                    }).unwrap();
-                    setIssuanceOpen(false);
-                  },
-                  t("review.done.scheduleIssuance", "Pickup scheduled"),
-                )
-              }
-            >
-              <IconCheck size={18} />
-            </ActionIcon>
          </ModalFooter>
        </Stack>
      </Modal>
--- a/apps/backoffice/src/app/i18n/locales/am.ts
+++ b/apps/backoffice/src/app/i18n/locales/am.ts
@@ -986,6 +986,9 @@ export const am: Translations = {
    morning: "ጠዋት",
    afternoon: "ከሰዓት በኋላ",
    schedule: "ያዝ",
+    reschedule: "አዛውር",
+    rescheduleReason: "ለምን ይዛወራል?",
+    rescheduleReasonHint: "በኦዲት መዝገብ ውስጥ ተይዞ ለአመልካቹ ይላካል።",
    pickDate: "መጀመሪያ ቀን ይምረጡ",
    passed: "አልፏል",
    failed: "ወድቋል",
@@ -1022,6 +1025,7 @@ export const am: Translations = {
      completeReview: "ግምገማ አጠናቅቅ",
      approveDocuments: "ሰነዶችን አጽድቅ",
      scheduleInspection: "ምርመራ ያዝ",
+      rescheduleInspection: "ምርመራ አዛውር",
      recordInspection: "የምርመራ ውጤት መዝግብ",
      finalApprove: "አጽድቅ እና ስጥ",
      requestAdjustment: "ማስተካከያ ጠይቅ",
@@ -1175,6 +1179,7 @@ export const am: Translations = {
      assign: "እንደገና ተመድቧል",
      assignReviewer: "ግምገማ ተመድቧል",
      scheduled: "ምርመራ ተይዟል",
+      rescheduled: "ምርመራ ተዛውሯል",
      inspectionPassed: "ምርመራ አልፏል",
      inspectionFailed: "ምርመራ ወድቋል",
    },
--- a/apps/backoffice/src/app/i18n/locales/en.ts
+++ b/apps/backoffice/src/app/i18n/locales/en.ts
@@ -995,6 +995,9 @@ export const en = {
    morning: 'Morning',
    afternoon: 'Afternoon',
    schedule: 'Schedule',
+    reschedule: 'Reschedule',
+    rescheduleReason: 'Why is it moving?',
+    rescheduleReasonHint: 'Kept in the audit trail and sent to the applicant.',
    pickDate: 'Pick a date first',
    passed: 'Passed',
    failed: 'Failed',
@@ -1031,6 +1034,7 @@ export const en = {
      completeReview: 'Complete review',
      approveDocuments: 'Approve documents',
      scheduleInspection: 'Schedule inspection',
+      rescheduleInspection: 'Reschedule inspection',
      recordInspection: 'Record inspection result',
      finalApprove: 'Approve & issue',
      requestAdjustment: 'Request adjustment',
@@ -1181,6 +1185,7 @@ export const en = {
      assign: 'Reassigned',
      assignReviewer: 'Review assigned',
      scheduled: 'Inspection scheduled',
+      rescheduled: 'Inspection rescheduled',
      inspectionPassed: 'Inspection passed',
      inspectionFailed: 'Inspection failed',
    },
--- a/apps/backoffice/vite.config.mts
+++ b/apps/backoffice/vite.config.mts
@@ -42,14 +42,14 @@ export default defineConfig({
    emptyOutDir: true,
    reportCompressedSize: true,
  },
-  // Unit tests for the pure helpers behind a screen (formatters, URL state).
-  // Component tests are deliberately not set up: nothing here renders React,
-  // so no jsdom environment or setup file is needed.
-  // test: {
-  //   watch: false,
-  //   globals: true,
-  //   environment: 'node',
-  //   include: ['src/**/*.spec.ts'],
-  //   reporters: ['default'],
-  // },
+  // Unit tests for the pure helpers behind a screen (formatters, URL state,
+  // queue views). Component tests are deliberately not set up: nothing here
+  // renders React, so no jsdom environment or setup file is needed.
+  test: {
+    watch: false,
+    globals: true,
+    environment: 'node',
+    include: ['src/**/*.spec.ts', 'src/**/*.test.ts'],
+    reporters: ['default'],
+  },
 });
--- a/apps/portal/src/app/features/licensing/components/DocumentSlots.tsx
+++ b/apps/portal/src/app/features/licensing/components/DocumentSlots.tsx
@@ -37,6 +37,12 @@ interface Props {
  flagged?: Record<string, string>;
  /** When set, only flagged slots accept a new upload. */
  restrictToFlagged?: boolean;
+  /**
+   * Requirement keys opened because a flagged section drives their condition —
+   * a category correction can make documents newly required, and those have to
+   * be uploadable even though the officer flagged no document.
+   */
+  alsoUnlocked?: string[];
  onUploaded: () => void;
  readOnly?: boolean;
 }
@@ -55,6 +61,7 @@ export function DocumentSlots({
  ownerId,
  flagged = {},
  restrictToFlagged = false,
+  alsoUnlocked = [],
  onUploaded,
  readOnly,
 }: Props) {
@@ -106,7 +113,11 @@ export function DocumentSlots({
        const uploaded = Boolean(existing?.files?.length);
        const fileUrl = existing?.files?.[0]?.url;
        const flagRemark = flagged[requirement.key];
-        const locked = readOnly || (restrictToFlagged && !flagRemark);
+        const locked =
+          readOnly ||
+          (restrictToFlagged &&
+            !flagRemark &&
+            !alsoUnlocked.includes(requirement.key));

        return (
          <Card
--- a/apps/portal/src/app/features/licensing/pages/LicenseApplicationPage.tsx
+++ b/apps/portal/src/app/features/licensing/pages/LicenseApplicationPage.tsx
@@ -32,6 +32,8 @@ import { useTranslation } from "react-i18next";
 import {
  buildWizardSteps,
  conditionHolds,
+  conditionSections,
+  sectionsDependingOn,
  extractErrorMessage,
  extractValidationIssues,
  useLocalized,
@@ -361,8 +363,34 @@ export function LicenseApplicationPage() {
  // filed.
  const roundIsItemised = isAdjusting && roundRemarks.length > 0;

+  // An answer the officer flagged can decide which fields *other* sections
+  // require — the vessel category is the live example. Freeze those and the
+  // applicant is shown newly-required fields they cannot fill, and cannot
+  // resubmit; the server unlocks them the same way.
+  const cascadeUnlocked = useMemo(
+    () =>
+      sectionsDependingOn(
+        config?.licenseType?.formSchema?.sections ?? [],
+        new Set(Object.keys(flaggedSections)),
+      ),
+    [config, flaggedSections],
+  );
+  const unlockedDocuments = useMemo(
+    () =>
+      (config?.documentRequirements ?? [])
+        .filter((requirement) =>
+          conditionSections(requirement.conditionExpression).some(
+            (sectionKey) => sectionKey in flaggedSections,
+          ),
+        )
+        .map((requirement) => requirement.key),
+    [config, flaggedSections],
+  );
+
  const isSectionLocked = (sectionKey: string) =>
-    roundIsItemised && !flaggedSections[sectionKey];
+    roundIsItemised &&
+    !flaggedSections[sectionKey] &&
+    !cascadeUnlocked.has(sectionKey);
  const staffLocked = roundIsItemised && !hasStaffRemarks;

  // Sections that share a group collapse onto one step, so the stepper stays
@@ -942,6 +970,7 @@ export function LicenseApplicationPage() {
              ownerId={appId}
              flagged={flaggedDocuments}
              restrictToFlagged={roundIsItemised}
+              alsoUnlocked={unlockedDocuments}
              readOnly={readOnly}
              onUploaded={() => {
                refetchAttachments();
--- a/libs/api/src/lib/features/licensing/licensing-api.ts
+++ b/libs/api/src/lib/features/licensing/licensing-api.ts
@@ -1015,6 +1015,30 @@ export const licensingApi = baseApi
          error ? [] : [itemTag('LicenseApplication', applicationId), listTag('Inspection')],
      }),

+      /** Moves a booked visit: another day, slot, inspector or place. */
+      rescheduleInspection: builder.mutation<
+        Inspection,
+        {
+          inspectionId: string;
+          applicationId: string;
+          scheduledDate: string;
+          timeSlot: 'MORNING' | 'AFTERNOON';
+          inspectorId?: string;
+          location?: string;
+          reason?: string;
+        }
+      >({
+        query: ({ inspectionId, scheduledDate, timeSlot, inspectorId, location, reason }) => ({
+          url: `/inspections/${inspectionId}/schedule`,
+          method: 'PATCH',
+          // applicationId is for cache invalidation only; the visit knows its
+          // own application.
+          body: { scheduledDate, timeSlot, inspectorId, location, reason },
+        }),
+        invalidatesTags: (_r, error, { applicationId }) =>
+          error ? [] : [itemTag('LicenseApplication', applicationId), listTag('Inspection')],
+      }),
+
      getInspections: builder.query<Inspection[], string>({
        query: (applicationId) => ({ url: `/inspections/application/${applicationId}` }),
        providesTags: () => [listTag('Inspection')],
@@ -1152,6 +1176,7 @@ export const {
  useScheduleIssuanceMutation,
  useIssueCertificateMutation,
  useScheduleInspectionMutation,
+  useRescheduleInspectionMutation,
  useGetInspectionsQuery,
  useRecordInspectionResultMutation,
  useGetNotificationsQuery,
--- a/libs/api/src/lib/features/licensing/licensing.helpers.ts
+++ b/libs/api/src/lib/features/licensing/licensing.helpers.ts
@@ -595,6 +595,49 @@ interface ConditionLike {
  anyOf?: ConditionLike[];
 }

+/**
+ * Section keys a condition reads, recursing `anyOf`.
+ *
+ * `FieldCondition.field` is a `sectionKey.fieldKey` path, so the prefix names
+ * the section whose answer decides the condition.
+ */
+export function conditionSections(
+  condition: FieldCondition | undefined | null,
+): string[] {
+  if (!condition) return [];
+  if (condition.anyOf) return condition.anyOf.flatMap(conditionSections);
+  if (!condition.field) return [];
+  const [sectionKey] = condition.field.split('.');
+  return sectionKey ? [sectionKey] : [];
+}
+
+/**
+ * Sections whose visibility hangs on an answer in one of `flagged`.
+ *
+ * Mirrors the server's `sectionsDependingOn`: an officer flagging the section
+ * that holds the vessel category is asking for an answer that decides which
+ * fields in other sections are required, so those sections have to open too —
+ * otherwise the applicant sees newly-required fields they cannot edit and
+ * cannot resubmit.
+ */
+export function sectionsDependingOn(
+  sections: FormSectionConfig[],
+  flagged: Set<string>,
+): Set<string> {
+  const dependent = new Set<string>();
+  if (flagged.size === 0) return dependent;
+
+  for (const section of sections) {
+    if (flagged.has(section.key)) continue;
+    const reads = [
+      section.showWhen,
+      ...(section.fields ?? []).map((field) => field.showWhen),
+    ].flatMap(conditionSections);
+    if (reads.some((key) => flagged.has(key))) dependent.add(section.key);
+  }
+  return dependent;
+}
+
 export function conditionHolds(
  condition: FieldCondition | undefined | null,
  formData: Record<string, Record<string, unknown>>,