RYZZ-H5页面
RYZZ H5 页面是嵌入 App 内或独立运行的移动端 Web 应用集合，包含三个独立项目：Public（核心功能应用）、Binding（Web3 社交绑定）和 LandPages（营销落地页）。其中 Public 是功能最复杂的项目，涵盖钱包（Fiat + Crypto + NFT）、游戏、任务、支付、竞猜、签到、空投等完整的平台生态功能。
一、项目全景架构
1.1 三个项目的定位
1.2 技术栈对比
| 特性 | Public | Binding | LandPages |
|---|---|---|---|
| 框架 | UmiJS Max 4 | UmiJS Max 4 | React 18 + 自定义 Webpack |
| 路由 | UmiJS 约定式 (30+ 页) | UmiJS 约定式 (6 页) | React Router v6 (2 页) |
| 样式 | Tailwind CSS + SCSS | SASS | Less + Styled Components |
| UI 库 | Antd Mobile + @ryzz/uikit | Antd Mobile | React Vant |
| Web3 | ethers.js 5.7.2 | - | - |
| 监控 | Sentry React 7.91 | - | - |
| 国际化 | UmiJS locale + 手动检测 | UmiJS locale | i18next |
| App 交互 | JS Bridge SDK | JS Bridge SDK | - |
| 构建 | Max (UmiJS) | Max (UmiJS) | Webpack 5 自定义配置 |
| 移动适配 | Tailwind 响应式 | - | amfe-flexible (rem) |
二、Public - 核心功能应用（重点项目）
2.1 整体架构
2.2 路由全景图
2.3 钱包系统（最核心模块）
钱包系统是 Public 项目中最复杂的模块，采用双钱包架构，同时支持平台内虚拟货币和 Web3 加密资产。这是 Web2 与 Web3 融合的典型实践，通过 Tab 切换无缝衔接两套资产体系。
Balance 消费钱包：
- 管理平台内虚拟币（Coins 和 Gem）
- 支持发送/接收/提现/申诉完整操作链
- 交易历史查询和筛选
Ryzz Wallet 加密钱包：
- 基于 ethers.js 的多链加密资产管理
- Crypto Tab：查看持有的加密货币列表、实时价格估算
- NFT Tab：查看和管理 NFT 资产
- 发送/接收加密资产
数据获取流程：
获取支持的货币列表 → 批量查询估算价值 → 渲染资产列表（含实时价格）
2.4 Web3 登录体系
特点：
- 支持 DAuth 和标准 Web3 钱包两种方式
- 自动 Token 刷新机制
- 支持断开连接和重新认证
2.5 游戏模块
游戏模块受 App 环境保护，只能在原生 App 的 WebView 中访问。
游戏模块受 App 环境保护，通过 User Agent 中的 vico 标识判断是否在 App 内。在浏览器中直接访问会被拦截并显示下载引导页，开发调试时需要注意使用 isDebug 模式绕过此检测。
2.6 任务系统
平台提供多种类型的任务激励机制：
| 任务类型 | 路由 | 目标用户 |
|---|---|---|
| 回购任务 | /task/repurchase | 全部用户 |
| 币任务 | /task/coin | 全部用户 |
| 代币任务 | /task/token | 全部用户 |
| 用户分享任务 | /task/share/user | 普通用户 |
| 创作者分享任务 | /task/share/creator | 创作者 |
2.7 竞猜系统
2.8 其他功能模块
| 模块 | 路由 | 功能 |
|---|---|---|
| 签到 | /sign/dayrewards, /sign/streakrewards | 每日签到奖励 + 连续签到奖励 |
| Flame | /flame/index | 火力值系统 |
| Check-in | /checkin/index | 签到打卡 |
| 奖励 | /rewards/index | 奖励中心 |
| 空投规则 | /airdrop/rule | 空投活动规则说明 |
| Vote to Earn | /vote2earn/content | 投票赚币 |
| 公会邀请 | /guild/invite | 公会邀请页 |
| 推荐下载 | /recommend/download | App 下载引导 |
| JS Bridge 调试 | /test/bridge（非生产） | 开发调试工具 |
2.9 组件架构
2.10 请求拦截器
Public 项目的请求拦截器实现了丰富的 Header 注入：
| Header | 来源 | 用途 |
|---|---|---|
Authorization | Bearer Token | 身份认证 |
X-Lcid | 语言 ID | 国际化 |
X-Device-Id | 设备 UUID | 设备追踪 |
X-Sid | 会话 UUID | 会话追踪 |
2.11 服务层（20+ 模块）
三、Binding - Web3 社交账号绑定
3.1 功能定位
Binding 是专门处理 Web3 钱包与社交账号绑定 的 H5 应用，通过 OAuth 2.0 协议对接多个社交平台。
3.2 支持的绑定平台
3.3 绑定流程
3.4 核心技术要点
多业务类型支持：
bizType: 1 // 账号绑定
bizType: 2 // 市场
bizType: 3 // 任务
使用 Web API BroadcastChannel 实现多标签页状态同步，相比传统的 postMessage / localStorage 事件监听方案更简洁。典型场景：OAuth 回调页通知原始页面绑定结果，通过 UmiJS Model 管理 channel 实例生命周期。
路由保护：
wrappers/Auth.tsx实现路由级身份验证- 未登录用户显示提示而非跳转
JS Bridge 集成：
// 从 App 获取登录信息
const loginInfo = User.getLoginInfo();
const accessToken = loginInfo?.data?.accessToken;
// 获取语言设置
const languageInfo = User.getLanguageInfo()?.data;
// App 环境检测
const isApp = navigator.userAgent.includes('vico');
3.5 页面结构
| 页面 | 路径 | 功能 |
|---|---|---|
| 引导页 | /guide | 绑定入口（需身份验证） |
| 登录页 | /login | 登录页面 |
| 登录回调 | /afterlogin | 登录后处理 |
| 连接回调 | /afterconnect | 钱包连接后处理 |
| 任务详情 | /Task/Detail | 任务详情页 |
| 备用页 | /fallback | 降级处理 |
| 404 | /404 | 错误页面 |
四、LandPages - 营销落地页
4.1 功能定位
LandPages 是面向外部用户的营销引流落地页，不依赖 App 环境，可在任意浏览器中独立运行。
4.2 技术特色
完全自定义 Webpack 构建：
- 不依赖 Create React App，100% 自定义 Webpack 5 配置
- 支持 CSS Modules + Less 预处理
- Babel 转译 + Styled Components
- 三环境独立构建（local / test / production）
rem 移动端适配：
使用手淘 amfe-flexible 方案，自动根据屏幕宽度计算根字号，实现像素级还原设计稿。
4.3 页面详情
RoomShare - 直播间分享页
三种分享文案（根据 identity 参数动态切换）：
- 好友推荐："My live streaming room will surprise you..."
- 主播推荐："I highly recommend this streamer..."
- 内容推荐："I've seen a lot of interesting content..."
Follow - 关注引导页
简洁的关注引导页面，引导用户关注平台。
4.4 类型安全的 HTTP 请求
通过 TypeScript 泛型约束实现 API 端点、请求参数、响应数据的三方类型联动，编译期即可捕获接口调用错误。
// 通过 TypeScript 泛型确保 API 调用类型安全
const request = <T extends keyof typeof apis>(
api: T,
data: HttpRequest[T], // 请求参数类型自动推导
method = 'post'
): Promise<Response<HttpResponse[T]>> // 响应类型自动推导
API 端点和类型定义分离，通过 apis.ts、HttpRequest.d.ts、HttpResponse.d.ts 三个文件实现类型映射。
五、JS Bridge SDK - App 桥接核心
三个 H5 项目与原生 App 的交互都通过 JS Bridge SDK 实现。
5.1 模块架构
5.2 Transaction 模块（关键）
Transaction 模块封装了所有需要与 App 协作完成的链上操作：
| 方法 | 功能 | 参数 |
|---|---|---|
send | 转账 | amount, to, currency |
pledgeChannel | 质押频道 | channelId |
unlockKeys | 解锁 Keys | channelId |
buyKeys | 购买 Keys | channelId, amount |
withdrawKeys | 提取 Keys 收益 | channelId |
buyKeysFromMarket | 二级市场购买 | saleId, channelId |
addBettingTopic | 开启竞猜 | orderId |
betUp | 用户下注 | orderId |
addBettingOdds | 添加赔率 | orderId |
addPledgeAmount | 添加质押金额 | orderId |
5.3 Router 模块 URL 协议
六、埋点分析体系
埋点系统同时对接 Google Analytics、Facebook Pixel、Twitter Conversion 和自有后端四个渠道，实现一次埋点多端上报，覆盖广告归因和用户行为分析。
6.1 Report SDK 三平台集成
Twitter 事件映射（17 个核心事件）：
register_show_count→ 注册展示login_success_count→ 登录成功recharge_success_count→ 充值成功send_gift_count→ 送礼betting_bet_up_count→ 投注- 等等...
七、技术亮点总结
7.1 双钱包架构
Public 项目的钱包系统同时支持平台内虚拟货币（Coins/Gem）和 Web3 加密资产（多链 Crypto + NFT），通过 Tab 切换无缝衔接，是 Web2 与 Web3 融合的典型实践。
7.2 App 内嵌 H5 的完整解决方案
- 认证同步：通过 Bridge 获取 App 中的 accessToken，避免重复登录
- 语言同步：读取 App 语言设置，H5 页面自动适配
- 交易协作：复杂的链上操作通过 Bridge 委托给 App 原生层执行
- 环境保护：游戏等敏感模块通过 UA 检测限制只能在 App 内访问
7.3 BroadcastChannel 跨标签页通信
Binding 项目创新性地使用 Web BroadcastChannel API 解决 OAuth 回调场景下的跨标签页状态同步问题，避免了传统 postMessage / localStorage 事件监听的复杂性。
7.4 类型安全的全链路
- Public/Binding：OpenAPI 自动生成 API 类型
- LandPages：手动定义
HttpRequest/HttpResponse类型映射，通过泛型约束确保 API 调用的类型安全
7.5 多端适配策略
| 项目 | 适配方案 | 优势 |
|---|---|---|
| Public | Tailwind CSS + @ryzz/uikit 预设 | 原子化样式，开发效率高 |
| Binding | SASS 模块化样式 | 组件级隔离 |
| LandPages | amfe-flexible + postcss-pxtorem | 像素级还原设计稿，自动 rem 转换 |
7.6 Sentry 生产环境监控
Public 项目集成 Sentry React SDK，实现：
- 生产环境错误自动捕获和上报
- 错误堆栈还原
- 性能监控
7.7 自定义 Webpack 构建（LandPages）
LandPages 完全脱离脚手架，自定义 Webpack 5 配置：
- 环境变量注入（.env.local / .env.test / .env.production）
- CSS Modules + Less 预处理
- React.lazy + Suspense 代码分割
- Bundle 分析工具
- Styled Components + px2rem 插件
7.8 国际化多策略
八、三项目对比总结
8.1 复杂度对比
| 维度 | Public | Binding | LandPages |
|---|---|---|---|
| 页面数量 | 30+ | 6 | 2 |
| API 模块 | 20+ | 4 | 1 |
| 组件数 | 15+ | 5 | 1 |
| 代码规模 | 大 | 中 | 小 |
| 业务复杂度 | 极高 | 中 | 低 |
8.2 共同特征
- 移动优先：所有项目都针对移动端优化
- 多环境支持：开发/测试/生产三套环境
- 国际化：支持英文、中文、印尼文等多语言
- 统一错误处理：HTTP 状态码 + 业务状态码双重校验
- Token 认证：Bearer Token + 请求/响应拦截器
8.3 业务价值
九、项目数据概览
| 指标 | Public | Binding | LandPages | 合计 |
|---|---|---|---|---|
| 页面路由 | 30+ | 6 | 2 | 38+ |
| API 服务模块 | 20+ | 4 | 1 | 25+ |
| 技术框架 | UmiJS Max | UmiJS Max | React+Webpack | 3 种 |
| Web3 集成 | ethers.js | 间接 | 无 | - |
| 移动适配方案 | Tailwind | - | rem | 2 种 |
| 监控 | Sentry | - | - | - |
| JS Bridge | 完整集成 | 完整集成 | - | - |