rustjr-account-management/README.md

银行账户管理系统 (RustJR)

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

📁 仓库信息

• 仓库地址: https://gitea.devops.1msoft.cn/tangweijie/rustjr-account-management
• SSH 克隆: git clone ssh://git@gitea.devops.1msoft.cn:12224/tangweijie/rustjr-account-management.git
• HTTPS 克隆: git clone https://gitea.devops.1msoft.cn/tangweijie/rustjr-account-management.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+

配置

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

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

数据库初始化

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

运行

cargo run

构建

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