HIS-GUI/docs/支付系统设计文档.md

# HIS-GUI 支付系统 - 系统设计文档

## 目录

1. [系统概述](#系统概述)
2. [架构设计](#架构设计)
3. [数据模型](#数据模型)
4. [服务层设计](#服务层设计)
5. [UI设计](#ui设计)
6. [集成方案](#集成方案)
7. [部署和维护](#部署和维护)

## 系统概述

HIS-GUI支付系统是一个完整的医院支付管理解决方案，用于处理医院所有付费操作（挂号、检查、用药等）的支付流程。该系统具备以下核心功能：

### 核心功能
- ✅ **支付处理**：支持多种支付方式（现金、信用卡、移动支付、医保）
- ✅ **支付记录管理**：完整记录每一笔支付
- ✅ **结算单生成**：患者出院时自动生成详细结算单
- ✅ **费用统计**：支持医保/患者费用分配
- ✅ **报表生成**：支持日报表、月报表、收入报表
- ✅ **退款管理**：支持快速退款和原因记录
- ✅ **管理员界面**：完整的支付管理和统计界面

## 架构设计

### 整体架构

```
┌─────────────────────────────────────────────────────┐
│                    GUI层                            │
├─────────────────────────────────────────────────────┤
│ PaymentDialog  │  SettlementDialog  │ PaymentMgmtDlg │
├─────────────────────────────────────────────────────┤
│                  核心业务层(HisCore)                 │
├─────────────────────────────────────────────────────┤
│ PaymentService    │ SettlementService │ PaymentMgmtSvc │
├─────────────────────────────────────────────────────┤
│                   数据访问层                          │
├─────────────────────────────────────────────────────┤
│              数据存储(JSON文件)                       │
└─────────────────────────────────────────────────────┘
```

### 模块依赖

```
main_gui.cpp
    ↓
mainwindow.cpp (包含支付相关菜单)
    ↓
    ├→ payment_dialog.cpp ─── PaymentService
    ├→ settlement_dialog.cpp ─ SettlementService
    ├→ payment_management_dialog.cpp ─ PaymentManagementService
    ↓
his_core (核心库)
    ├→ payment_service
    ├→ settlement_service
    ├→ payment_management_service
    ↓
数据模型 & 文件IO
    ├→ payment.cpp/h
    ├→ settlement.cpp/h
    ├→ file_manager.cpp
```

## 数据模型

### Payment 模型

```cpp
class Payment {
    std::string PaymentID;              // 唯一标识 (格式: PAY_xxxxxxxx)
    std::string PatientID;              // 患者ID
    double Amount;                      // 支付金额
    PaymentMethod Method;               // 支付方式 (Cash/CreditCard/MobilePayment/HealthInsurance)
    std::string PaymentType;            // 支付类型 (挂号/检查/用药等)
    std::string OperationID;            // 关联操作ID
    time_t PaymentTime;                 // 支付时间戳
    std::string Status;                 // 支付状态 (Pending/Completed/Failed/Refunded)
    std::string Description;            // 支付描述
};
```

### Settlement 模型

```cpp
class Settlement {
    std::string SettlementID;           // 唯一标识 (格式: SET_xxxxxxxx)
    std::string PatientID;              // 患者ID
    std::string PatientName;            // 患者姓名
    std::string DischargeDate;          // 出院日期
    time_t SettlementTime;              // 结算时间
    std::vector<SettlementItem> Items;  // 费用明细
    double TotalAmount;                 // 医疗总费用
    double InsurancePaid;               // 医保支付金额
    double PatientPaid;                 // 患者自付金额
    std::string Status;                 // 结算状态 (Pending/Completed/Settled)
    std::string Notes;                  // 备注
};

struct SettlementItem {
    std::string ItemName;               // 项目名称
    std::string ItemType;               // 项目类型
    std::string OperationID;            // 关联操作ID
    double Quantity;                    // 数量
    double UnitPrice;                   // 单价
    double Amount;                      // 金额
    std::string PaymentMethod;          // 支付方式
};
```

### 支付方式枚举

```cpp
enum class PaymentMethod {
    Cash = 0,               // 现金支付
    CreditCard = 1,         // 信用卡
    MobilePayment = 2,      // 移动支付 (微信/支付宝)
    HealthInsurance = 3     // 医保
};
```

### 数据存储格式

**payments.txt (JSON格式)**
```json
[
  {
    "paymentId": "PAY_abc123",
    "patientId": "P001",
    "amount": 200.0,
    "method": "Cash",
    "paymentType": "检查",
    "operationId": "CHECK_001",
    "paymentTime": 1712361600.0,
    "status": "Completed",
    "description": "CT扫描费用"
  }
]
```

**settlements.txt (JSON格式)**
```json
[
  {
    "settlementId": "SET_xyz789",
    "patientId": "P001",
    "patientName": "张三",
    "dischargeDate": "2025-04-10",
    "settlementTime": 1712371200.0,
    "items": [
      {
        "itemName": "挂号费",
        "itemType": "Registration",
        "operationId": "REG_001",
        "quantity": 1.0,
        "unitPrice": 50.0,
        "amount": 50.0,
        "paymentMethod": "Cash"
      }
    ],
    "totalAmount": 450.0,
    "insurancePaid": 225.0,
    "patientPaid": 225.0,
    "status": "Completed",
    "notes": ""
  }
]
```

## 服务层设计

### PaymentService

**职责**：处理所有支付相关的操作

**主要方法**：

| 方法名 | 参数 | 返回值 | 说明 |
|-----|---|---|---|
| `createPayment` | 患者ID, 金额, 支付方式等 | bool, paymentID | 创建新的支付记录 |
| `findPayment` | paymentId | Payment* | 查找支付记录 |
| `updatePaymentStatus` | paymentId, newStatus | bool | 更新支付状态 |
| `completePayment` | paymentId | bool | 完成支付 |
| `refundPayment` | paymentId | bool | 退款 |
| `getTotalPaymentAmount` | patientId | double | 获取患者总支付金额 |
| `findByPatientId` | patientId, visitor | void | 按患者查询 |
| `findByPaymentType` | paymentType, visitor | void | 按支付类型查询 |

**实现要点**：
- 所有支付操作都记录日志
- 支付ID自动生成（PAY_前缀 + UUID）
- 支持多种查询方式（按患者、按类型等）
- 使用LinkedList存储支持高效查询

### SettlementService

**职责**：管理结算单的生成、修改和计算

**主要方法**：

| 方法名 | 参数 | 返回值 | 说明 |
|-----|---|---|---|
| `generateSettlement` | 患者ID, 姓名, 出院日期 | bool, settlementID | 生成新结算单 |
| `addItemToSettlement` | settlementId, item | bool | 添加费用项 |
| `calculateSettlement` | settlementId | bool | 计算费用总额 |
| `completeSettlement` | settlementId | bool | 完成结算 |
| `generateSettlementReport` | settlementId | string | 生成结算报告 |

**费用分配逻辑**：
```
默认情况下：
  医保支付 = 总费用 × 50%
  患者自付 = 总费用 × 50%

可根据具体医保政策调整
```

**结算报告格式**：
```
========== 医疗费用结算单 ==========
结算单号: SET_xyz789
患者姓名: 张三
患者ID: P001
出院日期: 2025-04-10
...
```

### PaymentManagementService

**职责**：为管理员提供支付统计、报表和异常处理

**主要方法**：

| 方法名 | 参数 | 返回值 | 说明 |
|-----|---|---|---|
| `getPaymentStatistics` | 无 | PaymentStatistics | 获取总支付统计 |
| `getTodayPaymentStatistics` | 无 | PaymentStatistics | 获取今日统计 |
| `getMonthlyPaymentStatistics` | 无 | PaymentStatistics | 获取月统计 |
| `generateDailyReport` | 日期 | string | 生成日报表 |
| `generateMonthlyReport` | 月份 | string | 生成月报表 |
| `generateRevenueReport` | 无 | string | 生成收入报表 |
| `processRefund` | paymentId, reason | bool | 处理退款 |
| `getAnomalousPayments` | visitor | void | 获取异常支付 |

**统计信息结构**：
```cpp
struct PaymentStatistics {
    double TotalRevenue;        // 总收入 (已完成-已退款)
    double CompletedAmount;     // 已完成金额
    double PendingAmount;       // 待支付金额
    double RefundedAmount;      // 已退款金额
    int TotalPayments;          // 总笔数
    int CompletedPayments;      // 已完成笔数
    int PendingPayments;        // 待支付笔数
    int RefundedPayments;       // 已退款笔数
};
```

## UI设计

### PaymentDialog (支付对话框)

**用途**：用户在进行付费操作时弹出的支付界面

**主要组件**：
- 患者信息区（只读）
- 操作类型显示
- 金额输入（只读，自动填充）
- 支付方式下拉框
- 备注文本框
- 确认/取消按钮

**交互流程**：
```
1. 系统调用 setPaymentInfo() 设置支付信息
2. 用户选择支付方式
3. 用户点击确认
4. 系统创建支付记录
5. 系统更新支付状态为Completed
6. 对话框返回成功
```

**关键信号**：
- `onPaymentMethodChanged(int)`: 支付方式改变时
- `onConfirmPayment()`: 点击确认时
- `onCancel()`: 点击取消时

### SettlementDialog (结算单对话框)

**用途**：显示和管理患者的结算单

**主要组件**：
- 结算单信息区（只读）
- 患者信息区（只读）
- 出院日期
- 费用明细表格
- 费用汇总区
- 备注区
- 打印/导出/确认按钮

**主要功能**：
- 显示结算单详情
- 添加/编辑费用项
- 计算费用总额
- 打印结算单
- 导出为文本文件
- 确认结算

### PaymentManagementDialog (支付管理对话框)

**用途**：为管理员提供支付管理和报表功能

**包含三个标签页**：

#### 1. 支付记录标签页
- 支付记录表格（可排序可搜索）
- 按状态筛选
- 新增支付记录
- 退款操作
- 统计信息显示

#### 2. 结算单标签页
- 结算单列表
- 结算单详情预览
- 按状态筛选

#### 3. 报表标签页
- 每日报表
- 月报表
- 收入总报表
- 支付方式统计

## 集成方案

### 与现有系统的集成

#### 1. 与患者管理的集成

```cpp
// 在PatientService中添加支付信息查询
class PatientService {
    // ... 现有方法 ...
    
    // 新增方法
    double getPatientTotalPayment(const std::string& patientId) {
        return ctx_.paymentService.getTotalPaymentAmount(patientId);
    }
};
```

#### 2. 与患者病例的集成

```cpp
// 在PatientCase中添加支付ID字段
class PatientCase {
    // ... 现有字段 ...
    std::vector<std::string> paymentIDs;  // 支付ID列表
    std::string settlementID;             // 结算单ID
};
```

#### 3. 与主窗口的集成

```cpp
// 在MainWindow中添加支付菜单
class MainWindow : public QMainWindow {
    void createMenus() {
        // ... 现有菜单 ...
        QMenu* paymentMenu = menuBar()->addMenu("支付管理");
        paymentMenu->addAction("新建支付", this, &MainWindow::onNewPayment);
        paymentMenu->addAction("支付管理", this, &MainWindow::onPaymentManagement);
        paymentMenu->addAction("结算管理", this, &MainWindow::onSettlementManagement);
    }
    
    void onNewPayment() {
        PaymentDialog dlg(core_);
        dlg.exec();
    }
    
    void onPaymentManagement() {
        PaymentManagementDialog dlg(core_);
        dlg.exec();
    }
};
```

### 业务流程集成

#### 挂号流程
```
用户提交挂号信息
  ↓
系统验证挂号信息
  ↓
打开支付对话框
  ↓
用户完成支付
  ↓
系统创建支付记录
  ↓
系统保存挂号信息 (关联支付ID)
  ↓
显示挂号成功消息
```

#### 患者出院流程
```
医生确认出院
  ↓
系统生成结算单
  ↓
系统从支付记录中提取费用项
  ↓
系统计算医保/患者分配
  ↓
显示结算单对话框
  ↓
用户确认结算
  ↓
系统标记结算完成
  ↓
生成出院小结
```

## 部署和维护

### 文件结构

```
HIS-GUI/
├── include/
│   └── models/
│       ├── payment.h
│       └── settlement.h
│   └── core/
│       ├── payment_service.h
│       ├── settlement_service.h
│       └── payment_management_service.h
├── src/
│   ├── models/
│   │   ├── payment.cpp
│   │   └── settlement.cpp
│   ├── core/
│   │   ├── payment_service.cpp
│   │   ├── settlement_service.cpp
│   │   └── payment_management_service.cpp
│   └── utils/
│       └── file_manager.cpp (已更新)
├── gui/
│   ├── payment_dialog.h/cpp
│   ├── settlement_dialog.h/cpp
│   └── payment_management_dialog.h/cpp
└── data/
    ├── payments.txt
    └── settlements.txt
```

### 编译配置

CMakeLists.txt已更新，包含以下新文件：
```cmake
# Models
src/models/payment.cpp
src/models/settlement.cpp

# Services
src/core/payment_service.cpp
src/core/settlement_service.cpp
src/core/payment_management_service.cpp

# GUI
gui/payment_dialog.cpp
gui/settlement_dialog.cpp
gui/payment_management_dialog.cpp
```

### 数据备份和恢复

支付数据自动备份到JSON文件：
- `data/payments.txt`
- `data/settlements.txt`

恢复流程：
```cpp
// 系统启动时自动加载
bool HisCore::loadDataFromFolder(const std::string& dataFolder) {
    // ... 自动加载payments.txt和settlements.txt
}
```

### 日志记录

所有支付相关操作都被记录：
```cpp
LOG_INFO("PaymentService::createPayment - Created payment: " + paymentID);
LOG_WARN("PaymentService::refundPayment - Cannot refund non-completed payment");
```

日志位置：`logs/his.log`

### 性能考虑

- **存储优化**：使用LinkedList支持O(1)插入和删除
- **查询优化**：支持多种索引方式（按患者、按类型等）
- **报表优化**：报表生成使用流式处理，避免一次性加载全部数据

### 扩展建议

1. **添加数据库支持**
   - 替换JSON文件存储为SQLite/MySQL
   - 支持复杂查询和事务

2. **添加支付网关**
   - 集成支付宝、微信等第三方支付
   - 实时支付状态同步

3. **添加审计日志**
   - 记录所有支付相关的改动
   - 支持操作追溯和合规性检查

4. **添加权限控制**
   - 基于角色的权限管理
   - 支付敏感操作需要审批

5. **添加对账工具**
   - 与银行系统对账
   - 异常交易检测和处理

## 总结

HIS-GUI支付系统提供了完整的从支付到结算的解决方案，具备以下优势：

✅ **便于集成**：清晰的API设计，易于集成到现有系统
✅ **功能完整**：支支付全流程，从支付到结算一应俱全
✅ **数据安全**：完整的历史记录和备份机制
✅ **易于扩展**：模块化设计，便于添加新功能
✅ **用户友好**：直观的UI界面，提升用户体验

通过本支付系统的集成，HIS-GUI将成为一个功能完整的医院管理信息系统。