# 金融服务API设计文档

## 1. 概述

本文档详细描述了金融服务(finance-service)提供的API接口，包括贷款管理、保险管理等核心功能。

## 2. 基础信息

- 基础路径: `/api/v1/finance`
- 版本: v1
- 通信协议: HTTP/HTTPS
- 数据格式: JSON
- 状态码: 遵循HTTP状态码规范

## 3. 全局Headers

| Header名称 | 是否必填 | 描述 |
|------------|----------|------|
| Authorization | 是 | Bearer Token认证信息 |
| Content-Type | 是 | application/json |

## 4. 全局响应格式

### 4.1 成功响应
```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

### 4.2 错误响应
```json
{
  "code": 20001,
  "message": "错误描述",
  "data": null
}
```

## 5. 贷款管理接口

### 5.1 获取贷款产品列表

**接口地址**: `GET /loans/products`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 产品状态(ACTIVE/INACTIVE) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 贷款产品列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 5,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1,
        "name": "养殖贷款",
        "description": "专为养殖户设计的贷款产品",
        "interest_rate": 0.052,
        "term_months": 12,
        "min_amount": 10000.00,
        "max_amount": 1000000.00,
        "status": "ACTIVE",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}
```

### 5.2 提交贷款申请

**接口地址**: `POST /loans/applications`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| product_id | integer | 是 | 贷款产品ID |
| amount | number | 是 | 申请金额 |
| term_months | integer | 是 | 申请期限(月) |
| purpose | string | 否 | 贷款用途 |
| contact_info | object | 是 | 联系信息 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 贷款申请ID |
| user_id | integer | 申请人用户ID |
| product_id | integer | 贷款产品ID |
| amount | number | 申请金额 |
| term_months | integer | 申请期限(月) |
| status | string | 申请状态 |
| purpose | string | 贷款用途 |
| contact_info | object | 联系信息 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "product_id": 1,
  "amount": 50000.00,
  "term_months": 12,
  "purpose": "购买饲料",
  "contact_info": {
    "phone": "13800138000",
    "email": "user@example.com",
    "address": "北京市朝阳区xxx街道"
  }
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "product_id": 1,
    "amount": 50000.00,
    "term_months": 12,
    "status": "SUBMITTED",
    "purpose": "购买饲料",
    "contact_info": {
      "phone": "13800138000",
      "email": "user@example.com",
      "address": "北京市朝阳区xxx街道"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 5.3 查询贷款申请列表

**接口地址**: `GET /loans/applications`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 申请状态 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 贷款申请列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1001,
        "user_id": 12345,
        "product": {
          "id": 1,
          "name": "养殖贷款"
        },
        "amount": 50000.00,
        "term_months": 12,
        "status": "APPROVED",
        "purpose": "购买饲料",
        "contact_info": {
          "phone": "13800138000",
          "email": "user@example.com"
        },
        "approval_time": "2024-01-16T09:00:00Z",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 5.4 查询贷款申请详情

**接口地址**: `GET /loans/applications/{id}`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 贷款申请ID |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 贷款申请ID |
| user_id | integer | 申请人用户ID |
| product | object | 贷款产品信息 |
| amount | number | 申请金额 |
| term_months | integer | 申请期限(月) |
| status | string | 申请状态 |
| purpose | string | 贷款用途 |
| contact_info | object | 联系信息 |
| credit_score | integer | 信用评分 |
| approval_time | string | 审批时间 |
| disbursement_time | string | 放款时间 |
| settlement_time | string | 结清时间 |
| repayment_schedules | array | 还款计划列表 |
| created_at | string | 创建时间 |
| updated_at | string | 更新时间 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1001,
    "user_id": 12345,
    "product": {
      "id": 1,
      "name": "养殖贷款",
      "interest_rate": 0.052,
      "term_months": 12
    },
    "amount": 50000.00,
    "term_months": 12,
    "status": "DISBURSED",
    "purpose": "购买饲料",
    "contact_info": {
      "phone": "13800138000",
      "email": "user@example.com",
      "address": "北京市朝阳区xxx街道"
    },
    "credit_score": 750,
    "approval_time": "2024-01-16T09:00:00Z",
    "disbursement_time": "2024-01-17T10:00:00Z",
    "repayment_schedules": [
      {
        "id": 1,
        "installment_number": 1,
        "due_date": "2024-02-17",
        "principal_amount": 4166.67,
        "interest_amount": 216.67,
        "total_amount": 4383.34,
        "status": "PENDING"
      }
    ],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-17T10:00:00Z"
  }
}
```

## 6. 保险管理接口

### 6.1 获取保险产品列表

**接口地址**: `GET /insurance/products`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| type | string | 否 | 保险类型(CATTLE/PROPERTY/LIABILITY) |
| status | string | 否 | 产品状态(ACTIVE/INACTIVE) |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 保险产品列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 3,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 1,
        "name": "牲畜保险",
        "description": "为牲畜提供全面保障的保险产品",
        "premium_rate": 0.005,
        "coverage_amount": 10000.00,
        "term_months": 12,
        "type": "CATTLE",
        "status": "ACTIVE",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}
```

### 6.2 提交保险投保申请

**接口地址**: `POST /insurance/policies`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| product_id | integer | 是 | 保险产品ID |
| insured_amount | number | 是 | 投保金额 |
| start_date | string | 是 | 保险起始日期(YYYY-MM-DD) |
| beneficiary_info | object | 是 | 受益人信息 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 保单ID |
| user_id | integer | 投保人用户ID |
| product_id | integer | 保险产品ID |
| policy_no | string | 保单号 |
| insured_amount | number | 投保金额 |
| premium_amount | number | 保费金额 |
| status | string | 保单状态 |
| start_date | string | 保险起始日期 |
| end_date | string | 保险结束日期 |
| beneficiary_info | object | 受益人信息 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "product_id": 1,
  "insured_amount": 50000.00,
  "start_date": "2024-02-01",
  "beneficiary_info": {
    "name": "张三",
    "id_card": "110101199001011234",
    "phone": "13800138000"
  }
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 2001,
    "user_id": 12345,
    "product_id": 1,
    "policy_no": "INS202401150001",
    "insured_amount": 50000.00,
    "premium_amount": 250.00,
    "status": "ACTIVE",
    "start_date": "2024-02-01",
    "end_date": "2025-01-31",
    "beneficiary_info": {
      "name": "张三",
      "id_card": "110101199001011234",
      "phone": "13800138000"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

### 6.3 查询保险投保列表

**接口地址**: `GET /insurance/policies`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| status | string | 否 | 保单状态 |
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认10 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| total | integer | 总记录数 |
| page | integer | 当前页码 |
| size | integer | 每页数量 |
| items | array | 保险投保列表 |

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": 2001,
        "user_id": 12345,
        "policy_no": "INS202401150001",
        "product": {
          "id": 1,
          "name": "牲畜保险"
        },
        "insured_amount": 50000.00,
        "premium_amount": 250.00,
        "status": "ACTIVE",
        "start_date": "2024-02-01",
        "end_date": "2025-01-31",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}
```

### 6.4 提交理赔申请

**接口地址**: `POST /insurance/claims`

**请求参数**:

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| policy_id | integer | 是 | 保单ID |
| claim_amount | number | 是 | 理赔金额 |
| incident_date | string | 是 | 事故日期(YYYY-MM-DD) |
| incident_description | string | 是 | 事故描述 |
| supporting_documents | array | 否 | 支持文件URL列表 |

**响应数据**:

| 字段名 | 类型 | 描述 |
|--------|------|------|
| id | integer | 理赔申请ID |
| policy_id | integer | 关联保单ID |
| claim_no | string | 理赔编号 |
| claim_amount | number | 理赔金额 |
| status | string | 理赔状态 |
| incident_date | string | 事故日期 |
| incident_description | string | 事故描述 |
| supporting_documents | array | 支持文件URL列表 |
| created_at | string | 创建时间 |

**示例请求**:
```json
{
  "policy_id": 2001,
  "claim_amount": 20000.00,
  "incident_date": "2024-03-01",
  "incident_description": "牲畜因疾病死亡",
  "supporting_documents": [
    "http://example.com/document1.jpg",
    "http://example.com/document2.jpg"
  ]
}
```

**示例响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 3001,
    "policy_id": 2001,
    "claim_no": "CLM202403010001",
    "claim_amount": 20000.00,
    "status": "SUBMITTED",
    "incident_date": "2024-03-01",
    "incident_description": "牲畜因疾病死亡",
    "supporting_documents": [
      "http://example.com/document1.jpg",
      "http://example.com/document2.jpg"
    ],
    "created_at": "2024-03-01T10:30:00Z"
  }
}
```

## 7. 错误码定义

| 错误码 | 错误信息 | 描述 |
|--------|----------|------|
| 0 | success | 请求成功 |
| 20001 | 参数错误 | 请求参数不合法 |
| 20002 | 贷款产品不存在 | 指定的贷款产品不存在 |
| 20003 | 贷款申请不存在 | 指定的贷款申请不存在 |
| 20004 | 保险产品不存在 | 指定的保险产品不存在 |
| 20005 | 保单不存在 | 指定的保单不存在 |
| 20006 | 理赔申请不存在 | 指定的理赔申请不存在 |
| 20007 | 申请金额超出范围 | 贷款申请金额超出产品规定范围 |
| 20008 | 保险金额超出范围 | 保险金额超出产品规定范围 |
| 20009 | 保单已过期 | 保单已过期，无法提交理赔 |
| 20010 | 理赔金额超出保额 | 理赔金额超出保险金额 |
| 20011 | 申请状态错误 | 当前申请状态无法执行该操作 |
| 30001 | 权限不足 | 用户权限不足，无法访问该资源 |
| 30002 | 认证失败 | 用户认证失败 |
| 99999 | 系统错误 | 服务器内部错误 |