/**
 * @swagger
 * tags:
 *   name: Authentication
 *   description: 用户认证API
 */
/**
 * @swagger
 * components:
 *   schemas:
 *     LoginCredentials:
 *       type: object
 *       required:
 *         - username
 *         - password
 *       properties:
 *         username:
 *           type: string
 *           description: 用户名或手机号
 *         password:
 *           type: string
 *           description: 密码
 *     RegisterRequest:
 *       type: object
 *       required:
 *         - username
 *         - phone
 *         - password
 *         - registrationCode
 *         - city
 *         - district_id
 *         - captchaId
 *         - captchaText
 *         - smsCode
 *       properties:
 *         username:
 *           type: string
 *           description: 用户名
 *         phone:
 *           type: string
 *           description: 手机号
 *         password:
 *           type: string
 *           description: 密码
 *         registrationCode:
 *           type: string
 *           description: 注册激活码
 *         city:
 *           type: string
 *           description: 城市
 *         district_id:
 *           type: string
 *           description: 区域ID
 *         captchaId:
 *           type: string
 *           description: 图形验证码ID
 *         captchaText:
 *           type: string
 *           description: 图形验证码文本
 *         smsCode:
 *           type: string
 *           description: 短信验证码
 *         role:
 *           type: string
 *           description: 用户角色
 *           default: user
 */
/**
 * @swagger
 * /auth/register:
 *   post:
 *     summary: 用户注册
 *     description: 需要提供有效的激活码才能注册
 *     tags: [Authentication]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/RegisterRequest'
 *     responses:
 *       201:
 *         description: 用户注册成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 message:
 *                   type: string
 *                 token:
 *                   type: string
 *                   description: JWT认证令牌
 *                 user:
 *                   type: object
 *                   properties:
 *                     id:
 *                       type: integer
 *                     username:
 *                       type: string
 *                     role:
 *                       type: string
 *       400:
 *         description: 请求参数错误
 *       500:
 *         description: 服务器错误
 */

/**
 * @swagger
 * /auth/login:
 *   post:
 *     summary: 用户登录
 *     tags: [Authentication]
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/LoginCredentials'
 *     responses:
 *       200:
 *         description: 登录成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 message:
 *                   type: string
 *                 token:
 *                   type: string
 *                   description: JWT认证令牌
 *                 user:
 *                   type: object
 *                   properties:
 *                     id:
 *                       type: integer
 *                     username:
 *                       type: string
 *                     role:
 *                       type: string
 *                     avatar:
 *                       type: string
 *                     points:
 *                       type: integer
 *       400:
 *         description: 请求参数错误
 *       401:
 *         description: 用户名或密码错误
 *       403:
 *         description: 账户审核未通过
 *       500:
 *         description: 服务器错误
 */
/**
 * @swagger
 * /api/users/{id}/distribute:
 *   put:
 *     summary: 设置用户分发状态
 *     description: 更新指定用户的分发状态
 *     tags: [Users]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: 用户ID
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - is_distribute
 *             properties:
 *               is_distribute:
 *                 type: boolean
 *                 description: 分发状态，true为启用分发，false为禁用分发
 *                 example: true
 *     responses:
 *       200:
 *         description: 分发状态更新成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 message:
 *                   type: string
 *                   example: "分发状态更新成功"
 *                 is_distribute:
 *                   type: boolean
 *                   description: 更新后的分发状态
 *                   example: true
 *       400:
 *         description: 请求参数错误
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: false
 *                 message:
 *                   type: string
 *                   example: "分发状态无效"
 *       404:
 *         description: 用户不存在
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: false
 *                 message:
 *                   type: string
 *                   example: "用户不存在"
 *       500:
 *         description: 服务器内部错误
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: false
 *                 message:
 *                   type: string
 *                   example: "服务器内部错误"
 */
/**
 * @swagger
 * components:
 *   schemas:
 *     User:
 *       type: object
 *       required:
 *         - username
 *         - password
 *         - real_name
 *         - id_card
 *       properties:
 *         id:
 *           type: integer
 *           description: 用户ID
 *         username:
 *           type: string
 *           description: 用户名
 *         role:
 *           type: string
 *           description: 用户角色
 *           enum: [user, admin, merchant]
 *         avatar:
 *           type: string
 *           description: 用户头像URL
 *         points:
 *           type: integer
 *           description: 用户积分
 *         real_name:
 *           type: string
 *           description: 真实姓名
 *         id_card:
 *           type: string
 *           description: 身份证号
 *         phone:
 *           type: string
 *           description: 手机号
 *         is_system_account:
 *           type: boolean
 *           description: 是否为系统账户
 *         is_distribute:
 *           type: boolean
 *           description: 是否为分发账户
 *         created_at:
 *           type: string
 *           format: date-time
 *           description: 创建时间
 *         updated_at:
 *           type: string
 *           format: date-time
 *           description: 更新时间
 */

/**
 * @swagger
 * /users:
 *   post:
 *     summary: 创建用户（管理员权限）
 *     tags: [Users]
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - username
 *               - password
 *               - real_name
 *               - id_card
 *             properties:
 *               username:
 *                 type: string
 *               password:
 *                 type: string
 *               role:
 *                 type: string
 *                 enum: [user, admin, merchant]
 *                 default: user
 *               is_system_account:
 *                 type: boolean
 *                 default: false
 *               real_name:
 *                 type: string
 *               id_card:
 *                 type: string
 *               wechat_qr:
 *                 type: string
 *               alipay_qr:
 *                 type: string
 *               bank_card:
 *                 type: string
 *               unionpay_qr:
 *                 type: string
 *               phone:
 *                 type: string
 *     responses:
 *       201:
 *         description: 用户创建成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 message:
 *                   type: string
 *                 user:
 *                   $ref: '#/components/schemas/User'
 *       400:
 *         description: 请求参数错误
 *       401:
 *         description: 未授权
 *       403:
 *         description: 权限不足
 *       500:
 *         description: 服务器错误
 */