DEV Community

Gavin gui
Gavin gui

Posted on AI-assisted

Designing a Cross-Border Airport Transfer Checklist as Structured Data

#tutorial

Travel logistics look simple until one missing field breaks the plan. A destination such as β€œShenzhen” is not enough for a driver, dispatcher, or booking form. The useful design problem is to turn a human request into structured data that can be validated before a vehicle is assigned.

This post uses a Hong Kong Airport to Shenzhen or Dongguan transfer as a practical example. CrossBorderHK operates the referenced service; this is an engineering-oriented adaptation, not a neutral price comparison. I used AI assistance for outlining and copy editing, and the operator must verify current operational details before publishing or using the data.

1. Model the request before calculating a quote

A minimum request should capture:

  • flight date and number
  • airport pickup location
  • exact destination address
  • city district or Dongguan township
  • passengers and children
  • luggage dimensions and unusual items
  • extra stops
  • return or waiting requirements
  • accessibility and child-seat needs

A small JSON object is easier to validate than a paragraph copied from a chat message:

{
  "arrival": { "date": "2026-10-18", "flight": "CX000", "airport": "HKG" },
  "destination": { "city": "Shenzhen", "district": "Nanshan", "address": "Hotel name and entrance" },
  "passengers": 4,
  "children": 1,
  "luggage": [{ "count": 4, "size": "24in" }],
  "stops": [],
  "needs": ["child-seat"]
}
Enter fullscreen mode Exit fullscreen mode

For Dongguan, replace district with township and include the industrial park or factory gate. This prevents a city-level quote from hiding the last-mile problem.

2. Validate fields at the edge

Validation should happen before dispatch. A lightweight TypeScript example:

type TransferRequest = {
  arrival: { date: string; flight: string; airport: "HKG" };
  destination: { city: "Shenzhen" | "Dongguan"; district?: string; township?: string; address: string };
  passengers: number;
  children: number;
  luggage: { count: number; size?: string }[];
  stops: string[];
};

function validate(r: TransferRequest) {
  if (!r.arrival.flight || !r.destination.address) throw new Error("Flight and exact address are required");
  if (r.destination.city === "Shenzhen" && !r.destination.district) throw new Error("Add the Shenzhen district");
  if (r.destination.city === "Dongguan" && !r.destination.township) throw new Error("Add the Dongguan township");
  if (r.passengers < 1 || r.passengers > 6) throw new Error("Check vehicle passenger capacity");
}
Enter fullscreen mode Exit fullscreen mode

The six-passenger limit reflects the normal Alphard arrangement described by the operator: seven seats including the driver. Keep this rule in configuration so the UI and dispatch service share one source of truth.

3. Keep price and route assumptions explicit

A quote object should separate a published reference value from a confirmed booking:

{
  "currency": "RMB",
  "referenceFare": 800,
  "destinationScope": "listed Shenzhen districts",
  "includes": ["driver", "fuel", "standard tolls"],
  "requiresConfirmation": ["waiting", "night surcharge", "extra stops", "border procedure"],
  "status": "reference"
}
Enter fullscreen mode Exit fullscreen mode

The published Hong Kong Airport to Shenzhen reference starts at RMB 800 / HKD 930. The listed Hong Kong to Dongguan route starts at RMB 1,200 / HKD 1,400 for some townships. Treat both as starting references. The final address, date, vehicle, waiting, and route conditions still need written confirmation.

Avoid representing border behavior as a deterministic API response. Passenger and luggage procedures can depend on permits, checkpoint, documents, lane, and on-site officer instructions. Store the planned procedure together with a visible uncertainty note.

4. Generate a human-readable enquiry

The last step is a message a traveler can review:

Please quote a private transfer from HKG to [district/township and exact address]. Flight: [number/date]. Passengers: [count, children]. Luggage: [count and dimensions]. Stops: [list]. Please confirm total fare and currency, inclusions, waiting and overtime rules, cancellation terms, and planned border procedure.

This exposes assumptions before payment and gives a dispatcher enough context to correct the data instead of guessing.

5. Test failure paths

A useful test matrix includes:

  1. Flight delay after the included waiting period.
  2. Six passengers with oversized luggage.
  3. A Dongguan request with two factory stops.
  4. A midnight arrival requiring a different crossing plan.
  5. An address change after booking.
  6. A checkpoint instruction that requires passengers to leave the vehicle.

The test should verify that the interface asks for clarification, preserves the original request, and never silently converts a reference fare or estimated time into a guarantee.

Structured data does not remove uncertainty from cross-border travel. It makes the uncertainty visible early enough for a traveler, dispatcher, and driver to act on it.

References

Top comments (0)