nxxmdata/backend/swagger-alerts.js

/**
 * 预警管理模块 Swagger 文档
 * @file swagger-alerts.js
 */

const alertsPaths = {
  // 获取所有预警
  '/alerts': {
    get: {
      tags: ['预警管理'],
      summary: '获取预警列表',
      description: '分页获取系统中的所有预警信息',
      security: [{ bearerAuth: [] }],
      parameters: [
        {
          name: 'page',
          in: 'query',
          schema: { type: 'integer', default: 1 },
          description: '页码'
        },
        {
          name: 'limit',
          in: 'query',
          schema: { type: 'integer', default: 10 },
          description: '每页数量'
        },
        {
          name: 'search',
          in: 'query',
          schema: { type: 'string' },
          description: '搜索关键词（预警标题、描述）'
        },
        {
          name: 'type',
          in: 'query',
          schema: { type: 'string', enum: ['health', 'environment', 'device', 'security', 'breeding'] },
          description: '预警类型筛选'
        },
        {
          name: 'level',
          in: 'query',
          schema: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
          description: '预警级别筛选'
        },
        {
          name: 'status',
          in: 'query',
          schema: { type: 'string', enum: ['pending', 'processing', 'resolved', 'ignored'] },
          description: '预警状态筛选'
        },
        {
          name: 'farmId',
          in: 'query',
          schema: { type: 'integer' },
          description: '养殖场ID筛选'
        }
      ],
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'array',
                    items: { $ref: '#/components/schemas/Alert' }
                  },
                  pagination: {
                    type: 'object',
                    properties: {
                      page: { type: 'integer' },
                      limit: { type: 'integer' },
                      total: { type: 'integer' },
                      totalPages: { type: 'integer' }
                    }
                  }
                }
              }
            }
          }
        },
        '401': {
          description: '未授权',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    },
    post: {
      tags: ['预警管理'],
      summary: '创建新预警',
      description: '创建新的预警记录',
      security: [{ bearerAuth: [] }],
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              required: ['title', 'type', 'level', 'farmId'],
              properties: {
                title: { type: 'string', description: '预警标题' },
                description: { type: 'string', description: '预警描述' },
                type: { 
                  type: 'string', 
                  enum: ['health', 'environment', 'device', 'security', 'breeding'],
                  description: '预警类型：health-健康，environment-环境，device-设备，security-安全，breeding-繁殖'
                },
                level: { 
                  type: 'string', 
                  enum: ['low', 'medium', 'high', 'critical'],
                  description: '预警级别：low-低，medium-中，high-高，critical-紧急'
                },
                farmId: { type: 'integer', description: '养殖场ID' },
                animalId: { type: 'integer', description: '动物ID（可选）' },
                deviceId: { type: 'integer', description: '设备ID（可选）' },
                threshold: { type: 'number', description: '阈值' },
                currentValue: { type: 'number', description: '当前值' },
                location: { type: 'string', description: '位置信息' },
                metadata: { type: 'object', description: '额外元数据' }
              }
            }
          }
        }
      },
      responses: {
        '201': {
          description: '创建成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '预警创建成功' },
                  data: { $ref: '#/components/schemas/Alert' }
                }
              }
            }
          }
        },
        '400': {
          description: '请求参数错误',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 获取公共预警数据
  '/alerts/public': {
    get: {
      tags: ['预警管理'],
      summary: '获取公共预警数据',
      description: '获取可公开访问的预警基本信息',
      security: [], // 公共接口不需要认证
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'array',
                    items: {
                      type: 'object',
                      properties: {
                        id: { type: 'integer' },
                        title: { type: 'string' },
                        type: { type: 'string' },
                        level: { type: 'string' },
                        status: { type: 'string' },
                        createdAt: { type: 'string', format: 'date-time' }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },

  // 搜索预警
  '/alerts/search': {
    get: {
      tags: ['预警管理'],
      summary: '搜索预警',
      description: '根据养殖场名称等关键词搜索预警',
      security: [{ bearerAuth: [] }],
      parameters: [
        {
          name: 'q',
          in: 'query',
          required: true,
          schema: { type: 'string' },
          description: '搜索关键词'
        },
        {
          name: 'limit',
          in: 'query',
          schema: { type: 'integer', default: 10 },
          description: '返回结果数量限制'
        }
      ],
      responses: {
        '200': {
          description: '搜索成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'array',
                    items: { $ref: '#/components/schemas/Alert' }
                  }
                }
              }
            }
          }
        }
      }
    }
  },

  // 获取预警详情
  '/alerts/{id}': {
    get: {
      tags: ['预警管理'],
      summary: '获取预警详情',
      description: '根据预警ID获取详细信息',
      parameters: [
        {
          name: 'id',
          in: 'path',
          required: true,
          schema: { type: 'integer' },
          description: '预警ID'
        }
      ],
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: { $ref: '#/components/schemas/Alert' }
                }
              }
            }
          }
        },
        '404': {
          description: '预警不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    },
    put: {
      tags: ['预警管理'],
      summary: '更新预警信息',
      description: '更新指定预警的信息',
      security: [{ bearerAuth: [] }],
      parameters: [
        {
          name: 'id',
          in: 'path',
          required: true,
          schema: { type: 'integer' },
          description: '预警ID'
        }
      ],
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              properties: {
                title: { type: 'string', description: '预警标题' },
                description: { type: 'string', description: '预警描述' },
                type: { 
                  type: 'string', 
                  enum: ['health', 'environment', 'device', 'security', 'breeding'],
                  description: '预警类型'
                },
                level: { 
                  type: 'string', 
                  enum: ['low', 'medium', 'high', 'critical'],
                  description: '预警级别'
                },
                status: { 
                  type: 'string', 
                  enum: ['pending', 'processing', 'resolved', 'ignored'],
                  description: '预警状态'
                },
                threshold: { type: 'number', description: '阈值' },
                currentValue: { type: 'number', description: '当前值' },
                location: { type: 'string', description: '位置信息' },
                handlerNotes: { type: 'string', description: '处理备注' },
                metadata: { type: 'object', description: '额外元数据' }
              }
            }
          }
        }
      },
      responses: {
        '200': {
          description: '更新成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '预警信息更新成功' },
                  data: { $ref: '#/components/schemas/Alert' }
                }
              }
            }
          }
        },
        '400': {
          description: '请求参数错误',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        },
        '404': {
          description: '预警不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    },
    delete: {
      tags: ['预警管理'],
      summary: '删除预警',
      description: '删除指定预警（软删除）',
      security: [{ bearerAuth: [] }],
      parameters: [
        {
          name: 'id',
          in: 'path',
          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: '预警删除成功' }
                }
              }
            }
          }
        },
        '404': {
          description: '预警不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 更新预警状态
  '/alerts/{id}/status': {
    put: {
      tags: ['预警管理'],
      summary: '更新预警状态',
      description: '更新指定预警的处理状态',
      parameters: [
        {
          name: 'id',
          in: 'path',
          required: true,
          schema: { type: 'integer' },
          description: '预警ID'
        }
      ],
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              required: ['status'],
              properties: {
                status: { 
                  type: 'string', 
                  enum: ['pending', 'processing', 'resolved', 'ignored'],
                  description: '预警状态'
                },
                handlerNotes: { type: 'string', description: '处理备注' },
                handlerId: { type: 'integer', description: '处理人ID' }
              }
            }
          }
        }
      },
      responses: {
        '200': {
          description: '状态更新成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '预警状态更新成功' }
                }
              }
            }
          }
        },
        '400': {
          description: '请求参数错误',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        },
        '404': {
          description: '预警不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 获取预警统计信息
  '/alerts/stats/type': {
    get: {
      tags: ['预警管理'],
      summary: '获取按类型统计的预警数据',
      description: '获取各种预警类型的统计信息',
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'object',
                    properties: {
                      health: { type: 'integer', description: '健康预警数量' },
                      environment: { type: 'integer', description: '环境预警数量' },
                      device: { type: 'integer', description: '设备预警数量' },
                      security: { type: 'integer', description: '安全预警数量' },
                      breeding: { type: 'integer', description: '繁殖预警数量' }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },

  '/alerts/stats/level': {
    get: {
      tags: ['预警管理'],
      summary: '获取按级别统计的预警数据',
      description: '获取各种预警级别的统计信息',
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'object',
                    properties: {
                      low: { type: 'integer', description: '低级预警数量' },
                      medium: { type: 'integer', description: '中级预警数量' },
                      high: { type: 'integer', description: '高级预警数量' },
                      critical: { type: 'integer', description: '紧急预警数量' }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },

  '/alerts/stats/status': {
    get: {
      tags: ['预警管理'],
      summary: '获取按状态统计的预警数据',
      description: '获取各种预警状态的统计信息',
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'object',
                    properties: {
                      pending: { type: 'integer', description: '待处理预警数量' },
                      processing: { type: 'integer', description: '处理中预警数量' },
                      resolved: { type: 'integer', description: '已解决预警数量' },
                      ignored: { type: 'integer', description: '已忽略预警数量' }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },

  // 批量操作预警
  '/alerts/batch': {
    post: {
      tags: ['预警管理'],
      summary: '批量操作预警',
      description: '批量更新预警状态或删除预警',
      security: [{ bearerAuth: [] }],
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              required: ['ids', 'action'],
              properties: {
                ids: {
                  type: 'array',
                  items: { type: 'integer' },
                  description: '预警ID列表'
                },
                action: {
                  type: 'string',
                  enum: ['resolve', 'ignore', 'delete', 'reopen'],
                  description: '操作类型：resolve-解决，ignore-忽略，delete-删除，reopen-重新打开'
                },
                handlerNotes: { type: 'string', description: '处理备注' }
              }
            }
          }
        }
      },
      responses: {
        '200': {
          description: '批量操作成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '批量操作完成' },
                  data: {
                    type: 'object',
                    properties: {
                      successCount: { type: 'integer', description: '成功处理数量' },
                      failedCount: { type: 'integer', description: '失败数量' },
                      failedIds: {
                        type: 'array',
                        items: { type: 'integer' },
                        description: '失败的预警ID列表'
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
};

// 数据模型定义
const alertSchemas = {
  Alert: {
    type: 'object',
    properties: {
      id: { type: 'integer', description: '预警ID' },
      title: { type: 'string', description: '预警标题' },
      description: { type: 'string', description: '预警描述' },
      type: { 
        type: 'string', 
        enum: ['health', 'environment', 'device', 'security', 'breeding'],
        description: '预警类型：health-健康，environment-环境，device-设备，security-安全，breeding-繁殖'
      },
      level: { 
        type: 'string', 
        enum: ['low', 'medium', 'high', 'critical'],
        description: '预警级别：low-低，medium-中，high-高，critical-紧急'
      },
      status: { 
        type: 'string', 
        enum: ['pending', 'processing', 'resolved', 'ignored'],
        description: '预警状态：pending-待处理，processing-处理中，resolved-已解决，ignored-已忽略'
      },
      farmId: { type: 'integer', description: '养殖场ID' },
      farmName: { type: 'string', description: '养殖场名称' },
      animalId: { type: 'integer', description: '动物ID（可选）' },
      animalEarNumber: { type: 'string', description: '动物耳标号（可选）' },
      deviceId: { type: 'integer', description: '设备ID（可选）' },
      deviceName: { type: 'string', description: '设备名称（可选）' },
      threshold: { type: 'number', description: '阈值' },
      currentValue: { type: 'number', description: '当前值' },
      location: { type: 'string', description: '位置信息' },
      handlerId: { type: 'integer', description: '处理人ID' },
      handlerName: { type: 'string', description: '处理人姓名' },
      handlerNotes: { type: 'string', description: '处理备注' },
      handledAt: { type: 'string', format: 'date-time', description: '处理时间' },
      metadata: { type: 'object', description: '额外元数据' },
      createdAt: { type: 'string', format: 'date-time', description: '创建时间' },
      updatedAt: { type: 'string', format: 'date-time', description: '更新时间' }
    }
  },

  AlertInput: {
    type: 'object',
    required: ['title', 'type', 'level', 'farmId'],
    properties: {
      title: { type: 'string', description: '预警标题' },
      description: { type: 'string', description: '预警描述' },
      type: { 
        type: 'string', 
        enum: ['health', 'environment', 'device', 'security', 'breeding'],
        description: '预警类型'
      },
      level: { 
        type: 'string', 
        enum: ['low', 'medium', 'high', 'critical'],
        description: '预警级别'
      },
      farmId: { type: 'integer', description: '养殖场ID' },
      animalId: { type: 'integer', description: '动物ID（可选）' },
      deviceId: { type: 'integer', description: '设备ID（可选）' },
      threshold: { type: 'number', description: '阈值' },
      currentValue: { type: 'number', description: '当前值' },
      location: { type: 'string', description: '位置信息' },
      metadata: { type: 'object', description: '额外元数据' }
    }
  },

  AlertUpdate: {
    type: 'object',
    properties: {
      title: { type: 'string', description: '预警标题' },
      description: { type: 'string', description: '预警描述' },
      type: { 
        type: 'string', 
        enum: ['health', 'environment', 'device', 'security', 'breeding'],
        description: '预警类型'
      },
      level: { 
        type: 'string', 
        enum: ['low', 'medium', 'high', 'critical'],
        description: '预警级别'
      },
      status: { 
        type: 'string', 
        enum: ['pending', 'processing', 'resolved', 'ignored'],
        description: '预警状态'
      },
      threshold: { type: 'number', description: '阈值' },
      currentValue: { type: 'number', description: '当前值' },
      location: { type: 'string', description: '位置信息' },
      handlerNotes: { type: 'string', description: '处理备注' },
      metadata: { type: 'object', description: '额外元数据' }
    }
  },

  AlertStats: {
    type: 'object',
    properties: {
      totalAlerts: { type: 'integer', description: '总预警数' },
      pendingAlerts: { type: 'integer', description: '待处理预警数' },
      resolvedAlerts: { type: 'integer', description: '已解决预警数' },
      criticalAlerts: { type: 'integer', description: '紧急预警数' },
      todayAlerts: { type: 'integer', description: '今日新增预警数' },
      byType: {
        type: 'object',
        properties: {
          health: { type: 'integer' },
          environment: { type: 'integer' },
          device: { type: 'integer' },
          security: { type: 'integer' },
          breeding: { type: 'integer' }
        }
      },
      byLevel: {
        type: 'object',
        properties: {
          low: { type: 'integer' },
          medium: { type: 'integer' },
          high: { type: 'integer' },
          critical: { type: 'integer' }
        }
      },
      byStatus: {
        type: 'object',
        properties: {
          pending: { type: 'integer' },
          processing: { type: 'integer' },
          resolved: { type: 'integer' },
          ignored: { type: 'integer' }
        }
      }
    }
  }
};

module.exports = { alertsPaths, alertSchemas };