| | |
|---|
| | | # 开票与回款关联（先开票后回款） - 前端联调方案 |
|---|
| | | |
|---|
| | | > **本次调整（最新）**：回款创建表单的【关联开票】与【回款期数】由必填改为**选填**，支持「未关联开票 / 未关联回款计划」直接录入回款。 |
|---|
| | | > 后端已放开（`invoiceId` 不再强制），前端需去掉这两个字段的必填校验，详见文末「本次调整」章节。 |
|---|
| | | |
|---|
| | | ## 涉及页面 |
|---|
| | | |
|---|
| | | - 回款管理列表页 |
|---|
| | |
|---|
| | | |
|---|
| | | | 方法 | 路径 | 说明 | |
|---|
| | | |------|------|------| |
|---|
| | | | POST | `/crm/receivable/create` | 请求体新增 `invoiceId`（**必填**） | |
|---|
| | | | POST | `/crm/receivable/create` | 请求体新增 `invoiceId`（**选填**） | |
|---|
| | | | PUT | `/crm/receivable/update` | 请求体新增 `invoiceId`（可修改） | |
|---|
| | | |
|---|
| | | **请求参数新增：** |
|---|
| | | |
|---|
| | | | 参数 | 类型 | 必填 | 说明 | |
|---|
| | | |------|------|------|------| |
|---|
| | | | invoiceId | Long | 是 | 关联的开票编号，必须为审批通过且已上传附件的开票 | |
|---|
| | | | invoiceId | Long | 否 | 关联的开票编号。填写时必须为审批通过且已上传附件的开票；不填表示该笔回款暂不关联开票 | |
|---|
| | | | planId | Long | 否 | 关联的回款计划编号。不填表示不占用回款计划期数 | |
|---|
| | | |
|---|
| | | ### 3. 变更接口：回款查询（响应新增字段） |
|---|
| | | |
|---|
| | |
|---|
| | | | 剩余可回款金额 | 开票列表列、开票详情页 | 开票金额 - 该开票已回款金额 | |
|---|
| | | | 是否已上传附件 | 开票列表列 | 辅助判断开票是否可回款（需审批通过 + 已上传附件） | |
|---|
| | | |
|---|
| | | ## 本次调整（【关联开票】【回款期数】改为选填） |
|---|
| | | |
|---|
| | | ### 变更点 |
|---|
| | | |
|---|
| | | | 项 | 调整前 | 调整后 | |
|---|
| | | |----|--------|--------| |
|---|
| | | | 关联开票（invoiceId） | 必填，不选无法保存 | 选填；不选即录入一笔不关联开票的回款 | |
|---|
| | | | 回款期数（planId） | 必填，不选无法保存 | 选填；不选即不占用回款计划期数 | |
|---|
| | | | 合同（contractId） | 必填 | **仍为必填**（金额上限校验依赖合同） | |
|---|
| | | | 回款金额、回款日期 | 必填 | **仍为必填** | |
|---|
| | | |
|---|
| | | ### 前端的改动点（去必填） |
|---|
| | | |
|---|
| | | - 回款创建/编辑表单的【关联开票】【回款期数】两个字段，去掉必填校验规则即可，其余联动逻辑（选合同后加载开票/期数选项、选中后带入客户与金额）保持不变。 |
|---|
| | | - 建议取消必填后，字段提示文案相应改为「可不选」类表述，避免用户误以为漏填。 |
|---|
| | | |
|---|
| | | ### 不填时的后端行为 |
|---|
| | | |
|---|
| | | | 场景 | 行为 | |
|---|
| | | |------|------| |
|---|
| | | | 不选关联开票 | 跳过「开票是否审批通过 / 是否已上传附件 / 是否与合同一致」及「不超过该开票剩余可回款金额」两组校验 | |
|---|
| | | | 不选关联开票时的金额上限 | 仍受**合同级**校验约束：累计回款不得超过合同总金额 | |
|---|
| | | | 不选回款期数 | 不更新任何回款计划的已回款标记，回款计划列表中该期仍显示未回款 | |
|---|
| | | | 编辑既有回款 | 未提交 invoiceId 时保留原关联关系（不会因漏传而被清空）；如需解除关联，需显式清空该字段（当前前端编辑态该字段为禁用，如需支持解除需另行开放） | |
|---|
| | | |
|---|
| | | ## 业务规则说明 |
|---|
| | | |
|---|
| | | | 场景 | 规则 | |
|---|
| | |
|---|
| | | |
|---|
| | | ## 注意事项 |
|---|
| | | |
|---|
| | | - `invoiceId` 为必填，回款创建/更新**必须**携带，否则返回参数校验错误。 |
|---|
| | | - `invoiceId`、`planId` 均为**选填**；填了开票就按开票校验，不填只受合同金额上限约束。 |
|---|
| | | - `invoice`、`remainingInvoicePrice`、`hasAttachment` 均为后端计算的只读字段，前端**不要**提交。 |
|---|
| | | - 回款金额建议在选中开票后预填为 `remainingInvoicePrice`，避免超限被后端拦截。 |
|---|
| | | - 存量回款数据若未关联开票（`invoiceId` 为空），编辑时会被要求重新选择合格开票。 |
|---|
| | | - 存量回款数据若未关联开票（`invoiceId` 为空），编辑保存时不再被要求补选开票。 |
|---|
| | | - 开票列表展示"剩余可回款金额"时，文案建议用"剩余可回款金额（含审批中）"避免歧义，与合同"已开票金额（含审批中）"口径一致。 |
|---|
