/**
 * @swagger
 * /api/v1/appointments:
 *   post:
 *     summary: 创建预约
 *     description: 创建新的预约订单
 *     tags: [Appointments]
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - serviceId
 *               - realName
 *               - contactMethod
 *               - contactValue
 *             properties:
 *               serviceId:
 *                 type: string
 *                 format: uuid
 *                 description: 服务ID
 *               realName:
 *                 type: string
 *                 description: 真实姓名
 *                 example: "张三"
 *               contactMethod:
 *                 type: string
 *                 enum: [phone, whatsapp, wechat]
 *                 description: 联系方式类型
 *                 example: "phone"
 *               contactValue:
 *                 type: string
 *                 description: 联系方式值
 *                 example: "+86 13800138000"
 *               appointmentDate:
 *                 type: string
 *                 format: date
 *                 description: 预约日期
 *                 example: "2023-12-15"
 *               appointmentTime:
 *                 type: string
 *                 description: 预约时间
 *                 example: "14:30"
 *               notes:
 *                 type: string
 *                 description: 备注
 *                 example: "请准时到达"
 *               amount:
 *                 type: number
 *                 format: decimal
 *                 description: 金额
 *                 example: 299.00
 *     responses:
 *       201:
 *         description: 创建成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 data:
 *                   $ref: '#/components/schemas/Appointment'
 *       400:
 *         description: 请求参数错误
 *       401:
 *         description: 未授权
 *
 *   get:
 *     summary: 获取预约列表
 *     description: 获取当前用户的预约列表，支持分页和状态筛选
 *     tags: [Appointments]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           minimum: 1
 *           default: 1
 *         description: 页码
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           minimum: 1
 *           maximum: 100
 *           default: 10
 *         description: 每页数量
 *       - in: query
 *         name: status
 *         schema:
 *           type: string
 *           enum: [pending, confirmed, in-progress, completed, cancelled]
 *         description: 状态筛选
 *     responses:
 *       200:
 *         description: 获取成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 data:
 *                   type: object
 *                   properties:
 *                     appointments:
 *                       type: array
 *                       items:
 *                         $ref: '#/components/schemas/Appointment'
 *                     pagination:
 *                       $ref: '#/components/schemas/PaginationMeta'
 *       401:
 *         description: 未授权
 *
 * /api/v1/appointments/{id}:
 *   get:
 *     summary: 获取预约详情
 *     description: 根据ID获取预约详细信息
 *     tags: [Appointments]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *           format: uuid
 *         description: 预约ID
 *     responses:
 *       200:
 *         description: 获取成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 data:
 *                   $ref: '#/components/schemas/Appointment'
 *       401:
 *         description: 未授权
 *       404:
 *         description: 预约不存在
 *
 *   put:
 *     summary: 更新预约
 *     description: 更新预约信息
 *     tags: [Appointments]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *           format: uuid
 *         description: 预约ID
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               realName:
 *                 type: string
 *                 example: "张三"
 *               contactMethod:
 *                 type: string
 *                 enum: [phone, whatsapp, wechat]
 *               contactValue:
 *                 type: string
 *               appointmentDate:
 *                 type: string
 *                 format: date
 *               appointmentTime:
 *                 type: string
 *               notes:
 *                 type: string
 *               status:
 *                 type: string
 *                 enum: [pending, confirmed, in-progress, completed, cancelled]
 *     responses:
 *       200:
 *         description: 更新成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 data:
 *                   $ref: '#/components/schemas/Appointment'
 *       400:
 *         description: 请求参数错误
 *       401:
 *         description: 未授权
 *       404:
 *         description: 预约不存在
 *
 *   delete:
 *     summary: 取消预约
 *     description: 取消预约订单
 *     tags: [Appointments]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *           format: uuid
 *         description: 预约ID
 *     responses:
 *       200:
 *         description: 取消成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 message:
 *                   type: string
 *                   example: "Appointment cancelled successfully"
 *       401:
 *         description: 未授权
 *       404:
 *         description: 预约不存在
 */
