loan-pricing/doc/api/loan-pricing-workflow-api.md

# 利率定价流程 API 接口文档

## 概述

本文档描述利率定价流程管理相关的后端 API 接口。

**基础路径:** `/loanPricing/workflow`

**认证方式:** Bearer Token (JWT)

**Content-Type:** `application/json`

---

## 接口列表

### 1. 发起利率定价流程

创建新的利率定价申请。

**接口地址:** `POST /loanPricing/workflow/create`

**权限要求:** `loanPricing:workflow:create`

**请求参数:**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| orgCode | String | 是 | 机构编码,固定值: 931000 |
| runType | String | 是 | 运行模式,固定值: 1(同步) |
| custIsn | String | 是 | 客户内码 |
| custType | String | 是 | 客户类型,可选值: 个人/企业 |
| guarType | String | 是 | 担保方式,可选值: 信用/保证/抵押/质押 |
| midPerQuickPay | String | 否 | 中间业务_个人_快捷支付,值: true/false |
| midPerEleDdc | String | 否 | 中间业务_个人_电费代扣,值: true/false |
| midEntEleDdc | String | 否 | 中间业务_企业_电费代扣,值: true/false |
| midEntWaterDdc | String | 否 | 中间业务_企业_水费代扣,值: true/false |
| applyAmt | String | 是 | 申请金额,单位: 元 |
| isCleanEnt | String | 否 | 净身企业,值: true/false |
| hasSettleAcct | String | 否 | 开立基本结算账户,值: true/false |
| isManufacturing | String | 否 | 制造业企业,值: true/false |
| isAgriGuar | String | 否 | 省农担担保贷款,值: true/false |
| isTaxA | String | 否 | 是否纳税信用等级A级,值: true/false |
| isAgriLeading | String | 否 | 是否县级及以上农业龙头企业,值: true/false |
| loanPurpose | String | 否 | 贷款用途,可选值: consumer/business |
| bizProof | String | 否 | 是否有经营佐证,值: true/false |
| collType | String | 否 | 抵质押类型,可选值: 一线/一类/二类 |
| collThirdParty | String | 否 | 抵质押物是否三方所有,值: true/false |
| loanRate | String | 是 | 贷款利率 |
| custName | String | 否 | 客户名称 |
| idType | String | 否 | 证件类型 |
| isInclusiveFinance | String | 否 | 是否普惠小微借款人,值: true/false |

**请求示例:**

```json
{
  "orgCode": "931000",
  "runType": "1",
  "custIsn": "CUST001",
  "custType": "企业",
  "guarType": "抵押",
  "applyAmt": "1000000",
  "loanRate": "4.35",
  "custName": "某某科技有限公司",
  "loanPurpose": "business"
}
```

**响应示例:**

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "modelOutputId": 100,
    "serialNum": "20250119143025123",
    "orgCode": "931000",
    "runType": "1",
    "custIsn": "CUST001",
    "custType": "企业",
    "guarType": "抵押",
    "applyAmt": "1000000",
    "loanRate": "4.35",
    "custName": "某某科技有限公司",
    "createTime": "2025-01-19 14:30:25",
    "createBy": "admin"
  }
}
```

---

### 2. 查询利率定价流程列表

分页查询利率定价流程记录,支持多条件筛选。

**接口地址:** `GET /loanPricing/workflow/list`

**权限要求:** `loanPricing:workflow:list`

**请求参数:**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | Integer | 否 | 页码,默认 1 |
| pageSize | Integer | 否 | 每页数量,默认 10 |
| createBy | String | 否 | 创建者(筛选条件) |
| custName | String | 否 | 客户名称(模糊查询) |
| orgCode | String | 否 | 机构号(筛选条件) |
| custType | String | 否 | 客户类型(筛选条件) |
| guarType | String | 否 | 担保方式(筛选条件) |

**请求示例:**

```
GET /loanPricing/workflow/list?pageNum=1&pageSize=10&custName=科技
```

**响应示例:**

```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "modelOutputId": 100,
      "serialNum": "20250119143025123",
      "orgCode": "931000",
      "custIsn": "CUST001",
      "custType": "企业",
      "guarType": "抵押",
      "applyAmt": "1000000",
      "loanRate": "4.35",
      "custName": "某某科技有限公司",
      "createTime": "2025-01-19 14:30:25",
      "updateTime": "2025-01-19 15:20:10",
      "createBy": "admin"
    }
  ],
  "total": 1
}
```

**说明:** 结果按更新时间(update_time)倒序排列。

---

### 3. 查看利率定价流程详情

根据业务方流水号查询流程的完整信息,包括模型输出字段。

**接口地址:** `GET /loanPricing/workflow/{serialNum}`

**权限要求:** `loanPricing:workflow:query`

**路径参数:**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| serialNum | String | 是 | 业务方流水号 |

**请求示例:**

```
GET /loanPricing/workflow/20250119143025123
```

**响应示例:**

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "loanPricingWorkflow": {
      "id": 1,
      "modelOutputId": 100,
      "serialNum": "20250119143025123",
      "orgCode": "931000",
      "runType": "1",
      "custIsn": "CUST001",
      "custType": "企业",
      "guarType": "抵押",
      "midPerQuickPay": "false",
      "midPerEleDdc": "false",
      "midEntEleDdc": "false",
      "midEntWaterDdc": "false",
      "applyAmt": "1000000",
      "isCleanEnt": "false",
      "hasSettleAcct": "false",
      "isManufacturing": "true",
      "isAgriGuar": "false",
      "isTaxA": "false",
      "isAgriLeading": "false",
      "loanPurpose": "business",
      "bizProof": "true",
      "collType": "一类",
      "collThirdParty": "false",
      "loanRate": "4.35",
      "executeRate": "4.20",
      "custName": "某某科技有限公司",
      "idType": "统一社会信用代码",
      "isInclusiveFinance": "true",
      "createTime": "2025-01-19 14:30:25",
      "createBy": "admin",
      "updateTime": "2025-01-19 15:20:10",
      "updateBy": "admin"
    },
    "modelRetailOutputFields": {
      "id": 1,
      "custIsn": "CUST001",
      "custType": "个人",
      "custName": "张三",
      "idType": "身份证",
      "idNum": "330102199001011234",
      "baseLoanRate": "3.45",
      "isFirstLoan": "true",
      "faithDay": "365",
      "custAge": "35",
      "bpFirstLoan": "-10",
      "bpAgeLoan": "-5",
      "bpAge": "0",
      "totalBpLoyalty": "-15",
      "balanceAvg": "50000",
      "loanAvg": "300000",
      "derivationRate": "0.6",
      "totalBpContribution": "-20",
      "midPerCard": "true",
      "midPerPass": "false",
      "midPerHarvest": "true",
      "midPerEffect": "true",
      "midPerQuickPay": "false",
      "midPerEleDdc": "false",
      "midPerWaterDdc": "false",
      "midPerHuashuDdc": "false",
      "MidPerGasDdc": "false",
      "midPerCitizencard": "true",
      "midPerFinMan": "false",
      "midPerEtc": "true",
      "bpMid": "-15",
      "totoalBpRelevance": "-50",
      "applyAmt": "500000",
      "bpLoanAmount": "0",
      "loanPurpose": "consumer",
      "bizProof": "false",
      "bpLoanUse": "0",
      "loanLoop": "false",
      "bpLoanLoop": "0",
      "collType": "一类",
      "collThirdParty": "false",
      "bpCollateral": "-30",
      "greyCust": "false",
      "prinOverdue": "false",
      "interestOverdue": "false",
      "cardOverdue": "false",
      "bpGreyOverdue": "0",
      "totoalBpRisk": "0",
      "totalBp": "-80",
      "calculateRate": "2.65"
    },
    "modelCorpOutputFields": {
      "id": 2,
      "custIsn": "CUST001",
      "custType": "企业",
      "custName": "某某科技有限公司",
      "idType": "统一社会信用代码",
      "idNum": "91330100MA2ABCDE01",
      "baseLoanRate": "3.45",
      "isFirstLoan": "false",
      "faithDay": "730",
      "bpFirstLoan": "0",
      "bpAgeLoan": "-5",
      "totalBpLoyalty": "-5",
      "balanceAvg": "500000",
      "loanAvg": "3000000",
      "derivationRate": "0.16",
      "totalBpContribution": "-30",
      "midEntConnect": "true",
      "midEntEffect": "true",
      "midEntInter": "false",
      "midEntAccept": "true",
      "midEntDiscount": "false",
      "midEntEleDdc": "true",
      "midEntWaterDdc": "false",
      "midEntTax": "true",
      "bpMid": "-20",
      "payroll": "50",
      "invLoanAmount": "2000000",
      "bpPayroll": "-10",
      "isCleanEnt": "true",
      "hasSettleAcct": "true",
      "isAgriGuar": "false",
      "isGreenLoan": "false",
      "isTechEnt": "true",
      "bpEntType": "-25",
      "totoalBpRelevance": "-55",
      "loanTerm": "36",
      "bpLoanTerm": "0",
      "applyAmt": "1000000",
      "bpLoanAmount": "0",
      "collType": "一类",
      "collThirdParty": "false",
      "bpCollateral": "-30",
      "greyCust": "false",
      "prinOverdue": "false",
      "interestOverdue": "false",
      "cardOverdue": "false",
      "bpGreyOverdue": "0",
      "totoalBpRisk": "0",
      "totalBp": "-85",
      "calculateRate": "2.60"
    }
  }
}
```

**说明:**
- `loanPricingWorkflow`: 利率定价流程基本信息
- `modelRetailOutputFields`: 个人客户模型输出字段(当 custType 为个人时返回)
- `modelCorpOutputFields`: 企业客户模型输出字段(当 custType 为企业时返回)

---

### 4. 设定执行利率

为利率定价流程设定或更新最终执行利率。

**接口地址:** `PUT /loanPricing/workflow/{serialNum}/executeRate`

**权限要求:** 无特殊权限要求

**路径参数:**

| 参数名       | 类型     | 必填 | 说明     |
|-----------|--------|----|--------|
| serialNum | String | 是  | 业务方流水号 |

**请求参数:**

| 参数名         | 类型     | 必填 | 说明      |
|-------------|--------|----|---------|
| executeRate | String | 是  | 执行利率(%) |

**请求示例:**

```bash
PUT /loanPricing/workflow/20250119143025123/executeRate
```

```json
{
  "executeRate": "4.20"
}
```

**响应示例:**

成功 (200):

```json
{
  "code": 200,
  "msg": "操作成功"
}
```

失败 (记录不存在):

```json
{
  "code": 500,
  "msg": "设定失败"
}
```

**说明:**

- 该接口支持多次设定/更新执行利率
- 更新成功后会自动记录 `updateBy` 和 `updateTime`
- 如果指定的 `serialNum` 不存在,返回"设定失败"

---

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 401 | 未授权,请先登录 |
| 403 | 无权限访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

**错误响应示例:**

```json
{
  "code": 404,
  "msg": "记录不存在"
}
```

---

## 数据字典

### 客户类型 (custType)

| 值 | 说明 |
|----|------|
| 个人 | 个人客户 |
| 企业 | 企业客户 |

### 担保方式 (guarType)

| 值 | 说明 |
|----|------|
| 信用 | 信用贷款 |
| 保证 | 保证贷款 |
| 抵押 | 抵押贷款 |
| 质押 | 质押贷款 |

### 贷款用途 (loanPurpose)

| 值 | 说明 |
|----|------|
| consumer | 消费贷款 |
| business | 经营贷款 |

### 抵质押类型 (collType)

| 值 | 说明 |
|----|------|
| 一线 | 一线抵押 |
| 一类 | 一类抵押 |
| 二类 | 二类抵押 |

### 运行模式 (runType)

| 值 | 说明 |
|----|------|
| 1 | 同步运行 |

---

## 在线文档

访问 Swagger UI 查看交互式 API 文档: `http://localhost:8080/swagger-ui.html`