# 监管任务 API 接口文档

## 概述
监管任务管理系统的后端API接口，提供监管任务的增删改查功能。

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

## 接口列表

### 1. 创建监管任务
**POST** `/api/supervision-tasks`

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

#### 请求参数
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| applicationNumber | string | 是 | 申请单号，最大50字符，唯一 | "APP001" |
| contractNumber | string | 是 | 放款合同编号，最大50字符，唯一 | "CONTRACT001" |
| productName | string | 是 | 产品名称，最大100字符 | "农业贷款产品A" |
| customerName | string | 是 | 客户姓名，最大50字符 | "张三" |
| idType | string | 是 | 证件类型 | "id_card" (身份证), "passport" (护照), "other" (其他) |
| idNumber | string | 是 | 证件号码，最大50字符 | "110101199001011234" |
| assetType | string | 是 | 养殖生资种类 | "cattle" (牛), "sheep" (羊), "pig" (猪), "poultry" (家禽), "other" (其他) |
| assetQuantity | number | 是 | 监管生资数量，非负数 | 10 |
| startTime | string | 是 | 监管起始时间，格式：YYYY-MM-DD | "2024-01-15" |
| endTime | string | 是 | 监管结束时间，格式：YYYY-MM-DD | "2024-12-15" |
| supervisionStatus | string | 否 | 监管状态，默认：pending | "pending", "supervising", "completed", "suspended" |
| loanAmount | number | 否 | 贷款金额，默认：0 | 500000.00 |
| interestRate | number | 否 | 利率，默认：0，范围：0-1 | 0.0650 |
| loanTerm | number | 否 | 贷款期限（月），默认：12 | 12 |
| supervisorName | string | 否 | 监管员姓名，最大50字符 | "李监管员" |
| supervisorPhone | string | 否 | 监管员电话，最大20字符 | "13800138001" |
| farmAddress | string | 否 | 养殖场地址，最大200字符 | "北京市朝阳区某某养殖场" |
| remarks | string | 否 | 备注 | "重点监管项目，需要定期检查" |

#### 请求示例
```json
{
  "applicationNumber": "APP001",
  "contractNumber": "CONTRACT001",
  "productName": "农业贷款产品A",
  "customerName": "张三",
  "idType": "id_card",
  "idNumber": "110101199001011234",
  "assetType": "cattle",
  "assetQuantity": 10,
  "supervisionStatus": "pending",
  "startTime": "2024-01-15",
  "endTime": "2024-12-15",
  "loanAmount": 500000.00,
  "interestRate": 0.0650,
  "loanTerm": 12,
  "supervisorName": "李监管员",
  "supervisorPhone": "13800138001",
  "farmAddress": "北京市朝阳区某某养殖场",
  "remarks": "重点监管项目，需要定期检查"
}
```

#### 响应示例
**成功响应 (201)**
```json
{
  "success": true,
  "message": "监管任务创建成功",
  "data": {
    "id": 1,
    "applicationNumber": "APP001",
    "contractNumber": "CONTRACT001",
    "productName": "农业贷款产品A",
    "customerName": "张三",
    "idType": "id_card",
    "idNumber": "110101199001011234",
    "assetType": "cattle",
    "assetQuantity": 10,
    "supervisionStatus": "pending",
    "importTime": "2024-12-20T10:30:00.000Z",
    "startTime": "2024-01-15",
    "endTime": "2024-12-15",
    "loanAmount": "500000.00",
    "interestRate": "0.0650",
    "loanTerm": 12,
    "supervisorName": "李监管员",
    "supervisorPhone": "13800138001",
    "farmAddress": "北京市朝阳区某某养殖场",
    "remarks": "重点监管项目，需要定期检查",
    "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": "管理员"
    }
  }
}
```

### 2. 获取监管任务列表
**GET** `/api/supervision-tasks`

#### 查询参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| page | number | 否 | 页码，默认：1 | 1 |
| limit | number | 否 | 每页数量，默认：10 | 10 |
| search | string | 否 | 搜索关键词（申请单号、合同编号、客户姓名、产品名称） | "张三" |
| supervisionStatus | string | 否 | 状态筛选 | "pending", "supervising", "completed", "suspended" |
| dateRange | string | 否 | 日期范围筛选，格式：startDate,endDate | "2024-01-01,2024-12-31" |
| sortBy | string | 否 | 排序字段，默认：createdAt | "applicationNumber", "customerName", "supervisionStatus" |
| sortOrder | string | 否 | 排序方向，默认：DESC | "ASC", "DESC" |

#### 请求示例
```
GET /api/supervision-tasks?page=1&limit=10&search=张三&supervisionStatus=supervising&dateRange=2024-01-01,2024-12-31&sortBy=customerName&sortOrder=ASC
```

#### 响应示例
```json
{
  "success": true,
  "message": "监管任务列表获取成功",
  "data": {
    "tasks": [
      {
        "id": 1,
        "applicationNumber": "APP001",
        "contractNumber": "CONTRACT001",
        "productName": "农业贷款产品A",
        "customerName": "张三",
        "idType": "id_card",
        "idNumber": "110101199001011234",
        "assetType": "cattle",
        "assetQuantity": 10,
        "supervisionStatus": "supervising",
        "importTime": "2024-01-15T10:30:00.000Z",
        "startTime": "2024-01-15",
        "endTime": "2024-12-15",
        "loanAmount": "500000.00",
        "interestRate": "0.0650",
        "loanTerm": 12,
        "supervisorName": "李监管员",
        "supervisorPhone": "13800138001",
        "farmAddress": "北京市朝阳区某某养殖场",
        "remarks": "重点监管项目，需要定期检查",
        "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": 10,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPrevPage": false
    }
  }
}
```

### 3. 获取监管任务详情
**GET** `/api/supervision-tasks/:id`

#### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | number | 是 | 监管任务ID |

#### 响应示例
```json
{
  "success": true,
  "message": "监管任务详情获取成功",
  "data": {
    "id": 1,
    "applicationNumber": "APP001",
    "contractNumber": "CONTRACT001",
    "productName": "农业贷款产品A",
    "customerName": "张三",
    "idType": "id_card",
    "idNumber": "110101199001011234",
    "assetType": "cattle",
    "assetQuantity": 10,
    "supervisionStatus": "supervising",
    "importTime": "2024-01-15T10:30:00.000Z",
    "startTime": "2024-01-15",
    "endTime": "2024-12-15",
    "loanAmount": "500000.00",
    "interestRate": "0.0650",
    "loanTerm": 12,
    "supervisorName": "李监管员",
    "supervisorPhone": "13800138001",
    "farmAddress": "北京市朝阳区某某养殖场",
    "remarks": "重点监管项目，需要定期检查",
    "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/supervision-tasks/:id`

#### 请求参数
与创建监管任务相同，所有字段都是可选的。

#### 响应示例
```json
{
  "success": true,
  "message": "监管任务更新成功",
  "data": {
    "id": 1,
    "applicationNumber": "APP001",
    "contractNumber": "CONTRACT001",
    "productName": "农业贷款产品A",
    "customerName": "张三",
    "supervisionStatus": "supervising",
    "remarks": "更新后的备注信息",
    "updatedAt": "2024-12-20T11:00:00.000Z"
  }
}
```

### 5. 删除监管任务
**DELETE** `/api/supervision-tasks/:id`

#### 响应示例
```json
{
  "success": true,
  "message": "监管任务删除成功"
}
```

### 6. 获取监管任务统计
**GET** `/api/supervision-tasks/stats`

#### 响应示例
```json
{
  "success": true,
  "message": "监管任务统计获取成功",
  "data": {
    "total": 8,
    "pending": 2,
    "supervising": 3,
    "completed": 2,
    "suspended": 1
  }
}
```

### 7. 批量更新监管任务状态
**PUT** `/api/supervision-tasks/batch/status`

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

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

### 8. 批量删除监管任务
**DELETE** `/api/supervision-tasks/batch`

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

#### 响应示例
```json
{
  "success": true,
  "message": "成功删除 3 个监管任务",
  "data": {
    "deletedCount": 3
  }
}
```

## 错误码说明

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

## 数据验证规则

### 必填字段验证
- `applicationNumber`: 申请单号，不能为空，最大50字符，唯一
- `contractNumber`: 放款合同编号，不能为空，最大50字符，唯一
- `productName`: 产品名称，不能为空，最大100字符
- `customerName`: 客户姓名，不能为空，最大50字符
- `idNumber`: 证件号码，不能为空，最大50字符
- `startTime`: 监管起始时间，不能为空
- `endTime`: 监管结束时间，不能为空

### 枚举值验证
- `idType`: 只能是 "id_card", "passport", "other"
- `assetType`: 只能是 "cattle", "sheep", "pig", "poultry", "other"
- `supervisionStatus`: 只能是 "pending", "supervising", "completed", "suspended"

### 数值字段验证
- `assetQuantity`: 不能为负数
- `loanAmount`: 不能为负数
- `interestRate`: 必须在0-1之间
- `loanTerm`: 不能为负数

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

## 使用示例

### JavaScript (axios)
```javascript
// 创建监管任务
const createSupervisionTask = async (taskData) => {
  try {
    const response = await axios.post('/api/supervision-tasks', taskData, {
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      }
    });
    return response.data;
  } catch (error) {
    console.error('创建监管任务失败:', error.response.data);
    throw error;
  }
};

// 获取监管任务列表
const getSupervisionTasks = async (params = {}) => {
  try {
    const response = await axios.get('/api/supervision-tasks', {
      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/supervision-tasks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationNumber": "APP001",
    "contractNumber": "CONTRACT001",
    "productName": "农业贷款产品A",
    "customerName": "张三",
    "idType": "id_card",
    "idNumber": "110101199001011234",
    "assetType": "cattle",
    "assetQuantity": 10,
    "startTime": "2024-01-15",
    "endTime": "2024-12-15"
  }'

# 获取监管任务列表
curl -X GET "http://localhost:5351/api/supervision-tasks?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## 数据库表结构

### supervision_tasks 表
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | INTEGER | 主键，自增 |
| applicationNumber | VARCHAR(50) | 申请单号，唯一 |
| contractNumber | VARCHAR(50) | 放款合同编号，唯一 |
| productName | VARCHAR(100) | 产品名称 |
| customerName | VARCHAR(50) | 客户姓名 |
| idType | ENUM | 证件类型 |
| idNumber | VARCHAR(50) | 证件号码 |
| assetType | ENUM | 养殖生资种类 |
| assetQuantity | INTEGER | 监管生资数量 |
| supervisionStatus | ENUM | 监管状态 |
| importTime | DATETIME | 任务导入时间 |
| startTime | DATE | 监管起始时间 |
| endTime | DATE | 监管结束时间 |
| loanAmount | DECIMAL(15,2) | 贷款金额 |
| interestRate | DECIMAL(5,4) | 利率 |
| loanTerm | INTEGER | 贷款期限（月） |
| supervisorName | VARCHAR(50) | 监管员姓名 |
| supervisorPhone | VARCHAR(20) | 监管员电话 |
| farmAddress | VARCHAR(200) | 养殖场地址 |
| remarks | TEXT | 备注 |
| createdBy | INTEGER | 创建人ID |
| updatedBy | INTEGER | 更新人ID |
| createdAt | DATETIME | 创建时间 |
| updatedAt | DATETIME | 更新时间 |
