tangweijie/rustjr-account-management
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
rustjr-account-management/README.md
tangweijie d7f81893c5 Initial commit: 完整的 Rust 账户管理系统 
- 实现账户管理改进设计文档中的所有核心功能
- 三科目余额管理 (个人余额、劳动报酬、冻结余额)
- 交易状态机 (created → pending → bank_submitted → success/failed/timeout → reversed)
- 三键幂等体系 (JZTxId/BankTxId/SourceKey)
- 优先级扣款规则 (先个人后劳动)
- 在途资金管理 (可用→在途→结转/回退)
- 三账对账闭环 (总账 = 银行账 + 在途净额)
- 补偿服务域 (超时检测、重试、死信队列)
- 虚拟银行模拟器用于业务测试
- 完整的集成测试套件 (133 个测试全部通过)
- Docker 容器化部署配置
- 前端 Vue3 + TypeScript 项目结构
2026-01-05 17:56:01 +08:00

7.5 KiB
Raw Blame History

银行账户管理系统 (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+

配置

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

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