# 销售折扣数据（ZkJinE）接口更新说明

## 问题回顾

你们反馈 `/api/v1/i-sale/by-customer` 接口的 `ZkJinE` 字段始终返回 0，导致销售折扣金额（583 元部分）无法正确获取。

## 根因确认

经查证，问题属实但需要澄清：

- `/api/v1/i-sale/by-customer` 接口**确实返回了 `ZkJinE` 字段**，但该字段的数据来源是 `I_Sale` 表，而 `I_Sale` 表中该字段的值本身就是 0。这不是接口遗漏字段，而是数据源的问题。
- **真实的销售折扣数据**存在于 `F_Skd` 表中 `BianHaoID` 以 `XS` 开头的记录里。

## 解决方案

我们已在 `/api/v1/finance/by-customer` 接口新增了 `sale_discount` 类型，用于从 `F_Skd` 表查询 XS% 行的财务数据（包含 `ZkJinE`）。

**此改动为纯增量更新，不影响任何现有接口和字段。**

---

## 对接方式

### 请求

```
GET /api/v1/finance/by-customer?customer_name_b64={base64url编码的客户名}&record_types=sale_discount
```

也可以和其它类型组合使用：

```
GET /api/v1/finance/by-customer?customer_name_b64={base64url编码的客户名}&record_types=sale,sale_discount,receipt
```

### record_types 可选值

| 值 | 说明 | 数据来源 |
|---|---|---|
| `sale` | 成品销售单 | I_Sale 表 |
| `sale_return` | 客户退货单 | I_Sale 表 |
| `receipt` | 收款记录（SK%） | F_Skd 表 |
| `refund` | 退款记录（XT%） | F_Skd 表 |
| **`sale_discount`** | **销售折扣记录（XS%）** | **F_Skd 表** ← 新增 |

### 响应结构

新增字段（在原有响应基础上）：

```json
{
  "mode": "customer_finance",
  "customer_name": "客户名称",
  "customer_ids": ["KH001"],
  "record_types": ["sale_discount"],
  "status": "active",
  "snapshot_at": "2026-05-19T10:00:00Z",
  "total_count": 5,
  "sale_discounts_count": 5,
  "sale_discounts": [
    {
      "BianHaoID": "XS20260101-001",
      "KhID": "KH001",
      "RiQi": "2026-01-01T00:00:00Z",
      "KdRiQi": "2026-01-01T00:00:00Z",
      "YfJinE": 1000.00,
      "FkJinE": 800.00,
      "ZkJinE": 200.00,
      "JieSunFS": "...",
      "YhID": "...",
      "ZhaiYao": "...",
      "BeiZhu": "..."
    }
  ]
}
```

### sale_discount 每条记录包含的字段

| 字段 | 说明 |
|---|---|
| `BianHaoID` | 单据编号（XS 开头） |
| `KhID` | 客户 ID |
| `RiQi` | 日期 |
| `KdRiQi` | 开单日期 |
| `YfJinE` | 应付金额 |
| `FkJinE` | 付款金额 |
| **`ZkJinE`** | **折扣金额（你们需要的字段）** |
| `JieSunFS` | 结算方式 |
| `YhID` | 银行 ID |
| `ZhaiYao` | 摘要 |
| `BeiZhu` | 备注 |

---

## 关于差额 816 的对账建议

根据你们的分析：
- receipt.ZkJinE = 233 → 通过 `record_types=receipt` 获取 ✅
- sales.ZkJinE = 583 → 现在通过 `record_types=sale_discount` 获取 ✅

建议对账时同时请求：
```
record_types=receipt,sale_discount
```

然后分别对 `receipts` 和 `sale_discounts` 数组中的 `ZkJinE` 字段求和，即可得到完整的折扣金额。

---

## 注意事项

1. `sale_discount` 不会包含在默认查询中。如果不传 `record_types` 参数，默认只返回 `sale, sale_return, receipt, refund` 四种类型（保持向后兼容）。
2. 请求 `sale_discount` 时不需要传 `include_cash_movement` 或 `include_adjustments` 参数，这两个参数只对 `receipt` 和 `refund` 类型生效。
3. `customer_name_b64` 使用 base64url 编码（无 padding），与之前的用法一致。

如有疑问请随时联系。