# 开票与回款关联（先开票后回款） - 前端联调方案

## 涉及页面

- 回款管理列表页
- 回款创建 / 编辑表单
- 回款详情页
- 开票管理列表页、开票详情页（**前端目前缺失，需新建**）
- 合同管理列表页、合同详情页（上个任务已接入"已开票金额/未开票金额"，本次不涉及）

## 业务流程与数据带入

1. **开票 → 回款**：开票单审批通过 + 上传发票附件后，才会出现在回款创建表单的"关联开票"下拉中。
2. **回款创建**：选择客户 → 选择合同 → 选择关联开票（自动带入客户、合同）→（可选）选择回款计划 → 填回款金额（可预填为该开票的剩余可回款金额）。
3. **合同下拉（simple-list）**：已返回 `totalInvoicePrice`（已开票金额，含审批中），用于展示合同剩余可开额度。
4. **开票下拉（simple-list）**：返回 `remainingInvoicePrice`（该开票剩余可回款金额），用于创建回款时预填金额。

## API

### 1. 新增接口：按合同查询可选开票

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/crm/invoice/simple-list?contractId=` | 回款创建时选择关联开票，只返回合格开票 |

**筛选规则（后端已实现）**：审批通过 + 已上传发票附件 + 剩余可回款金额 > 0。

**响应示例：**

```json
{
  "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，需前端新建。

1. **开票管理页**：`views/crm/invoice/`（列表、创建/编辑、审批提交、发票附件上传与展示）。
2. **开票 API**：`api/crm/invoice/`（page / get / create / update / delete / submit / audit-count / export-excel / simple-list）。
3. **回款表单开票选择器**：选合同后调用 `/crm/invoice/simple-list?contractId=`，展示"开票编号 / 发票号码 / 开票金额 / 剩余可回款"，选中后预填金额。
4. **菜单**：已由后端 SQL 配置完成（营销管理 -> 开票管理，`component = crm/invoice/index`），前端建好页面后菜单即可用。

## 注意事项

- `invoiceId` 为必填，回款创建/更新**必须**携带，否则返回参数校验错误。
- `invoice`、`remainingInvoicePrice`、`hasAttachment` 均为后端计算的只读字段，前端**不要**提交。
- 回款金额建议在选中开票后预填为 `remainingInvoicePrice`，避免超限被后端拦截。
- 存量回款数据若未关联开票（`invoiceId` 为空），编辑时会被要求重新选择合格开票。
- 开票列表展示"剩余可回款金额"时，文案建议用"剩余可回款金额（含审批中）"避免歧义，与合同"已开票金额（含审批中）"口径一致。