nxxmdata/backend/swagger-reports.js

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

// 报表管理相关的 API 路径定义
const reportsPaths = {
  '/api/reports/farm': {
    post: {
      summary: '生成养殖统计报表',
      tags: ['报表管理'],
      security: [{ bearerAuth: [] }],
      requestBody: {
        required: false,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              properties: {
                startDate: { type: 'string', format: 'date', description: '开始日期' },
                endDate: { type: 'string', format: 'date', description: '结束日期' },
                farmIds: { 
                  type: 'array', 
                  items: { type: 'integer' },
                  description: '农场ID列表'
                },
                format: { 
                  type: 'string', 
                  enum: ['excel', 'pdf'],
                  description: '报表格式'
                }
              }
            }
          }
        }
      },
      responses: {
        200: { $ref: '#/components/responses/Success' },
        400: { $ref: '#/components/responses/BadRequest' }
      }
    }
  },
  '/api/reports/animal': {
    post: {
      summary: '生成动物统计报表',
      tags: ['报表管理'],
      security: [{ bearerAuth: [] }],
      requestBody: {
        required: false,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              properties: {
                startDate: { type: 'string', format: 'date', description: '开始日期' },
                endDate: { type: 'string', format: 'date', description: '结束日期' },
                farmId: { type: 'integer', description: '农场ID' },
                format: { 
                  type: 'string', 
                  enum: ['excel', 'pdf'],
                  description: '报表格式'
                }
              }
            }
          }
        }
      },
      responses: {
        200: { $ref: '#/components/responses/Success' },
        400: { $ref: '#/components/responses/BadRequest' }
      }
    }
  },
  '/api/reports/device': {
    post: {
      summary: '生成设备统计报表',
      tags: ['报表管理'],
      security: [{ bearerAuth: [] }],
      requestBody: {
        required: false,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              properties: {
                startDate: { type: 'string', format: 'date', description: '开始日期' },
                endDate: { type: 'string', format: 'date', description: '结束日期' },
                format: { 
                  type: 'string', 
                  enum: ['excel', 'pdf'],
                  description: '报表格式'
                }
              }
            }
          }
        }
      },
      responses: {
        200: { $ref: '#/components/responses/Success' },
        400: { $ref: '#/components/responses/BadRequest' }
      }
    }
  }
};

// 报表管理相关的数据模型定义
const reportsSchemas = {
  ReportRequest: {
    type: 'object',
    properties: {
      startDate: { type: 'string', format: 'date', description: '开始日期' },
      endDate: { type: 'string', format: 'date', description: '结束日期' },
      farmIds: { 
        type: 'array', 
        items: { type: 'integer' },
        description: '农场ID列表'
      },
      format: { 
        type: 'string', 
        enum: ['excel', 'pdf'],
        description: '报表格式'
      }
    }
  },
  ReportResponse: {
    type: 'object',
    properties: {
      success: { type: 'boolean' },
      message: { type: 'string' },
      data: {
        type: 'object',
        properties: {
          reportId: { type: 'string', description: '报表ID' },
          downloadUrl: { type: 'string', description: '下载链接' },
          fileName: { type: 'string', description: '文件名' }
        }
      }
    }
  }
};

module.exports = {
  reportsPaths,
  reportsSchemas
};