# 回款管理模块 - API接口文档

> **模块**: 08-回款管理  
> **版本**: v1.0  
> **日期**: 2025-10-03  
> **关联文档**:
> - 需求文档: `docs/08-回款管理模块需求.md`
> - 原型图: `yuanxing/08-回款管理原型图.md`
> - 数据库: `sql/crm/08-crm_payment.sql`

---

## 📋 目录

- [1. 回款计划接口](#1-回款计划接口)
- [2. 回款记录接口](#2-回款记录接口)
- [3. 统计分析接口](#3-统计分析接口)
- [4. 数据模型](#4-数据模型)

---

## 1. 回款计划接口

### 1.1 查询回款计划列表（分页）

**接口地址**: `GET /crm/payment/plan/list`

**接口描述**: 分页查询回款计划列表，支持多条件筛选

**权限标识**: `crm:payment:plan:list`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | Integer | 否 | 页码，默认1 |
| pageSize | Integer | 否 | 每页条数，默认10 |
| planNo | String | 否 | 计划编号（模糊查询） |
| contractId | Long | 否 | 合同ID |
| contractNo | String | 否 | 合同编号（模糊查询） |
| customerId | Long | 否 | 客户ID |
| customerName | String | 否 | 客户名称（模糊查询） |
| status | String | 否 | 状态 |
| isOverdue | Integer | 否 | 是否逾期(0否 1是) |
| ownerUserId | Long | 否 | 负责人ID |
| planDateBegin | String | 否 | 计划回款日期开始 |
| planDateEnd | String | 否 | 计划回款日期结束 |
| beginTime | String | 否 | 创建开始时间 |
| endTime | String | 否 | 创建结束时间 |

**返回示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "planNo": "PLAN20250115001",
      "contractId": 1,
      "contractNo": "CON20250115001",
      "customerId": 1,
      "customerName": "华为技术有限公司",
      "period": 1,
      "planAmount": 40500.00,
      "planDate": "2025-01-22",
      "planPercent": 30.00,
      "receivedAmount": 40500.00,
      "unreceivedAmount": 0.00,
      "status": "finished",
      "isOverdue": 0,
      "overduedays": 0,
      "remindDays": 7,
      "remindStatus": "reminded",
      "lastRemindTime": "2025-01-15 09:00:00",
      "ownerUserId": 1,
      "ownerUserName": "张三",
      "createTime": "2025-01-15 10:00:00",
      "remark": "首期款30%"
    }
  ],
  "total": 156
}
```

---

### 1.2 查询回款计划详情

**接口地址**: `GET /crm/payment/plan/{id}`

**接口描述**: 根据ID查询回款计划详细信息

**权限标识**: `crm:payment:plan:query`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 回款计划ID |

**返回示例**: 同1.1列表返回的单条数据，包含完整字段

---

### 1.3 新增回款计划

**接口地址**: `POST /crm/payment/plan`

**接口描述**: 新增回款计划信息

**权限标识**: `crm:payment:plan:add`

**请求体**:
```json
{
  "planNo": "PLAN20250115001",
  "contractId": 1,
  "customerId": 1,
  "period": 1,
  "planAmount": 40500.00,
  "planDate": "2025-01-22",
  "planPercent": 30.00,
  "remindDays": 7,
  "ownerUserId": 1,
  "remark": "首期款30%"
}
```

**请求参数说明**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| planNo | String | 是 | 计划编号，唯一，格式：PLAN+yyyyMMdd+4位流水号 |
| contractId | Long | 是 | 合同ID |
| customerId | Long | 是 | 客户ID |
| period | Integer | 是 | 期数，必须大于0 |
| planAmount | BigDecimal | 是 | 计划回款金额，保留2位小数 |
| planDate | String | 是 | 计划回款日期 yyyy-MM-dd |
| planPercent | BigDecimal | 否 | 计划比例（百分比） |
| remindDays | Integer | 否 | 提前提醒天数，默认7天 |
| ownerUserId | Long | 否 | 负责人ID，默认当前用户 |
| remark | String | 否 | 备注，最大500字符 |

**校验规则**:
- 计划编号必须唯一
- 计划金额必须大于0
- 合同ID必须存在
- 期数不能重复（同一合同）

**业务规则**:
- 自动计算未回款金额：planAmount - receivedAmount
- 默认状态为pending（待回款）
- 自动验证计划总金额是否超过合同金额

**返回示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "planNo": "PLAN20250115001"
  }
}
```

---

### 1.4 修改回款计划

**接口地址**: `PUT /crm/payment/plan`

**接口描述**: 修改回款计划信息

**权限标识**: `crm:payment:plan:edit`

**请求体**: 同新增接口，但需要传入id

**业务规则**:
- 只有待回款状态的计划才能修改
- 如果有关联回款记录，不允许修改金额

**返回示例**:
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 1.5 删除回款计划

**接口地址**: `DELETE /crm/payment/plan/{ids}`

**接口描述**: 删除回款计划（支持批量）

**权限标识**: `crm:payment:plan:remove`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | Long[] | 是 | 回款计划ID数组 |

**业务规则**:
- 有关联回款记录的计划不允许删除
- 已完成的计划不允许删除

**返回示例**:
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 1.6 查询合同回款计划

**接口地址**: `GET /crm/payment/plan/contract/{contractId}`

**接口描述**: 查询指定合同的所有回款计划

**权限标识**: `crm:payment:plan:query`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| contractId | Long | 是 | 合同ID |

**返回示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "id": 1,
      "period": 1,
      "planAmount": 40500.00,
      "planDate": "2025-01-22",
      "planPercent": 30.00,
      "receivedAmount": 40500.00,
      "status": "finished"
    },
    {
      "id": 2,
      "period": 2,
      "planAmount": 81000.00,
      "planDate": "2025-02-15",
      "planPercent": 60.00,
      "receivedAmount": 0.00,
      "status": "pending"
    }
  ]
}
```

---

### 1.7 批量生成回款计划

**接口地址**: `POST /crm/payment/plan/batchGenerate`

**接口描述**: 根据合同自动生成回款计划

**权限标识**: `crm:payment:plan:add`

**请求体**:
```json
{
  "contractId": 1,
  "plans": [
    {
      "period": 1,
      "planPercent": 30.00,
      "planDate": "2025-01-22",
      "remark": "首期款"
    },
    {
      "period": 2,
      "planPercent": 60.00,
      "planDate": "2025-02-15",
      "remark": "二期款"
    },
    {
      "period": 3,
      "planPercent": 10.00,
      "planDate": "2025-03-01",
      "remark": "尾款"
    }
  ]
}
```

**请求参数说明**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| contractId | Long | 是 | 合同ID |
| plans | Array | 是 | 计划列表，至少1个 |

**业务规则**:
- 自动根据合同金额计算每期金额
- 验证总比例是否为100%
- 自动生成计划编号

**返回示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "count": 3
  }
}
```

---

### 1.8 导出回款计划

**接口地址**: `POST /crm/payment/plan/export`

**接口描述**: 导出回款计划数据到Excel

**权限标识**: `crm:payment:plan:export`

**请求体**: 查询参数同1.1列表查询接口

**返回**: Excel文件流

---

## 2. 回款记录接口

### 2.1 查询回款记录列表（分页）

**接口地址**: `GET /crm/payment/list`

**接口描述**: 分页查询回款记录列表，支持多条件筛选

**权限标识**: `crm:payment:list`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | Integer | 否 | 页码，默认1 |
| pageSize | Integer | 否 | 每页条数，默认10 |
| paymentNo | String | 否 | 回款编号（模糊查询） |
| contractId | Long | 否 | 合同ID |
| contractNo | String | 否 | 合同编号（模糊查询） |
| customerId | Long | 否 | 客户ID |
| customerName | String | 否 | 客户名称（模糊查询） |
| planId | Long | 否 | 回款计划ID |
| paymentMethod | String | 否 | 付款方式 |
| status | String | 否 | 回款状态 |
| ownerUserId | Long | 否 | 负责人ID |
| confirmBy | Long | 否 | 确认人ID |
| paymentDateBegin | String | 否 | 回款日期开始 |
| paymentDateEnd | String | 否 | 回款日期结束 |
| beginTime | String | 否 | 创建开始时间 |
| endTime | String | 否 | 创建结束时间 |

**返回示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "paymentNo": "PAY20250120001",
      "contractId": 1,
      "contractNo": "CON20250115001",
      "customerId": 1,
      "customerName": "华为技术有限公司",
      "planId": 1,
      "planNo": "PLAN20250115001",
      "period": 1,
      "amount": 40500.00,
      "paymentDate": "2025-01-20",
      "paymentMethod": "bank",
      "paymentAccount": "6222 **** **** 1234",
      "voucherNo": "20250120123456",
      "voucherFile": "/upload/payment/voucher1.pdf",
      "status": "confirmed",
      "confirmBy": 2,
      "confirmByName": "李四",
      "confirmTime": "2025-01-20 14:30:00",
      "ownerUserId": 1,
      "ownerUserName": "张三",
      "bankName": "中国工商银行",
      "bankAccount": "1234567890",
      "createTime": "2025-01-20 10:00:00",
      "remark": "首期款已到账"
    }
  ],
  "total": 234
}
```

---

### 2.2 查询回款记录详情

**接口地址**: `GET /crm/payment/{id}`

**接口描述**: 根据ID查询回款记录详细信息

**权限标识**: `crm:payment:query`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 回款记录ID |

**返回示例**: 同2.1列表返回的单条数据，包含完整字段

---

### 2.3 新增回款记录

**接口地址**: `POST /crm/payment`

**接口描述**: 新增回款记录信息

**权限标识**: `crm:payment:add`

**请求体**:
```json
{
  "paymentNo": "PAY20250120001",
  "contractId": 1,
  "customerId": 1,
  "planId": 1,
  "amount": 40500.00,
  "paymentDate": "2025-01-20",
  "paymentMethod": "bank",
  "paymentAccount": "6222 **** **** 1234",
  "voucherNo": "20250120123456",
  "bankName": "中国工商银行",
  "bankAccount": "1234567890",
  "ownerUserId": 1,
  "remark": "首期款已到账"
}
```

**请求参数说明**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| paymentNo | String | 是 | 回款编号，唯一，格式：PAY+yyyyMMdd+4位流水号 |
| contractId | Long | 是 | 合同ID |
| customerId | Long | 是 | 客户ID |
| planId | Long | 否 | 回款计划ID |
| amount | BigDecimal | 是 | 回款金额，保留2位小数 |
| paymentDate | String | 是 | 回款日期 yyyy-MM-dd |
| paymentMethod | String | 是 | 付款方式：bank/cash/check/alipay/wechat/other |
| paymentAccount | String | 否 | 付款账户，最大100字符 |
| voucherNo | String | 否 | 凭证号，最大100字符 |
| voucherFile | String | 否 | 凭证文件路径 |
| bankName | String | 否 | 收款银行，最大100字符 |
| bankAccount | String | 否 | 收款账号，最大100字符 |
| ownerUserId | Long | 否 | 负责人ID，默认当前用户 |
| remark | String | 否 | 备注，最大500字符 |

**校验规则**:
- 回款编号必须唯一
- 回款金额必须大于0
- 合同ID必须存在
- 回款日期不能超过当前日期

**业务规则**:
- 默认状态为pending（待确认）
- 如果关联了回款计划，自动更新计划的receivedAmount
- 自动更新合同的receivedAmount和unreceivedAmount

**返回示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "paymentNo": "PAY20250120001"
  }
}
```

---

### 2.4 修改回款记录

**接口地址**: `PUT /crm/payment`

**接口描述**: 修改回款记录信息

**权限标识**: `crm:payment:edit`

**请求体**: 同新增接口，但需要传入id

**业务规则**:
- 只有待确认状态的回款记录才能修改
- 已确认的记录只能修改备注和凭证

**返回示例**:
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 2.5 删除回款记录

**接口地址**: `DELETE /crm/payment/{ids}`

**接口描述**: 删除回款记录（支持批量）

**权限标识**: `crm:payment:remove`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | Long[] | 是 | 回款记录ID数组 |

**业务规则**:
- 只能删除待确认状态的回款记录
- 删除时自动更新关联的计划和合同金额

**返回示例**:
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 2.6 确认回款

**接口地址**: `PUT /crm/payment/confirm`

**接口描述**: 确认回款到账

**权限标识**: `crm:payment:confirm`

**请求体**:
```json
{
  "id": 1,
  "remark": "已核实到账"
}
```

**请求参数说明**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 回款记录ID |
| remark | String | 否 | 确认说明 |

**业务规则**:
- 只有待确认状态的回款记录才能确认
- 确认后状态变为confirmed
- 记录确认人和确认时间
- 如果关联了回款计划，自动更新计划状态

**返回示例**:
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 2.7 批量确认回款

**接口地址**: `PUT /crm/payment/batchConfirm`

**接口描述**: 批量确认回款到账

**权限标识**: `crm:payment:confirm`

**请求体**:
```json
{
  "ids": [1, 2, 3],
  "remark": "批量确认"
}
```

**返回示例**:
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 2.8 作废回款

**接口地址**: `PUT /crm/payment/invalid`

**接口描述**: 作废回款记录

**权限标识**: `crm:payment:invalid`

**请求体**:
```json
{
  "id": 1,
  "invalidReason": "客户退款",
  "remark": ""
}
```

**请求参数说明**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 回款记录ID |
| invalidReason | String | 是 | 作废原因，最大500字符 |
| remark | String | 否 | 备注 |

**业务规则**:
- 状态变更为invalid
- 记录作废原因和作废时间
- 自动更新关联的计划和合同金额

**返回示例**:
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

---

### 2.9 上传回款凭证

**接口地址**: `POST /crm/payment/uploadVoucher`

**接口描述**: 上传回款凭证文件

**权限标识**: `crm:payment:edit`

**请求参数**: multipart/form-data
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 回款记录ID |
| file | File | 是 | 凭证文件（PDF/图片） |

**业务规则**:
- 支持PDF、JPG、PNG格式
- 文件大小不超过5MB
- 更新voucherFile字段

**返回示例**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "fileUrl": "/upload/payment/voucher1.pdf"
  }
}
```

---

### 2.10 查询合同回款记录

**接口地址**: `GET /crm/payment/contract/{contractId}`

**接口描述**: 查询指定合同的所有回款记录

**权限标识**: `crm:payment:query`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| contractId | Long | 是 | 合同ID |

**返回示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "id": 1,
      "paymentNo": "PAY20250120001",
      "amount": 40500.00,
      "paymentDate": "2025-01-20",
      "paymentMethod": "bank",
      "status": "confirmed"
    }
  ]
}
```

---

### 2.11 导出回款记录

**接口地址**: `POST /crm/payment/export`

**接口描述**: 导出回款记录数据到Excel

**权限标识**: `crm:payment:export`

**请求体**: 查询参数同2.1列表查询接口

**返回**: Excel文件流

---

## 3. 统计分析接口

### 3.1 回款统计概览

**接口地址**: `GET /crm/payment/statistics/overview`

**接口描述**: 获取回款统计概览数据

**权限标识**: `crm:payment:list`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ownerUserId | Long | 否 | 负责人ID，不传则查询当前用户 |
| beginTime | String | 否 | 开始时间 |
| endTime | String | 否 | 结束时间 |

**返回示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "planTotalCount": 156,
    "planPendingCount": 68,
    "planFinishedCount": 78,
    "planOverdueCount": 12,
    "planTotalAmount": 8750000.00,
    "planReceivedAmount": 4350000.00,
    "planUnreceivedAmount": 4400000.00,
    "paymentTotalCount": 234,
    "paymentPendingCount": 18,
    "paymentConfirmedCount": 208,
    "paymentInvalidCount": 8,
    "paymentTotalAmount": 4350000.00,
    "paymentAvgAmount": 18589.74,
    "receivedRate": 49.71
  }
}
```

---

### 3.2 回款趋势分析

**接口地址**: `GET /crm/payment/statistics/trend`

**接口描述**: 分析回款金额趋势

**权限标识**: `crm:payment:list`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| type | String | 否 | 统计类型：month/quarter/year，默认month |
| beginTime | String | 否 | 开始时间 |
| endTime | String | 否 | 结束时间 |

**返回示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "period": "2025-01",
      "planCount": 45,
      "planAmount": 2580000.00,
      "paymentCount": 38,
      "paymentAmount": 1850000.00,
      "receivedRate": 71.71
    }
  ]
}
```

---

### 3.3 逾期回款统计

**接口地址**: `GET /crm/payment/statistics/overdue`

**接口描述**: 统计逾期回款情况

**权限标识**: `crm:payment:list`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ownerUserId | Long | 否 | 负责人ID |

**返回示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "totalCount": 12,
    "totalAmount": 850000.00,
    "avgOverdueDays": 15.5,
    "list": [
      {
        "id": 5,
        "planNo": "PLAN20241215001",
        "contractNo": "CON20241201001",
        "customerName": "XX科技有限公司",
        "planAmount": 120000.00,
        "planDate": "2025-01-05",
        "overdueDays": 18,
        "ownerUserName": "张三"
      }
    ]
  }
}
```

---

### 3.4 回款方式统计

**接口地址**: `GET /crm/payment/statistics/method`

**接口描述**: 按付款方式统计回款分布

**权限标识**: `crm:payment:list`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| beginTime | String | 否 | 开始时间 |
| endTime | String | 否 | 结束时间 |

**返回示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "paymentMethod": "bank",
      "methodName": "银行转账",
      "count": 180,
      "amount": 3850000.00,
      "percent": 88.51
    },
    {
      "paymentMethod": "alipay",
      "methodName": "支付宝",
      "count": 35,
      "amount": 350000.00,
      "percent": 8.05
    }
  ]
}
```

---

### 3.5 负责人回款统计

**接口地址**: `GET /crm/payment/statistics/owner`

**接口描述**: 按负责人统计回款情况

**权限标识**: `crm:payment:list`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| beginTime | String | 否 | 开始时间 |
| endTime | String | 否 | 结束时间 |

**返回示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "ownerUserId": 1,
      "ownerUserName": "张三",
      "planCount": 45,
      "planAmount": 2850000.00,
      "paymentCount": 38,
      "paymentAmount": 1950000.00,
      "receivedRate": 68.42
    }
  ]
}
```

---

### 3.6 待回款提醒

**接口地址**: `GET /crm/payment/statistics/reminder`

**接口描述**: 查询即将到期的回款计划

**权限标识**: `crm:payment:list`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| days | Integer | 否 | 提前天数，默认7天 |

**返回示例**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "id": 8,
      "planNo": "PLAN20250115003",
      "contractNo": "CON20250115001",
      "customerName": "华为技术有限公司",
      "planAmount": 13500.00,
      "planDate": "2025-03-01",
      "remainDays": 5,
      "ownerUserName": "张三"
    }
  ]
}
```

---

## 4. 数据模型

### 4.1 PaymentPlanBo（回款计划业务对象）

```java
public class CrmPaymentPlanBo extends BaseEntity {
    /** 主键ID */
    @NotNull(message = "主键不能为空", groups = { EditGroup.class })
    private Long id;

    /** 计划编号 */
    @NotBlank(message = "计划编号不能为空", groups = { AddGroup.class, EditGroup.class })
    private String planNo;

    /** 合同ID */
    @NotNull(message = "合同ID不能为空", groups = { AddGroup.class, EditGroup.class })
    private Long contractId;

    /** 客户ID */
    @NotNull(message = "客户ID不能为空", groups = { AddGroup.class, EditGroup.class })
    private Long customerId;

    /** 期数 */
    @NotNull(message = "期数不能为空", groups = { AddGroup.class, EditGroup.class })
    @Min(value = 1, message = "期数必须大于0")
    private Integer period;

    /** 计划回款金额 */
    @NotNull(message = "计划回款金额不能为空", groups = { AddGroup.class, EditGroup.class })
    @Min(value = 0, message = "计划回款金额必须大于0")
    private BigDecimal planAmount;

    /** 计划回款日期 */
    @NotBlank(message = "计划回款日期不能为空", groups = { AddGroup.class, EditGroup.class })
    private String planDate;

    /** 计划比例 */
    private BigDecimal planPercent;

    /** 提前提醒天数 */
    private Integer remindDays;

    /** 负责人ID */
    private Long ownerUserId;

    /** 备注 */
    private String remark;
}
```

---

### 4.2 PaymentBo（回款记录业务对象）

```java
public class CrmPaymentBo extends BaseEntity {
    /** 主键ID */
    @NotNull(message = "主键不能为空", groups = { EditGroup.class })
    private Long id;

    /** 回款编号 */
    @NotBlank(message = "回款编号不能为空", groups = { AddGroup.class, EditGroup.class })
    private String paymentNo;

    /** 合同ID */
    @NotNull(message = "合同ID不能为空", groups = { AddGroup.class, EditGroup.class })
    private Long contractId;

    /** 客户ID */
    @NotNull(message = "客户ID不能为空", groups = { AddGroup.class, EditGroup.class })
    private Long customerId;

    /** 回款计划ID */
    private Long planId;

    /** 回款金额 */
    @NotNull(message = "回款金额不能为空", groups = { AddGroup.class, EditGroup.class })
    @Min(value = 0, message = "回款金额必须大于0")
    private BigDecimal amount;

    /** 回款日期 */
    @NotBlank(message = "回款日期不能为空", groups = { AddGroup.class, EditGroup.class })
    private String paymentDate;

    /** 付款方式 */
    @NotBlank(message = "付款方式不能为空", groups = { AddGroup.class, EditGroup.class })
    private String paymentMethod;

    /** 付款账户 */
    private String paymentAccount;

    /** 凭证号 */
    private String voucherNo;

    /** 凭证文件 */
    private String voucherFile;

    /** 收款银行 */
    private String bankName;

    /** 收款账号 */
    private String bankAccount;

    /** 负责人ID */
    private Long ownerUserId;

    /** 备注 */
    private String remark;
}
```

---

## 5. 数据字典

### 5.1 回款计划状态 (crm_payment_plan_status)

| 字典值 | 字典标签 | 说明 |
|--------|---------|------|
| pending | 待回款 | 等待回款 |
| partial | 部分回款 | 部分到账 |
| finished | 已完成 | 全部到账 |
| overdue | 已逾期 | 超过计划日期 |

---

### 5.2 回款状态 (crm_payment_status)

| 字典值 | 字典标签 | 说明 |
|--------|---------|------|
| pending | 待确认 | 等待财务确认 |
| confirmed | 已确认 | 已确认到账 |
| invalid | 已作废 | 回款作废 |

---

### 5.3 付款方式 (crm_payment_method)

| 字典值 | 字典标签 | 说明 |
|--------|---------|------|
| bank | 银行转账 | 银行转账 |
| cash | 现金 | 现金支付 |
| check | 支票 | 支票支付 |
| alipay | 支付宝 | 支付宝转账 |
| wechat | 微信 | 微信转账 |
| other | 其他 | 其他方式 |

---

## 6. 权限标识汇总

| 权限标识 | 说明 |
|---------|------|
| crm:payment:plan:list | 回款计划列表查询 |
| crm:payment:plan:query | 回款计划详情查询 |
| crm:payment:plan:add | 回款计划新增 |
| crm:payment:plan:edit | 回款计划修改 |
| crm:payment:plan:remove | 回款计划删除 |
| crm:payment:plan:export | 回款计划导出 |
| crm:payment:list | 回款记录列表查询 |
| crm:payment:query | 回款记录详情查询 |
| crm:payment:add | 回款记录新增 |
| crm:payment:edit | 回款记录修改 |
| crm:payment:remove | 回款记录删除 |
| crm:payment:export | 回款记录导出 |
| crm:payment:confirm | 回款确认 |
| crm:payment:invalid | 回款作废 |

---

## 7. 注意事项

1. **计划编号唯一性**: 同一租户下计划编号必须唯一
2. **回款编号唯一性**: 同一租户下回款编号必须唯一
3. **金额一致性**: 回款记录金额更新时，自动更新计划和合同的相关金额
4. **逾期判断**: 定时任务定期检查逾期的回款计划
5. **提醒机制**: 定时任务定期检查即将到期的回款计划，发送提醒通知
6. **状态流转**: 计划状态自动判断（待回款->部分回款->已完成/已逾期）
7. **确认机制**: 回款记录需要财务人员确认后才生效
8. **凭证管理**: 回款记录需要上传回款凭证
9. **数据权限**: 需要根据负责人字段实现数据权限控制
10. **关联关系**: 回款记录可以关联回款计划，也可以独立存在

---

**文档结束**