Skip to Content
Ranlanka CRM documentation — pre-release, subject to change.
FeaturesBookings & Operations

Bookings & Operations

Visa pipeline

Visa requests move through a defined state machine: new inquiry → pending documents → embassy processing → approved/rejected → passport collected. Requests capture entry type (single/multiple entry, transit) sourced from a shared lookup table.

Daily Approved Visas & Passport Handover Manifest (A4 Printable)

When a visa application is approved by the consulate/embassy:

  • Approval Timestamp (approved_at): The backend records the exact timestamp of approval (approved_at = now()) when transitioning status to approved.
  • Dynamic Visa Short Codes: Generates compact standardized codes dynamically from reference data (e.g. IND-B-3M-M-S, UK-S-1Y-M-S, UAE-T-1M-S-E) capturing Country, Type, Validity, Entry Type, and Sticker/eVisa format.
  • Physical Register Page Identification (2026OCT18PG1):
    • Sequential page codes (<yyyy><MMM><dd>PG<pageNumber>, e.g. 2026OCT18PG1, 2026OCT18PG2) computed dynamically in-memory based on approval date in Asia/Colombo time (8 rows per page matching physical register sheets).
    • Manifest Top Header: Prominently displayed in the top-right header box of each printed sheet (Register Page Code: 2026OCT18PG1).
    • Manifest Bottom Footer: Displayed subtly as a greyed-out code badge (footer-code-badge) inside the bottom Custody Notice card and as a muted watermark line (Register Page: 2026OCT18PG1) at the bottom of the page.
    • Clean Table Layout: Removed the redundant per-row Signing Page column in favor of 8 balanced columns (#, Customer Name, Traveler Name, Visa Code, Visa / Sticker No., Handover Date, Staff Name, Customer Signature).
    • Task Detail Drawer Integration: Displays a monospace blue badge Signing Page: 2026OCT18PG1 in the drawer header and a dedicated register card in VisaDetailPanel, allowing front-desk staff to instantly pull the corresponding paper signature sheet from the physical book.
    • Visa Only: Computed strictly for Visa requests; zero inclusion in flight responses or database schemas.
  • Automated Daily Email (20:00 Asia/Colombo): Fires every evening at 8:00 PM Sri Lanka time to dispatch an HTML summary and attached A4 PDF (Approved_Visas_Handover_Manifest_YYYY-MM-DD.pdf) to agency managers and owners.
  • On-Demand API (GET /api/v1/visas/daily-approved/pdf): Allows generating and streaming the A4 printable manifest for today or any past calendar date on-demand.

Rejected Visa Operational Lifecycle

When an embassy or consulate refuses a visa application:

  • Status Transition: The application moves to rejected status.
  • Client Decision Notification: Staff can send an official rejection notification email directly to the customer containing the embassy remarks, assigned consultant contact details, and passport collection instructions.
  • Passport Return Finalization: Staff click “Return Passport”, which transitions the status to passport_collected, flags is_visa_request_rejected = true, and records the completion timestamp (completed_at). Approval emails remain suppressed.
  • Visual Red Dot Indicator: On the Task Tracker, Admin Table, and Client Dossier, rejected applications whose passport has been collected display a distinct red dot indicator (bg-red-600 ring-2 ring-red-200) and red status badges instead of the green checkmark icon.
  • Dossier & Active Services Visibility: In the customer’s Active Services panel, rejected applications are clearly badged in red as REJECTED alongside PASSPORT RETURNED. They are strictly omitted from active held visas in the Passport Vault.

Flight bookings

Flight requests are created and tracked against a customer, moving through their own status lifecycle including issued tickets.

Ticket cancellation & reschedule

  • Cancellation — staff can cancel an issued ticket with a manual cancellation fee, refund amount, and reason (a judgment call per booking, not a rules engine); the cancelled state is shown inline on the case.
  • Reschedule — staff can change a ticketed booking’s flight date, with a reason field. The full change history (previous date, new date, who, when) is kept server-side.

Outdated Ticket Departure Warning Indicator

To prevent departing flights with pending payments or unissued tickets from falling through the cracks:

  • Database Query-Level Check: FlightRequestRepository evaluates departure expiration directly in the JPQL projection (f.flightDate < :now AND f.status NOT IN ('CANCELLED', 'TICKETED') AND f.isFinalised = false), populating isTicketOutdated and ticketDaysOutdated.
  • Suppression Criteria: The icon is suppressed only when the ticket is issued AND all payments are completely settled (isFinalised == true or ticketNumber != null && invoiceStatus == 'paid'). If payments remain unpaid, partial, or un-invoiced after the flight departure date, the warning icon remains active.
  • Task Tracker Indicator: Displayed as a compact circular amber Info (i) icon (w-5 h-5) with a rich tooltip showing scheduled flight date and overdue days in <TaskListView />, <AdminTaskTable />, and an alert banner in <FlightDetailPanel />.

Task tracker & Document Management

  • Admins see an aggregated, filterable table of every ongoing case across the agency.
  • Consultants see a Kanban board of their own assigned cases.
  • Finalized Status Indicators & Decoupled Operational Completion:
    • Operational completion (completed_at = now()) occurs when a visa or flight reaches fulfillment (e.g. visa issued or moved to passport_collected; flight ticketed).
    • A case is only marked finalized (is_finalised = true with a green checkmark) when all operational steps are fulfilled, passport handover has occurred, AND all associated invoices (direct and group-linked) are fully settled (PAID).
    • Non-Blocking Transitions: Moving a visa to passport_collected (or a flight to TICKETED) is non-blocking regardless of invoice status. If invoices remain unpaid or partial, the status updates successfully, recording completed_at while keeping is_finalised = false. Staff receive an informational toast noting that the case remains unfinalized until all invoices are paid.
    • Approved Visas: Display a green checkmark circle (CheckCircle2) and FINALIZED badge when visa number is issued, passport collection is finalized (is_finalised = true), and all linked invoices are fully paid (PAID).
    • Rejected Visas: Display a solid red dot indicator and Passport Returned (Rejected) badge when is_visa_request_rejected is true, passport return is finalized (is_finalised = true), and all associated invoices are fully settled.
    • Flights: Ticket number is issued (ticketNumber is present), the booking is not cancelled, and all linked invoices are fully settled (is_finalised = true).
    • If an invoice is created or modified with an outstanding balance, the finalized status is automatically revoked until payment receipt is recorded.
  • Task Detail Drawer:
    • Anti-Flicker Drawer Loader: Opens with a unified loading state powered by concurrent fetches (Promise.allSettled), avoiding UI jumps between “Issue Invoice” and “View Invoice”.
      • Traveler Fidelity & Account Holder Hierarchy: When a ticket or visa is booked for a family member or dependent under an account holder, the drawer prominently displays the traveler’s name as the primary header with a relationship subtitle and direct dossier link to the primary account holder. Flight and Visa panels render dedicated Passenger & Traveler Information sections containing the traveler’s passport number, expiry date, nationality, date of birth, and relationship.
    • Full-Drawer Finalization Overlay: When passport collection is finalized (for both approved and rejected applications), a full-coverage loading overlay (absolute inset-0 z-50 bg-background-cream/85) covers the entire drawer. All buttons receive disabled={isFinalizing} and isLoading={isFinalizing}, cancel/delete actions are locked, and the modal backdrop is guarded against accidental dismissal until server persistence and Redux state synchronization complete.
    • Contextual Document Checklist & Downloadable Templates: Displays both required checklist items and matched downloadable templates/forms from Staff Utilities (e.g. embassy visa forms, NOC templates, flight vouchers) with direct downloads formatted as customer_name_visatype_doc_type_doc_name.ext.
  • Query Optimization & Embedded DTO Architecture:
    • VisaResponseDTO and FlightResponseDTO embed customerName (via a database LEFT JOIN CustomerEntity c) and invoiceStatus (via targeted queries in InvoiceRepository).
    • The Task Tracker board relies entirely on these embedded attributes, eliminating both the previous full invoice table scan (getAllInvoices) and the customer search query (search?query=), saving over 2.7s on board load.
  • Service Issuance & Update Workflows:
    • Unblocked Visa Details Management: Staff can save or update issued visa details and upload visa PDFs freely even when invoices are partially paid. The issue form intelligently adapts its primary action to “Save & Issue Visa” (or “Save & Update Visa”) when invoices are pending, reserving “Issue Visa & Finalize (Passport Collected)” exclusively for cases that are fully settled (PAID).
    • Explicit Finalization Gate: In the passport_collected stage, the explicit “Finalize (Passport Collected)” button remains disabled with an explanatory tooltip until all invoices are fully paid.
    • Issue / Update Visa Flow: Staff enter visa numbers and dates while directly attaching finalized Visa PDF(s). Before any network upload, all required fields are validated. Existing uploaded documents are listed with file sizes, instant download (powered by triggerSafeDownload with automatic presigned URL refresh if links expire, accompanied by real-time toasts), and Delete actions backed by styled React ConfirmModal dialogs.
    • Issue / Update Ticket Flow: Staff enter ticket numbers and prices while attaching e-ticket PDFs. Existing documents are displayed directly in the drawer with resilient download and delete controls.
    • Permanent Purge on Request Deletion: Deleting a flight or visa request permanently purges all attached documents from Cloudflare R2 and deletes rows from PostgreSQL.
    • All files uploaded via the drawer automatically link to the customer dossier and receive structured R2 keys.

Dashboard

The app serves a role-specific dashboard automatically on login — a high-level admin view for owners, an operational view for consultants. Core dashboard data is fetched once at login (not refetched on every tab switch), with a manual “Refresh” button on each consuming page.

Reference data

  • Lookup values — a single generic table backs job titles, departments, branches, commission tiers, employment types, and visa entry types.
  • Sequential codes — a row-locked counter table generates human-readable, prefix-based codes for employee IDs and quotation numbers.

Overdue Passport Custody Tracking (> 7 Days)

To enforce the 7-day complimentary passport collection grace period (PRIVACY_POLICY.md §4.2), the system tracks uncollected passports across both approved and rejected visa requests (i.e., cases where a decision has been reached and the physical passport is ready for handover, but the status has not yet moved to passport_collected):

  • Single-Query JPQL Indicator (Zero $N+1$ Queries): VisaRequestRepository computes a CASE WHEN ... THEN true ELSE false END boolean projection directly inside findAllFilteredWithIssuedVisa, findTrackerVisasWithIssuedVisa, and findByCustomerIdWithIssuedVisa using :overdueCutoff = OffsetDateTime.now().minusDays(7) against COALESCE(v.approvedAt, v.createdAt) for statuses 'approved' and 'rejected'.
  • PostgreSQL Native Enum Compatibility: Native SQL queries against visa_requests.status compare CAST(v.status AS text) against string literals ('approved', 'rejected') rather than Hibernate’s default ::VisaStatus cast, avoiding PostgreSQL search_path / case-sensitive visastatus type resolution errors in production and scheduled jobs (UncollectedPassportReminderJob).
  • Compact Info (i) Warning Icon in Task Tracker: In <TaskListView /> (both single rows and group parent/child rows) and <AdminTaskTable />, overdue cases display a compact circular amber Info (i) icon (w-5 h-5). Hovering over the icon reveals a dark tooltip detailing the exact number of days held in custody, days past the 7-day grace period, and the applicable LKR 500/week (LKR 100/day) vault holding fee policy.
  • Visa Detail Drawer Banner: Opening an overdue visa in <VisaDetailPanel /> renders an amber Overdue Passport Custody alert banner at the top of the drawer advising staff to notify the customer and apply any applicable vault holding fee before marking the passport collected.
Last updated on