# 贷款解押模块API接口文档

## 概述

本文档详细描述了银行管理系统贷款解押模块的所有API接口，包括接口地址、请求方法、参数说明、响应格式等信息。

## 基础信息

- **基础URL**: `http://localhost:5351`
- **模块路径**: `/api/loan-releases`
- **认证方式**: JWT Token
- **数据格式**: JSON
- **字符编码**: UTF-8

## 通用响应格式

### 成功响应
```json
{
  "success": true,
  "message": "操作成功",
  "data": {},
  "timestamp": "2025-09-26T10:30:00.000Z"
}
```

### 错误响应
```json
{
  "success": false,
  "message": "错误信息",
  "error": "ERROR_CODE",
  "timestamp": "2025-09-26T10:30:00.000Z"
}
```

## 1. 获取解押申请列表

- **接口地址**: `GET /api/loan-releases`
- **功能描述**: 获取贷款解押申请列表，支持分页和搜索
- **认证要求**: 需要JWT Token
- **请求参数**:
  - `page` (integer, optional): 页码，默认1
  - `pageSize` (integer, optional): 每页数量，默认10，最大100
  - `searchField` (string, optional): 搜索字段，可选值：
    - `application_number`: 申请单号
    - `customer_name`: 客户姓名
    - `product_name`: 产品名称
  - `searchValue` (string, optional): 搜索值
  - `status` (string, optional): 解押状态筛选，可选值：
    - `pending`: 待处理
    - `processing`: 处理中
    - `approved`: 已通过
    - `rejected`: 已拒绝
    - `completed`: 已完成
    - `released`: 已解押
  - `sortField` (string, optional): 排序字段，默认created_at
  - `sortOrder` (string, optional): 排序方向，可选值：asc, desc，默认desc

- **请求示例**:
  ```bash
  GET /api/loan-releases?page=1&pageSize=10&searchField=application_number&searchValue=20240227&status=pending
  ```

- **响应数据**:
  ```json
  {
    "success": true,
    "data": {
      "releases": [
        {
          "id": 1,
          "applicationNumber": "20240227145555918",
          "productName": "中国工商银行扎旗支行\"畜禽活体抵押\"",
          "farmerName": "刘超",
          "applicantName": "刘超",
          "applicantIdNumber": "511123199001013017",
          "applicantPhone": "13800138000",
          "assetType": "牛",
          "releaseQuantity": "10头",
          "releaseAmount": 10000,
          "status": "released",
          "applicationTime": "2024-02-27T06:55:55.000Z",
          "processTime": "2024-02-27T07:30:00.000Z",
          "completeTime": "2024-02-27T08:00:00.000Z",
          "processorName": "系统管理员",
          "processComment": "审核通过，同意解押",
          "rejectionReason": null,
          "remark": "客户信用良好",
          "created_at": "2025-09-26T03:38:50.000Z",
          "updated_at": "2025-09-26T03:38:50.000Z"
        }
      ],
      "pagination": {
        "current": 1,
        "pageSize": 10,
        "total": 6,
        "totalPages": 1
      }
    }
  }
  ```

## 2. 获取解押申请详情

- **接口地址**: `GET /api/loan-releases/:id`
- **功能描述**: 获取指定解押申请的详细信息
- **认证要求**: 需要JWT Token
- **路径参数**:
  - `id` (integer, required): 解押申请ID

- **请求示例**:
  ```bash
  GET /api/loan-releases/1
  ```

- **响应数据**:
  ```json
  {
    "success": true,
    "data": {
      "id": 1,
      "releaseNumber": "20240227145555918",
      "customerName": "刘超",
      "contractNumber": "CONTRACT-000007",
      "status": "released",
      "collateralType": "livestock",
      "collateralDescription": "优质肉牛",
      "loanAmount": 100000,
      "collateralValue": 150000,
      "applicationTime": "2024-02-27T06:55:55.000Z",
      "processTime": "2024-02-27T07:30:00.000Z",
      "completeTime": "2024-02-27T08:00:00.000Z",
      "phone": "13800138000",
      "idCard": "511123199001013017",
      "reason": "需要资金周转，申请部分解押",
      "remark": "客户信用良好",
      "history": [
        {
          "id": 1,
          "action": "apply",
          "operator": "刘超",
          "time": "2025-09-26T03:38:51.000Z",
          "comment": "提交解押申请"
        },
        {
          "id": 2,
          "action": "complete",
          "operator": "系统管理员",
          "time": "2025-09-26T03:38:51.000Z",
          "comment": "解押手续办理完成"
        }
      ]
    }
  }
  ```

## 3. 创建解押申请

- **接口地址**: `POST /api/loan-releases`
- **功能描述**: 创建新的解押申请
- **认证要求**: 需要JWT Token
- **请求参数**:
  ```json
  {
    "contract_id": 1,
    "customer_name": "测试用户",
    "customer_phone": "13800138000",
    "customer_id_card": "511123199001010001",
    "farmer_name": "测试用户",
    "product_name": "测试产品",
    "collateral_type": "livestock",
    "collateral_description": "测试抵押物",
    "collateral_value": 100000,
    "loan_amount": 80000,
    "release_amount": 50000,
    "release_quantity": "5头",
    "application_reason": "测试解押申请",
    "remark": "测试备注"
  }
  ```

- **字段说明**:
  - `contract_id` (integer, optional): 关联合同ID
  - `customer_name` (string, required): 客户姓名
  - `customer_phone` (string, required): 客户电话
  - `customer_id_card` (string, required): 客户身份证号
  - `farmer_name` (string, optional): 养殖户姓名
  - `product_name` (string, optional): 贷款产品名称
  - `collateral_type` (string, required): 抵押物类型，可选值：
    - `house`: 房产
    - `car`: 车辆
    - `land`: 土地
    - `equipment`: 设备
    - `livestock`: 牲畜
  - `collateral_description` (string, optional): 抵押物描述
  - `collateral_value` (number, optional): 抵押物价值
  - `loan_amount` (number, optional): 贷款金额
  - `release_amount` (number, required): 解押金额
  - `release_quantity` (string, optional): 解押数量
  - `application_reason` (string, optional): 申请原因
  - `remark` (string, optional): 备注

- **请求示例**:
  ```bash
  POST /api/loan-releases
  Content-Type: application/json
  Authorization: Bearer <your-jwt-token>
  
  {
    "customer_name": "测试用户",
    "customer_phone": "13800138000",
    "customer_id_card": "511123199001010001",
    "collateral_type": "livestock",
    "release_amount": 50000,
    "release_quantity": "5头",
    "application_reason": "测试解押申请"
  }
  ```

- **响应数据**:
  ```json
  {
    "success": true,
    "message": "解押申请创建成功",
    "data": {
      "id": 13,
      "applicationNumber": "REL-1758868323652"
    }
  }
  ```

## 4. 更新解押申请

- **接口地址**: `PUT /api/loan-releases/:id`
- **功能描述**: 更新指定解押申请信息
- **认证要求**: 需要JWT Token
- **路径参数**:
  - `id` (integer, required): 解押申请ID
- **请求参数**: 同创建解押申请参数
- **限制条件**: 只有待处理状态的申请才能更新

- **请求示例**:
  ```bash
  PUT /api/loan-releases/13
  Content-Type: application/json
  Authorization: Bearer <your-jwt-token>
  
  {
    "release_amount": 60000,
    "application_reason": "更新后的申请原因"
  }
  ```

- **响应数据**:
  ```json
  {
    "success": true,
    "message": "解押申请更新成功"
  }
  ```

## 5. 处理解押申请

- **接口地址**: `POST /api/loan-releases/:id/process`
- **功能描述**: 处理解押申请（通过/拒绝）
- **认证要求**: 需要JWT Token
- **路径参数**:
  - `id` (integer, required): 解押申请ID
- **请求参数**:
  ```json
  {
    "action": "approve",
    "comment": "审核通过",
    "remark": "测试处理"
  }
  ```

- **字段说明**:
  - `action` (string, required): 处理动作，可选值：
    - `approve`: 通过
    - `reject`: 拒绝
  - `comment` (string, required): 处理意见
  - `remark` (string, optional): 备注

- **请求示例**:
  ```bash
  POST /api/loan-releases/13/process
  Content-Type: application/json
  Authorization: Bearer <your-jwt-token>
  
  {
    "action": "approve",
    "comment": "审核通过，同意解押",
    "remark": "客户信用良好"
  }
  ```

- **响应数据**:
  ```json
  {
    "success": true,
    "message": "解押申请已通过",
    "data": {
      "id": 13,
      "status": "approved",
      "action": "approve",
      "comment": "审核通过"
    }
  }
  ```

## 6. 完成解押

- **接口地址**: `POST /api/loan-releases/:id/complete`
- **功能描述**: 完成解押手续
- **认证要求**: 需要JWT Token
- **路径参数**:
  - `id` (integer, required): 解押申请ID
- **请求参数**:
  ```json
  {
    "comment": "解押手续办理完成"
  }
  ```

- **字段说明**:
  - `comment` (string, required): 完成说明

- **请求示例**:
  ```bash
  POST /api/loan-releases/13/complete
  Content-Type: application/json
  Authorization: Bearer <your-jwt-token>
  
  {
    "comment": "解押手续办理完成，抵押物已释放"
  }
  ```

- **响应数据**:
  ```json
  {
    "success": true,
    "message": "解押完成",
    "data": {
      "id": 13,
      "status": "completed"
    }
  }
  ```

## 7. 删除解押申请

- **接口地址**: `DELETE /api/loan-releases/:id`
- **功能描述**: 删除指定解押申请（仅限待处理状态）
- **认证要求**: 需要JWT Token
- **路径参数**:
  - `id` (integer, required): 解押申请ID
- **限制条件**: 只有待处理状态的申请才能删除

- **请求示例**:
  ```bash
  DELETE /api/loan-releases/13
  Authorization: Bearer <your-jwt-token>
  ```

- **响应数据**:
  ```json
  {
    "success": true,
    "message": "解押申请删除成功"
  }
  ```

## 8. 获取解押统计信息

- **接口地址**: `GET /api/loan-releases/stats`
- **功能描述**: 获取解押申请统计信息
- **认证要求**: 需要JWT Token

- **请求示例**:
  ```bash
  GET /api/loan-releases/stats
  Authorization: Bearer <your-jwt-token>
  ```

- **响应数据**:
  ```json
  {
    "success": true,
    "data": {
      "total": 6,
      "pending": 0,
      "processing": 0,
      "approved": 0,
      "rejected": 0,
      "completed": 0,
      "released": 6,
      "statusStats": [
        {
          "status": "released",
          "count": 6
        }
      ],
      "amountStats": {
        "totalReleaseAmount": 1500000,
        "averageReleaseAmount": 250000
      }
    }
  }
  ```

## 状态说明

### 解押申请状态流转

1. **pending** (待处理) - 初始状态，申请已提交
2. **processing** (处理中) - 正在审核中
3. **approved** (已通过) - 审核通过
4. **rejected** (已拒绝) - 审核拒绝
5. **completed** (已完成) - 解押手续完成
6. **released** (已解押) - 抵押物已释放

### 状态流转规则

- `pending` → `processing` (开始处理)
- `processing` → `approved` (审核通过)
- `processing` → `rejected` (审核拒绝)
- `approved` → `completed` (完成解押)
- `completed` → `released` (释放抵押物)

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 400 | 请求参数错误 |
| 401 | 未授权访问 |
| 403 | 禁止访问 |
| 404 | 解押申请不存在 |
| 409 | 状态不允许此操作 |
| 422 | 数据验证失败 |
| 500 | 服务器内部错误 |

## 数据验证规则

### 必填字段验证
- `customer_name`: 客户姓名不能为空
- `customer_phone`: 客户电话不能为空，格式验证
- `customer_id_card`: 客户身份证号不能为空，格式验证
- `collateral_type`: 抵押物类型不能为空
- `release_amount`: 解押金额不能为空，必须大于0

### 格式验证
- `customer_phone`: 手机号格式验证
- `customer_id_card`: 身份证号格式验证
- `release_amount`: 金额格式验证，保留2位小数

### 业务规则验证
- 解押金额不能超过贷款金额
- 只有待处理状态的申请才能更新或删除
- 只有已通过状态的申请才能完成解押

## 权限说明

- **查看权限**: 所有认证用户
- **创建权限**: 所有认证用户
- **更新权限**: 申请创建者或管理员
- **处理权限**: 贷款专员或管理员
- **删除权限**: 申请创建者或管理员

---

**文档版本**: v1.0.0  
**最后更新**: 2025-09-26  
**维护人员**: 开发团队
