# LianLianPay

**Repository Path**: leafCore/LianLianPay

## Basic Information

- **Project Name**: LianLianPay
- **Description**: LianLianPay 是一个基于 .NET 8 的连连支付第三方支付 SDK，源自 Essensoft/Payment 开源项目（v3.0.0）。该项目完整封装了连连支付的企业级 API，涵盖支付、付款、退款、绑卡签约、账户查询等全链路业务场景，并提供开箱即用的 WebAPI + Blazor WebAssembly 示例和 79 个单元测试。
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://gitee.com/leafCore/LianLianPay
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LianLianPay Demo — 连连支付 .NET SDK 完整示例

基于 [LianLianPay SDK](https://github.com/Essensoft/Payment) 构建的 **WebAPI + Blazor WebAssembly** 完整示例项目，包含全面的单元测试。

## 项目结构

```
LianLianPayDemo/
├── LianLianPayDemo.sln
├── README.md
├── LianLianPay/                    # 连连支付 .NET SDK（现有库）
│   ├── ILianLianPayClient.cs       # 支付客户端接口
│   ├── LianLianPayClient.cs        # 支付客户端实现
│   ├── ILianLianPayNotifyClient.cs # 通知客户端接口
│   ├── LianLianPayNotifyClient.cs  # 通知客户端实现
│   ├── Request/                    # 请求模型（14种）
│   ├── Response/                   # 响应模型（14种）
│   ├── Notify/                     # 通知模型（4种）
│   ├── Parser/                     # JSON/字典解析器
│   └── Utility/                    # 加密/签名/工具类
├── src/
│   ├── LianLianPayDemo.Api/        # ASP.NET Core WebAPI
│   │   ├── Controllers/
│   │   │   ├── LianLianPayController.cs  # 支付操作端点
│   │   │   └── NotifyController.cs       # 异步通知端点
│   │   ├── Program.cs
│   │   └── appsettings.json
│   └── LianLianPayDemo.Blazor/     # Blazor WebAssembly 前端
│       ├── Pages/
│       │   ├── Index.razor         # 首页仪表盘
│       │   ├── Payment.razor       # 支付创单
│       │   ├── PaymentOrder.razor  # 付款申请
│       │   ├── Query.razor         # 订单/支付/账户查询
│       │   ├── Refund.razor        # 退款申请与查询
│       │   └── Bankcard.razor      # 银行卡管理
│       ├── Layout/MainLayout.razor # 布局
│       ├── App.razor
│       └── Program.cs
└── tests/
    └── LianLianPayDemo.Tests/       # xUnit 单元测试（79个用例）
        ├── CryptoUtilityTests.cs
        ├── LianLianPayDictionaryTests.cs
        ├── LianLianPayJsonParserTests.cs
        ├── LianLianPaySecurityTests.cs
        ├── LianLianPayUtilityTests.cs
        ├── LianLianPayClientTests.cs       # Mocked HttpClient
        ├── LianLianPayNotifyClientTests.cs # Mocked HttpRequest
        ├── LianLianPayRequestTests.cs
        ├── LianLianPayResponseTests.cs
        ├── LianLianPayExceptionAndNotifyResultTests.cs
        └── LianLianPayOptionsTests.cs
```

## 功能覆盖

### WebAPI 端点

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/api/lianlianpay/create-bill` | 统一支付创单 |
| POST | `/api/lianlianpay/payment` | 付款申请 |
| POST | `/api/lianlianpay/confirm-payment` | 确认付款 |
| GET | `/api/lianlianpay/order-query` | 收款结果查询 |
| POST | `/api/lianlianpay/refund` | 退款申请 |
| GET | `/api/lianlianpay/refund-query` | 退款查询 |
| GET | `/api/lianlianpay/bank-card-bin` | 卡BIN查询 |
| GET | `/api/lianlianpay/support-banks` | 支持银行查询 |
| GET | `/api/lianlianpay/query-payment` | 支付单查询 |
| GET | `/api/lianlianpay/bank-card-bind-list` | 绑卡列表查询 |
| POST | `/api/lianlianpay/unified-card-bind` | 统一绑卡 |
| POST | `/api/lianlianpay/bank-card-unbind` | 银行卡解绑 |
| GET | `/api/lianlianpay/trader-acct-query` | 商户账户查询 |

### 异步通知端点

| 方法 | 路径 | 功能 |
|------|------|------|
| POST | `/api/notify/receive-money` | 收款结果通知 |
| POST | `/api/notify/refund` | 退款结果通知 |
| POST | `/api/notify/send-money` | 付款结果通知 |
| POST | `/api/notify/card-bind` | 绑卡结果通知 |

### Blazor 前端页面

- **首页** — 功能导航仪表盘
- **支付创单** — 创建统一支付订单、获取支付令牌和网关URL
- **付款申请** — 向指定银行卡付款，支持确认码二次验证
- **订单查询** — 收款结果查询、支付单查询、商户账户查询
- **退款管理** — 发起退款、查询退款结果
- **银行卡管理** — 卡BIN查询、支持银行查询、绑卡列表、统一绑卡

## 快速开始

### 1. 配置

编辑 `src/LianLianPayDemo.Api/appsettings.json`：

```json
{
  "LianLianPay": {
    "OidPartner": "你的商户号",
    "BusiPartner": "101001",
    "RsaPrivateKey": "你的商户私钥(Base64)",
    "RsaPublicKey": "连连支付公钥(Base64)"
  }
}
```

### 2. 启动 WebAPI

```bash
# 进入项目目录
cd src/LianLianPayDemo.Api

# 启动（默认 http://localhost:5000）
dotnet run
```

### 3. 启动 Blazor 前端

```bash
cd src/LianLianPayDemo.Blazor

# 启动开发服务器
dotnet run
```

### 4. 运行测试

```bash
# 运行全部 79 个单元测试
dotnet test LianLianPayDemo.sln
```

## 测试覆盖详情

**79 个测试用例全部通过**：

| 测试类 | 用例数 | 覆盖内容 |
|--------|--------|----------|
| `CryptoUtilityTests` | 13 | MD5WithRSA 签名/验签, RSA-OAEP 加解密, AES-CTR 加解密, HMACSHA256 |
| `LianLianPayDictionaryTests` | 14 | 字典添加/排序, 类型转换(string/int/long/double/bool/DateTime), 空值处理 |
| `LianLianPayJsonParserTests` | 7 | JSON 解析, 空 JSON, 无效 JSON, Body/Parameters 设置 |
| `LianLianPaySecurityTests` | 11 | SignContent 生成, 排除 sign/空值/指定键, 加密解密往返, 空值处理 |
| `LianLianPayUtilityTests` | 3 | Query 字符串构建, 空值排除 |
| `LianLianPayClientTests` | 3 | HTTP Mock 测试, 签名验证, 命名 Options |
| `LianLianPayNotifyClientTests` | 6 | Form/JSON 内容类型解析, 不支持类型, 缺少签名, 自定义 Options |
| `LianLianPayRequestTests` | 10 | 请求 URL, 参数构建, API 版本, 空字段排除 |
| `LianLianPayResponseTests` | 8 | JSON 反序列化, 继承关系, Body/Parameters |
| `LianLianPayExceptionAndNotifyResultTests` | 4 | 异常消息, 通知结果(成功/失败) |
| `LianLianPayOptionsTests` | 3 | 默认值, 属性设置 |

## 关键技术栈

- **.NET 8**
- **ASP.NET Core WebAPI** — RESTful API 后端
- **Blazor WebAssembly** — SPA 前端（Bootstrap 5 样式）
- **xUnit + Moq** — 单元测试框架
- **BouncyCastle 2.4.0** — RSA/AES 加密
- **LianLianPay SDK** — 连连支付 API 封装

## API 调用流程

```
Blazor 前端 ──HTTP──▶ WebAPI 控制器 ──调用──▶ ILianLianPayClient
                                                    │
                                              ┌─────▼─────┐
                                              │ 1. 组装参数 │
                                              │ 2. 添加签名 │
                                              │ 3. 加密(可选)│
                                              │ 4. POST 请求│
                                              │ 5. 验证响应 │
                                              └───────────┘
                                                    │
连连支付服务器 ◀─────────────────────────────────────┘
```

### 异步通知流程

```
连连支付服务器 ──POST──▶ /api/notify/* ──▶ ILianLianPayNotifyClient
                                              │
                                        ┌─────▼─────┐
                                        │ 1. 读取请求│
                                        │ 2. 解析参数│
                                        │ 3. 验证签名│
                                        │ 4. 返回结果│
                                        └───────────┘
```