xlxumu/docs/api/API文档.md

# xlxumu 畜牧管理系统 API 文档

## 概述

本文档描述了 xlxumu 畜牧管理系统的 RESTful API 接口。系统提供用户认证、牛只管理、财务管理、交易管理、商城管理和政府监管等功能。

## 基础信息

- **基础URL**: `http://localhost:8889/api/v1`
- **认证方式**: JWT Token
- **数据格式**: JSON
- **字符编码**: UTF-8

## 通用响应格式

### 成功响应
```json
{
  "success": true,
  "data": {
    // 具体数据内容
  },
  "message": "操作成功"
}
```

### 错误响应
```json
{
  "success": false,
  "message": "错误描述",
  "code": "ERROR_CODE"
}
```

## 认证接口 (/auth)

### 用户注册
- **URL**: `POST /auth/register`
- **描述**: 用户注册
- **请求体**:
```json
{
  "username": "string",
  "email": "string",
  "phone": "string",
  "password": "string",
  "real_name": "string",
  "user_type": "farmer|government|bank|insurance"
}
```
- **响应**:
```json
{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "test@example.com",
      "user_type": "farmer"
    },
    "token": "jwt_token_string"
  }
}
```

### 用户登录
- **URL**: `POST /auth/login`
- **描述**: 用户登录
- **请求体**:
```json
{
  "username": "string",
  "password": "string"
}
```

### 刷新Token
- **URL**: `POST /auth/refresh`
- **描述**: 刷新访问令牌
- **请求头**: `Authorization: Bearer <token>`

### 用户登出
- **URL**: `POST /auth/logout`
- **描述**: 用户登出
- **请求头**: `Authorization: Bearer <token>`

## 用户管理接口 (/users)

### 获取用户信息
- **URL**: `GET /users/profile`
- **描述**: 获取当前用户信息
- **请求头**: `Authorization: Bearer <token>`

### 更新用户信息
- **URL**: `PUT /users/profile`
- **描述**: 更新用户信息
- **请求头**: `Authorization: Bearer <token>`
- **请求体**:
```json
{
  "real_name": "string",
  "phone": "string",
  "avatar_url": "string"
}
```

### 修改密码
- **URL**: `PUT /users/password`
- **描述**: 修改用户密码
- **请求头**: `Authorization: Bearer <token>`
- **请求体**:
```json
{
  "old_password": "string",
  "new_password": "string"
}
```

## 牛只管理接口 (/cattle)

### 获取牛只列表
- **URL**: `GET /cattle`
- **描述**: 获取牛只列表
- **请求头**: `Authorization: Bearer <token>`
- **查询参数**:
  - `page`: 页码 (默认: 1)
  - `limit`: 每页数量 (默认: 10)
  - `breed`: 品种筛选
  - `status`: 状态筛选
  - `health_status`: 健康状态筛选

### 添加牛只
- **URL**: `POST /cattle`
- **描述**: 添加新牛只
- **请求头**: `Authorization: Bearer <token>`
- **请求体**:
```json
{
  "ear_tag": "string",
  "name": "string",
  "breed": "string",
  "gender": "male|female",
  "birth_date": "YYYY-MM-DD",
  "color": "string",
  "weight": 500.5,
  "farm_location": "string",
  "notes": "string"
}
```

### 获取牛只详情
- **URL**: `GET /cattle/:id`
- **描述**: 获取指定牛只详情
- **请求头**: `Authorization: Bearer <token>`

### 更新牛只信息
- **URL**: `PUT /cattle/:id`
- **描述**: 更新牛只信息
- **请求头**: `Authorization: Bearer <token>`

### 删除牛只
- **URL**: `DELETE /cattle/:id`
- **描述**: 删除牛只记录
- **请求头**: `Authorization: Bearer <token>`

### 牛只统计
- **URL**: `GET /cattle/statistics`
- **描述**: 获取牛只统计信息
- **请求头**: `Authorization: Bearer <token>`

## 财务管理接口 (/finance)

### 获取财务记录
- **URL**: `GET /finance/records`
- **描述**: 获取财务记录列表
- **请求头**: `Authorization: Bearer <token>`
- **查询参数**:
  - `page`: 页码
  - `limit`: 每页数量
  - `type`: 类型 (income|expense)
  - `category`: 分类
  - `start_date`: 开始日期
  - `end_date`: 结束日期

### 添加财务记录
- **URL**: `POST /finance/records`
- **描述**: 添加财务记录
- **请求头**: `Authorization: Bearer <token>`
- **请求体**:
```json
{
  "type": "income|expense",
  "category": "string",
  "amount": 1000.00,
  "description": "string",
  "record_date": "YYYY-MM-DD"
}
```

### 财务统计
- **URL**: `GET /finance/statistics`
- **描述**: 获取财务统计信息
- **请求头**: `Authorization: Bearer <token>`
- **查询参数**:
  - `period`: 统计周期 (month|quarter|year)

## 交易管理接口 (/trading)

### 获取交易列表
- **URL**: `GET /trading/transactions`
- **描述**: 获取交易记录列表
- **请求头**: `Authorization: Bearer <token>`
- **查询参数**:
  - `page`: 页码
  - `limit`: 每页数量
  - `status`: 交易状态
  - `product_type`: 产品类型

### 创建交易
- **URL**: `POST /trading/transactions`
- **描述**: 创建新交易
- **请求头**: `Authorization: Bearer <token>`
- **请求体**:
```json
{
  "seller_id": 1,
  "product_type": "cattle",
  "product_id": 1,
  "quantity": 10,
  "unit_price": 8500.00,
  "notes": "string"
}
```

### 获取交易详情
- **URL**: `GET /trading/transactions/:id`
- **描述**: 获取交易详情
- **请求头**: `Authorization: Bearer <token>`

### 更新交易状态
- **URL**: `PUT /trading/transactions/:id/status`
- **描述**: 更新交易状态
- **请求头**: `Authorization: Bearer <token>`
- **请求体**:
```json
{
  "status": "pending|confirmed|completed|cancelled",
  "payment_status": "pending|paid|refunded",
  "delivery_status": "pending|shipped|delivered"
}
```

## 商城管理接口 (/mall)

### 获取产品列表
- **URL**: `GET /mall/products`
- **描述**: 获取商城产品列表
- **查询参数**:
  - `page`: 页码
  - `limit`: 每页数量
  - `category_id`: 分类ID
  - `keyword`: 搜索关键词
  - `min_price`: 最低价格
  - `max_price`: 最高价格

### 获取产品详情
- **URL**: `GET /mall/products/:id`
- **描述**: 获取产品详情

### 添加产品
- **URL**: `POST /mall/products`
- **描述**: 添加新产品
- **请求头**: `Authorization: Bearer <token>`
- **请求体**:
```json
{
  "name": "string",
  "description": "string",
  "category_id": 1,
  "price": 100.00,
  "stock_quantity": 50,
  "images": ["url1", "url2"],
  "specifications": {}
}
```

### 获取订单列表
- **URL**: `GET /mall/orders`
- **描述**: 获取订单列表
- **请求头**: `Authorization: Bearer <token>`

### 创建订单
- **URL**: `POST /mall/orders`
- **描述**: 创建新订单
- **请求头**: `Authorization: Bearer <token>`
- **请求体**:
```json
{
  "items": [
    {
      "product_id": 1,
      "quantity": 2,
      "price": 100.00
    }
  ],
  "shipping_address": "string",
  "notes": "string"
}
```

## 政府监管接口 (/government)

### 获取农场监管列表
- **URL**: `GET /government/farms/supervision`
- **描述**: 获取农场监管信息
- **请求头**: `Authorization: Bearer <token>`
- **查询参数**:
  - `page`: 页码
  - `limit`: 每页数量
  - `region`: 地区
  - `status`: 监管状态

### 获取监管统计
- **URL**: `GET /government/statistics`
- **描述**: 获取监管统计数据
- **请求头**: `Authorization: Bearer <token>`
- **响应示例**:
```json
{
  "success": true,
  "data": {
    "overview": {
      "total_farms": 1250,
      "total_cattle": 45680,
      "active_farms": 1180,
      "compliance_rate": 94.4
    },
    "by_region": [
      {
        "region": "华北地区",
        "farms": 320,
        "cattle": 12500,
        "compliance_rate": 96.2
      }
    ],
    "by_type": [
      {
        "type": "肉牛养殖",
        "count": 680,
        "percentage": 54.4
      }
    ],
    "monthly_trend": [
      {
        "month": "2024-01",
        "new_registrations": 25,
        "inspections": 156,
        "violations": 8
      }
    ]
  }
}
```

## 系统接口

### 健康检查
- **URL**: `GET /health`
- **描述**: 系统健康检查
- **响应**:
```json
{
  "status": "ok",
  "timestamp": "2024-01-20T10:30:00Z",
  "database": "connected",
  "version": "1.0.0"
}
```

### 数据库状态
- **URL**: `GET /database/status`
- **描述**: 数据库连接状态

### 数据库表信息
- **URL**: `GET /database/tables`
- **描述**: 获取数据库表信息

## 错误码说明

| 错误码 | 描述 |
|--------|------|
| VALIDATION_ERROR | 请求参数验证失败 |
| UNAUTHORIZED | 未授权访问 |
| FORBIDDEN | 禁止访问 |
| NOT_FOUND | 资源未找到 |
| DATABASE_ERROR | 数据库操作失败 |
| INTERNAL_SERVER_ERROR | 服务器内部错误 |

## 认证说明

大部分API接口需要在请求头中包含JWT Token：

```
Authorization: Bearer <your_jwt_token>
```

Token可通过登录接口获取，有效期为24小时。

## 分页说明

支持分页的接口使用以下参数：
- `page`: 页码，从1开始
- `limit`: 每页数量，默认10，最大100

分页响应格式：
```json
{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "total": 100,
      "page": 1,
      "limit": 10,
      "pages": 10
    }
  }
}
```

## 开发环境

- **服务器地址**: http://localhost:8889
- **数据库**: SQLite (开发环境)
- **日志级别**: DEBUG

## 注意事项

1. 所有时间格式使用 ISO 8601 标准
2. 金额字段使用 DECIMAL 类型，保留2位小数
3. 文件上传大小限制为 10MB
4. API请求频率限制：每15分钟100次请求
5. 开发环境下会返回详细的错误信息，生产环境下会隐藏敏感信息