/**
 * @swagger
 * tags:
 *   name: Announcements
 *   description: 通知公告管理API
 */

/**
 * @swagger
 * /api/announcements/{id}:
 *   get:
 *     summary: 获取单个公告详情
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: 公告ID
 *     responses:
 *       200:
 *         description: 成功获取公告详情
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   $ref: '#/components/schemas/Announcement'
 *       401:
 *         description: 未授权
 *       404:
 *         description: 公告不存在
 *       500:
 *         description: 服务器错误
 */

/**
 * @swagger
 * /api/announcements/{id}/read:
 *   post:
 *     summary: 标记公告为已读
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: 公告ID
 *     responses:
 *       200:
 *         description: 标记已读成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 message:
 *                   type: string
 *                   example: "已标记为已读"
 *       401:
 *         description: 未授权
 *       404:
 *         description: 公告不存在
 *       500:
 *         description: 服务器错误
 */

/**
 * @swagger
 * /api/announcements/unread/count:
 *   get:
 *     summary: 获取用户未读公告数量
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     responses:
 *       200:
 *         description: 获取未读数量成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 data:
 *                   type: object
 *                   properties:
 *                     unread_count:
 *                       type: integer
 *                       example: 5
 *                       description: 未读公告数量
 *       401:
 *         description: 未授权
 *       500:
 *         description: 服务器错误
 */

/**
 * @swagger
 * /api/announcements/batch/read:
 *   post:
 *     summary: 批量标记公告为已读
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - announcement_ids
 *             properties:
 *               announcement_ids:
 *                 type: array
 *                 items:
 *                   type: integer
 *                 example: [1, 2, 3]
 *                 description: 公告ID列表
 *     responses:
 *       200:
 *         description: 批量标记已读成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 message:
 *                   type: string
 *                   example: "批量标记已读成功"
 *       400:
 *         description: 请求参数错误
 *       401:
 *         description: 未授权
 *       500:
 *         description: 服务器错误
 */

/**
 * @swagger
 * /api/announcements:
 *   post:
 *     summary: 创建新公告
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - title
 *               - content
 *             properties:
 *               title:
 *                 type: string
 *                 description: 公告标题
 *               content:
 *                 type: string
 *                 description: 公告内容
 *               type:
 *                 type: string
 *                 enum: [system, maintenance, promotion, warning]
 *                 default: system
 *               priority:
 *                 type: string
 *                 enum: [low, medium, high, urgent]
 *                 default: medium
 *               status:
 *                 type: string
 *                 enum: [draft, published]
 *                 default: draft
 *               is_pinned:
 *                 type: boolean
 *                 default: false
 *               publish_time:
 *                 type: string
 *                 format: date-time
 *               expire_time:
 *                 type: string
 *                 format: date-time
 *     responses:
 *       201:
 *         description: 公告创建成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 message:
 *                   type: string
 *                 data:
 *                   type: object
 *                   properties:
 *                     id:
 *                       type: integer
 *       400:
 *         description: 请求参数错误
 *       401:
 *         description: 未授权
 *       500:
 *         description: 服务器错误
 */

/**
 * @swagger
 * /api/announcements/{id}:
 *   put:
 *     summary: 更新公告
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: 公告ID
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               title:
 *                 type: string
 *               content:
 *                 type: string
 *               type:
 *                 type: string
 *                 enum: [system, maintenance, promotion, warning]
 *               priority:
 *                 type: string
 *                 enum: [low, medium, high, urgent]
 *               status:
 *                 type: string
 *                 enum: [draft, published, archived]
 *               is_pinned:
 *                 type: boolean
 *               publish_time:
 *                 type: string
 *                 format: date-time
 *               expire_time:
 *                 type: string
 *                 format: date-time
 *     responses:
 *       200:
 *         description: 公告更新成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 message:
 *                   type: string
 *                 data:
 *                   $ref: '#/components/schemas/Announcement'
 *       400:
 *         description: 请求参数错误
 *       401:
 *         description: 未授权
 *       404:
 *         description: 公告不存在
 *       500:
 *         description: 服务器错误
 *
 *   delete:
 *     summary: 删除公告
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: 公告ID
 *     responses:
 *       200:
 *         description: 公告删除成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 message:
 *                   type: string
 *       401:
 *         description: 未授权
 *       404:
 *         description: 公告不存在
 *       500:
 *         description: 服务器错误
 */

/**
 * @swagger
 * /api/announcements/public/list:
 *   get:
 *     summary: 获取公开发布的公告列表（无需认证）
 *     tags: [Announcements]
 *     parameters:
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 5
 *         description: 获取数量
 *     responses:
 *       200:
 *         description: 成功获取公开公告列表
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   type: array
 *                   items:
 *                     $ref: '#/components/schemas/Announcement'
 *       500:
 *         description: 服务器错误
 */

/**
 * @swagger
 * components:
 *   schemas:
 *     Announcement:
 *       type: object
 *       required:
 *         - title
 *         - content
 *       properties:
 *         id:
 *           type: integer
 *           description: 公告ID
 *         title:
 *           type: string
 *           description: 公告标题
 *         content:
 *           type: string
 *           description: 公告内容
 *         type:
 *           type: string
 *           description: 公告类型
 *           enum: [system, maintenance, promotion, warning]
 *         priority:
 *           type: string
 *           description: 优先级
 *           enum: [low, medium, high, urgent]
 *         status:
 *           type: string
 *           description: 状态
 *           enum: [draft, published, archived]
 *         is_pinned:
 *           type: boolean
 *           description: 是否置顶
 *         publish_time:
 *           type: string
 *           format: date-time
 *           description: 发布时间
 *         expire_time:
 *           type: string
 *           format: date-time
 *           description: 过期时间
 *         created_by:
 *           type: integer
 *           description: 创建者ID
 *         created_at:
 *           type: string
 *           format: date-time
 *           description: 创建时间
 *         updated_at:
 *           type: string
 *           format: date-time
 *           description: 更新时间
 */

/**
 * @swagger
 * /api/announcements:
 *   get:
 *     summary: 获取通知公告列表
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: page
 *         schema:
 *           type: integer
 *           default: 1
 *         description: 页码
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *           default: 10
 *         description: 每页数量
 *       - in: query
 *         name: search
 *         schema:
 *           type: string
 *         description: 搜索关键词（标题或内容）
 *       - in: query
 *         name: type
 *         schema:
 *           type: string
 *           enum: [system, activity, maintenance, urgent]
 *         description: 公告类型
 *       - in: query
 *         name: priority
 *         schema:
 *           type: string
 *           enum: [high, medium, low]
 *         description: 优先级
 *       - in: query
 *         name: status
 *         schema:
 *           type: string
 *           enum: [draft, published, expired]
 *         description: 状态
 *       - in: query
 *         name: isTop
 *         schema:
 *           type: boolean
 *         description: 是否置顶
 *       - in: query
 *         name: sortBy
 *         schema:
 *           type: string
 *           enum: [created_at, updated_at, publish_time, priority]
 *           default: created_at
 *         description: 排序字段
 *       - in: query
 *         name: sortOrder
 *         schema:
 *           type: string
 *           enum: [ASC, DESC]
 *           default: DESC
 *         description: 排序方向
 *     responses:
 *       200:
 *         description: 成功获取公告列表
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 data:
 *                   type: object
 *                   properties:
 *                     announcements:
 *                       type: array
 *                       items:
 *                         $ref: '#/components/schemas/Announcement'
 *                     total:
 *                       type: integer
 *                       example: 50
 *                     page:
 *                       type: integer
 *                       example: 1
 *                     limit:
 *                       type: integer
 *                       example: 10
 *                     totalPages:
 *                       type: integer
 *                       example: 5
 *       401:
 *         description: 未授权
 *       500:
 *         description: 服务器错误
 *
 *   post:
 *     summary: 创建新的通知公告
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required:
 *               - title
 *               - content
 *               - type
 *               - priority
 *             properties:
 *               title:
 *                 type: string
 *                 description: 公告标题
 *                 example: "系统维护通知"
 *               content:
 *                 type: string
 *                 description: 公告内容
 *                 example: "系统将于今晚进行维护，预计维护时间2小时"
 *               type:
 *                 type: string
 *                 enum: [system, activity, maintenance, urgent]
 *                 description: 公告类型
 *                 example: "maintenance"
 *               priority:
 *                 type: string
 *                 enum: [high, medium, low]
 *                 description: 优先级
 *                 example: "high"
 *               status:
 *                 type: string
 *                 enum: [draft, published]
 *                 default: draft
 *                 description: 状态
 *               isTop:
 *                 type: boolean
 *                 default: false
 *                 description: 是否置顶
 *               publishTime:
 *                 type: string
 *                 format: date-time
 *                 description: 发布时间
 *               expireTime:
 *                 type: string
 *                 format: date-time
 *                 description: 过期时间
 *     responses:
 *       201:
 *         description: 公告创建成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 message:
 *                   type: string
 *                   example: "公告创建成功"
 *                 data:
 *                   $ref: '#/components/schemas/Announcement'
 *       400:
 *         description: 请求参数错误
 *       401:
 *         description: 未授权
 *       500:
 *         description: 服务器错误
 */

/**
 * @swagger
 * /api/announcements/{id}:
 *   put:
 *     summary: 更新通知公告
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: 公告ID
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               title:
 *                 type: string
 *                 description: 公告标题
 *               content:
 *                 type: string
 *                 description: 公告内容
 *               type:
 *                 type: string
 *                 enum: [system, activity, maintenance, urgent]
 *                 description: 公告类型
 *               priority:
 *                 type: string
 *                 enum: [high, medium, low]
 *                 description: 优先级
 *               status:
 *                 type: string
 *                 enum: [draft, published, expired]
 *                 description: 状态
 *               isTop:
 *                 type: boolean
 *                 description: 是否置顶
 *               publishTime:
 *                 type: string
 *                 format: date-time
 *                 description: 发布时间
 *               expireTime:
 *                 type: string
 *                 format: date-time
 *                 description: 过期时间
 *     responses:
 *       200:
 *         description: 公告更新成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 message:
 *                   type: string
 *                   example: "公告更新成功"
 *                 data:
 *                   $ref: '#/components/schemas/Announcement'
 *       400:
 *         description: 请求参数错误
 *       401:
 *         description: 未授权
 *       404:
 *         description: 公告不存在
 *       500:
 *         description: 服务器错误
 *
 *   delete:
 *     summary: 删除通知公告
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: 公告ID
 *     responses:
 *       200:
 *         description: 公告删除成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 message:
 *                   type: string
 *                   example: "公告删除成功"
 *       401:
 *         description: 未授权
 *       404:
 *         description: 公告不存在
 *       500:
 *         description: 服务器错误
 */

/**
 * @swagger
 * /api/announcements/{id}/toggle-top:
 *   put:
 *     summary: 切换公告置顶状态
 *     tags: [Announcements]
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: 公告ID
 *     responses:
 *       200:
 *         description: 置顶状态切换成功
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 message:
 *                   type: string
 *                   example: "置顶状态更新成功"
 *                 data:
 *                   type: object
 *                   properties:
 *                     isTop:
 *                       type: boolean
 *                       example: true
 *       401:
 *         description: 未授权
 *       404:
 *         description: 公告不存在
 *       500:
 *         description: 服务器错误
 */