736 lines
21 KiB
JavaScript
736 lines
21 KiB
JavaScript
/**
|
||
* 报表管理模块 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 = {}; |