nxxmdata/backend/swagger-farms.js

/**
 * 养殖场管理模块 Swagger 文档
 * @file swagger-farms.js
 */

const farmsPaths = {
  // 获取所有养殖场
  '/farms': {
    get: {
      tags: ['养殖场管理'],
      summary: '获取养殖场列表',
      description: '分页获取系统中的所有养殖场',
      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: 'status',
          in: 'query',
          schema: { type: 'string', enum: ['active', 'inactive', 'suspended'] },
          description: '养殖场状态筛选'
        },
        {
          name: 'type',
          in: 'query',
          schema: { type: 'string', enum: ['cattle', 'sheep', 'pig', 'poultry'] },
          description: '养殖类型筛选'
        }
      ],
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'array',
                    items: { $ref: '#/components/schemas/Farm' }
                  },
                  pagination: {
                    type: 'object',
                    properties: {
                      page: { type: 'integer' },
                      limit: { type: 'integer' },
                      total: { type: 'integer' },
                      totalPages: { type: 'integer' }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    post: {
      tags: ['养殖场管理'],
      summary: '创建新养殖场',
      description: '创建新的养殖场记录',
      requestBody: {
        required: true,
        content: {
          'application/json': {
            schema: {
              type: 'object',
              required: ['name', 'address', 'type', 'ownerId'],
              properties: {
                name: { type: 'string', description: '养殖场名称' },
                address: { type: 'string', description: '养殖场地址' },
                type: { 
                  type: 'string', 
                  enum: ['cattle', 'sheep', 'pig', 'poultry'],
                  description: '养殖类型：cattle-牛，sheep-羊，pig-猪，poultry-家禽'
                },
                ownerId: { type: 'integer', description: '养殖场主ID' },
                description: { type: 'string', description: '养殖场描述' },
                area: { type: 'number', description: '养殖场面积（平方米）' },
                capacity: { type: 'integer', description: '最大养殖容量' },
                contactPhone: { type: 'string', description: '联系电话' },
                contactEmail: { type: 'string', format: 'email', description: '联系邮箱' },
                coordinates: {
                  type: 'object',
                  properties: {
                    latitude: { type: 'number', description: '纬度' },
                    longitude: { type: 'number', description: '经度' }
                  },
                  description: '地理坐标'
                },
                status: { 
                  type: 'string', 
                  enum: ['active', 'inactive', 'suspended'],
                  default: 'active',
                  description: '养殖场状态'
                }
              }
            }
          }
        }
      },
      responses: {
        '201': {
          description: '创建成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '养殖场创建成功' },
                  data: { $ref: '#/components/schemas/Farm' }
                }
              }
            }
          }
        },
        '400': {
          description: '请求参数错误',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 搜索养殖场
  '/farms/search': {
    get: {
      tags: ['养殖场管理'],
      summary: '搜索养殖场',
      description: '根据名称、地址等关键词搜索养殖场',
      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/Farm' }
                  }
                }
              }
            }
          }
        }
      }
    }
  },

  // 公共养殖场数据
  '/farms/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' },
                        name: { type: 'string' },
                        type: { type: 'string' },
                        address: { type: 'string' },
                        area: { type: 'number' }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },

  // 获取指定养殖场详情
  '/farms/{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/Farm' }
                }
              }
            }
          }
        },
        '404': {
          description: '养殖场不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    },
    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',
              properties: {
                name: { type: 'string', description: '养殖场名称' },
                address: { type: 'string', description: '养殖场地址' },
                type: { 
                  type: 'string', 
                  enum: ['cattle', 'sheep', 'pig', 'poultry'],
                  description: '养殖类型'
                },
                description: { type: 'string', description: '养殖场描述' },
                area: { type: 'number', description: '养殖场面积（平方米）' },
                capacity: { type: 'integer', description: '最大养殖容量' },
                contactPhone: { type: 'string', description: '联系电话' },
                contactEmail: { type: 'string', format: 'email', description: '联系邮箱' },
                coordinates: {
                  type: 'object',
                  properties: {
                    latitude: { type: 'number', description: '纬度' },
                    longitude: { type: 'number', description: '经度' }
                  },
                  description: '地理坐标'
                },
                status: { 
                  type: 'string', 
                  enum: ['active', 'inactive', 'suspended'],
                  description: '养殖场状态'
                }
              }
            }
          }
        }
      },
      responses: {
        '200': {
          description: '更新成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  message: { type: 'string', example: '养殖场信息更新成功' },
                  data: { $ref: '#/components/schemas/Farm' }
                }
              }
            }
          }
        },
        '400': {
          description: '请求参数错误',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        },
        '404': {
          description: '养殖场不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    },
    delete: {
      tags: ['养殖场管理'],
      summary: '删除养殖场',
      description: '删除指定养殖场（软删除）',
      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' }
            }
          }
        }
      }
    }
  },

  // 获取养殖场的动物列表
  '/farms/{id}/animals': {
    get: {
      tags: ['养殖场管理'],
      summary: '获取养殖场的动物列表',
      description: '获取指定养殖场的所有动物',
      parameters: [
        {
          name: 'id',
          in: 'path',
          required: true,
          schema: { type: 'integer' },
          description: '养殖场ID'
        },
        {
          name: 'page',
          in: 'query',
          schema: { type: 'integer', default: 1 },
          description: '页码'
        },
        {
          name: 'limit',
          in: 'query',
          schema: { type: 'integer', default: 10 },
          description: '每页数量'
        },
        {
          name: 'status',
          in: 'query',
          schema: { type: 'string', enum: ['healthy', 'sick', 'quarantine', 'sold'] },
          description: '动物状态筛选'
        }
      ],
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'array',
                    items: { $ref: '#/components/schemas/Animal' }
                  },
                  pagination: {
                    type: 'object',
                    properties: {
                      page: { type: 'integer' },
                      limit: { type: 'integer' },
                      total: { type: 'integer' },
                      totalPages: { type: 'integer' }
                    }
                  }
                }
              }
            }
          }
        },
        '404': {
          description: '养殖场不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 获取养殖场的设备列表
  '/farms/{id}/devices': {
    get: {
      tags: ['养殖场管理'],
      summary: '获取养殖场的设备列表',
      description: '获取指定养殖场的所有设备',
      parameters: [
        {
          name: 'id',
          in: 'path',
          required: true,
          schema: { type: 'integer' },
          description: '养殖场ID'
        },
        {
          name: 'type',
          in: 'query',
          schema: { type: 'string', enum: ['sensor', 'camera', 'feeder', 'monitor'] },
          description: '设备类型筛选'
        },
        {
          name: 'status',
          in: 'query',
          schema: { type: 'string', enum: ['online', 'offline', 'maintenance'] },
          description: '设备状态筛选'
        }
      ],
      responses: {
        '200': {
          description: '获取成功',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  success: { type: 'boolean', example: true },
                  data: {
                    type: 'array',
                    items: { $ref: '#/components/schemas/Device' }
                  }
                }
              }
            }
          }
        },
        '404': {
          description: '养殖场不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  },

  // 获取养殖场统计信息
  '/farms/{id}/statistics': {
    get: {
      tags: ['养殖场管理'],
      summary: '获取养殖场统计信息',
      description: '获取指定养殖场的统计数据',
      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: {
                    type: 'object',
                    properties: {
                      totalAnimals: { type: 'integer', description: '动物总数' },
                      healthyAnimals: { type: 'integer', description: '健康动物数' },
                      sickAnimals: { type: 'integer', description: '患病动物数' },
                      totalDevices: { type: 'integer', description: '设备总数' },
                      onlineDevices: { type: 'integer', description: '在线设备数' },
                      offlineDevices: { type: 'integer', description: '离线设备数' },
                      alertsCount: { type: 'integer', description: '预警数量' },
                      utilizationRate: { type: 'number', description: '利用率（%）' }
                    }
                  }
                }
              }
            }
          }
        },
        '404': {
          description: '养殖场不存在',
          content: {
            'application/json': {
              schema: { $ref: '#/components/schemas/ErrorResponse' }
            }
          }
        }
      }
    }
  }
};

// 养殖场数据模型
const farmSchemas = {
  Farm: {
    type: 'object',
    properties: {
      id: { type: 'integer', description: '养殖场ID' },
      name: { type: 'string', description: '养殖场名称' },
      address: { type: 'string', description: '养殖场地址' },
      type: { 
        type: 'string', 
        enum: ['cattle', 'sheep', 'pig', 'poultry'],
        description: '养殖类型：cattle-牛，sheep-羊，pig-猪，poultry-家禽'
      },
      description: { type: 'string', description: '养殖场描述' },
      area: { type: 'number', description: '养殖场面积（平方米）' },
      capacity: { type: 'integer', description: '最大养殖容量' },
      currentCount: { type: 'integer', description: '当前动物数量' },
      contactPhone: { type: 'string', description: '联系电话' },
      contactEmail: { type: 'string', format: 'email', description: '联系邮箱' },
      coordinates: {
        type: 'object',
        properties: {
          latitude: { type: 'number', description: '纬度' },
          longitude: { type: 'number', description: '经度' }
        },
        description: '地理坐标'
      },
      status: { 
        type: 'string', 
        enum: ['active', 'inactive', 'suspended'],
        description: '养殖场状态：active-活跃，inactive-未激活，suspended-暂停'
      },
      owner: {
        type: 'object',
        properties: {
          id: { type: 'integer' },
          username: { type: 'string' },
          realName: { type: 'string' },
          phone: { type: 'string' }
        },
        description: '养殖场主信息'
      },
      createdAt: { type: 'string', format: 'date-time', description: '创建时间' },
      updatedAt: { type: 'string', format: 'date-time', description: '更新时间' }
    }
  }
};

module.exports = { farmsPaths, farmSchemas };