/**
 * @swagger
 * /vehicle/driver-register:
 *   post:
 *     summary: Register a vehicle and driver
 *     description: API to signup a new driver with mandatory details.
 *     tags:
 *       - Vehicle
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - name
 *               - phone_number
 *               - country_code
 *               - vehicle_plate_number
 *               - vehicle_registration_number
 *               - resident_id
 *               - passport_number
 *             properties:
 *               name:
 *                 type: string
 *                 description: Full name of the resident
 *                 example: "John Doe"
 *               phone_number:
 *                 type: string
 *                 description: Phone number of the resident
 *                 example: "9876543210"
 *               country_code:
 *                 type: string
 *                 description: ISO country dialing code
 *                 example: "+91"
 *               vehicle_plate_number:
 *                 type: string
 *                 description: Vehicle license plate number
 *                 example: "TN01AB1234"
 *               vehicle_registration_number:
 *                 type: string
 *                 description: Vehicle registration number
 *                 example: "REG123456"
 *               resident_id:
 *                 type: string
 *                 description: Unique driver identifier
 *                 example: "RES-1001"
 *               passport_number:
 *                 type: string
 *                 description: Passport number of the driver
 *                 example: "M1234567"
 *     responses:
 *       201:
 *         description: driver created successfully
 *       400:
 *         description: Invalid input data
 */

/**
 * @swagger
 * /vehicle/vehicle-gps-data:
 *   post:
 *     summary: Vehicle gps data logs
 *     description: Logs on vehicle gps API
 *     tags:
 *       - Vehicle
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: array
 *             items:
 *               type: object
 *               required:
 *                  - latitude
 *                  - longitude
 *                  - timestamp
 *                  - vehicle_id
 *                  - driver_id
 *               properties:
 *                  latitude:
 *                      type: string
 *                      description: Latitude of current vehicle location
 *                      example: "24.7136"
 *                  longitude:
 *                      type: string
 *                      description: Longitude of current vehicle location
 *                      example: "46.6753"
 *                  timestamp:
 *                      type: string
 *                      format: date-time
 *                      description: Logged timestamp (ISO 8601)
 *                      example: "2025-09-01T00:00:00.000Z"
 *                  unique_gps_data_id:
 *                      type: string
 *                      description: Unique reference for logs
 *                      example: "U0001"
 *                  vehicle_id:
 *                      type: number
 *                      description: Vehicle id
 *                      example: 1
 *                  driver_id:
 *                      type: number
 *                      description: Driver id
 *                      example: 1
 *                  trip_type:
 *                      type: string
 *                      description: Type of trip
 *                      example: "delivery"
 *                  shipment_location_uid:
 *                      type: string
 *                      description: Shipment location unique identifier
 *                      example: "64ce76ab-ad61-4131-91e8-445c1237b567"
 *                  shipment_id:
 *                      type: number
 *                      description: Shipment id
 *                      example: 123
 *     security:
 *       - AccessToken: []
 *       - Language: []
 *     responses:
 *       201:
 *         description: GPS data synced successfully
 *       400:
 *         description: Invalid input data
 */

/**
 * @swagger
 * /vehicle/test-send-otp:
 *   post:
 *     summary: Send OTP for testing
 *     description: Sends OTP to a mobile number with custom SMS content and stores request/response in database
 *     tags:
 *       - Vehicle
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - mobile_number
 *               - sms_content
 *             properties:
 *               mobile_number:
 *                 type: string
 *                 minLength: 5
 *                 description: Mobile number to send OTP to
 *                 example: "1234567890"
 *               sms_content:
 *                 type: string
 *                 minLength: 1
 *                 description: Custom SMS content that will be appended with OTP
 *                 example: "Your SMS content"
 *     security:
 *       - AccessToken: []
 *       - Language: []
 *     responses:
 *       200:
 *         description: OTP sent successfully
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 code:
 *                   type: integer
 *                   example: 200
 *                 status:
 *                   type: boolean
 *                   example: true
 *                 message:
 *                   type: string
 *                   example: "OTP sent successfully"
 *                 data:
 *                   type: object
 *                   properties:
 *                     otp:
 *                       type: string
 *                       example: "123456"
 *       400:
 *         description: Invalid input data or SMS sending failed
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 code:
 *                   type: integer
 *                   example: 400
 *                 status:
 *                   type: boolean
 *                   example: false
 *                 message:
 *                   type: string
 *                   example: "Failed to send OTP"
 *                 error:
 *                   type: string
 *                   example: "SMS provider error"
 *                 data:
 *                   type: object
 *                   properties:
 *                     otp_generated:
 *                       type: string
 *                       example: "123456"
 *       500:
 *         description: Internal server error
 */

/**
 * @openapi
 * /vehicle/get-pod-otp:
 *   post:
 *     tags:
 *       - Vehicle
 *     summary: Get OTP for POD completion.
 *     requestBody:
 *       required: true
 *       content:
 *         'application/json':
 *           schema:
 *             type: object
 *             required:
 *               - shipment_location_uid
 *             properties:
 *               shipment_location_uid:
 *                 type: string
 *                 description: Unique reference for shipment location
 *                 example: "48849fef-5e42-4d0e-a9fe-2ef3a82d3d80"
 *     security:
 *       - AccessToken: []
 *       - Language: []
 *     responses:
 *       200:
 *         description: OTP sent successfully
 *       400:
 *         description: Invalid input data
 */

/**
 * @openapi
 * /vehicle/verify-pod-otp:
 *   post:
 *     tags:
 *       - Vehicle
 *     summary: Verify OTP for POD completion.
 *     requestBody:
 *       required: true
 *       content:
 *         'application/json':
 *           schema:
 *             type: object
 *             required:
 *               - otp
 *               - shipment_location_uid
 *             properties:
 *               otp:
 *                 type: string
 *                 example: "123456"
 *               shipment_location_uid:
 *                 type: string
 *                 description: Unique reference for shipment location
 *                 example: "48849fef-5e42-4d0e-a9fe-2ef3a82d3d80"
 *     security:
 *       - AccessToken: []
 *       - Language: []
 *     responses:
 *       200:
 *         description: OTP verified successfully
 *       400:
 *         description: Invalid input data
 */