feat: correct first

docs/SALE-DISCOUNT-API-UPDATE.md

@@ -0,0 +1,117 @@
+# 销售折扣数据（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），与之前的用法一致。
+
+如有疑问请随时联系。