# 项目清单 API 接口文档

## 概述
项目清单管理系统的后端API接口，提供项目的增删改查功能。

## 基础信息
- **基础URL**: `http://localhost:5351/api/projects`
- **认证方式**: Bearer Token
- **内容类型**: `application/json`

## 接口列表

### 1. 创建项目
**POST** `/api/projects`

#### 请求头
```
Authorization: Bearer <token>
Content-Type: application/json
```

#### 请求参数
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| name | string | 是 | 项目名称，最大100字符 | "张洪彬养殖项目" |
| farmName | string | 是 | 养殖场名称，最大200字符 | "张洪彬养殖场" |
| supervisionObject | string | 是 | 监管对象 | "牛" |
| supervisionPeriod | string | 是 | 监管周期 | "12个月" |
| startTime | string | 是 | 起始时间，格式：YYYY-MM-DD | "2024-01-01" |
| endTime | string | 是 | 结束时间，格式：YYYY-MM-DD | "2024-12-31" |
| status | string | 否 | 项目状态，默认：supervision | "supervision" 或 "completed" |
| supervisionQuantity | number | 否 | 监管数量，默认：0 | 100 |
| supervisionAmount | number | 否 | 监管金额，默认：0.00 | 500000.00 |
| earTag | number | 否 | 耳标数量，默认：0 | 50 |
| collar | number | 否 | 项圈数量，默认：0 | 30 |
| host | number | 否 | 主机数量，默认：0 | 20 |
| loanOfficer | string | 否 | 贷款专员 | "张专员" |
| description | string | 否 | 项目描述 | "这是一个测试项目" |

#### 请求示例
```json
{
  "name": "张洪彬养殖项目",
  "farmName": "张洪彬养殖场",
  "supervisionObject": "牛",
  "supervisionPeriod": "12个月",
  "startTime": "2024-01-01",
  "endTime": "2024-12-31",
  "status": "supervision",
  "supervisionQuantity": 100,
  "supervisionAmount": 500000.00,
  "earTag": 50,
  "collar": 30,
  "host": 20,
  "loanOfficer": "张专员",
  "description": "这是一个测试项目"
}
```

#### 响应示例
**成功响应 (201)**
```json
{
  "success": true,
  "message": "创建项目成功",
  "data": {
    "id": 9,
    "name": "张洪彬养殖项目",
    "status": "supervision",
    "farmName": "张洪彬养殖场",
    "supervisionObject": "牛",
    "supervisionQuantity": 100,
    "supervisionPeriod": "12个月",
    "supervisionAmount": "500000.00",
    "startTime": "2024-01-01",
    "endTime": "2024-12-31",
    "earTag": 50,
    "collar": 30,
    "host": 20,
    "loanOfficer": "张专员",
    "description": "这是一个测试项目",
    "createdBy": 1,
    "updatedBy": 1,
    "createdAt": "2024-12-20T10:30:00.000Z",
    "updatedAt": "2024-12-20T10:30:00.000Z",
    "creator": {
      "id": 1,
      "username": "admin",
      "real_name": "管理员"
    },
    "updater": {
      "id": 1,
      "username": "admin",
      "real_name": "管理员"
    }
  }
}
```

**错误响应 (400)**
```json
{
  "success": false,
  "message": "请填写所有必填字段: name, farmName"
}
```

**错误响应 (400)**
```json
{
  "success": false,
  "message": "项目名称已存在，请使用其他名称"
}
```

**错误响应 (400)**
```json
{
  "success": false,
  "message": "结束时间必须晚于开始时间"
}
```

### 2. 获取项目列表
**GET** `/api/projects`

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| page | number | 否 | 页码，默认：1 | 1 |
| limit | number | 否 | 每页数量，默认：10 | 12 |
| search | string | 否 | 搜索关键词 | "张洪彬" |
| status | string | 否 | 状态筛选 | "supervision" 或 "completed" |
| sortBy | string | 否 | 排序字段，默认：createdAt | "name" |
| sortOrder | string | 否 | 排序方向，默认：DESC | "ASC" 或 "DESC" |

#### 请求示例
```
GET /api/projects?page=1&limit=12&search=张洪彬&status=supervision&sortBy=name&sortOrder=ASC
```

#### 响应示例
```json
{
  "success": true,
  "message": "获取项目列表成功",
  "data": {
    "projects": [
      {
        "id": 1,
        "name": "张洪彬",
        "status": "completed",
        "farmName": "大数据中心",
        "supervisionObject": "牛",
        "supervisionQuantity": 100,
        "supervisionPeriod": "12个月",
        "supervisionAmount": "500000.00",
        "startTime": "2024-01-01",
        "endTime": "2024-12-31",
        "earTag": 50,
        "collar": 30,
        "host": 20,
        "loanOfficer": "张专员",
        "description": "项目描述",
        "createdAt": "2024-12-20T10:30:00.000Z",
        "updatedAt": "2024-12-20T10:30:00.000Z",
        "creator": {
          "id": 1,
          "username": "admin",
          "real_name": "管理员"
        },
        "updater": {
          "id": 1,
          "username": "admin",
          "real_name": "管理员"
        }
      }
    ],
    "pagination": {
      "total": 8,
      "currentPage": 1,
      "pageSize": 12,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPrevPage": false
    }
  }
}
```

### 3. 获取项目详情
**GET** `/api/projects/:id`

#### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | number | 是 | 项目ID |

#### 响应示例
```json
{
  "success": true,
  "message": "获取项目详情成功",
  "data": {
    "id": 1,
    "name": "张洪彬",
    "status": "completed",
    "farmName": "大数据中心",
    "supervisionObject": "牛",
    "supervisionQuantity": 100,
    "supervisionPeriod": "12个月",
    "supervisionAmount": "500000.00",
    "startTime": "2024-01-01",
    "endTime": "2024-12-31",
    "earTag": 50,
    "collar": 30,
    "host": 20,
    "loanOfficer": "张专员",
    "description": "项目描述",
    "createdAt": "2024-12-20T10:30:00.000Z",
    "updatedAt": "2024-12-20T10:30:00.000Z",
    "creator": {
      "id": 1,
      "username": "admin",
      "real_name": "管理员"
    },
    "updater": {
      "id": 1,
      "username": "admin",
      "real_name": "管理员"
    }
  }
}
```

### 4. 更新项目
**PUT** `/api/projects/:id`

#### 请求参数
与创建项目相同，所有字段都是可选的。

#### 响应示例
```json
{
  "success": true,
  "message": "项目更新成功",
  "data": {
    "id": 1,
    "name": "更新后的项目名称",
    "status": "completed",
    // ... 其他字段
  }
}
```

### 5. 删除项目
**DELETE** `/api/projects/:id`

#### 响应示例
```json
{
  "success": true,
  "message": "项目删除成功"
}
```

### 6. 获取项目统计
**GET** `/api/projects/stats`

#### 响应示例
```json
{
  "success": true,
  "message": "项目统计获取成功",
  "data": {
    "total": 8,
    "supervision": 3,
    "completed": 5
  }
}
```

### 7. 批量更新项目状态
**PUT** `/api/projects/batch/status`

#### 请求参数
```json
{
  "ids": [1, 2, 3],
  "status": "completed"
}
```

#### 响应示例
```json
{
  "success": true,
  "message": "成功更新 3 个项目状态",
  "data": {
    "updatedCount": 3
  }
}
```

## 错误码说明

| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 201 | 创建成功 |
| 400 | 请求参数错误 |
| 401 | 未授权，需要登录 |
| 403 | 禁止访问，权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

## 数据验证规则

### 必填字段验证
- `name`: 项目名称，不能为空
- `farmName`: 养殖场名称，不能为空
- `supervisionObject`: 监管对象，不能为空
- `supervisionPeriod`: 监管周期，不能为空
- `startTime`: 起始时间，不能为空
- `endTime`: 结束时间，不能为空

### 字段长度限制
- `name`: 最大100个字符
- `farmName`: 最大200个字符
- `supervisionObject`: 最大50个字符
- `supervisionPeriod`: 最大50个字符
- `loanOfficer`: 最大100个字符

### 数值字段验证
- `supervisionQuantity`: 不能为负数
- `supervisionAmount`: 不能为负数
- `earTag`: 不能为负数
- `collar`: 不能为负数
- `host`: 不能为负数

### 日期验证
- `startTime` 和 `endTime` 必须是有效的日期格式 (YYYY-MM-DD)
- `endTime` 必须晚于 `startTime`

### 状态验证
- `status` 只能是 "supervision" 或 "completed"

## 使用示例

### JavaScript (axios)
```javascript
// 创建项目
const createProject = async (projectData) => {
  try {
    const response = await axios.post('/api/projects', projectData, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });
    return response.data;
  } catch (error) {
    console.error('创建项目失败:', error.response.data);
    throw error;
  }
};

// 获取项目列表
const getProjects = async (params = {}) => {
  try {
    const response = await axios.get('/api/projects', {
      headers: {
        'Authorization': `Bearer ${token}`
      },
      params
    });
    return response.data;
  } catch (error) {
    console.error('获取项目列表失败:', error.response.data);
    throw error;
  }
};
```

### cURL
```bash
# 创建项目
curl -X POST http://localhost:5351/api/projects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "测试项目",
    "farmName": "测试养殖场",
    "supervisionObject": "牛",
    "supervisionPeriod": "12个月",
    "startTime": "2024-01-01",
    "endTime": "2024-12-31"
  }'

# 获取项目列表
curl -X GET "http://localhost:5351/api/projects?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"
```
