236 lines
8.0 KiB
Markdown
236 lines
8.0 KiB
Markdown
# 银行账户管理系统 (RustJR)
|
||
|
||
一个基于 Rust 构建的银行账户管理平台，支持实体账户、虚拟子账户、复式记账、对账补录、积分管理等核心功能。
|
||
|
||
## 📁 仓库信息
|
||
|
||
- **后端仓库**: https://gitea.devops.1msoft.cn/tangweijie/rustjr-account-management
|
||
- **前端仓库**: https://gitea.devops.1msoft.cn/tangweijie/rustjr-account-management-frontend
|
||
|
||
### 克隆项目
|
||
|
||
```bash
|
||
# 克隆后端项目
|
||
git clone ssh://git@gitea.devops.1msoft.cn:12224/tangweijie/rustjr-account-management.git
|
||
|
||
# 克隆前端项目
|
||
git clone ssh://git@gitea.devops.1msoft.cn:12224/tangweijie/rustjr-account-management-frontend.git
|
||
```
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 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
|
||
|