RYZZ-管理后台
RYZZ Admin 是支撑主站和 App 端全业务线的运营管理后台，基于 UmiJS Max 4 + Ant Design Pro 构建。覆盖公会管理、订单审核、资金空投、Keys 股息奖励、Token War 活动配置、Banner 运营、品类管理、数字货币配置等核心运营功能，为平台的日常运营和财务管理提供全方位支持。
一、项目技术架构
1.1 架构概览
1.2 核心技术栈
| 领域 | 技术选型 | 版本 |
|---|---|---|
| 框架 | UmiJS Max | 4.0.52 |
| UI 框架 | Ant Design | 5.2.2 |
| Pro 组件 | Ant Design Pro | 2.3.57 |
| 状态管理 | UmiJS Model（基于 hooks） | 内置 |
| HTTP | UmiJS request（Axios 封装） | 内置 |
| React Hooks | ahooks | 3.7.8 |
| 日期处理 | dayjs + date-fns | 1.11.9 / 2.29.3 |
| 工具库 | lodash | 4.17.21 |
| 数字动画 | react-countup | 6.4.2 |
| 构建加速 | mfsu（模块联邦） | 内置 |
| 国际化 | UmiJS locale | 9 种语言 |
| API 代码生成 | OpenAPI Generator | 内置 |
1.3 请求拦截与统一错误处理
环境自动切换
- 生产环境：
//api-gateway.ryzz.tv - 测试环境：
//api-test.x3live.info
通过 UmiJS 的环境变量机制，构建时自动注入对应环境的 API 地址，无需手动切换。
二、功能模块全景
2.1 模块总览
2.2 路由结构
| 菜单 | 路由 | 功能 |
|---|---|---|
| 公会管理 | /guild/list | 公会列表、创建、成员管理 |
/guild/settle | 公会结算记录 | |
| 白名单 | /whitelist/channel | 频道白名单管理 |
| 查询 | /query/channel | 频道信息查询 |
| 资金管理 | /funds/coin | 金币空投管理 |
| Keys 管理 | /keys/incentiveaudit | 股息奖励审核 |
| 品类 | /category/catalogue | 一级目录管理 |
/category/list | 二级品类管理 | |
| 推荐游戏 | /recGame/list | 推荐配置 |
| 邀请码 | /inviteCode/list | 邀请码生成 |
| Banner | /banner/homeList | 官网首页 Banner |
/banner/zoneHList | 游戏专区首页 Banner | |
/banner/webList | Web 首页 Banner | |
/banner/reGameList | 推荐游戏封面 | |
/banner/zoneList | 专区详情页 Banner | |
| 订单管理 | /order/list | 充值订单 |
/order/gemstone | 宝石提现 | |
| 申诉举报 | /appeal/recharge | 充值申诉处理 |
| Token War | /war/tokenlist | 代币管理 |
/war/activelist | 活动配置 | |
/war/datalist | 数据查询 | |
| 数字货币 | /coin/list | 币种管理 |
三、核心功能详解
3.1 公会管理系统
公会是平台主播聚集和管理的核心单元，公会管理模块支撑了整个 MCN 运营体系。
公会列表功能：
- 展示公会 ID、外显 ID（shortId）、名称、会长信息（头像+昵称+钱包地址）
- 创建公会：表单提交（名称、会长钱包地址、Logo 上传、人数上限）
- 实时修改成员上限
- 按名称模糊搜索、按状态筛选（正常/解散）
- 导航到成员管理页查看签约主播频道
结算记录功能：
- 账户总结算金额展示（CountUp 动画效果）
- 多币种支持（通过全局 currency model）
- 结算来源明细：门票、礼物、打赏、时间卡等
- 结算状态跟踪：成功 / 失败
- 多字段排序：创建时间、总金额、结算金额
3.2 Keys 股息奖励系统
Keys 是 RYZZ 平台的创作者股份代币机制，持有者可获得股息奖励。
功能要点：
- 按轮次管理股息奖励，每轮显示参与频道数、总股息（ETH）、持股人数量
- 四级状态流转：未下发 → 部分下发 → 等待下发 → 已下发
- 支持钻取到频道级别查看详细奖励明细
3.3 Token War 活动配置
Token War 是平台的特色活动模块，管理后台提供完整的活动配置和数据查询能力。
代币管理：创建/编辑/删除代币，支持上线/下线状态切换，Logo 上传 活动管理：创建活动时关联多个在线代币，设置时间范围，支持提前终止 数据查询：查看活动期间的交易数据和参与者排名
3.4 Banner 运营系统
管理平台多个位置的 Banner 轮播，是运营最频繁使用的模块之一。
五个独立 Banner 管理页面：
| 位置 | 路由 | 用途 |
|---|---|---|
| 官网首页 | /banner/homeList | 官网首屏轮播 |
| 游戏专区首页 | /banner/zoneHList | 游戏专区入口 |
| Web 首页 | /banner/webList | Web 版本首屏 |
| 推荐游戏封面 | /banner/reGameList | 游戏推荐卡片 |
| 游戏专区详情 | /banner/zoneList | 专区内部轮播 |
通用功能：
- Banner CRUD（标题、描述、图片上传、跳转 URL）
- 标签管理（动态添加/删除/编辑 Tag）
- 权重设置控制展示排序
- 启用/禁用开关
3.5 资金空投管理
管理平台内金币（Coin）的空投发放。
功能特点：
- 空投账户余额实时展示（CountUp 动画）
- 支持输入钱包地址和金额进行空投
- 空投订单追踪（成功/失败状态）
- 确认机制防止误操作
3.6 订单与申诉管理
- 充值订单：查看订单 ID、用户 ID、金额、状态，支持操作处理
- 宝石提现：审核提现申请，查看地址、数量、状态
- 充值申诉：处理用户关于充值问题的申诉，包含转账平台、钱包地址、金额等信息
3.7 品类与游戏管理
品类目录（两级结构）：
- 一级目录：标题 + Icon 上传，支持启用/禁用
- 二级品类：关联一级目录，具体游戏分类
推荐游戏：
- 关联品类目录和具体游戏
- 权重设置控制推荐排序
- 支持增删改操作
邀请码：
- 批量生成邀请码（调用 NFT 服务
batchMintInviteCode） - 关联推荐游戏
- 使用状态追踪
3.8 数字货币配置
管理平台支持的所有加密货币。
配置字段：
- 币种名称、链 ID（chainId）、合约地址（address）、小数位数（decimal）
- Icon 上传和预览
- 本地货币标记（localCurrency）
- 显示开关（display）
全局共享：通过 useModel('currency') 将币种信息共享给所有需要的页面。
3.9 频道查询与白名单
频道查询：
- 多维度查询：频道 ID、频道 Code、用户 ID
- 返回频道详情：名称、Handle、直播间 ID、主播信息
- 跨服务查询：同时调用 Live 服务、User 服务、NFT 服务
白名单：
- 管理频道级别的白名单
- 白名单频道享有特殊权限或功能
四、服务层架构
4.1 API 服务模块分布
4.2 API 接口对接的后端微服务
| 服务路径前缀 | 微服务 | 功能域 |
|---|---|---|
/x/guild/admin/ | 公会服务 | 公会 CRUD、成员管理 |
/x/live/admin/ | 直播服务 | 频道管理、品类管理 |
/x/pay/admin/ | 支付服务 | 充值/提现/结算 |
/x/coin/admin/ | 币种服务 | 货币配置 |
/x/nft/admin/ | NFT 服务 | NFT 铸造、邀请码 |
/x/fire/admin/ | 火力值服务 | Token War、激励 |
/x/recommend/admin/ | 推荐服务 | Banner、推荐管理 |
/x/file/admin/ | 文件服务 | 文件上传 |
/x/user/admin/ | 用户服务 | 用户查询 |
/x/market/admin/ | 市场服务 | Keys 交易、股息 |
4.3 OpenAPI 代码自动生成
后台 API 服务层大量使用 OpenAPI Generator 自动生成：
OpenAPI 代码生成
pnpm openapi # 从 Swagger/OpenAPI 规范自动生成 TypeScript 类型和请求函数
生成特点：
- 请求参数和响应类型自动推导
- 分页参数自动展开处理
- 完整的 TypeScript 类型覆盖
五、开发模式与最佳实践
5.1 页面开发模板
管理后台的页面遵循统一的开发模式：
统一的数据流模式：
useRequest(API, { manual: true }) → 状态更新 → 表格渲染
↑ |
└────── 分页/搜索/筛选变更触发 ──────────────┘
5.2 关键技术模式
| 模式 | 实现 | 用途 |
|---|---|---|
| 异步请求 | useRequest（ahooks） | 统一管理 loading、error 状态 |
| 函数稳定 | useMemoizedFn（ahooks） | 回调函数引用稳定，避免不必要重渲染 |
| 全局状态 | useModel('currency') | 跨页面共享币种信息 |
| 表单管理 | Form.useForm() + Modal | CRUD 操作的统一模式 |
| 文件上传 | Upload + uploadLog1 API | 统一的文件上传路径管理 |
| 事件通信 | EventEmitter | 登录过期等跨组件事件 |
5.3 权限管理
当前为简化权限模型
当前采用 canAdmin = true 的简化模型，所有管理员拥有全部权限。后续如需细粒度权限控制（如角色分级、菜单级权限），需基于 UmiJS 的 access 插件进行扩展。
当前采用简化模型（canAdmin = true），预留了扩展接口：
src/access.ts
export default function access(initialState) {
return { canAdmin: true };
}
页面中使用权限组件
<Access accessible={access.canAdmin}>
<SensitiveComponent />
</Access>
六、技术亮点总结
6.1 企业级管理后台架构
核心架构优势
- UmiJS Max 全家桶：路由、请求、状态、国际化、权限一体化方案，避免了多库整合的配置成本
- Ant Design Pro 布局：Mix 混合布局（侧边栏+顶部），开箱即用的企业级 UI
- mfsu 模块联邦：开发时编译加速，大幅提升 DX，冷启动时间减少 50% 以上
6.2 与公共包的深度集成
- login 包：统一的认证体系，Admin 端与主站共用同一套登录逻辑
- constant 包：共享 API 地址、存储键名等常量
- function 包：复用工具函数（复制到剪贴板、数字格式化等）
6.3 多后端微服务对接
微服务架构
后台对接了 12+ 个后端微服务，通过统一的 API Gateway 路由，服务层按业务域清晰划分，50+ 个接口文件覆盖全业务场景。所有微服务通过统一的请求拦截器处理认证和错误，降低了多服务对接的复杂度。
6.4 OpenAPI 驱动的类型安全
类型安全的 API 层
通过 OpenAPI 代码生成器，所有 API 调用都有完整的 TypeScript 类型支持，从根源上消除了前后端接口不一致的问题：
- 请求参数类型检查
- 响应数据类型推导
- 业务模型自动生成
6.5 运营效率工具
| 功能 | 技术实现 |
|---|---|
| 数字动画 | react-countup，结算金额、账户余额等关键数据的动态展示 |
| 批量操作 | 邀请码批量生成、空投批量发放 |
| 图片上传 | 统一的文件上传服务，按业务路径分类存储 |
| 标签管理 | Banner 标签的动态添加/编辑/删除 |
| 多维排序 | 表格支持多字段排序（时间、金额等） |
6.6 九种语言国际化
zh-CN（简体中文，默认）| zh-TW | en-US | ja-JP | ko-KR | pt-BR | id-ID | bn-BD | fa-IR
七、业务价值总结
管理后台作为平台的"大脑"，承担了：
- MCN/公会运营：完整的公会生命周期管理和财务结算
- 创作者经济：Keys 股息发放、收益分配
- 游戏生态：品类管理、推荐配置、邀请码发放
- 金融合规：充值/提现审核、申诉处理、空投管理
- 活动运营：Token War 活动全生命周期管理
- 内容运营：多位置 Banner 管理、推荐策略配置
八、项目数据概览
| 指标 | 数据 |
|---|---|
| 页面视图文件 | 83 个 TSX |
| API 服务文件 | 50+ |
| 路由菜单 | 13 个一级菜单 |
| 对接微服务 | 12+ 个 |
| 样式模块 | 17 个 |
| 支持语言 | 9 种 |
| 全局 Model | 1 个（currency） |
| 工具函数 | 15+ 个通用工具 |