# 养殖管理系统 API 文档 (v1.1.0)

## 1. 接口概述

### 1.1 功能范围
- 牛只档案管理
- 饲喂记录管理
- 防疫管理
- 繁殖管理
- 环境监测

### 1.2 基础路径
`/api/v1/farming`

### 1.3 权限控制
- 公开接口（无需认证）：数据查询
- 管理接口（需要认证）：数据录入和管理
- 系统接口（高级权限）：批量操作和配置

### 1.4 全局错误码
| 状态码 | 说明               |
|--------|--------------------|
| 400    | 请求参数无效       |
| 401    | 未授权             |
| 403    | 权限不足           |
| 404    | 资源不存在         |
| 500    | 服务器内部错误     |

## 2. 接口明细

### 2.1 添加牛只
```
POST /cattles
```

**请求参数**:
| 字段         | 类型   | 必填 | 说明               |
|--------------|--------|------|--------------------|
| ear_tag      | string | 是   | 耳标号(唯一)       |
| breed        | string | 是   | 品种               |
| birth_date   | string | 是   | 出生日期(YYYY-MM-DD)|
| gender       | string | 是   | 性别(公/母)        |
| weight       | number | 否   | 体重(kg)           |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "id": "CATTLE001",
    "ear_tag": "NM000001",
    "created_at": "2024-01-20T10:00:00Z"
  }
}
```

### 2.2 批量导入牛只
```
POST /cattles/batch
```

**请求参数**:
| 字段         | 类型   | 必填 | 说明               |
|--------------|--------|------|--------------------|
| file         | file   | 是   | Excel文件          |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "imported_count": 50,
    "failed_count": 2,
    "failed_items": [
      {
        "row": 25,
        "error": "耳标号格式错误"
      }
    ]
  }
}
```

### 2.3 添加防疫记录
```
POST /vaccinations
```

**请求参数**:
| 字段         | 类型   | 必填 | 说明               |
|--------------|--------|------|--------------------|
| cattle_id    | string | 是   | 牛只ID             |
| vaccine_type | string | 是   | 疫苗类型           |
| date         | string | 是   | 接种日期(YYYY-MM-DD)|
| dosage       | number | 否   | 剂量(ml)           |
| veterinarian | string | 否   | 兽医姓名           |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "id": "VACC001",
    "cattle_id": "CATTLE001",
    "vaccine_type": "口蹄疫",
    "created_at": "2024-01-20T10:30:00Z"
  }
}
```

## 3. 数据规范
- 耳标号格式：省简称+6位数字(如NM000001)
- 疫苗记录保留至少5年
- 敏感数据需RSA加密传输
- 日期格式：YYYY-MM-DD
- 时间格式：YYYY-MM-DDTHH:mm:ssZ

## 4. 版本历史

### v1.1.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完善养殖管理接口定义
## 3. 版本历史

### v1.0.0 (2024-01-20)
- 新增: 按照API文档规范标准统一格式
- 优化: 统一响应格式和错误处理
- 功能: 完成基础接口定义