完善养殖端小程序

backend/swagger-integrated.js

@@ -0,0 +1,498 @@
+/**
+ * 宁夏智慧养殖监管平台 - 完整API文档整合配置
+ * @file swagger-integrated.js
+ * @description 整合所有模块的Swagger API文档
+ */
+
+const swaggerJSDoc = require('swagger-jsdoc');
+
+// 导入各模块的Swagger文档
+const { usersPaths, usersSchemas } = require('./swagger-users');
+const { authPaths, authSchemas } = require('./swagger-auth');
+const { farmsPaths, farmsSchemas } = require('./swagger-farms');
+const { animalsPaths, animalsSchemas } = require('./swagger-animals');
+const { devicesPaths, devicesSchemas } = require('./swagger-devices');
+const { alertsPaths, alertSchemas } = require('./swagger-alerts');
+const { smartAlertsPaths, smartAlertsSchemas } = require('./swagger-smart-alerts');
+const { statsPaths, statsSchemas } = require('./swagger-stats');
+const { reportsPaths, reportsSchemas } = require('./swagger-reports');
+const { systemPaths, systemSchemas } = require('./swagger-system');
+
+const options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: '宁夏智慧养殖监管平台 API',
+      version: '2.0.0',
+      description: `
+        # 宁夏智慧养殖监管平台API文档
+        
+        ## 平台概述
+        宁夏智慧养殖监管平台是一个集成了物联网、大数据、人工智能等技术的现代化养殖管理系统。
+        
+        ## 功能模块
+        
+        ### 🔐 用户认证与权限
+        - **用户认证**: 登录、注册、JWT令牌管理
+        - **用户管理**: 用户信息管理、角色权限分配
+        - **权限控制**: 基于角色的访问控制(RBAC)
+        
+        ### 🏭 养殖场管理
+        - **养殖场信息**: 养殖场基本信息管理
+        - **圈舍管理**: 圈舍分配、容量管理
+        - **养殖场统计**: 养殖场数据统计分析
+        
+        ### 🐄 动物管理
+        - **动物档案**: 牲畜基本信息、健康档案
+        - **批次管理**: 动物批次跟踪、转移记录
+        - **繁殖管理**: 配种、产仔记录管理
+        - **健康监控**: 疫苗接种、疾病记录
+        
+        ### 📱 设备管理
+        - **IoT设备**: 智能耳标、项圈设备管理
+        - **设备绑定**: 设备与动物绑定关系
+        - **设备监控**: 设备状态、电量、信号监控
+        - **维护记录**: 设备维护、故障记录
+        
+        ### ⚠️ 预警系统
+        - **智能预警**: 健康、环境、设备预警
+        - **预警处理**: 预警状态管理、处理记录
+        - **预警统计**: 预警数据分析、趋势分析
+        
+        ### 🗺️ 地理信息
+        - **电子围栏**: 围栏设置、越界预警
+        - **位置追踪**: 动物位置实时监控
+        - **地图服务**: 地图展示、轨迹回放
+        
+        ### 📊 数据统计
+        - **实时统计**: 养殖场、动物、设备实时数据
+        - **报表生成**: 各类统计报表、数据导出
+        - **数据分析**: 趋势分析、预测分析
+        
+        ### ⚙️ 系统管理
+        - **系统配置**: 系统参数配置
+        - **菜单管理**: 系统菜单权限配置
+        - **操作日志**: 系统操作记录审计
+        - **数据备份**: 数据备份与恢复
+        
+        ## 认证方式
+        
+        本API使用JWT(JSON Web Token)进行身份认证。
+        
+        ### 获取Token
+        1. 调用登录接口 \`POST /auth/login\` 获取访问令牌
+        2. 在后续请求的Header中添加: \`Authorization: Bearer <token>\`
+        
+        ### Token格式
+        \`\`\`
+        Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+        \`\`\`
+        
+        ## 响应格式
+        
+        ### 成功响应
+        \`\`\`json
+        {
+          "success": true,
+          "message": "操作成功",
+          "data": { ... },
+          "total": 100,
+          "pagination": {
+            "page": 1,
+            "limit": 10,
+            "total": 100,
+            "totalPages": 10
+          }
+        }
+        \`\`\`
+        
+        ### 错误响应
+        \`\`\`json
+        {
+          "success": false,
+          "message": "错误描述",
+          "error": "详细错误信息"
+        }
+        \`\`\`
+        
+        ## 状态码说明
+        
+        | 状态码 | 说明 |
+        |--------|------|
+        | 200 | 请求成功 |
+        | 201 | 创建成功 |
+        | 400 | 请求参数错误 |
+        | 401 | 未授权访问 |
+        | 403 | 权限不足 |
+        | 404 | 资源不存在 |
+        | 500 | 服务器内部错误 |
+        
+        ## 分页参数
+        
+        大部分列表接口支持分页查询：
+        - \`page\`: 页码，从1开始
+        - \`limit\`: 每页数量，默认10，最大100
+        - \`search\`: 搜索关键词
+        
+        ## 联系方式
+        
+        - 开发团队: dev@nxxm.com
+        - 技术支持: support@nxxm.com
+        - 项目地址: https://github.com/nxxm/breeding-platform
+      `,
+      contact: {
+        name: '宁夏智慧养殖平台开发团队',
+        email: 'dev@nxxm.com',
+        url: 'https://www.nxxm.com'
+      },
+      license: {
+        name: 'MIT License',
+        url: 'https://opensource.org/licenses/MIT'
+      },
+      termsOfService: 'https://www.nxxm.com/terms'
+    },
+    servers: [
+      {
+        url: 'http://localhost:5350/api',
+        description: '本地开发环境'
+      },
+      {
+        url: 'https://dev-api.nxxm.com/api',
+        description: '开发测试环境'
+      },
+      {
+        url: 'https://staging-api.nxxm.com/api',
+        description: '预发布环境'
+      },
+      {
+        url: 'https://api.nxxm.com/api',
+        description: '生产环境'
+      }
+    ],
+    tags: [
+      {
+        name: '用户认证',
+        description: '用户登录、注册、JWT令牌管理',
+        externalDocs: {
+          description: '认证文档',
+          url: 'https://docs.nxxm.com/auth'
+        }
+      },
+      {
+        name: '用户管理',
+        description: '用户信息管理、角色权限分配'
+      },
+      {
+        name: '养殖场管理',
+        description: '养殖场信息的增删改查、统计分析'
+      },
+      {
+        name: '动物管理',
+        description: '牲畜信息管理、批次管理、健康档案'
+      },
+      {
+        name: '圈舍管理',
+        description: '圈舍信息管理、牲畜圈舍分配'
+      },
+      {
+        name: '设备管理',
+        description: 'IoT设备管理、设备绑定、状态监控'
+      },
+      {
+        name: '智能设备',
+        description: '智能耳标、智能项圈等设备管理'
+      },
+      {
+        name: '预警管理',
+        description: '系统预警、告警处理、预警统计'
+      },
+      {
+        name: '智能预警',
+        description: '智能耳标、项圈预警系统'
+      },
+      {
+        name: '电子围栏',
+        description: '电子围栏设置、围栏点管理'
+      },
+      {
+        name: '地图服务',
+        description: '地图相关功能、位置服务'
+      },
+      {
+        name: '数据统计',
+        description: '各类统计数据、实时监控'
+      },
+      {
+        name: '报表管理',
+        description: '报表生成、数据导出功能'
+      },
+      {
+        name: '系统管理',
+        description: '系统配置、菜单管理、权限配置'
+      },
+      {
+        name: '备份管理',
+        description: '数据备份、恢复功能'
+      },
+      {
+        name: '操作日志',
+        description: '系统操作日志记录和查询'
+      },
+      {
+        name: '产品管理',
+        description: '产品信息管理'
+      },
+      {
+        name: '订单管理',
+        description: '订单处理、订单查询'
+      }
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT',
+          description: 'JWT认证令牌，格式：Bearer <token>'
+        },
+        apiKey: {
+          type: 'apiKey',
+          in: 'header',
+          name: 'X-API-Key',
+          description: 'API密钥认证（用于第三方集成）'
+        }
+      },
+      schemas: {
+        // 通用响应模型
+        ApiResponse: {
+          type: 'object',
+          properties: {
+            success: {
+              type: 'boolean',
+              description: '请求是否成功',
+              example: true
+            },
+            message: {
+              type: 'string',
+              description: '响应消息',
+              example: '操作成功'
+            },
+            data: {
+              description: '响应数据，具体结构根据接口而定'
+            },
+            total: {
+              type: 'integer',
+              description: '总记录数（分页时使用）',
+              example: 100
+            },
+            pagination: {
+              type: 'object',
+              properties: {
+                page: { type: 'integer', description: '当前页码', example: 1 },
+                limit: { type: 'integer', description: '每页记录数', example: 10 },
+                total: { type: 'integer', description: '总记录数', example: 100 },
+                totalPages: { type: 'integer', description: '总页数', example: 10 }
+              }
+            }
+          }
+        },
+        
+        ErrorResponse: {
+          type: 'object',
+          properties: {
+            success: {
+              type: 'boolean',
+              example: false,
+              description: '请求是否成功'
+            },
+            message: {
+              type: 'string',
+              description: '错误消息',
+              example: '请求失败'
+            },
+            error: {
+              type: 'string',
+              description: '详细错误信息',
+              example: '参数验证失败'
+            },
+            code: {
+              type: 'string',
+              description: '错误代码',
+              example: 'VALIDATION_ERROR'
+            }
+          }
+        },
+        
+        PaginationQuery: {
+          type: 'object',
+          properties: {
+            page: {
+              type: 'integer',
+              minimum: 1,
+              default: 1,
+              description: '页码，从1开始'
+            },
+            limit: {
+              type: 'integer',
+              minimum: 1,
+              maximum: 100,
+              default: 10,
+              description: '每页记录数，最大100'
+            },
+            search: {
+              type: 'string',
+              description: '搜索关键词'
+            },
+            sortBy: {
+              type: 'string',
+              description: '排序字段'
+            },
+            sortOrder: {
+              type: 'string',
+              enum: ['asc', 'desc'],
+              default: 'desc',
+              description: '排序方向'
+            }
+          }
+        },
+        
+        // 整合各模块的数据模型
+        ...usersSchemas,
+        ...authSchemas,
+        ...farmsSchemas,
+        ...animalsSchemas,
+        ...devicesSchemas,
+        ...alertSchemas,
+        ...smartAlertsSchemas,
+        ...statsSchemas,
+        ...reportsSchemas,
+        ...systemSchemas
+      },
+      
+      parameters: {
+        PageParam: {
+          name: 'page',
+          in: 'query',
+          schema: { type: 'integer', minimum: 1, default: 1 },
+          description: '页码'
+        },
+        LimitParam: {
+          name: 'limit',
+          in: 'query',
+          schema: { type: 'integer', minimum: 1, maximum: 100, default: 10 },
+          description: '每页数量'
+        },
+        SearchParam: {
+          name: 'search',
+          in: 'query',
+          schema: { type: 'string' },
+          description: '搜索关键词'
+        },
+        IdParam: {
+          name: 'id',
+          in: 'path',
+          required: true,
+          schema: { type: 'integer' },
+          description: '资源ID'
+        }
+      },
+      
+      responses: {
+        Success: {
+          description: '操作成功',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/ApiResponse' }
+            }
+          }
+        },
+        Created: {
+          description: '创建成功',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/ApiResponse' }
+            }
+          }
+        },
+        BadRequest: {
+          description: '请求参数错误',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+            }
+          }
+        },
+        Unauthorized: {
+          description: '未授权访问',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+            }
+          }
+        },
+        Forbidden: {
+          description: '权限不足',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+            }
+          }
+        },
+        NotFound: {
+          description: '资源不存在',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+            }
+          }
+        },
+        InternalError: {
+          description: '服务器内部错误',
+          content: {
+            'application/json': {
+              schema: { $ref: '#/components/schemas/ErrorResponse' }
+            }
+          }
+        }
+      }
+    },
+    
+    security: [
+      { bearerAuth: [] }
+    ],
+    
+    // 整合所有模块的API路径
+    paths: {
+      ...authPaths,
+      ...usersPaths,
+      ...farmsPaths,
+      ...animalsPaths,
+      ...devicesPaths,
+      ...alertsPaths,
+      ...smartAlertsPaths,
+      ...statsPaths,
+      ...reportsPaths,
+      ...systemPaths
+    }
+  },
+  
+  apis: [
+    './routes/*.js',
+    './controllers/*.js',
+    './swagger-*.js'
+  ]
+};
+
+const specs = swaggerJSDoc(options);
+
+// 确保paths对象存在
+if (!specs.paths) {
+  specs.paths = {};
+}
+
+// 添加API版本信息
+specs.info.version = '2.0.0';
+specs.info['x-api-version'] = '2.0';
+specs.info['x-build-date'] = new Date().toISOString();
+
+module.exports = specs;