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)
259 lines
11 KiB
Markdown
259 lines
11 KiB
Markdown
# 系统架构文档
|
||
|
||
## 一、系统概述
|
||
|
||
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 出金流程
|
||
|
||
```mermaid
|
||
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 对账流程
|
||
|
||
```mermaid
|
||
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 部署
|
||
|
||
```yaml
|
||
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 |
|
||
|
||
## 九、安全考虑
|
||
|
||
1. **资金安全**：三科目不变量约束，确保资金不会凭空消失或增加
|
||
2. **幂等性**：三键体系确保交易不重复
|
||
3. **并发控制**：乐观锁 + 版本号防止并发更新冲突
|
||
4. **审计追踪**：所有操作记录完整日志
|
||
|
||
## 十、性能优化
|
||
|
||
1. **异步处理**：基于 Tokio 的异步运行时
|
||
2. **连接池**：SQLx 数据库连接池
|
||
3. **批量操作**：批量创建账户、批量对账
|
||
4. **索引优化**：关键查询字段建立索引
|
||
|