tangweijie
1460187516
- 系统架构文档 (architecture/README.md) - 6个领域文档: - 账户域 (01-account.md) - 账务域 (02-ledger.md) - 交易域 (03-transaction.md) - 对账域 (04-reconciliation.md) - 补偿域 (05-compensation.md) - 积分域 (06-points.md) - API 参考文档 (api/README.md) - 前后端对接清单 (integration/frontend-backend.md)
11 KiB
11 KiB
系统架构文档
一、系统概述
RustJR 是一个基于 Rust 构建的银行账户管理平台，采用领域驱动设计（DDD）架构，支持实体账户、虚拟子账户、复式记账、对账补录、积分管理等核心功能。
二、技术栈
| 层次 | 技术 | 说明 |
|---|---|---|
| Web框架 | Axum | 高性能异步 Web 框架 |
| 数据库 | MySQL 8.0 | 关系型数据库 |
| ORM | SQLx | 编译时检查的 SQL 查询 |
| 序列化 | Serde | JSON/YAML 序列化 |
| 日志 | Tracing | 结构化日志 |
| 数值计算 | rust_decimal | 高精度十进制计算 |
| 时间处理 | Chrono | 日期时间处理 |
| UUID | uuid | 唯一标识符生成 |
三、系统架构图
┌─────────────────────────────────────────────────────────────────┐
│ API 层 │
│ (HTTP REST API - axum) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │账户API │ │交易API │ │账务API │ │对账API │ │积分API │ │
│ │11端点 │ │5端点 │ │3端点 │ │8端点 │ │5端点 │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ 应用层 │
│ (Commands / Queries / DTOs) │
├─────────────────────────────────────────────────────────────────┤
│ 领域层 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ 账户域 │ │ 账务域 │ │ 交易域 │ │ 对账域 │ │ 积分域 │ │
│ │Account │ │ Ledger │ │ Txn │ │ Recon │ │ Points │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ ┌─────────┐ │
│ │ 补偿域 │ (后台服务) │
│ │Compensa │ │
│ └─────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ 基础设施层 │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ MySQL 持久化 │ │ 银行对接 (直连/第三方) │ │
│ │ (SQLx) │ │ (MockBank / DirectConnect) │ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
四、项目目录结构
rustjr/
├── src/
│ ├── main.rs # 应用入口
│ ├── lib.rs # 库入口
│ ├── config.rs # 配置管理
│ ├── error.rs # 错误定义
│ │
│ ├── api/ # API 层
│ │ ├── mod.rs # 路由注册
│ │ ├── state.rs # 应用状态
│ │ └── handlers/ # 请求处理器
│ │ ├── account.rs # 账户处理器
│ │ ├── transaction.rs # 交易处理器
│ │ ├── ledger.rs # 账务处理器
│ │ ├── reconciliation.rs # 对账处理器
│ │ └── points.rs # 积分处理器
│ │
│ ├── application/ # 应用层
│ │ ├── commands/ # 命令
│ │ ├── queries/ # 查询
│ │ └── dto/ # 数据传输对象
│ │
│ ├── domain/ # 领域层
│ │ ├── account/ # 账户域
│ │ │ ├── entity.rs # 实体
│ │ │ ├── repository.rs # 仓储接口
│ │ │ └── service.rs # 领域服务
│ │ ├── ledger/ # 账务域
│ │ ├── transaction/ # 交易域
│ │ ├── reconciliation/ # 对账域
│ │ ├── compensation/ # 补偿域
│ │ └── points/ # 积分域
│ │
│ └── infrastructure/ # 基础设施层
│ ├── persistence/ # 持久化
│ │ └── mysql/ # MySQL 实现
│ └── bank_integration/ # 银行对接
│ ├── mock_bank.rs # 模拟银行
│ ├── direct_connect.rs # 直连银行
│ └── third_party.rs # 第三方支付
│
├── migrations/ # 数据库迁移
│ ├── 001_init_schema.sql
│ └── 002_account_model_extension.sql
│
├── tests/ # 测试
│ ├── common/ # 测试公共代码
│ ├── unit/ # 单元测试
│ ├── integration/ # 集成测试
│ └── scenarios/ # 场景测试
│
└── docs/ # 文档
├── architecture/ # 架构文档
├── domains/ # 领域文档
├── api/ # API 文档
└── integration/ # 集成文档
五、领域划分
系统采用领域驱动设计，划分为 6 个核心领域：
| 领域 | 职责 | 核心实体 |
|---|---|---|
| Account | 账户管理 | PhysicalAccount, VirtualSubAccount |
| Ledger | 账务管理 | AccountBalance, LedgerEntry |
| Transaction | 交易处理 | SystemTransaction, BankTransaction |
| Reconciliation | 对账管理 | ReconciliationBatch, ManualAdjustment |
| Compensation | 补偿处理 | CompensationTask |
| Points | 积分管理 | PointsAccount, PointsTransaction |
六、核心设计理念
6.1 三科目余额模型
personal_balance + labor_balance + frozen_balance = bank_balance
(个人) (劳动) (冻结) (银行)
不变量约束：三科目之和必须等于银行余额，确保资金一致性。
6.2 交易状态机
Created → Pending → BankSubmitted → Success/Failed/Timeout → Reversed
↑ ↓
└─────────────────── Retry ───────────────┘
6.3 三键幂等体系
| 键名 | 说明 | 用途 |
|---|---|---|
| JZTxId | 狱政交易号 (txn_no) | 系统内唯一标识 |
| BankTxId | 银行交易号 (bank_ref_no) | 银行回执关联 |
| SourceKey | 来源幂等键 | 外部入账去重 |
6.4 三账对账闭环
总账余额 = 银行账余额 + 在途净额
通过三账校验确保资金安全：
- 银行账：实际银行余额
- 在途账：已扣未确认的资金
- 总账：系统记账余额
七、数据流
7.1 出金流程
sequenceDiagram
participant Client
participant API
participant TxnService
participant LedgerService
participant Bank
Client->>API: 发起转账请求
API->>TxnService: 创建交易 (Created)
TxnService->>LedgerService: 优先级扣款 (个人→劳动)
LedgerService->>LedgerService: 建立在途
TxnService->>TxnService: 更新状态 (Pending)
TxnService->>Bank: 提交银行
TxnService->>TxnService: 更新状态 (BankSubmitted)
Bank-->>TxnService: 银行回执
alt 成功
TxnService->>LedgerService: 结转在途
TxnService->>TxnService: 更新状态 (Success)
else 失败
TxnService->>LedgerService: 回退在途
TxnService->>TxnService: 更新状态 (Failed)
end
API-->>Client: 返回结果
7.2 对账流程
sequenceDiagram
participant Scheduler
participant ReconService
participant LedgerService
participant BankRepo
Scheduler->>ReconService: 触发对账
ReconService->>BankRepo: 获取银行流水
ReconService->>ReconService: 匹配系统交易
ReconService->>LedgerService: 三账校验
alt 平衡
ReconService->>ReconService: 标记完成
else 不平衡
ReconService->>ReconService: 生成差异报告
ReconService->>ReconService: 需要人工审核
end
八、部署架构
8.1 Docker 部署
services:
mysql:
image: mysql:8.0
ports: ["3306:3306"]
backend:
build: ./rustjr
ports: ["8080:8080"]
depends_on: [mysql]
frontend:
build: ./rustjr-vue-frontend
ports: ["3001:80"]
depends_on: [backend]
8.2 环境变量
| 变量 | 说明 | 默认值 |
|---|---|---|
| DATABASE_URL | 数据库连接串 | - |
| SERVER_HOST | 服务地址 | 0.0.0.0 |
| SERVER_PORT | 服务端口 | 8080 |
| RUST_LOG | 日志级别 | info |
九、安全考虑
- 资金安全：三科目不变量约束，确保资金不会凭空消失或增加
- 幂等性：三键体系确保交易不重复
- 并发控制：乐观锁 + 版本号防止并发更新冲突
- 审计追踪：所有操作记录完整日志
十、性能优化
- 异步处理：基于 Tokio 的异步运行时
- 连接池：SQLx 数据库连接池
- 批量操作：批量创建账户、批量对账
- 索引优化：关键查询字段建立索引