开票与回款关联（先开票后回款） - 前端联调方案
涉及页面
- 回款管理列表页
- 回款创建 / 编辑表单
- 回款详情页
- 开票管理列表页、开票详情页（**前端目前缺失，需新建**）
- 合同管理列表页、合同详情页（上个任务已接入"已开票金额/未开票金额"，本次不涉及）
业务流程与数据带入
- 开票 → 回款：开票单审批通过 + 上传发票附件后，才会出现在回款创建表单的"关联开票"下拉中。
- 回款创建：选择客户 → 选择合同 → 选择关联开票（自动带入客户、合同）→（可选）选择回款计划 → 填回款金额（可预填为该开票的剩余可回款金额）。
- 合同下拉（simple-list）：已返回
totalInvoicePrice（已开票金额，含审批中），用于展示合同剩余可开额度。
- 开票下拉（simple-list）：返回
remainingInvoicePrice（该开票剩余可回款金额），用于创建回款时预填金额。
API
1. 新增接口：按合同查询可选开票
| 方法 |
路径 |
说明 |
| GET |
/crm/invoice/simple-list?contractId= |
回款创建时选择关联开票，只返回合格开票 |
筛选规则（后端已实现）：审批通过 + 已上传发票附件 + 剩余可回款金额 > 0。
响应示例：
{
"code": 0,
"data": [
{
"id": 1,
"no": "KP20260810000001",
"invoiceNo": "02564178",
"invoiceTitle": "XX科技有限公司",
"price": 1090.00,
"customerId": 1,
"contractId": 31,
"auditStatus": 20,
"hasAttachment": true,
"remainingInvoicePrice": 1090.00
}
]
}
2. 变更接口：回款创建 / 更新
| 方法 |
路径 |
说明 |
| POST |
/crm/receivable/create |
请求体新增 invoiceId（**必填**） |
| PUT |
/crm/receivable/update |
请求体新增 invoiceId（可修改） |
请求参数新增：
| 参数 |
类型 |
必填 |
说明 |
| invoiceId |
Long |
是 |
关联的开票编号，必须为审批通过且已上传附件的开票 |
3. 变更接口：回款查询（响应新增字段）
| 方法 |
路径 |
新增响应字段 |
| GET |
/crm/receivable/page |
invoiceId、invoice（嵌套对象） |
| GET |
/crm/receivable/get |
invoiceId、invoice（嵌套对象） |
| GET |
/crm/receivable/page-by-customer |
invoiceId、invoice（嵌套对象） |
invoice 嵌套对象关键字段： id、no（开票编号）、invoiceNo（发票号码）、invoiceTitle（发票抬头）、price（开票金额）。
4. 变更接口：开票查询（响应新增字段）
| 方法 |
路径 |
新增响应字段 |
| GET |
/crm/invoice/page |
hasAttachment、remainingInvoicePrice |
| GET |
/crm/invoice/get |
hasAttachment、remainingInvoicePrice |
说明：
- hasAttachment（Boolean）：是否已上传发票附件，用于列表快速判断哪些开票可被回款关联。
- remainingInvoicePrice（BigDecimal）：剩余可回款金额 = 开票金额 - 该开票已回款金额（统计草稿 + 审批中 + 审批通过的回款）。
字段展示规则
| 字段 |
展示位置 |
说明 |
| 关联开票 |
回款列表列、回款详情页 |
展示 invoice.no / invoice.invoiceNo / invoice.price |
| 关联开票选择器 |
回款创建/编辑表单 |
选择后带入客户、合同、预填回款金额为 remainingInvoicePrice |
| 剩余可回款金额 |
开票列表列、开票详情页 |
开票金额 - 该开票已回款金额 |
| 是否已上传附件 |
开票列表列 |
辅助判断开票是否可回款（需审批通过 + 已上传附件） |
业务规则说明
| 场景 |
规则 |
| 审批中的开票 |
不可选为回款依据（后端拦截：关联开票不是审批通过状态） |
| 未上传发票附件的开票 |
不可选为回款依据（后端拦截：关联开票未上传发票附件） |
| 已全部回款的开票 |
从"关联开票"下拉过滤（剩余可回款 ≤ 0） |
| 回款金额超限 |
后端拦截：回款金额超出该开票剩余可回款金额 |
| 开票与合同不匹配 |
后端拦截：所选开票与回款合同不一致 |
| 编辑回款时改开票 |
草稿/审批中状态可修改关联开票，改后重新按新开票校验金额 |
前端缺口（需新建）
后端开票模块已完整（含审批流程、附件上传），但前端尚无开票页面与 API，需前端新建。
- 开票管理页：
views/crm/invoice/（列表、创建/编辑、审批提交、发票附件上传与展示）。
- 开票 API：
api/crm/invoice/（page / get / create / update / delete / submit / audit-count / export-excel / simple-list）。
- 回款表单开票选择器：选合同后调用
/crm/invoice/simple-list?contractId=，展示"开票编号 / 发票号码 / 开票金额 / 剩余可回款"，选中后预填金额。
- 菜单：已由后端 SQL 配置完成（营销管理 -> 开票管理，
component = crm/invoice/index），前端建好页面后菜单即可用。
注意事项
invoiceId 为必填，回款创建/更新**必须**携带，否则返回参数校验错误。invoice、remainingInvoicePrice、hasAttachment 均为后端计算的只读字段，前端**不要**提交。- 回款金额建议在选中开票后预填为
remainingInvoicePrice，避免超限被后端拦截。
- 存量回款数据若未关联开票（
invoiceId 为空），编辑时会被要求重新选择合格开票。
- 开票列表展示"剩余可回款金额"时，文案建议用"剩余可回款金额（含审批中）"避免歧义，与合同"已开票金额（含审批中）"口径一致。
