openapi: 3.0.3 info: title: 智慧农业生产管理系统 API description: 农业生产管理系统的后端接口文档 version: 1.0.0 contact: name: API Support email: support@smart-crop.com servers: - url: https://gitea-admin-test-app-app.dev.maimaiag.com/api/v1 description: 开发/测试/生产环境（统一地址） paths: # 用户管理 /users: get: summary: 获取用户列表 description: 获取所有用户的分页列表 tags: - 用户管理 parameters: - name: page in: query description: 页码 required: false schema: type: integer default: 1 minimum: 1 - name: limit in: query description: 每页数量 required: false schema: type: integer default: 20 minimum: 1 maximum: 100 - name: search in: query description: 搜索关键词 required: false schema: type: string maxLength: 100 responses: '200': description: 成功获取用户列表 content: application/json: schema: type: object properties: code: type: integer example: 200 message: type: string example: "success" data: type: object properties: users: type: array items: $ref: '#/components/schemas/User' total: type: integer example: 100 page: type: integer example: 1 limit: type: integer example: 20 /users/{id}: get: summary: 获取用户详情 description: 根据用户ID获取用户详细信息 tags: - 用户管理 parameters: - name: id in: path required: true description: 用户ID schema: type: integer minimum: 1 responses: '200': description: 成功获取用户详情 content: application/json: schema: type: object properties: code: type: integer example: 200 message: type: string example: "success" data: $ref: '#/components/schemas/User' '404': description: 用户不存在 content: application/json: schema: $ref: '#/components/schemas/Error' # 农机管理 /machinery: get: summary: 获取农机列表 description: 获取所有农机的分页列表 tags: - 农机管理 parameters: - name: page in: query schema: type: integer default: 1 - name: limit in: query schema: type: integer default: 20 - name: status in: query description: 农机状态筛选 schema: type: string enum: [running, idle, maintenance, error, offline] responses: '200': description: 成功获取农机列表 content: application/json: schema: type: object properties: code: type: integer example: 200 message: type: string example: "success" data: type: object properties: machinery: type: array items: $ref: '#/components/schemas/Machinery' total: type: integer example: 50 post: summary: 创建农机 description: 创建新的农机记录 tags: - 农机管理 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMachineryRequest' responses: '201': description: 农机创建成功 content: application/json: schema: type: object properties: code: type: integer example: 201 message: type: string example: "农机创建成功" data: $ref: '#/components/schemas/Machinery' /machinery/{id}: get: summary: 获取农机详情 tags: - 农机管理 parameters: - name: id in: path required: true schema: type: integer responses: '200': description: 成功获取农机详情 content: application/json: schema: type: object properties: code: type: integer example: 200 message: type: string example: "success" data: $ref: '#/components/schemas/Machinery' put: summary: 更新农机信息 tags: - 农机管理 parameters: - name: id in: path required: true schema: type: integer requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMachineryRequest' responses: '200': description: 农机更新成功 content: application/json: schema: type: object properties: code: type: integer example: 200 message: type: string example: "农机更新成功" data: $ref: '#/components/schemas/Machinery' delete: summary: 删除农机 tags: - 农机管理 parameters: - name: id in: path required: true schema: type: integer responses: '204': description: 农机删除成功 components: schemas: User: type: object properties: id: type: integer description: 用户ID example: 1 username: type: string description: 用户名 example: "john_doe" minLength: 3 maxLength: 50 email: type: string format: email description: 邮箱地址 example: "john@example.com" full_name: type: string description: 全名 example: "John Doe" maxLength: 100 phone: type: string description: 手机号码 example: "13800138000" pattern: "^1[3-9]\\d{9}$" role: type: string enum: [admin, manager, operator, viewer] description: 用户角色 example: "operator" status: type: string enum: [active, inactive, suspended] description: 用户状态 example: "active" created_at: type: string format: date-time description: 创建时间 example: "2024-01-15T10:30:00Z" updated_at: type: string format: date-time description: 更新时间 example: "2024-01-15T10:30:00Z" Machinery: type: object properties: id: type: integer description: 农机ID example: 1 name: type: string description: 农机名称 example: "拖拉机-001" maxLength: 100 type: type: string enum: [tractor, harvester, planter, sprayer, irrigation] description: 农机类型 example: "tractor" model: type: string description: 型号 example: "John Deere 6M Series" maxLength: 50 serial_number: type: string description: 序列号 example: "JD6M123456" maxLength: 50 status: type: string enum: [running, idle, maintenance, error, offline] description: 农机状态 example: "idle" location: $ref: '#/components/schemas/Location' operator: $ref: '#/components/schemas/User' purchase_date: type: string format: date description: 购买日期 example: "2024-01-01" last_maintenance: type: string format: date description: 上次维护日期 example: "2024-06-15" next_maintenance: type: string format: date description: 下次维护日期 example: "2024-09-15" created_at: type: string format: date-time description: 创建时间 updated_at: type: string format: date-time description: 更新时间 Location: type: object properties: field_id: type: integer description: 地块ID example: 1 field_name: type: string description: 地块名称 example: "北区A地块" coordinates: $ref: '#/components/schemas/Coordinates' Coordinates: type: object properties: latitude: type: number format: double description: 纬度 example: 39.9042 minimum: -90 maximum: 90 longitude: type: number format: double description: 经度 example: 116.4074 minimum: -180 maximum: 180 CreateMachineryRequest: type: object required: - name - type - model properties: name: type: string description: 农机名称 minLength: 1 maxLength: 100 type: type: string enum: [tractor, harvester, planter, sprayer, irrigation] description: 农机类型 model: type: string description: 型号 minLength: 1 maxLength: 50 serial_number: type: string description: 序列号 maxLength: 50 operator_id: type: integer description: 操作员ID example: 1 purchase_date: type: string format: date description: 购买日期 UpdateMachineryRequest: type: object properties: name: type: string description: 农机名称 maxLength: 100 status: type: string enum: [running, idle, maintenance, error, offline] description: 农机状态 operator_id: type: integer description: 操作员ID last_maintenance: type: string format: date description: 上次维护日期 next_maintenance: type: string format: date description: 下次维护日期 Error: type: object properties: code: type: integer description: 错误代码 example: 404 message: type: string description: 错误信息 example: "资源不存在" details: type: object description: 错误详情 example: field: "id" reason: "用户ID不存在" securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT 认证令牌 security: - BearerAuth: []