完善养殖端小程序
This commit is contained in:
xuqiuyun
@@ -45,7 +45,7 @@ exports.getCollarAlertStats = async (req, res) => {
|
||||
const dailySteps = totalSteps - yesterdaySteps;
|
||||
|
||||
// 离线预警
|
||||
if (device.state === 0) {
|
||||
if (device.is_connect === 0) {
|
||||
stats.offline++;
|
||||
stats.totalAlerts++;
|
||||
}
|
||||
@@ -191,8 +191,8 @@ exports.getCollarAlerts = async (req, res) => {
|
||||
alert.battery = actualBattery;
|
||||
alert.temperature = actualTemperature;
|
||||
alert.alertTime = alertTime;
|
||||
alert.deviceStatus = device.state === 1 ? '在线' : '离线';
|
||||
alert.gpsSignal = device.state === 1 ? '强' : '无';
|
||||
alert.deviceStatus = device.is_connect === 1 ? '在线' : '离线';
|
||||
alert.gpsSignal = device.is_connect === 1 ? '强' : '无';
|
||||
alert.wearStatus = device.bandge_status === 1 ? '已佩戴' : '未佩戴';
|
||||
alert.longitude = 116.3974 + (device.id % 100) * 0.0001;
|
||||
alert.latitude = 39.9093 + (device.id % 100) * 0.0001;
|
||||
@@ -200,7 +200,7 @@ exports.getCollarAlerts = async (req, res) => {
|
||||
};
|
||||
|
||||
// 离线预警
|
||||
if (device.state === 0) {
|
||||
if (device.is_connect === 0) {
|
||||
allAlerts.push(addBaseInfoToAlert({
|
||||
id: `${device.id}_offline`,
|
||||
alertType: 'offline',
|
||||
@@ -584,8 +584,8 @@ exports.exportCollarAlerts = async (req, res) => {
|
||||
alert.battery = actualBattery;
|
||||
alert.temperature = actualTemperature;
|
||||
alert.alertTime = alertTime;
|
||||
alert.deviceStatus = device.state === 1 ? '在线' : '离线';
|
||||
alert.gpsSignal = device.state === 1 ? '强' : '无';
|
||||
alert.deviceStatus = device.is_connect === 1 ? '在线' : '离线';
|
||||
alert.gpsSignal = device.is_connect === 1 ? '强' : '无';
|
||||
alert.wearStatus = device.bandge_status === 1 ? '已佩戴' : '未佩戴';
|
||||
alert.longitude = 116.3974 + (device.id % 100) * 0.0001;
|
||||
alert.latitude = 39.9093 + (device.id % 100) * 0.0001;
|
||||
|
||||
@@ -17,7 +17,7 @@ class IotXqClient extends Model {
|
||||
2: '报警',
|
||||
3: '维护'
|
||||
};
|
||||
return statusMap[this.state] || '未知';
|
||||
return statusMap[this.is_connect] || '未知';
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -30,7 +30,7 @@ class IotXqClient extends Model {
|
||||
2: 'orange', // 报警
|
||||
3: 'blue' // 维护
|
||||
};
|
||||
return colorMap[this.state] || 'default';
|
||||
return colorMap[this.is_connect] || 'default';
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -128,9 +128,9 @@ const swaggerOptions = {
|
||||
customfavIcon: '/favicon.ico'
|
||||
};
|
||||
|
||||
// 使用简化的API文档配置
|
||||
const simpleSwaggerSpec = require('./swagger-simple');
|
||||
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(simpleSwaggerSpec, swaggerOptions));
|
||||
// Swagger 文档路由配置 - 使用完整的集成配置
|
||||
const integratedSwaggerSpec = require('./swagger-integrated');
|
||||
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(integratedSwaggerSpec, swaggerOptions));
|
||||
|
||||
// 基础路由
|
||||
app.get('/', (req, res) => {
|
||||
|
||||
773
backend/swagger-alerts.js
Normal file
773
backend/swagger-alerts.js
Normal file
@@ -0,0 +1,773 @@
|
||||
/**
|
||||
* 预警管理模块 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 };
|
||||
706
backend/swagger-animals.js
Normal file
706
backend/swagger-animals.js
Normal file
@@ -0,0 +1,706 @@
|
||||
/**
|
||||
* 动物管理模块 Swagger 文档
|
||||
* @file swagger-animals.js
|
||||
*/
|
||||
|
||||
const animalsPaths = {
|
||||
// 获取所有动物列表
|
||||
'/animals': {
|
||||
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: 'farmId',
|
||||
in: 'query',
|
||||
schema: { type: 'integer' },
|
||||
description: '养殖场ID筛选'
|
||||
},
|
||||
{
|
||||
name: 'status',
|
||||
in: 'query',
|
||||
schema: { type: 'string', enum: ['healthy', 'sick', 'quarantine', 'sold'] },
|
||||
description: '动物状态筛选'
|
||||
},
|
||||
{
|
||||
name: 'category',
|
||||
in: 'query',
|
||||
schema: { type: 'integer', enum: [1, 2, 3, 4, 5, 6] },
|
||||
description: '动物类别筛选：1-犊牛，2-育成母牛，3-架子牛，4-青年牛，5-基础母牛，6-育肥牛'
|
||||
},
|
||||
{
|
||||
name: 'sex',
|
||||
in: 'query',
|
||||
schema: { type: 'integer', enum: [1, 2] },
|
||||
description: '性别筛选：1-公牛，2-母牛'
|
||||
}
|
||||
],
|
||||
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' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
post: {
|
||||
tags: ['动物管理'],
|
||||
summary: '创建新动物档案',
|
||||
description: '创建新的动物档案记录',
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
required: ['earNumber', 'sex', 'varieties', 'cate', 'farmId'],
|
||||
properties: {
|
||||
earNumber: { type: 'string', description: '耳标号' },
|
||||
sex: { type: 'integer', enum: [1, 2], description: '性别：1-公牛，2-母牛' },
|
||||
strain: { type: 'string', description: '品系' },
|
||||
varieties: { type: 'integer', description: '品种ID' },
|
||||
cate: {
|
||||
type: 'integer',
|
||||
enum: [1, 2, 3, 4, 5, 6],
|
||||
description: '类别：1-犊牛，2-育成母牛，3-架子牛，4-青年牛，5-基础母牛，6-育肥牛'
|
||||
},
|
||||
birthWeight: { type: 'number', description: '出生重量（kg）' },
|
||||
birthday: { type: 'integer', description: '出生日期（时间戳）' },
|
||||
farmId: { type: 'integer', description: '养殖场ID' },
|
||||
penId: { type: 'integer', description: '栏舍ID' },
|
||||
batchId: { type: 'integer', description: '批次ID' },
|
||||
intoTime: { type: 'integer', description: '入场时间（时间戳）' },
|
||||
parity: { type: 'integer', description: '胎次' },
|
||||
source: {
|
||||
type: 'integer',
|
||||
enum: [1, 2, 3, 4, 5],
|
||||
description: '来源：1-合作社，2-农户，3-养殖场，4-进口，5-自繁'
|
||||
},
|
||||
sourceDay: { type: 'integer', description: '来源日龄' },
|
||||
sourceWeight: { type: 'number', description: '来源重量（kg）' },
|
||||
weight: { type: 'number', description: '当前重量（kg）' },
|
||||
algebra: { type: 'string', description: '代数' },
|
||||
colour: { type: 'string', description: '毛色' },
|
||||
descent: { type: 'string', description: '血统' },
|
||||
imgs: { type: 'string', description: '图片URL（多个用逗号分隔）' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'201': {
|
||||
description: '创建成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '动物档案创建成功' },
|
||||
data: { $ref: '#/components/schemas/Animal' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'400': {
|
||||
description: '请求参数错误',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 公共动物数据
|
||||
'/animals/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' },
|
||||
earNumber: { type: 'string' },
|
||||
sex: { type: 'integer' },
|
||||
varieties: { type: 'integer' },
|
||||
cate: { type: 'integer' },
|
||||
weight: { type: 'number' },
|
||||
isOut: { type: 'integer' }
|
||||
}
|
||||
}
|
||||
},
|
||||
message: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 获取动物绑定信息
|
||||
'/animals/binding-info/{collarNumber}': {
|
||||
get: {
|
||||
tags: ['动物管理'],
|
||||
summary: '获取动物绑定信息',
|
||||
description: '根据项圈编号获取动物的详细绑定信息',
|
||||
parameters: [
|
||||
{
|
||||
name: 'collarNumber',
|
||||
in: 'path',
|
||||
required: true,
|
||||
schema: { type: 'string' },
|
||||
description: '项圈编号'
|
||||
}
|
||||
],
|
||||
responses: {
|
||||
'200': {
|
||||
description: '获取成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string' },
|
||||
data: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
basicInfo: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
collarNumber: { type: 'string', description: '项圈编号' },
|
||||
category: { type: 'string', description: '动物类别' },
|
||||
calvingCount: { type: 'integer', description: '产犊次数' },
|
||||
earTag: { type: 'string', description: '耳标号' },
|
||||
animalType: { type: 'string', description: '动物类型' },
|
||||
breed: { type: 'string', description: '品种' },
|
||||
sourceType: { type: 'string', description: '来源类型' }
|
||||
}
|
||||
},
|
||||
birthInfo: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
birthDate: { type: 'string', description: '出生日期' },
|
||||
birthWeight: { type: 'string', description: '出生重量' },
|
||||
weaningWeight: { type: 'string', description: '断奶重量' },
|
||||
entryDate: { type: 'string', description: '入场日期' },
|
||||
weaningAge: { type: 'integer', description: '断奶日龄' }
|
||||
}
|
||||
},
|
||||
pedigreeInfo: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
fatherId: { type: 'string', description: '父亲ID' },
|
||||
motherId: { type: 'string', description: '母亲ID' },
|
||||
grandfatherId: { type: 'string', description: '祖父ID' },
|
||||
grandmotherId: { type: 'string', description: '祖母ID' },
|
||||
bloodline: { type: 'string', description: '血统' },
|
||||
generation: { type: 'string', description: '世代' }
|
||||
}
|
||||
},
|
||||
insuranceInfo: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
policyNumber: { type: 'string', description: '保单号' },
|
||||
insuranceCompany: { type: 'string', description: '保险公司' },
|
||||
coverageAmount: { type: 'string', description: '保额' },
|
||||
premium: { type: 'string', description: '保费' },
|
||||
startDate: { type: 'string', description: '开始日期' },
|
||||
endDate: { type: 'string', description: '结束日期' },
|
||||
status: { type: 'string', description: '保险状态' }
|
||||
}
|
||||
},
|
||||
loanInfo: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
loanNumber: { type: 'string', description: '贷款编号' },
|
||||
bankName: { type: 'string', description: '银行名称' },
|
||||
loanAmount: { type: 'string', description: '贷款金额' },
|
||||
interestRate: { type: 'string', description: '利率' },
|
||||
loanDate: { type: 'string', description: '放款日期' },
|
||||
maturityDate: { type: 'string', description: '到期日期' },
|
||||
status: { type: 'string', description: '贷款状态' }
|
||||
}
|
||||
},
|
||||
deviceInfo: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
deviceId: { type: 'integer', description: '设备ID' },
|
||||
batteryLevel: { type: 'number', description: '电池电量' },
|
||||
temperature: { type: 'number', description: '温度' },
|
||||
status: { type: 'string', description: '设备状态' },
|
||||
lastUpdate: { type: 'string', description: '最后更新时间' },
|
||||
location: { type: 'string', description: '位置信息' }
|
||||
}
|
||||
},
|
||||
farmInfo: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
farmName: { type: 'string', description: '农场名称' },
|
||||
farmAddress: { type: 'string', description: '农场地址' },
|
||||
penName: { type: 'string', description: '栏舍名称' },
|
||||
batchName: { type: 'string', description: '批次名称' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'404': {
|
||||
description: '未找到指定的动物或设备',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 获取指定动物详情
|
||||
'/animals/{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/Animal' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'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: {
|
||||
earNumber: { type: 'string', description: '耳标号' },
|
||||
sex: { type: 'integer', enum: [1, 2], description: '性别' },
|
||||
strain: { type: 'string', description: '品系' },
|
||||
varieties: { type: 'integer', description: '品种ID' },
|
||||
cate: { type: 'integer', enum: [1, 2, 3, 4, 5, 6], description: '类别' },
|
||||
weight: { type: 'number', description: '当前重量（kg）' },
|
||||
penId: { type: 'integer', description: '栏舍ID' },
|
||||
batchId: { type: 'integer', description: '批次ID' },
|
||||
event: { type: 'string', description: '事件记录' },
|
||||
eventTime: { type: 'integer', description: '事件时间（时间戳）' },
|
||||
isVaccin: { type: 'integer', enum: [0, 1], description: '是否疫苗' },
|
||||
isInsemination: { type: 'integer', enum: [0, 1], description: '是否配种' },
|
||||
isInsure: { type: 'integer', enum: [0, 1], description: '是否保险' },
|
||||
isMortgage: { type: 'integer', enum: [0, 1], description: '是否抵押' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'200': {
|
||||
description: '更新成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '动物信息更新成功' },
|
||||
data: { $ref: '#/components/schemas/Animal' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'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' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 动物健康记录
|
||||
'/animals/{id}/health': {
|
||||
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: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
animalId: { type: 'integer' },
|
||||
checkDate: { type: 'string', format: 'date' },
|
||||
temperature: { type: 'number' },
|
||||
weight: { type: 'number' },
|
||||
healthStatus: { type: 'string' },
|
||||
symptoms: { type: 'string' },
|
||||
treatment: { type: 'string' },
|
||||
veterinarian: { type: 'string' },
|
||||
notes: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
post: {
|
||||
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: ['checkDate', 'healthStatus'],
|
||||
properties: {
|
||||
checkDate: { type: 'string', format: 'date', description: '检查日期' },
|
||||
temperature: { type: 'number', description: '体温' },
|
||||
weight: { type: 'number', description: '体重' },
|
||||
healthStatus: {
|
||||
type: 'string',
|
||||
enum: ['healthy', 'sick', 'recovering', 'quarantine'],
|
||||
description: '健康状态'
|
||||
},
|
||||
symptoms: { type: 'string', description: '症状描述' },
|
||||
treatment: { type: 'string', description: '治疗方案' },
|
||||
veterinarian: { type: 'string', description: '兽医姓名' },
|
||||
notes: { type: 'string', description: '备注' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'201': {
|
||||
description: '添加成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '健康记录添加成功' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 动物繁殖记录
|
||||
'/animals/{id}/breeding': {
|
||||
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: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
animalId: { type: 'integer' },
|
||||
breedingDate: { type: 'string', format: 'date' },
|
||||
matingType: { type: 'string', enum: ['natural', 'artificial'] },
|
||||
sireId: { type: 'integer' },
|
||||
expectedCalvingDate: { type: 'string', format: 'date' },
|
||||
actualCalvingDate: { type: 'string', format: 'date' },
|
||||
calvingResult: { type: 'string' },
|
||||
offspringCount: { type: 'integer' },
|
||||
notes: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// 动物数据模型
|
||||
const animalSchemas = {
|
||||
Animal: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer', description: '动物ID' },
|
||||
orgId: { type: 'integer', description: '组织ID' },
|
||||
earNumber: { type: 'string', description: '耳标号' },
|
||||
sex: {
|
||||
type: 'integer',
|
||||
enum: [1, 2],
|
||||
description: '性别：1-公牛，2-母牛'
|
||||
},
|
||||
strain: { type: 'string', description: '品系' },
|
||||
varieties: { type: 'integer', description: '品种ID' },
|
||||
cate: {
|
||||
type: 'integer',
|
||||
enum: [1, 2, 3, 4, 5, 6],
|
||||
description: '类别：1-犊牛，2-育成母牛，3-架子牛，4-青年牛，5-基础母牛，6-育肥牛'
|
||||
},
|
||||
birthWeight: { type: 'number', description: '出生重量（kg）' },
|
||||
birthday: { type: 'integer', description: '出生日期（时间戳）' },
|
||||
penId: { type: 'integer', description: '栏舍ID' },
|
||||
intoTime: { type: 'integer', description: '入场时间（时间戳）' },
|
||||
parity: { type: 'integer', description: '胎次' },
|
||||
source: {
|
||||
type: 'integer',
|
||||
enum: [1, 2, 3, 4, 5],
|
||||
description: '来源：1-合作社，2-农户，3-养殖场，4-进口，5-自繁'
|
||||
},
|
||||
sourceDay: { type: 'integer', description: '来源日龄' },
|
||||
sourceWeight: { type: 'number', description: '来源重量（kg）' },
|
||||
weight: { type: 'number', description: '当前重量（kg）' },
|
||||
event: { type: 'string', description: '事件记录' },
|
||||
eventTime: { type: 'integer', description: '事件时间（时间戳）' },
|
||||
lactationDay: { type: 'integer', description: '泌乳天数' },
|
||||
semenNum: { type: 'string', description: '精液编号' },
|
||||
isWear: { type: 'integer', enum: [0, 1], description: '是否佩戴设备' },
|
||||
batchId: { type: 'integer', description: '批次ID' },
|
||||
imgs: { type: 'string', description: '图片URL（多个用逗号分隔）' },
|
||||
isEleAuth: { type: 'integer', enum: [0, 1], description: '是否电子认证' },
|
||||
isQuaAuth: { type: 'integer', enum: [0, 1], description: '是否质量认证' },
|
||||
isDelete: { type: 'integer', enum: [0, 1], description: '是否删除' },
|
||||
isOut: { type: 'integer', enum: [0, 1], description: '是否出栏' },
|
||||
createUid: { type: 'integer', description: '创建用户ID' },
|
||||
createTime: { type: 'integer', description: '创建时间（时间戳）' },
|
||||
algebra: { type: 'string', description: '代数' },
|
||||
colour: { type: 'string', description: '毛色' },
|
||||
infoWeight: { type: 'number', description: '信息重量' },
|
||||
descent: { type: 'string', description: '血统' },
|
||||
isVaccin: { type: 'integer', enum: [0, 1], description: '是否疫苗' },
|
||||
isInsemination: { type: 'integer', enum: [0, 1], description: '是否配种' },
|
||||
isInsure: { type: 'integer', enum: [0, 1], description: '是否保险' },
|
||||
isMortgage: { type: 'integer', enum: [0, 1], description: '是否抵押' },
|
||||
updateTime: { type: 'integer', description: '更新时间（时间戳）' },
|
||||
breedBullTime: { type: 'integer', description: '配种时间（时间戳）' },
|
||||
level: { type: 'string', description: '等级' },
|
||||
sixWeight: { type: 'number', description: '6月龄重量' },
|
||||
eighteenWeight: { type: 'number', description: '18月龄重量' },
|
||||
twelveDayWeight: { type: 'number', description: '12日龄重量' },
|
||||
eighteenDayWeight: { type: 'number', description: '18日龄重量' },
|
||||
xxivDayWeight: { type: 'number', description: '24日龄重量' },
|
||||
semenBreedImgs: { type: 'string', description: '配种图片' },
|
||||
sellStatus: { type: 'integer', description: '销售状态' },
|
||||
weightCalculateTime: { type: 'integer', description: '重量计算时间' },
|
||||
dayOfBirthday: { type: 'integer', description: '出生天数' },
|
||||
userId: { type: 'integer', description: '用户ID' }
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
module.exports = { animalsPaths, animalSchemas };
|
||||
412
backend/swagger-auth.js
Normal file
412
backend/swagger-auth.js
Normal file
@@ -0,0 +1,412 @@
|
||||
/**
|
||||
* 用户认证模块 Swagger 文档
|
||||
* @file swagger-auth.js
|
||||
*/
|
||||
|
||||
const authPaths = {
|
||||
// 用户登录
|
||||
'/auth/login': {
|
||||
post: {
|
||||
tags: ['用户认证'],
|
||||
summary: '用户登录',
|
||||
description: '用户通过用户名/邮箱和密码登录系统',
|
||||
security: [], // 登录接口不需要认证
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
required: ['username', 'password'],
|
||||
properties: {
|
||||
username: {
|
||||
type: 'string',
|
||||
description: '用户名或邮箱',
|
||||
example: 'admin'
|
||||
},
|
||||
password: {
|
||||
type: 'string',
|
||||
description: '密码',
|
||||
example: '123456'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'200': {
|
||||
description: '登录成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '登录成功' },
|
||||
token: { type: 'string', description: 'JWT Token' },
|
||||
user: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
username: { type: 'string' },
|
||||
email: { type: 'string' },
|
||||
phone: { type: 'string' },
|
||||
avatar: { type: 'string' },
|
||||
status: { type: 'string' },
|
||||
roles: { type: 'array', items: { type: 'object' } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'400': {
|
||||
description: '请求参数错误',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
},
|
||||
'401': {
|
||||
description: '用户名或密码错误',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
},
|
||||
'429': {
|
||||
description: '登录尝试次数过多，请稍后再试',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 用户注册
|
||||
'/auth/register': {
|
||||
post: {
|
||||
tags: ['用户认证'],
|
||||
summary: '用户注册',
|
||||
description: '新用户注册账号',
|
||||
security: [], // 注册接口不需要认证
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
required: ['username', 'email', 'password'],
|
||||
properties: {
|
||||
username: {
|
||||
type: 'string',
|
||||
description: '用户名',
|
||||
example: 'newuser'
|
||||
},
|
||||
email: {
|
||||
type: 'string',
|
||||
format: 'email',
|
||||
description: '邮箱地址',
|
||||
example: 'newuser@example.com'
|
||||
},
|
||||
password: {
|
||||
type: 'string',
|
||||
minLength: 6,
|
||||
description: '密码（至少6位）',
|
||||
example: '123456'
|
||||
},
|
||||
phone: {
|
||||
type: 'string',
|
||||
description: '手机号码',
|
||||
example: '13800138000'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'201': {
|
||||
description: '注册成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '注册成功' },
|
||||
user: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
username: { type: 'string' },
|
||||
email: { type: 'string' },
|
||||
phone: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'400': {
|
||||
description: '请求参数错误或用户已存在',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 获取当前用户信息
|
||||
'/auth/me': {
|
||||
get: {
|
||||
tags: ['用户认证'],
|
||||
summary: '获取当前用户信息',
|
||||
description: '获取当前登录用户的详细信息',
|
||||
responses: {
|
||||
'200': {
|
||||
description: '获取成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
data: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
username: { type: 'string' },
|
||||
email: { type: 'string' },
|
||||
phone: { type: 'string' },
|
||||
avatar: { type: 'string' },
|
||||
status: { type: 'string' },
|
||||
roles: { type: 'array', items: { type: 'object' } },
|
||||
permissions: { type: 'array', items: { type: 'string' } },
|
||||
menus: { type: 'array', items: { type: 'object' } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'401': {
|
||||
description: '未授权，Token无效或已过期',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// Token验证
|
||||
'/auth/validate': {
|
||||
get: {
|
||||
tags: ['用户认证'],
|
||||
summary: 'Token验证',
|
||||
description: '验证当前Token是否有效',
|
||||
responses: {
|
||||
'200': {
|
||||
description: 'Token有效',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: 'Token有效' },
|
||||
user: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
username: { type: 'string' },
|
||||
email: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'401': {
|
||||
description: 'Token无效或已过期',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 获取所有角色
|
||||
'/auth/roles': {
|
||||
get: {
|
||||
tags: ['用户认证'],
|
||||
summary: '获取所有角色',
|
||||
description: '获取系统中所有可用的角色列表',
|
||||
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' },
|
||||
description: { type: 'string' },
|
||||
permissions: { type: 'array', items: { type: 'string' } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 为用户分配角色
|
||||
'/auth/users/{userId}/roles': {
|
||||
post: {
|
||||
tags: ['用户认证'],
|
||||
summary: '为用户分配角色',
|
||||
description: '为指定用户分配一个或多个角色',
|
||||
parameters: [
|
||||
{
|
||||
name: 'userId',
|
||||
in: 'path',
|
||||
required: true,
|
||||
schema: { type: 'integer' },
|
||||
description: '用户ID'
|
||||
}
|
||||
],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
required: ['roleIds'],
|
||||
properties: {
|
||||
roleIds: {
|
||||
type: 'array',
|
||||
items: { 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' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 移除用户角色
|
||||
'/auth/users/{userId}/roles/{roleId}': {
|
||||
delete: {
|
||||
tags: ['用户认证'],
|
||||
summary: '移除用户角色',
|
||||
description: '移除用户的指定角色',
|
||||
parameters: [
|
||||
{
|
||||
name: 'userId',
|
||||
in: 'path',
|
||||
required: true,
|
||||
schema: { type: 'integer' },
|
||||
description: '用户ID'
|
||||
},
|
||||
{
|
||||
name: 'roleId',
|
||||
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' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
module.exports = authPaths;
|
||||
223
backend/swagger-complete.js
Normal file
223
backend/swagger-complete.js
Normal file
@@ -0,0 +1,223 @@
|
||||
/**
|
||||
* 完整版Swagger配置
|
||||
* @file swagger-complete.js
|
||||
* @description 宁夏智慧养殖监管平台完整API文档配置
|
||||
*/
|
||||
|
||||
const swaggerJSDoc = require('swagger-jsdoc');
|
||||
|
||||
const options = {
|
||||
definition: {
|
||||
openapi: '3.0.0',
|
||||
info: {
|
||||
title: '宁夏智慧养殖监管平台 API',
|
||||
version: '2.0.0',
|
||||
description: `
|
||||
宁夏智慧养殖监管平台API文档
|
||||
|
||||
## 功能模块
|
||||
- **用户认证**: 登录、注册、权限验证
|
||||
- **用户管理**: 用户CRUD操作、角色管理
|
||||
- **养殖场管理**: 养殖场信息管理
|
||||
- **动物管理**: 牲畜信息管理、批次管理
|
||||
- **设备管理**: IoT设备管理、智能设备
|
||||
- **预警系统**: 智能预警、告警处理
|
||||
- **围栏管理**: 电子围栏设置
|
||||
- **数据统计**: 各类统计报表
|
||||
- **系统管理**: 系统配置、备份等
|
||||
|
||||
## 认证方式
|
||||
使用JWT Token进行身份认证，请在请求头中添加：
|
||||
\`Authorization: Bearer <token>\`
|
||||
`,
|
||||
contact: {
|
||||
name: '开发团队',
|
||||
email: 'dev@nxxm.com'
|
||||
},
|
||||
license: {
|
||||
name: 'MIT',
|
||||
url: 'https://opensource.org/licenses/MIT'
|
||||
}
|
||||
},
|
||||
servers: [
|
||||
{
|
||||
url: 'http://localhost:5350/api',
|
||||
description: '开发环境'
|
||||
},
|
||||
{
|
||||
url: 'https://api.nxxm.com/api',
|
||||
description: '生产环境'
|
||||
}
|
||||
],
|
||||
tags: [
|
||||
{
|
||||
name: '用户认证',
|
||||
description: '用户登录、注册、权限验证相关接口'
|
||||
},
|
||||
{
|
||||
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: '订单处理、订单查询'
|
||||
}
|
||||
],
|
||||
components: {
|
||||
securitySchemes: {
|
||||
bearerAuth: {
|
||||
type: 'http',
|
||||
scheme: 'bearer',
|
||||
bearerFormat: 'JWT',
|
||||
description: 'JWT认证，格式：Bearer <token>'
|
||||
}
|
||||
},
|
||||
schemas: {
|
||||
// 通用响应格式
|
||||
ApiResponse: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: {
|
||||
type: 'boolean',
|
||||
description: '请求是否成功'
|
||||
},
|
||||
message: {
|
||||
type: 'string',
|
||||
description: '响应消息'
|
||||
},
|
||||
data: {
|
||||
description: '响应数据'
|
||||
},
|
||||
total: {
|
||||
type: 'integer',
|
||||
description: '总记录数（分页时使用）'
|
||||
},
|
||||
page: {
|
||||
type: 'integer',
|
||||
description: '当前页码'
|
||||
},
|
||||
limit: {
|
||||
type: 'integer',
|
||||
description: '每页记录数'
|
||||
}
|
||||
}
|
||||
},
|
||||
// 错误响应
|
||||
ErrorResponse: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: {
|
||||
type: 'boolean',
|
||||
example: false
|
||||
},
|
||||
message: {
|
||||
type: 'string',
|
||||
description: '错误消息'
|
||||
},
|
||||
error: {
|
||||
type: 'string',
|
||||
description: '错误详情'
|
||||
}
|
||||
}
|
||||
},
|
||||
// 分页参数
|
||||
PaginationQuery: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
page: {
|
||||
type: 'integer',
|
||||
minimum: 1,
|
||||
default: 1,
|
||||
description: '页码'
|
||||
},
|
||||
limit: {
|
||||
type: 'integer',
|
||||
minimum: 1,
|
||||
maximum: 100,
|
||||
default: 10,
|
||||
description: '每页记录数'
|
||||
},
|
||||
search: {
|
||||
type: 'string',
|
||||
description: '搜索关键词'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
security: [
|
||||
{
|
||||
bearerAuth: []
|
||||
}
|
||||
]
|
||||
},
|
||||
apis: [
|
||||
'./routes/*.js',
|
||||
'./controllers/*.js'
|
||||
]
|
||||
};
|
||||
|
||||
const specs = swaggerJSDoc(options);
|
||||
|
||||
// 手动添加API路径定义
|
||||
if (!specs.paths) {
|
||||
specs.paths = {};
|
||||
}
|
||||
|
||||
module.exports = specs;
|
||||
684
backend/swagger-devices.js
Normal file
684
backend/swagger-devices.js
Normal file
@@ -0,0 +1,684 @@
|
||||
/**
|
||||
* 设备管理模块 Swagger 文档
|
||||
* @file swagger-devices.js
|
||||
*/
|
||||
|
||||
const devicesPaths = {
|
||||
// 获取所有设备
|
||||
'/devices': {
|
||||
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: 'type',
|
||||
in: 'query',
|
||||
schema: { type: 'string' },
|
||||
description: '设备类型筛选'
|
||||
},
|
||||
{
|
||||
name: 'status',
|
||||
in: 'query',
|
||||
schema: { type: 'string', enum: ['online', 'offline', 'maintenance', 'error'] },
|
||||
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/Device' }
|
||||
},
|
||||
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', 'type', 'farmId'],
|
||||
properties: {
|
||||
name: { type: 'string', description: '设备名称' },
|
||||
type: {
|
||||
type: 'string',
|
||||
enum: ['collar', 'ear_tag', 'temperature_sensor', 'humidity_sensor', 'camera', 'feeder', 'water_dispenser'],
|
||||
description: '设备类型'
|
||||
},
|
||||
deviceNumber: { type: 'string', description: '设备编号' },
|
||||
model: { type: 'string', description: '设备型号' },
|
||||
manufacturer: { type: 'string', description: '制造商' },
|
||||
status: {
|
||||
type: 'string',
|
||||
enum: ['online', 'offline', 'maintenance', 'error'],
|
||||
default: 'offline',
|
||||
description: '设备状态'
|
||||
},
|
||||
farmId: { type: 'integer', description: '所属养殖场ID' },
|
||||
location: { type: 'string', description: '设备位置' },
|
||||
installationDate: { type: 'string', format: 'date', description: '安装日期' },
|
||||
lastMaintenance: { type: 'string', format: 'date', description: '最近维护时间' },
|
||||
batteryLevel: { type: 'number', minimum: 0, maximum: 100, description: '电池电量（%）' },
|
||||
firmwareVersion: { type: 'string', description: '固件版本' },
|
||||
specifications: { type: 'object', description: '设备规格参数' },
|
||||
notes: { type: 'string', description: '备注' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'201': {
|
||||
description: '创建成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '设备创建成功' },
|
||||
data: { $ref: '#/components/schemas/Device' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'400': {
|
||||
description: '请求参数错误',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 公共设备数据
|
||||
'/devices/public': {
|
||||
get: {
|
||||
tags: ['设备管理'],
|
||||
summary: '获取公共设备数据',
|
||||
description: '获取可公开访问的设备基本信息',
|
||||
security: [], // 公共接口不需要认证
|
||||
parameters: [
|
||||
{
|
||||
name: 'type',
|
||||
in: 'query',
|
||||
schema: { type: 'string' },
|
||||
description: '设备类型筛选'
|
||||
},
|
||||
{
|
||||
name: 'status',
|
||||
in: 'query',
|
||||
schema: { type: 'string' },
|
||||
description: '设备状态筛选'
|
||||
}
|
||||
],
|
||||
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' },
|
||||
status: { type: 'string' },
|
||||
location: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 搜索设备
|
||||
'/devices/search': {
|
||||
get: {
|
||||
tags: ['设备管理'],
|
||||
summary: '搜索设备',
|
||||
description: '根据设备名称搜索设备',
|
||||
parameters: [
|
||||
{
|
||||
name: 'name',
|
||||
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/Device' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 设备统计 - 按状态
|
||||
'/devices/stats/status': {
|
||||
get: {
|
||||
tags: ['设备管理'],
|
||||
summary: '按状态统计设备数量',
|
||||
description: '获取不同状态下的设备数量统计',
|
||||
responses: {
|
||||
'200': {
|
||||
description: '统计成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
data: {
|
||||
type: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
status: { type: 'string', example: 'online' },
|
||||
count: { type: 'integer', example: 25 },
|
||||
percentage: { type: 'number', example: 62.5 }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 设备统计 - 按类型
|
||||
'/devices/stats/type': {
|
||||
get: {
|
||||
tags: ['设备管理'],
|
||||
summary: '按类型统计设备数量',
|
||||
description: '获取不同类型设备的数量统计',
|
||||
responses: {
|
||||
'200': {
|
||||
description: '统计成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
data: {
|
||||
type: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
type: { type: 'string', example: 'collar' },
|
||||
typeName: { type: 'string', example: '智能项圈' },
|
||||
count: { type: 'integer', example: 15 },
|
||||
percentage: { type: 'number', example: 37.5 }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 获取指定设备详情
|
||||
'/devices/{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/Device' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'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: '设备名称' },
|
||||
type: { type: 'string', description: '设备类型' },
|
||||
deviceNumber: { type: 'string', description: '设备编号' },
|
||||
model: { type: 'string', description: '设备型号' },
|
||||
manufacturer: { type: 'string', description: '制造商' },
|
||||
status: {
|
||||
type: 'string',
|
||||
enum: ['online', 'offline', 'maintenance', 'error'],
|
||||
description: '设备状态'
|
||||
},
|
||||
farmId: { type: 'integer', description: '所属养殖场ID' },
|
||||
location: { type: 'string', description: '设备位置' },
|
||||
lastMaintenance: { type: 'string', format: 'date', description: '最近维护时间' },
|
||||
batteryLevel: { type: 'number', minimum: 0, maximum: 100, description: '电池电量（%）' },
|
||||
firmwareVersion: { type: 'string', description: '固件版本' },
|
||||
specifications: { type: 'object', description: '设备规格参数' },
|
||||
notes: { type: 'string', description: '备注' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'200': {
|
||||
description: '更新成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '设备信息更新成功' },
|
||||
data: { $ref: '#/components/schemas/Device' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'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' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 设备维护记录
|
||||
'/devices/{id}/maintenance': {
|
||||
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: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
deviceId: { type: 'integer' },
|
||||
maintenanceDate: { type: 'string', format: 'date' },
|
||||
maintenanceType: { type: 'string', enum: ['routine', 'repair', 'upgrade'] },
|
||||
description: { type: 'string' },
|
||||
technician: { type: 'string' },
|
||||
cost: { type: 'number' },
|
||||
notes: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
post: {
|
||||
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: ['maintenanceDate', 'maintenanceType', 'description'],
|
||||
properties: {
|
||||
maintenanceDate: { type: 'string', format: 'date', description: '维护日期' },
|
||||
maintenanceType: {
|
||||
type: 'string',
|
||||
enum: ['routine', 'repair', 'upgrade'],
|
||||
description: '维护类型'
|
||||
},
|
||||
description: { type: 'string', description: '维护描述' },
|
||||
technician: { type: 'string', description: '技术员姓名' },
|
||||
cost: { type: 'number', description: '维护费用' },
|
||||
notes: { type: 'string', description: '备注' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'201': {
|
||||
description: '添加成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '维护记录添加成功' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 设备数据监控
|
||||
'/devices/{id}/data': {
|
||||
get: {
|
||||
tags: ['设备管理'],
|
||||
summary: '获取设备监控数据',
|
||||
description: '获取指定设备的实时监控数据',
|
||||
parameters: [
|
||||
{
|
||||
name: 'id',
|
||||
in: 'path',
|
||||
required: true,
|
||||
schema: { type: 'integer' },
|
||||
description: '设备ID'
|
||||
},
|
||||
{
|
||||
name: 'startTime',
|
||||
in: 'query',
|
||||
schema: { type: 'string', format: 'date-time' },
|
||||
description: '开始时间'
|
||||
},
|
||||
{
|
||||
name: 'endTime',
|
||||
in: 'query',
|
||||
schema: { type: 'string', format: 'date-time' },
|
||||
description: '结束时间'
|
||||
},
|
||||
{
|
||||
name: 'dataType',
|
||||
in: 'query',
|
||||
schema: { type: 'string', enum: ['temperature', 'humidity', 'location', 'battery', 'activity'] },
|
||||
description: '数据类型'
|
||||
}
|
||||
],
|
||||
responses: {
|
||||
'200': {
|
||||
description: '获取成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
data: {
|
||||
type: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
timestamp: { type: 'string', format: 'date-time' },
|
||||
dataType: { type: 'string' },
|
||||
value: { type: 'number' },
|
||||
unit: { type: 'string' },
|
||||
location: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
latitude: { type: 'number' },
|
||||
longitude: { type: 'number' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// 设备数据模型
|
||||
const deviceSchemas = {
|
||||
Device: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer', description: '设备ID' },
|
||||
name: { type: 'string', description: '设备名称' },
|
||||
type: {
|
||||
type: 'string',
|
||||
enum: ['collar', 'ear_tag', 'temperature_sensor', 'humidity_sensor', 'camera', 'feeder', 'water_dispenser'],
|
||||
description: '设备类型'
|
||||
},
|
||||
deviceNumber: { type: 'string', description: '设备编号' },
|
||||
model: { type: 'string', description: '设备型号' },
|
||||
manufacturer: { type: 'string', description: '制造商' },
|
||||
status: {
|
||||
type: 'string',
|
||||
enum: ['online', 'offline', 'maintenance', 'error'],
|
||||
description: '设备状态'
|
||||
},
|
||||
farmId: { type: 'integer', description: '所属养殖场ID' },
|
||||
farmName: { type: 'string', description: '养殖场名称' },
|
||||
location: { type: 'string', description: '设备位置' },
|
||||
installationDate: { type: 'string', format: 'date', description: '安装日期' },
|
||||
lastMaintenance: { type: 'string', format: 'date', description: '最近维护时间' },
|
||||
batteryLevel: { type: 'number', minimum: 0, maximum: 100, description: '电池电量（%）' },
|
||||
firmwareVersion: { type: 'string', description: '固件版本' },
|
||||
specifications: {
|
||||
type: 'object',
|
||||
description: '设备规格参数',
|
||||
additionalProperties: true
|
||||
},
|
||||
lastDataTime: { type: 'string', format: 'date-time', description: '最后数据时间' },
|
||||
isActive: { type: 'boolean', description: '是否激活' },
|
||||
notes: { type: 'string', description: '备注' },
|
||||
createdAt: { type: 'string', format: 'date-time', description: '创建时间' },
|
||||
updatedAt: { type: 'string', format: 'date-time', description: '更新时间' }
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
module.exports = { devicesPaths, deviceSchemas };
|
||||
623
backend/swagger-farms.js
Normal file
623
backend/swagger-farms.js
Normal file
@@ -0,0 +1,623 @@
|
||||
/**
|
||||
* 养殖场管理模块 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 };
|
||||
498
backend/swagger-integrated.js
Normal file
498
backend/swagger-integrated.js
Normal file
@@ -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;
|
||||
736
backend/swagger-reports.js
Normal file
736
backend/swagger-reports.js
Normal file
@@ -0,0 +1,736 @@
|
||||
/**
|
||||
* 报表管理模块 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 = {};
|
||||
1004
backend/swagger-smart-alerts.js
Normal file
1004
backend/swagger-smart-alerts.js
Normal file
File diff suppressed because it is too large
Load Diff
1151
backend/swagger-stats.js
Normal file
1151
backend/swagger-stats.js
Normal file
File diff suppressed because it is too large
Load Diff
1047
backend/swagger-system.js
Normal file
1047
backend/swagger-system.js
Normal file
File diff suppressed because it is too large
Load Diff
521
backend/swagger-users.js
Normal file
521
backend/swagger-users.js
Normal file
@@ -0,0 +1,521 @@
|
||||
/**
|
||||
* 用户管理模块 Swagger 文档
|
||||
* @file swagger-users.js
|
||||
*/
|
||||
|
||||
const usersPaths = {
|
||||
// 获取所有用户
|
||||
'/users': {
|
||||
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', 'banned'] },
|
||||
description: '用户状态筛选'
|
||||
},
|
||||
{
|
||||
name: 'role',
|
||||
in: 'query',
|
||||
schema: { type: 'string' },
|
||||
description: '角色筛选'
|
||||
}
|
||||
],
|
||||
responses: {
|
||||
'200': {
|
||||
description: '获取成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
data: {
|
||||
type: 'array',
|
||||
items: { $ref: '#/components/schemas/User' }
|
||||
},
|
||||
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: ['username', 'email', 'password'],
|
||||
properties: {
|
||||
username: { type: 'string', description: '用户名' },
|
||||
email: { type: 'string', format: 'email', description: '邮箱' },
|
||||
password: { type: 'string', minLength: 6, description: '密码' },
|
||||
phone: { type: 'string', description: '手机号' },
|
||||
realName: { type: 'string', description: '真实姓名' },
|
||||
avatar: { type: 'string', description: '头像URL' },
|
||||
status: { type: 'string', enum: ['active', 'inactive'], default: 'active' },
|
||||
roleIds: { type: 'array', items: { type: 'integer' }, description: '角色ID列表' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'201': {
|
||||
description: '创建成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '用户创建成功' },
|
||||
data: { $ref: '#/components/schemas/User' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'400': {
|
||||
description: '请求参数错误或用户已存在',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: { $ref: '#/components/schemas/ErrorResponse' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 根据用户名搜索用户
|
||||
'/users/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/User' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 获取指定用户详情
|
||||
'/users/{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/User' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'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: {
|
||||
username: { type: 'string', description: '用户名' },
|
||||
email: { type: 'string', format: 'email', description: '邮箱' },
|
||||
phone: { type: 'string', description: '手机号' },
|
||||
realName: { type: 'string', description: '真实姓名' },
|
||||
avatar: { type: 'string', description: '头像URL' },
|
||||
status: { type: 'string', enum: ['active', 'inactive', 'banned'] },
|
||||
roleIds: { type: 'array', items: { type: 'integer' }, description: '角色ID列表' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
responses: {
|
||||
'200': {
|
||||
description: '更新成功',
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
success: { type: 'boolean', example: true },
|
||||
message: { type: 'string', example: '用户信息更新成功' },
|
||||
data: { $ref: '#/components/schemas/User' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
'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' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 重置用户密码
|
||||
'/users/{id}/reset-password': {
|
||||
post: {
|
||||
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: ['newPassword'],
|
||||
properties: {
|
||||
newPassword: {
|
||||
type: 'string',
|
||||
minLength: 6,
|
||||
description: '新密码'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
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' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 批量操作用户
|
||||
'/users/batch': {
|
||||
post: {
|
||||
tags: ['用户管理'],
|
||||
summary: '批量操作用户',
|
||||
description: '批量启用、禁用或删除用户',
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
'application/json': {
|
||||
schema: {
|
||||
type: 'object',
|
||||
required: ['userIds', 'action'],
|
||||
properties: {
|
||||
userIds: {
|
||||
type: 'array',
|
||||
items: { type: 'integer' },
|
||||
description: '用户ID列表'
|
||||
},
|
||||
action: {
|
||||
type: 'string',
|
||||
enum: ['activate', 'deactivate', 'ban', 'delete'],
|
||||
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: '处理失败的用户数量' },
|
||||
errors: { type: 'array', items: { type: 'string' }, description: '错误信息列表' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
// 导出用户数据
|
||||
'/users/export': {
|
||||
get: {
|
||||
tags: ['用户管理'],
|
||||
summary: '导出用户数据',
|
||||
description: '导出用户数据为Excel文件',
|
||||
parameters: [
|
||||
{
|
||||
name: 'format',
|
||||
in: 'query',
|
||||
schema: { type: 'string', enum: ['xlsx', 'csv'], default: 'xlsx' },
|
||||
description: '导出格式'
|
||||
},
|
||||
{
|
||||
name: 'status',
|
||||
in: 'query',
|
||||
schema: { type: 'string', enum: ['active', 'inactive', 'banned'] },
|
||||
description: '用户状态筛选'
|
||||
},
|
||||
{
|
||||
name: 'role',
|
||||
in: 'query',
|
||||
schema: { type: 'string' },
|
||||
description: '角色筛选'
|
||||
}
|
||||
],
|
||||
responses: {
|
||||
'200': {
|
||||
description: '导出成功',
|
||||
content: {
|
||||
'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': {
|
||||
schema: {
|
||||
type: 'string',
|
||||
format: 'binary'
|
||||
}
|
||||
},
|
||||
'text/csv': {
|
||||
schema: {
|
||||
type: 'string',
|
||||
format: 'binary'
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
// 用户数据模型
|
||||
const userSchemas = {
|
||||
User: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer', description: '用户ID' },
|
||||
username: { type: 'string', description: '用户名' },
|
||||
email: { type: 'string', format: 'email', description: '邮箱' },
|
||||
phone: { type: 'string', description: '手机号' },
|
||||
realName: { type: 'string', description: '真实姓名' },
|
||||
avatar: { type: 'string', description: '头像URL' },
|
||||
status: {
|
||||
type: 'string',
|
||||
enum: ['active', 'inactive', 'banned'],
|
||||
description: '用户状态：active-活跃，inactive-未激活，banned-已封禁'
|
||||
},
|
||||
roles: {
|
||||
type: 'array',
|
||||
items: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
id: { type: 'integer' },
|
||||
name: { type: 'string' },
|
||||
description: { type: 'string' }
|
||||
}
|
||||
},
|
||||
description: '用户角色列表'
|
||||
},
|
||||
permissions: {
|
||||
type: 'array',
|
||||
items: { type: 'string' },
|
||||
description: '用户权限列表'
|
||||
},
|
||||
lastLoginAt: { type: 'string', format: 'date-time', description: '最后登录时间' },
|
||||
createdAt: { type: 'string', format: 'date-time', description: '创建时间' },
|
||||
updatedAt: { type: 'string', format: 'date-time', description: '更新时间' }
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
module.exports = { usersPaths, userSchemas };
|
||||
Reference in New Issue
Block a user