/**
 * 报表管理模块 Swagger 文档
 * @file swagger-reports.js
 * @description 定义报表管理相关的API文档
 */

/**
 * @swagger
 * tags:
 *   - name: 报表管理
 *     description: 报表生成、下载和管理
 */

/**
 * @swagger
 * components:
 *   schemas:
 *     ReportGenerateRequest:
 *       type: object
 *       properties:
 *         startDate:
 *           type: string
 *           format: date
 *           description: 开始日期
 *           example: "2024-01-01"
 *         endDate:
 *           type: string
 *           format: date
 *           description: 结束日期
 *           example: "2024-01-31"
 *         format:
 *           type: string
 *           enum: [pdf, excel, csv]
 *           description: 报表格式
 *           example: "pdf"
 *
 *     FarmReportRequest:
 *       allOf:
 *         - $ref: '#/components/schemas/ReportGenerateRequest'
 *         - type: object
 *           properties:
 *             farmIds:
 *               type: array
 *               items:
 *                 type: string
 *               description: 养殖场ID列表
 *               example: ["farm_001", "farm_002"]
 *
 *     SalesReportRequest:
 *       allOf:
 *         - $ref: '#/components/schemas/ReportGenerateRequest'
 *         - type: object
 *           properties:
 *             format:
 *               type: string
 *               enum: [pdf, excel]
 *               description: 报表格式（销售报表不支持CSV）
 *               example: "excel"
 *
 *     ComplianceReportRequest:
 *       allOf:
 *         - $ref: '#/components/schemas/ReportGenerateRequest'
 *         - type: object
 *           properties:
 *             format:
 *               type: string
 *               enum: [pdf, excel]
 *               description: 报表格式（合规报表不支持CSV）
 *               example: "pdf"
 *
 *     ReportFile:
 *       type: object
 *       properties:
 *         fileName:
 *           type: string
 *           description: 文件名
 *           example: "farm_report_20240115.pdf"
 *         downloadUrl:
 *           type: string
 *           description: 下载链接
 *           example: "/api/reports/download/farm_report_20240115.pdf"
 *         mimeType:
 *           type: string
 *           description: 文件MIME类型
 *           example: "application/pdf"
 *         size:
 *           type: integer
 *           description: 文件大小（字节）
 *           example: 1024000
 *         generatedAt:
 *           type: string
 *           format: date-time
 *           description: 生成时间
 *           example: "2024-01-15T10:30:00Z"
 *
 *     ReportListItem:
 *       type: object
 *       properties:
 *         id:
 *           type: string
 *           description: 报表ID
 *           example: "report_001"
 *         fileName:
 *           type: string
 *           description: 文件名
 *           example: "farm_report_20240115.pdf"
 *         type:
 *           type: string
 *           enum: [farm, sales, compliance, export]
 *           description: 报表类型
 *           example: "farm"
 *         format:
 *           type: string
 *           enum: [pdf, excel, csv]
 *           description: 文件格式
 *           example: "pdf"
 *         size:
 *           type: integer
 *           description: 文件大小（字节）
 *           example: 1024000
 *         status:
 *           type: string
 *           enum: [generating, completed, failed, expired]
 *           description: 报表状态
 *           example: "completed"
 *         createdBy:
 *           type: string
 *           description: 创建者
 *           example: "admin"
 *         createdAt:
 *           type: string
 *           format: date-time
 *           description: 创建时间
 *           example: "2024-01-15T10:30:00Z"
 *         expiresAt:
 *           type: string
 *           format: date-time
 *           description: 过期时间
 *           example: "2024-01-22T10:30:00Z"
 *         downloadUrl:
 *           type: string
 *           description: 下载链接
 *           example: "/api/reports/download/farm_report_20240115.pdf"
 *
 *     ReportTemplate:
 *       type: object
 *       properties:
 *         id:
 *           type: string
 *           description: 模板ID
 *           example: "template_001"
 *         name:
 *           type: string
 *           description: 模板名称
 *           example: "养殖场月度报表模板"
 *         type:
 *           type: string
 *           enum: [farm, sales, compliance]
 *           description: 模板类型
 *           example: "farm"
 *         description:
 *           type: string
 *           description: 模板描述
 *           example: "包含养殖场基本信息、动物统计、设备状态等"
 *         fields:
 *           type: array
 *           items:
 *             type: object
 *             properties:
 *               name:
 *                 type: string
 *                 description: 字段名称
 *               label:
 *                 type: string
 *                 description: 字段标签
 *               type:
 *                 type: string
 *                 description: 字段类型
 *               required:
 *                 type: boolean
 *                 description: 是否必填
 *           description: 模板字段配置
 *         isDefault:
 *           type: boolean
 *           description: 是否为默认模板
 *           example: true
 *         createdAt:
 *           type: string
 *           format: date-time
 *           description: 创建时间
 *           example: "2024-01-15T10:30:00Z"
 *
 *     ExportDataRequest:
 *       type: object
 *       properties:
 *         format:
 *           type: string
 *           enum: [excel, csv]
 *           description: 导出格式
 *           example: "excel"
 *         filters:
 *           type: object
 *           description: 筛选条件
 *           properties:
 *             status:
 *               type: string
 *               description: 状态筛选
 *             startDate:
 *               type: string
 *               format: date
 *               description: 开始日期
 *             endDate:
 *               type: string
 *               format: date
 *               description: 结束日期
 */

/**
 * @swagger
 * /reports/farm:
 *   post:
 *     tags:
 *       - 报表管理
 *     summary: 生成养殖统计报表
 *     description: 生成指定时间范围和养殖场的统计报表
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: false
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/FarmReportRequest'
 *     responses:
 *       200:
 *         description: 报表生成成功
 *         content:
 *           application/json:
 *             schema:
 *               allOf:
 *                 - $ref: '#/components/schemas/ApiResponse'
 *                 - type: object
 *                   properties:
 *                     data:
 *                       $ref: '#/components/schemas/ReportFile'
 *       400:
 *         description: 请求参数错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       401:
 *         description: 未授权
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       500:
 *         description: 服务器内部错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 */

/**
 * @swagger
 * /reports/sales:
 *   post:
 *     tags:
 *       - 报表管理
 *     summary: 生成销售分析报表
 *     description: 生成指定时间范围的销售分析报表（需要管理员或经理权限）
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: false
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/SalesReportRequest'
 *     responses:
 *       200:
 *         description: 报表生成成功
 *         content:
 *           application/json:
 *             schema:
 *               allOf:
 *                 - $ref: '#/components/schemas/ApiResponse'
 *                 - type: object
 *                   properties:
 *                     data:
 *                       $ref: '#/components/schemas/ReportFile'
 *       400:
 *         description: 请求参数错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       401:
 *         description: 未授权
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       403:
 *         description: 权限不足
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       500:
 *         description: 服务器内部错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 */

/**
 * @swagger
 * /reports/compliance:
 *   post:
 *     tags:
 *       - 报表管理
 *     summary: 生成监管合规报表
 *     description: 生成指定时间范围的监管合规报表（仅限管理员）
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: false
 *       content:
 *         application/json:
 *           schema:
 *             $ref: '#/components/schemas/ComplianceReportRequest'
 *     responses:
 *       200:
 *         description: 报表生成成功
 *         content:
 *           application/json:
 *             schema:
 *               allOf:
 *                 - $ref: '#/components/schemas/ApiResponse'
 *                 - type: object
 *                   properties:
 *                     data:
 *                       $ref: '#/components/schemas/ReportFile'
 *       400:
 *         description: 请求参数错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       401:
 *         description: 未授权
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       403:
 *         description: 权限不足（仅限管理员）
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       500:
 *         description: 服务器内部错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 */

/**
 * @swagger
 * /reports/download/{fileName}:
 *   get:
 *     tags:
 *       - 报表管理
 *     summary: 下载报表文件
 *     description: 下载指定的报表文件
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: path
 *         name: fileName
 *         required: true
 *         schema:
 *           type: string
 *         description: 文件名（需要URL编码）
 *         example: "farm_report_20240115.pdf"
 *     responses:
 *       200:
 *         description: 文件下载成功
 *         content:
 *           application/pdf:
 *             schema:
 *               type: string
 *               format: binary
 *           application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
 *             schema:
 *               type: string
 *               format: binary
 *           text/csv:
 *             schema:
 *               type: string
 *               format: binary
 *       401:
 *         description: 未授权
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       403:
 *         description: 非法文件路径
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       404:
 *         description: 文件不存在
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       500:
 *         description: 服务器内部错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 */

/**
 * @swagger
 * /reports/list:
 *   get:
 *     tags:
 *       - 报表管理
 *     summary: 获取报表列表
 *     description: 获取当前用户的报表列表，支持分页和筛选
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - $ref: '#/components/parameters/PaginationQuery/properties/page'
 *       - $ref: '#/components/parameters/PaginationQuery/properties/limit'
 *       - in: query
 *         name: type
 *         schema:
 *           type: string
 *           enum: [farm, sales, compliance, export]
 *         description: 报表类型筛选
 *       - in: query
 *         name: status
 *         schema:
 *           type: string
 *           enum: [generating, completed, failed, expired]
 *         description: 报表状态筛选
 *       - in: query
 *         name: format
 *         schema:
 *           type: string
 *           enum: [pdf, excel, csv]
 *         description: 文件格式筛选
 *       - in: query
 *         name: startDate
 *         schema:
 *           type: string
 *           format: date
 *         description: 创建开始日期
 *       - in: query
 *         name: endDate
 *         schema:
 *           type: string
 *           format: date
 *         description: 创建结束日期
 *     responses:
 *       200:
 *         description: 获取列表成功
 *         content:
 *           application/json:
 *             schema:
 *               allOf:
 *                 - $ref: '#/components/schemas/ApiResponse'
 *                 - type: object
 *                   properties:
 *                     data:
 *                       type: object
 *                       properties:
 *                         reports:
 *                           type: array
 *                           items:
 *                             $ref: '#/components/schemas/ReportListItem'
 *                         pagination:
 *                           type: object
 *                           properties:
 *                             total:
 *                               type: integer
 *                               example: 50
 *                             page:
 *                               type: integer
 *                               example: 1
 *                             limit:
 *                               type: integer
 *                               example: 10
 *                             totalPages:
 *                               type: integer
 *                               example: 5
 *       401:
 *         description: 未授权
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       500:
 *         description: 服务器内部错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 */

/**
 * @swagger
 * /reports/cleanup:
 *   post:
 *     tags:
 *       - 报表管理
 *     summary: 清理过期报表
 *     description: 清理过期的报表文件（仅限管理员）
 *     security:
 *       - bearerAuth: []
 *     requestBody:
 *       required: false
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             properties:
 *               daysOld:
 *                 type: integer
 *                 description: 清理多少天前的文件
 *                 example: 30
 *               force:
 *                 type: boolean
 *                 description: 是否强制清理（包括未过期的文件）
 *                 example: false
 *     responses:
 *       200:
 *         description: 清理成功
 *         content:
 *           application/json:
 *             schema:
 *               allOf:
 *                 - $ref: '#/components/schemas/ApiResponse'
 *                 - type: object
 *                   properties:
 *                     data:
 *                       type: object
 *                       properties:
 *                         deletedCount:
 *                           type: integer
 *                           description: 删除的文件数量
 *                           example: 15
 *                         freedSpace:
 *                           type: integer
 *                           description: 释放的空间（字节）
 *                           example: 15360000
 *       401:
 *         description: 未授权
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       403:
 *         description: 权限不足（仅限管理员）
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       500:
 *         description: 服务器内部错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 */

/**
 * @swagger
 * /reports/export/farms:
 *   get:
 *     tags:
 *       - 报表管理
 *     summary: 导出养殖场数据
 *     description: 导出养殖场基础数据为Excel或CSV格式
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: format
 *         schema:
 *           type: string
 *           enum: [excel, csv]
 *           default: excel
 *         description: 导出格式
 *       - in: query
 *         name: status
 *         schema:
 *           type: string
 *           enum: [active, inactive, all]
 *           default: all
 *         description: 状态筛选
 *     responses:
 *       200:
 *         description: 导出成功
 *         content:
 *           application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
 *             schema:
 *               type: string
 *               format: binary
 *           text/csv:
 *             schema:
 *               type: string
 *               format: binary
 *       401:
 *         description: 未授权
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       500:
 *         description: 服务器内部错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 */

/**
 * @swagger
 * /reports/export/devices:
 *   get:
 *     tags:
 *       - 报表管理
 *     summary: 导出设备数据
 *     description: 导出设备基础数据为Excel或CSV格式
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: format
 *         schema:
 *           type: string
 *           enum: [excel, csv]
 *           default: excel
 *         description: 导出格式
 *       - in: query
 *         name: status
 *         schema:
 *           type: string
 *           enum: [online, offline, maintenance, all]
 *           default: all
 *         description: 设备状态筛选
 *     responses:
 *       200:
 *         description: 导出成功
 *         content:
 *           application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
 *             schema:
 *               type: string
 *               format: binary
 *           text/csv:
 *             schema:
 *               type: string
 *               format: binary
 *       401:
 *         description: 未授权
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       500:
 *         description: 服务器内部错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 */

/**
 * @swagger
 * /reports/templates:
 *   get:
 *     tags:
 *       - 报表管理
 *     summary: 获取报表模板列表
 *     description: 获取可用的报表模板列表
 *     security:
 *       - bearerAuth: []
 *     parameters:
 *       - in: query
 *         name: type
 *         schema:
 *           type: string
 *           enum: [farm, sales, compliance]
 *         description: 模板类型筛选
 *     responses:
 *       200:
 *         description: 获取模板列表成功
 *         content:
 *           application/json:
 *             schema:
 *               allOf:
 *                 - $ref: '#/components/schemas/ApiResponse'
 *                 - type: object
 *                   properties:
 *                     data:
 *                       type: array
 *                       items:
 *                         $ref: '#/components/schemas/ReportTemplate'
 *       401:
 *         description: 未授权
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 *       500:
 *         description: 服务器内部错误
 *         content:
 *           application/json:
 *             schema:
 *               $ref: '#/components/schemas/ErrorResponse'
 */

module.exports = {};