# payment-processor

**Repository Path**: chjgfg/payment-processor

## Basic Information

- **Project Name**: payment-processor
- **Description**: 轻量化支付资金清算 Demo，完整复刻了支付平台最核心的账户与纠纷资金逻辑
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Simple Banking & Transaction Processing Engine

这是一个基于 Rust 开发的轻量级交易处理和账户管理引擎 Demo。项目通过解析 CSV 格式的交易记录流水，流式处理用户的资产变更，并支持基础的纠纷（Dispute）处理与账户冻结机制。

## ⚙️ 核心功能与业务逻辑

本引擎支持以下 5 种核心交易类型，并严格保证高精度的财务计算：

1. **Deposit（充值）**：增加客户的 `available`（可用余额）和 `total`（总资产）。
2. **Withdrawal（提现）**：减少客户的 `available` 和 `total`。若可用余额不足则交易失败。
3. **Dispute（交易纠纷）**：针对历史某笔充值提出异议。该笔充值的金额会从 `available` 冻结并转移到 `held`（冻结资产）中，`total` 保持不变。
4. **Resolve（纠纷解决）**：纠纷得到解决。冻结在 `held` 中的资产重新退回到 `available` 中。
5. **Chargeback（拒付/退款）**：纠纷确认，发生拒付。冲抵的金额从 `held` 和 `total` 中扣除，同时该账户将被**冻结（Locked）**，拒绝后续一切资金往来。

## 🛠️ 技术亮点

* **高精度金融计算**：采用 `rust_decimal` 库替代浮点数（f32/f64），确保四舍五入和资金计算不会出现精度丢失。默认资产精确到小数点后 4 位。
* **鲁棒的错误处理**：详尽的 `BankingError` 枚举，覆盖了账户冻结、余额不足、重复纠纷、非法交易等各种边界情况。
* **流式 CSV 处理**：使用 `csv` 库流式读取并反序列化数据，内存占用低，适合处理大规模的流水记录。

## 📂 项目结构

```text
src/
├── main.rs          # 命令行入口，负责解析参数与调度流式读取器
├── bank.rs          # 银行核心中央账本，管理账户集合与历史交易快照
├── account.rs       # 客户账户模型，定义资产状态机与核心资金操作
├── transaction.rs   # 交易模型，包含各类交易的字段校验与前置对齐逻辑
└── error.rs         # 业务异常枚举定义

```

## 🚀 快速开始

### 1. 前置要求

确保本地已安装 [Rust 和 Cargo](https://www.rust-lang.org/) 工具链。

### 2. 准备测试数据

创建一个名为 `input.csv` 的文件，输入以下测试流水：

```csv
type, client, tx, amount
deposit, 1, 1, 10.0
deposit, 2, 2, 5.0
withdrawal, 1, 3, 3.0
dispute, 1, 1,
chargeback, 1, 1,
```

### 3. 运行程序

通过命令行传入 CSV 文件的路径。程序处理完毕后，会将所有受影响账户的最终资产状态以 CSV 格式输出到标准输出（stdout）：

```bash
cargo run -- csv/sample-input/resolve_deposit_dispute.csv
```

### 4. 预期输出格式

```csv
client,available,held,total,locked
1,0,0,0,true
2,5,0,5,false
```

## 🧪 核心安全校验规则

为了保证资产安全，引擎在处理请求时会强制执行以下校验：

* **唯一性检查**：每一个 `Deposit` 和 `Withdrawal` 的交易 ID (`tx`) 必须唯一。
* **合规性检查**：`Dispute`、`Resolve` 和 `Chargeback` 只能针对已经存在的 `Deposit` 交易发起，且发起请求的 `client` ID 必须与原交易一致。
* **状态锁检查**：一旦账户因为 `Chargeback` 变为 `locked: true` 状态，后续的任何充值、提现或纠纷操作都将直接返回 `AccountLocked` 错误。