# 系统架构文档 ## 一、系统概述 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. **索引优化**：关键查询字段建立索引