# 金融业务系统 API 文档 (v1.1.0)

## 1. 接口概述

### 1.1 功能范围
- 贷款申请
- 保险购买
- 理赔处理
- 贷款审批

### 1.2 基础路径
`/api/v1/[系统名称]`

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

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

## 2. 接口明细

### 2.1 贷款申请
```
POST /loans
```

**请求参数**:
| 字段            | 类型    | 必填 | 说明               |
|-----------------|---------|------|--------------------|
| farmer_id       | number  | 是   | 牧户ID            |
| amount          | number  | 是   | 申请金额(元)      |
| collateral_type | string  | 是   | 抵押物类型        |
| term           | number  | 是   | 贷款期限(月)      |
| interest_rate   | number  | 是   | 年利率(%)         |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "loan_id": "loan_001",
    "farmer_id": 1001,
    "amount": 50000,
    "collateral_type": "牛只",
    "term": 12,
    "interest_rate": 4.35,
    "monthly_payment": 4260.25,
    "application_date": "2024-01-20T10:00:00Z",
    "status": "审批中"
  }
}
```

### 2.2 贷款审批状态查询
```
GET /loans/:id/status
```

**请求参数**:
| 参数        | 类型   | 必填 | 说明               |
|-------------|--------|------|--------------------|
| id          | string | 是   | 贷款ID             |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "loan_id": "loan_001",
    "status": "已批准",
    "approval_date": "2024-01-21T10:00:00Z",
    "approved_amount": 50000,
    "approver": "审批员001",
    "next_payment_date": "2024-02-20T10:00:00Z"
  }
}
```

### 2.3 保险购买
```
POST /insurances
```

**请求参数**:
| 字段            | 类型    | 必填 | 说明               |
|-----------------|---------|------|--------------------|
| farmer_id       | number  | 是   | 牧户ID            |
| cattle_id       | string  | 是   | 牛只ID            |
| insurance_type  | string  | 是   | 保险类型          |
| premium         | number  | 是   | 保费(元)          |

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "insurance_id": "ins_001",
    "farmer_id": 1001,
    "cattle_id": "cattle_123",
    "insurance_type": "疾病保险",
    "premium": 500,
    "coverage_amount": 10000,
    "effective_date": "2024-01-20T10:00:00Z",
    "expiry_date": "2025-01-20T10:00:00Z",
    "policy_number": "POL-20240120-001"
  }
}
```

## 3. 风控规则
- 单笔贷款金额 ≤ 牧户资产总额的50%
- 理赔申请需在灾害发生后30天内提交
- 敏感数据需RSA加密传输

## 4. 权限控制
- 贷款申请：牧户
- 贷款审批：银行管理员
- 保险购买：牧户
## 3. 版本历史

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