# 💳 组合支付功能实现指南

## 📋 项目概述
在 ERP 收银系统中实现**组合支付**功能，允许用户在一笔订单中使用多种支付方式组合支付。

---

## 🔧 实现清单

### ✅ 前端修改 (sy/settlement.html)

#### 1. 数据结构（data）
```javascript
paymentCombinations: []         // 已添加的支付组合数组
selectedPaymentMethod: ''       // 当前选择的支付方式
selectedPaymentAmount: ''       // 当前输入的支付金额
isComboPaymentMode: false       // 是否进入组合支付模式
paymentMethods: [...]           // 支付方式列表
```

#### 2. 计算属性（computed）
- `totalPaidAmount()` - 已支付总额
- `remainingAmount()` - 剩余应付金额
- `canSaveOrder()` - 是否可以保存订单（检查总额是否匹配）

#### 3. 核心方法（methods）
- `enterComboPaymentMode()` - 进入组合支付模式
- `addPaymentMethod(method)` - 添加支付方式
- `removePaymentMethod(index)` - 删除支付方式
- `updatePaymentAmount(index)` - 更新支付金额
- `finalizeComboPayment()` - 完成组合支付（已在 settlementPay 中集成）

#### 4. UI 修改
- 添加"💳 组合支付"按钮入口
- 组合支付配置面板（计算器下方）
  - 实时金额显示
  - 支付方式快速选择按钮
  - 已添加支付方式列表
- 修改"收款"按钮，支持两种模式显示

#### 5. 支付逻辑（settlementPay）
- 检测组合支付模式
- 组合支付时设置 `info.skzh = '组合支付'`
- 将支付明细序列化为 JSON 保存到 `info.skmx`

---

### ✅ 后端修改

#### 1. 实体模型 (Entity)
**文件**: `WtXsckdEntity.cs`
```csharp
/// <summary>
/// 收款明细 (JSON格式)
/// </summary>
[SugarColumn(ColumnName = "skmx", IsNullable = true)]
public string Skmx { get; set; }
```

#### 2. DTO - 输入参数
**文件**: `WtXsckdCrInput.cs`
```csharp
public string skmx { get; set; }
```

#### 3. DTO - 输出参数
**文件**: `WtXsckdInfoOutput.cs`
```csharp
public string skmx { get; set; }
```

#### 4. DTO - 列表输出
**文件**: `WtXsckdListOutput.cs`
```csharp
public string skmx { get; set; }
```

---

## 🎯 使用流程

### 普通支付（保持原有）
1. 选择单一支付方式（微信/支付宝/现金/余额/积分）
2. 点击"收款"
3. 订单保存

### 组合支付（新增）
1. 点击"💳 组合支付"按钮
2. 出现组合支付配置面板
3. 点击快速按钮添加支付方式（如"+ 微信"）
4. 输入该方式的支付金额
5. 重复步骤3-4，直到支付总额 = 应收金额
6. 剩余金额显示为绿色 ✅ 时可以点击"✅ 组合支付"按钮
7. 订单保存，支付明细保存在 `skmx` 字段为 JSON 格式

---

## 💾 数据存储格式

### skmx 字段示例
```json
[
  {"skfs":"微信","skje":"100.00"},
  {"skfs":"现金","skje":"50.00"},
  {"skfs":"余额","skje":"30.00"}
]
```

### 关键字段
- `skfs` - 支付方式 (微信/支付宝/现金/余额/积分抵扣)
- `skje` - 支付金额（2位小数）

---

## 🔍 API 调用示例

### 组合支付请求
```json
{
  "id": "LS20251026223030000",
  "djrq": "2025-10-26T22:30:30.000Z",
  "cjck": "出库仓库ID",
  "skzh": "组合支付",
  "skje": 180.00,
  "skmx": "[{\"skfs\":\"微信\",\"skje\":\"100.00\"},{\"skfs\":\"现金\",\"skje\":\"80.00\"}]",
  "wtXsckdMxList": [...]
}
```

---

## ✨ 核心特性

✅ **灵活性** - 支持任意数量的支付方式组合  
✅ **实时验证** - 金额动态计算，不匹配时禁用保存  
✅ **用户友好** - 快速按钮添加，清晰显示剩余金额  
✅ **数据完整** - JSON 存储完整的支付明细  
✅ **向后兼容** - 普通支付模式保持不变  

---

## 🧪 测试用例

| 场景 | 操作 | 预期结果 |
|------|------|--------|
| 普通支付 | 选择"微信" → 点击收款 | 订单正常保存，skzh='微信' |
| 组合支付-匹配 | 微信¥100+现金¥50, 应收¥150 | 金额显示绿色✅，能保存 |
| 组合支付-不匹配 | 微信¥100+现金¥40, 应收¥150 | 金额显示红色❌，禁用保存 |
| 删除支付方式 | 添加后点删除 | 该方式从列表移除 |
| 修改金额 | 输入金额后 blur | 金额自动格式化为2位小数 |

---

## 📚 后续优化建议

1. **支付方式细化** - 添加绑定卡号、支付宝账户等详情
2. **退款处理** - 组合支付订单的部分退款逻辑
3. **报表统计** - 统计各支付方式的组合情况
4. **审计日志** - 记录每笔组合支付的详细信息
5. **限制配置** - 后台可配置最多允许的组合方式数

---

## 🚀 部署指南

1. **数据库** - 运行 SQL 新增 `skmx` 列（如果未自动创建）
   ```sql
   ALTER TABLE wt_xsckd ADD skmx LONGTEXT NULL COMMENT '收款明细';
   ```

2. **后端编译** - 重新编译 .NET Core 项目
   ```bash
   cd netcore && dotnet build
   ```

3. **前端更新** - 浏览器清缓存后加载新版本

---

✅ 功能完成日期：2025-10-27