# 榴莲生态2.0 挖矿系统架构总览 ## 1. 系统架构图 ``` ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 用户端应用 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────────┐ ┌─────────────────────────┐ │ │ │ Mining App │ │ Mining Admin Web │ │ │ │ (Flutter 用户端) │ │ (Next.js 管理后台) │ │ │ │ │ │ │ │ │ │ - 贡献值展示 │ │ - 系统配置管理 │ │ │ │ - 实时收益显示 │ │ - 用户查询 │ │ │ │ - 买卖兑换 │ │ - 报表统计 │ │ │ │ - K线图 │ │ - 初始化任务 │ │ │ │ - 资产展示 │ │ - 审计日志 │ │ │ └───────────┬─────────────┘ └───────────┬─────────────┘ │ │ │ │ │ └──────────────┼────────────────────────────────────────┼──────────────────────────┘ │ │ ▼ ▼ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ API Gateway (Nginx) │ └─────────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 微服务层 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ │ │ Contribution │ │ Mining │ │ Trading │ │ │ │ Service │ │ Service │ │ Service │ │ │ │ (贡献值/算力) │ │ (挖矿分配) │ │ (交易) │ │ │ │ Port: 3020 │ │ Port: 3021 │ │ Port: 3022 │ │ │ ├─────────────────────┤ ├─────────────────────┤ ├─────────────────────┤ │ │ │ - CDC数据同步 │ │ - 积分股分配 │ │ - 买卖撮合 │ │ │ │ - 算力计算 │ │ - 每分钟销毁 │ │ - K线生成 │ │ │ │ - 明细账管理 │ │ - 价格计算 │ │ - 手续费处理 │ │ │ │ - 过期处理 │ │ - 全局状态 │ │ - 流通池管理 │ │ │ └──────────┬──────────┘ └──────────┬──────────┘ └──────────┬──────────┘ │ │ │ │ │ │ │ └────────────────────────┼────────────────────────┘ │ │ │ │ │ ┌───────────▼───────────┐ │ │ │ Mining Admin │ │ │ │ Service │ │ │ │ (挖矿管理) │ │ │ │ Port: 3023 │ │ │ ├───────────────────────┤ │ │ │ - 配置管理 │ │ │ │ - 系统监控 │ │ │ │ - 数据初始化 │ │ │ │ - 审计日志 │ │ │ └───────────────────────┘ │ │ │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ 现有服务 (集成) │ │ │ │ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ │ │ Identity │ │ Wallet │ │ Planting │ │ │ │ Service │ │ Service │ │ Service │ │ │ │ (用户) │ │ (钱包) │ │ (认种) │ │ │ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘ │ │ │ │ ┌─────────────────────┐ │ │ │ Referral │ │ │ │ Service │ │ │ │ (推荐关系) │ │ │ └─────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────────┐ │ 基础设施层 │ ├─────────────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ PostgreSQL │ │ Kafka │ │ Redis │ │ Debezium Connect │ │ │ │ (数据库) │ │ (消息队列) │ │ (缓存) │ │ (CDC) │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────────────┘ ``` --- ## 2. 服务职责与端口分配 | 服务名称 | 端口 | 数据库 | 核心职责 | |---------|------|--------|---------| | **contribution-service** | 3020 | rwa_contribution | 算力计算、CDC同步、明细账 | | **mining-service** | 3021 | rwa_mining | 积分股分配、销毁、价格计算 | | **trading-service** | 3022 | rwa_trading | 买卖交易、K线、流通池 | | **mining-admin-service** | 3023 | rwa_mining_admin | 配置管理、监控、初始化 | --- ## 3. 数据流向 ### 3.1 算力计算流程 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 算力计算数据流 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ Identity Service Planting Service Referral Service │ │ │ │ │ │ │ │ CDC │ CDC │ CDC │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Debezium Kafka Connect │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Contribution Service │ │ │ │ │ │ │ │ 1. 同步用户数据 (synced_users) │ │ │ │ 2. 同步认种数据 (synced_adoptions) │ │ │ │ 3. 同步推荐关系 (synced_referrals) │ │ │ │ 4. 计算用户算力: │ │ │ │ - 个人算力 (70%) │ │ │ │ - 团队层级算力 (0.5% × N级) │ │ │ │ - 团队额外奖励 (2.5% × N档) │ │ │ │ 5. 记录算力明细账 │ │ │ │ 6. 生成每日算力快照 │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ │ Event: daily-snapshot-created │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Mining Service │ │ │ │ │ │ │ │ 根据算力快照分配每日积分股 │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` ### 3.2 挖矿分配流程 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 挖矿分配数据流 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ 每日凌晨定时任务: │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Mining Service │ │ │ │ │ │ │ │ 1. 获取昨日算力快照 │ │ │ │ 2. 计算全网总算力 │ │ │ │ 3. 计算每个用户算力占比 │ │ │ │ 4. 根据占比分配当日积分股: │ │ │ │ - 第1-2年: 每日 1369.86 股 │ │ │ │ - 第3-4年: 每日 684.93 股 │ │ │ │ - 依次减半... │ │ │ │ 5. 更新用户积分股账户 │ │ │ │ 6. 记录挖矿明细账 │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ 每分钟定时任务: │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Mining Service │ │ │ │ │ │ │ │ 1. 计算当前销毁量: │ │ │ │ 销毁量 = (100亿 - 黑洞量) ÷ 剩余分钟数 │ │ │ │ 2. 执行销毁（进入黑洞） │ │ │ │ 3. 重新计算价格: │ │ │ │ 价格 = 积分股池 ÷ (100.02亿 - 黑洞 - 流通池) │ │ │ │ 4. 记录销毁明细账 │ │ │ │ 5. 记录价格快照 │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` ### 3.3 交易流程 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 交易数据流 (卖出) │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ 用户发起卖出: │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Trading Service │ │ │ │ │ │ │ │ 1. 获取当前价格 │ │ │ │ 2. 计算卖出倍数: │ │ │ │ 倍数 = (100亿 - 销毁量) ÷ (200万 - 流通池量) │ │ │ │ 3. 计算卖出销毁量: │ │ │ │ 销毁量 = 卖出量 × 倍数 │ │ │ │ 4. 计算交易额: │ │ │ │ 交易额 = (卖出量 + 销毁量) × 价格 │ │ │ │ 5. 计算手续费 (10%) │ │ │ │ 6. 执行交易: │ │ │ │ - 扣减用户积分股 │ │ │ │ - 积分股进入流通池 │ │ │ │ - 从积分股池扣减绿积分给用户 │ │ │ │ - 手续费注入积分股池 │ │ │ │ 7. 记录交易明细账 │ │ │ │ 8. 更新K线数据 │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ │ Event: trade-completed │ │ ▼ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Mining Service │ │ │ │ │ │ │ │ 1. 更新流通池状态 │ │ │ │ 2. 触发卖出销毁（提前销毁未来的量） │ │ │ │ 3. 重新计算每分钟销毁量 │ │ │ │ 4. 重新计算价格 │ │ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` --- ## 4. 服务间通信 ### 4.1 事件驱动 (Kafka Topics) | Topic | 发布者 | 订阅者 | 说明 | |-------|--------|--------|------| | `dbserver1.rwa_identity.users` | Debezium | contribution-service | 用户CDC | | `dbserver1.rwa_planting.adoptions` | Debezium | contribution-service | 认种CDC | | `dbserver1.rwa_referral.referral_relations` | Debezium | contribution-service | 推荐关系CDC | | `contribution.daily-snapshot-created` | contribution-service | mining-service | 每日算力快照 | | `mining.shares-distributed` | mining-service | trading-service, mining-admin | 积分股分配完成 | | `mining.price-updated` | mining-service | trading-service, mining-admin | 价格更新 | | `trading.trade-completed` | trading-service | mining-service | 交易完成 | | `mining-admin.config-updated` | mining-admin-service | 所有服务 | 配置更新 | ### 4.2 同步调用 (HTTP) ``` mining-admin-service → contribution-service: 获取用户算力详情 mining-admin-service → mining-service: 获取全局状态、用户积分股 mining-admin-service → trading-service: 获取交易统计、K线数据 trading-service → mining-service: 获取当前价格、全局状态 trading-service → wallet-service: 扣减/增加绿积分 ``` --- ## 5. 关键数据表关系 ### 5.1 跨服务数据关联 **所有服务统一使用 `account_sequence` 作为跨服务关联键，不使用 `userId`** ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ account_sequence 关联 │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ Identity Service │ │ └── users.account_sequence ────────────────────────────────┐ │ │ │ │ │ Contribution Service │ │ │ ├── synced_users.account_sequence ─────────────────────────┤ │ │ ├── contribution_accounts.account_sequence ────────────────┤ │ │ └── contribution_records.account_sequence ─────────────────┤ │ │ │ │ │ Mining Service │ │ │ ├── share_accounts.account_sequence ───────────────────────┤ │ │ └── daily_mining_records.account_sequence ─────────────────┤ │ │ │ │ │ Trading Service │ │ │ ├── trade_orders.account_sequence ─────────────────────────┤ │ │ └── trade_transactions.account_sequence ───────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` ### 5.2 明细账设计原则 每个服务都维护自己的明细账，确保数据可追溯： | 服务 | 明细账表 | 记录内容 | |------|---------|---------| | contribution-service | contribution_records | 每笔算力来源 | | mining-service | daily_mining_records | 每日挖矿分配 | | mining-service | burn_records | 每次销毁详情 | | trading-service | trade_transactions | 每笔交易流水 | --- ## 6. 关键配置参数 ### 6.1 贡献值配置 | 参数 | 默认值 | 说明 | |------|--------|------| | base_contribution | 22617 | 基础贡献值 | | increment_percentage | 0.3% | 每单位递增比例 | | unit_size | 100 | 单位大小（棵） | | personal_rate | 70% | 个人分配比例 | | level_rate_per | 0.5% | 每级分配比例 | | bonus_rate_per | 2.5% | 每档奖励比例 | ### 6.2 分配配置 | 阶段 | 时长 | 总量 | 每日分配 | |------|------|------|---------| | 第1阶段 | 2年 | 100万 | 1369.86 | | 第2阶段 | 2年 | 50万 | 684.93 | | 第3阶段 | 2年 | 25万 | 342.47 | | ... | ... | ... | ... | ### 6.3 交易配置 | 参数 | 默认值 | 说明 | |------|--------|------| | buy_fee_rate | 10% | 买入手续费 | | sell_fee_rate | 10% | 卖出手续费 | | transfer_enabled | false | 转账开关 | --- ## 7. 部署架构 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ Docker Compose │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ 服务容器: │ │ ├── contribution-service (3020) │ │ ├── mining-service (3021) │ │ ├── trading-service (3022) │ │ └── mining-admin-service (3023) │ │ │ │ 基础设施容器: │ │ ├── postgres (5432) - 已有，新增 schema │ │ ├── kafka (9092) - 已有 │ │ ├── redis (6379) - 已有 │ │ └── debezium-connect (8084) - 已有，新增 connector │ │ │ │ 前端容器: │ │ ├── mining-admin-web (3100) │ │ └── api-gateway (nginx) - 已有，新增路由 │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` --- ## 8. 开发顺序建议 1. **Phase 1: 数据同步** - contribution-service: CDC 消费者实现 - 同步用户、认种、推荐关系数据 2. **Phase 2: 算力计算** - contribution-service: 算力计算逻辑 - 老用户算力初始化 3. **Phase 3: 挖矿分配** - mining-service: 全局状态管理 - mining-service: 每日分配、每分钟销毁 4. **Phase 4: 交易功能** - trading-service: 买卖逻辑 - trading-service: K线生成 5. **Phase 5: 管理后台** - mining-admin-service: 配置管理、监控 - mining-admin-web: 前端实现 6. **Phase 6: 用户端** - mining-app: Flutter App 实现 --- ## 9. 文档索引 | 服务/应用 | 开发指导文档路径 | |----------|----------------| | contribution-service | [backend/services/contribution-service/DEVELOPMENT_GUIDE.md](../backend/services/contribution-service/DEVELOPMENT_GUIDE.md) | | mining-service | [backend/services/mining-service/DEVELOPMENT_GUIDE.md](../backend/services/mining-service/DEVELOPMENT_GUIDE.md) | | trading-service | [backend/services/trading-service/DEVELOPMENT_GUIDE.md](../backend/services/trading-service/DEVELOPMENT_GUIDE.md) | | mining-admin-service | [backend/services/mining-admin-service/DEVELOPMENT_GUIDE.md](../backend/services/mining-admin-service/DEVELOPMENT_GUIDE.md) | | mining-admin-web | [frontend/mining-admin-web/DEVELOPMENT_GUIDE.md](../frontend/mining-admin-web/DEVELOPMENT_GUIDE.md) | | mining-app | [frontend/mining-app/DEVELOPMENT_GUIDE.md](../frontend/mining-app/DEVELOPMENT_GUIDE.md) |