# 银行账户管理系统 (RustJR)

一个基于 Rust 构建的银行账户管理平台，支持实体账户、虚拟子账户、复式记账、对账补录、积分管理等核心功能。

## 系统架构

```
┌─────────────────────────────────────────────────────────────────┐
│                          API 层                                  │
│              (HTTP REST API - axum)                             │
├─────────────────────────────────────────────────────────────────┤
│                        应用层                                    │
│              (Commands / Queries / DTOs)                        │
├─────────────────────────────────────────────────────────────────┤
│                        领域层                                    │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │ 账户域  │ │ 账务域  │ │ 交易域  │ │ 对账域  │ │ 积分域  │   │
│  │Account  │ │ Ledger  │ │  Txn    │ │ Recon   │ │ Points  │   │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘   │
├─────────────────────────────────────────────────────────────────┤
│                      基础设施层                                  │
│  ┌─────────────────┐ ┌─────────────────────────────────────┐   │
│  │   MySQL 持久化   │ │        银行对接 (直连/第三方)        │   │
│  └─────────────────┘ └─────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
```

## 核心功能

### 账户管理
- 实体账户（银行账户）管理
- 虚拟子账户（结算/管理/临时）
- 临时账户池（生命周期管理）
- 账户冻结/解冻/销户

### 账务处理
- 复式记账引擎
- 多维度余额（系统/银行/可支配/冻结/在途）
- 会计科目体系
- 分录过账与冲销

### 交易处理
- 内部转账
- 充值/提现
- 银行流水同步
- 交易状态管理

### 对账补录
- 自动对账匹配
- 差异处理（自动/手工）
- 手工补录审批流程
- 对账报表

### 积分管理
- 多类型积分（生产/管理/其他）
- 积分获取/消费/转移
- 积分过期处理

## 技术栈

- **语言**: Rust 2021
- **Web 框架**: axum 0.7
- **ORM**: sea-orm 0.12
- **数据库**: MySQL 8.0
- **序列化**: serde
- **日志**: tracing

## 项目结构

```
rustjr/
├── Cargo.toml                 # 项目配置
├── src/
│   ├── main.rs               # 入口
│   ├── lib.rs                # 库入口
│   ├── config.rs             # 配置
│   ├── error.rs              # 错误处理
│   ├── domain/               # 领域层
│   │   ├── account/          # 账户域
│   │   ├── ledger/           # 账务域
│   │   ├── transaction/      # 交易域
│   │   ├── reconciliation/   # 对账域
│   │   └── points/           # 积分域
│   ├── application/          # 应用层
│   │   ├── commands/
│   │   ├── queries/
│   │   └── dto/
│   ├── infrastructure/       # 基础设施层
│   │   ├── persistence/      # 数据库
│   │   └── bank_integration/ # 银行对接
│   └── api/                  # API 层
│       └── handlers/
└── migrations/               # 数据库迁移
```

## 快速开始

### 环境要求

- Rust 1.70+
- MySQL 8.0+

### 配置

复制环境配置文件并修改：

```bash
cp .env.example .env
```

配置项：
```
DATABASE_URL=mysql://zjxt-rust:zjxt-rust@192.168.10.126:3306/zjxt-rust
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
RUST_LOG=info,rustjr=debug
RECONCILIATION_AUTO_ADJUST_THRESHOLD=100.00
```

### 数据库初始化

```bash
mysql -h 192.168.10.126 -u zjxt-rust -p zjxt-rust < migrations/001_init_schema.sql
```

### 运行

```bash
cargo run
```

### 构建

```bash
cargo build --release
```

## API 文档

### 健康检查
```
GET /health
```

### 账户 API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/v1/physical-accounts | 创建实体账户 |
| GET | /api/v1/physical-accounts | 获取实体账户列表 |
| GET | /api/v1/physical-accounts/:id | 获取实体账户详情 |
| POST | /api/v1/physical-accounts/:id/freeze | 冻结实体账户 |
| POST | /api/v1/physical-accounts/:id/unfreeze | 解冻实体账户 |
| POST | /api/v1/sub-accounts | 创建虚拟子账户 |
| GET | /api/v1/sub-accounts/:id | 获取子账户详情 |
| GET | /api/v1/sub-accounts/:id/balance | 获取子账户余额 |

### 交易 API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/v1/transactions/transfer | 内部转账 |
| POST | /api/v1/transactions/deposit | 充值 |
| POST | /api/v1/transactions/withdraw | 提现 |
| GET | /api/v1/transactions/:id | 获取交易详情 |
| GET | /api/v1/transactions | 查询交易列表 |

### 对账 API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/v1/reconciliation/run | 执行对账 |
| GET | /api/v1/reconciliation/batches/:id | 获取对账批次 |
| POST | /api/v1/reconciliation/adjustments | 创建手工补录 |
| POST | /api/v1/reconciliation/adjustments/:id/approve | 审批补录 |

### 积分 API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/v1/points/accounts/:sub_account_id | 获取积分账户 |
| POST | /api/v1/points/earn | 获取积分 |
| POST | /api/v1/points/spend | 消费积分 |
| POST | /api/v1/points/transfer | 转移积分 |

## 账务闭环设计

### 余额类型

| 余额类型 | 说明 |
|----------|------|
| system_balance | 系统余额 = 所有已确认分录的净额 |
| bank_balance | 银行余额 = 银行对账单确认的余额 |
| available_balance | 可支配余额 = system - frozen - transit |
| frozen_amount | 冻结金额（预授权、担保等） |
| transit_amount | 在途金额（已发起未确认的出金） |

### 复式记账示例

**子账户 A 转账 100 元到子账户 B：**

| 分录行 | 账户 | 科目 | 借方 | 贷方 |
|--------|------|------|------|------|
| 1 | 子账户A | 2001客户存款 | 100 | - |
| 2 | 子账户B | 2001客户存款 | - | 100 |

### 对账流程

```
系统交易 ──┐
          ├─→ 对账匹配 ─→ 匹配成功 ─→ 确认分录
银行流水 ──┘              │
                        └─→ 存在差异 ─→ 小额自动调整
                                      └─→ 大额手工补录
```

## License

MIT