主 题
博客系统自文档 · 第 10/16 篇
目录 · 上一篇：RPG 玩法全览 · 下一篇：事件驱动与模块解耦
写在前面
第 9 篇讲了 RPG 玩什么；本篇讲 怎么搭：模块目录、实时推送、充值、异步经验三条线。
功能与体验（技术视角）
| 用户动作 | 同步反馈 | 异步处理 |
|---|---|---|
| 签到升级 | /realtime 弹窗 Toast |
写 DB、成就判定 |
| 评论得经验 | 可选 WS expGain |
Stream 消费者加 EXP |
| 发文 | — | ARTICLE_PUBLISHED → 经验 |
| 钻石充值到账 | WS rechargeComplete 关弹窗 |
pay 履约 → adjustCurrency |
客户端：use-rpg-realtime-handlers.ts 把 WS 事件映射为 Toast / 全屏动画 / 充值弹窗关闭（Nuxt 与 uni-app 各有一份）。
设计与实现
模块目录（按领域）
rpg/
├── core/ rpg.service, rpg-notify.service, punishment, rpg.controller
├── level/ sign, article-level
├── social/ tip, social-interact, reputation
├── lottery/ lottery
├── recharge/ recharge.service ← C 端钻石充值
├── listeners/ rpg-event.consumer ← 消费 blog:events
└── entity/ 17+ 表单一 RpgModule 注册全部 provider，API 前缀 /rpg/*。
充值链路
sequenceDiagram
participant Home as Nuxt / uni-app
participant RPG as RechargeService
participant Pay as pay 模块
participant GW as RealtimeGateway
Home->>RPG: POST /rpg/recharge/create
RPG->>Pay: 创建支付宝订单
Pay-->>Home: 动态二维码 URL
Note over Home: 用户扫码支付
Pay->>RPG: 履约 / Admin 手工 mark-recharge-fulfilled
RPG->>RPG: adjustCurrency + 更新意向单
RPG->>GW: rechargeComplete
GW->>Home: 关 RpgRechargeDynamicModal
| 端点 | 说明 |
|---|---|
POST /rpg/recharge/create |
创建充值意向 + 支付单 |
GET /rpg/recharge/status |
轮询兜底 |
POST /pay/order/mark-recharge-fulfilled |
Admin 手工补钻后发 WS |
Home 组件：RpgRechargeDynamicModal.vue + use-rpg-recharge.ts。
实时推送链
flowchart LR
Biz[RPG Service]
Notify[RpgNotifyService enrich/防抖]
GW[RealtimeGateway /realtime]
Client[use-rpg-realtime-handlers]
Biz --> Notify --> GW --> Client
- 网关统一在
core/realtime，不是独立/rpgnamespace - 事件名见
ws-events.ts：levelUp、expGain、achievementComplete、rechargeComplete、rankChange、weatherBuff等 - Nginx：
/socket.io/→ :5000
异步：Redis Stream
Comment/Like/Article → BlogEventPublisher → blog:events
→ rpg-event.consumer → 加经验/成就/任务进度解耦原因：评论接口快速返回，RPG 计算与 DB 写入在 consumer 里重试、聚合。充值到账不走 Stream，直接 WS 同步 UI。
物品配置单一数据源
rpg_item_config + 启动种子 COSMETIC_ITEM_SEEDS；C 端展示字段 API 下发，Home 不硬编码物品 map。
Home composables 速查
| 文件 | 职责 |
|---|---|
use-rpg.ts |
RPG 状态、五 Tab 数据加载 |
use-rpg-recharge.ts |
充值下单、轮询、WS 监听 |
use-rpg-audio.ts |
BGM + 短音效 |
use-rpg-realtime-handlers.ts |
WS → UI 反馈 |
use-realtime-socket.ts |
Socket.IO 连接 |
踩坑与取舍
- RpgNotifyService 防抖：连续 exp 合并推送，避免 WS 风暴。
- BanGuard：禁言用户不可签到（
POST /rpg/sign）；评论/留言/回复亦受 BanGuard 拦截，与banStatusWS 联动。 - PM2 多实例：Socket.IO 靠 Redis Adapter 同步 room。
- 排行榜 Top50 用户主页进 sitemap：
server/api/__sitemap__/urls.ts拉/rpg/leaderboard生成/user/{uid}。
系列导航
- 目录：博客系统分类
- 上一篇：09 RPG 玩法全览
- 下一篇：11 事件驱动与模块解耦
- 导读：导读 · 第 0 篇
延伸阅读
RPG-TECH.md、table.mdrpg/recharge/recharge.service.tscore/realtime/README.md
全部评论(0)