hy/hyapp-server

Fork 0

zhx 9001fce4b7 Configure room rocket launch messaging

2026-06-05 19:56:13 +08:00

11 KiB

Raw Permalink Blame History

幸运礼物 Flutter 对接

本文只保留 App 对接需要的信息：地址、参数、返回值、IM 字段。服务端实现细节看幸运礼物实现文档，礼物面板通用字段看礼物 Tab Flutter 对接。

1. 送礼前检查

地址：

POST /api/v1/activities/lucky-gifts/check
Authorization: Bearer <access_token>
X-App-Code: lalu
Content-Type: application/json

请求参数：

字段	类型	必填	说明
`room_id`	string	是	当前房间 ID。
`gift_id`	string	是	礼物 ID。
`pool_id`	string	是	幸运礼物奖池 ID，例如 `lucky`、`super_lucky` 或后台配置值。

请求示例：

{
  "room_id": "lalu_room_001",
  "gift_id": "rose",
  "pool_id": "super_lucky"
}

返回值：

字段	类型	说明
`enabled`	bool	是否可参与幸运礼物抽奖。
`reason`	string	不可参与原因；可为空。
`room_id`	string	房间 ID。
`gift_id`	string	礼物 ID。
`pool_id`	string	奖池 ID。
`gift_price`	int64	当前规则参考礼物价格，只展示用，扣费以后端送礼结果为准。
`rule_version`	int64	命中的幸运礼物规则版本。
`target_rtp_ppm`	int64	目标 RTP，ppm 口径；`950000` 表示 95%。
`experience_pool`	string	当前用户体验池，例如 `novice`、`normal`、`advanced`。

返回示例：

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "enabled": true,
    "reason": "",
    "room_id": "lalu_room_001",
    "gift_id": "rose",
    "pool_id": "super_lucky",
    "gift_price": 100,
    "rule_version": 12,
    "target_rtp_ppm": 950000,
    "experience_pool": "novice"
  }
}

2. 发送幸运礼物

地址：

POST /api/v1/rooms/gift/send
Authorization: Bearer <access_token>
X-App-Code: lalu
Content-Type: application/json

请求参数：

字段	类型	必填	说明
`room_id`	string	是	当前房间 ID。
`command_id`	string	是	本次送礼幂等键；同一次重试必须复用。
`target_type`	string	否	当前固定传 `user`；为空后端按 `user`。
`target_user_ids`	int64[]	是	收礼用户列表；当前只传 1 个用户。
`target_user_id`	int64	否	旧单目标兼容字段，新代码优先用 `target_user_ids`。
`gift_id`	string	是	礼物 ID。
`gift_count`	int32	是	礼物数量，必须大于 0；批量送礼会聚合返回一次中奖结果。
`pool_id`	string	是	幸运礼物奖池 ID；普通礼物不传。

请求示例：

{
  "room_id": "lalu_room_001",
  "command_id": "gift_1779259000000_10001_rose_01",
  "target_type": "user",
  "target_user_ids": [10002],
  "gift_id": "rose",
  "gift_count": 9,
  "pool_id": "super_lucky"
}

返回值：

字段	类型	说明
`result.applied`	bool	本次命令是否实际落地；重复提交同一 `command_id` 可能为 `false`。
`result.room_version`	int64	房间版本。
`result.server_time_ms`	int64	服务端时间。
`billing_receipt_id`	string	送礼扣费回执。
`room_heat`	int64	送礼后的房间热度。
`gift_rank`	array	当前房间礼物榜。
`room`	object	房间快照。
`rocket`	object	房间火箭状态。
`lucky_gift`	object	幸运礼物抽奖结果；普通礼物可为空。

lucky_gift 返回字段：

字段	类型	说明
`enabled`	bool	本次是否触发幸运礼物。
`draw_id`	string	聚合抽奖 ID。
`command_id`	string	本次送礼命令 ID。
`pool_id`	string	奖池 ID。
`gift_id`	string	礼物 ID。
`rule_version`	int64	规则版本。
`experience_pool`	string	用户体验池。
`selected_tier_id`	string	命中奖档 ID。
`multiplier_ppm`	int64	倍率 ppm；`2000000` 表示 2x。
`base_reward_coins`	int64	基础奖池返奖金币。
`room_atmosphere_reward_coins`	int64	房间气氛池返奖金币。
`activity_subsidy_coins`	int64	活动补贴返奖金币。
`effective_reward_coins`	int64	实际中奖金币；0 表示未中奖。
`reward_status`	string	`granted` 已入账；`pending`/`granting` 到账处理中；`failed` 需要人工处理。
`stage_feedback`	bool	是否有阶段反馈表现。
`high_multiplier`	bool	是否高倍率中奖。
`created_at_ms`	int64	抽奖创建时间。
`wallet_transaction_id`	string	返奖钱包交易 ID；已入账时有值。
`coin_balance_after`	int64	返奖入账后的 COIN 可用余额。

返回示例：

{
  "code": "OK",
  "message": "ok",
  "request_id": "req_abc",
  "data": {
    "result": {
      "applied": true,
      "room_version": 14,
      "server_time_ms": 1779259000000
    },
    "billing_receipt_id": "receipt-lucky",
    "room_heat": 123456,
    "gift_rank": [],
    "room": {},
    "rocket": {},
    "lucky_gift": {
      "enabled": true,
      "draw_id": "lucky_draw_test",
      "command_id": "gift_1779259000000_10001_rose_01",
      "pool_id": "super_lucky",
      "gift_id": "rose",
      "rule_version": 12,
      "experience_pool": "novice",
      "selected_tier_id": "novice_2x",
      "multiplier_ppm": 2000000,
      "base_reward_coins": 1800,
      "room_atmosphere_reward_coins": 0,
      "activity_subsidy_coins": 0,
      "effective_reward_coins": 1800,
      "reward_status": "granted",
      "stage_feedback": false,
      "high_multiplier": false,
      "created_at_ms": 1779259000000,
      "wallet_transaction_id": "wallet_tx_lucky",
      "coin_balance_after": 8800
    }
  }
}

客户端处理：

reward_status=granted 且 effective_reward_coins > 0：立即展示中奖，并用 coin_balance_after 覆盖本地金币余额。
reward_status=pending 或 granting：展示“到账处理中”，不要本地加金币，不要生成新 command_id 重发。
effective_reward_coins=0：未中奖，只展示普通送礼表现。
同一用户同一房间连续发送幸运礼物时，客户端需要本地排队；重试必须复用原 command_id。

3. IM 字段

3.1 送礼房间 IM

用途：房间内播放普通送礼动效、同步热度和礼物榜。幸运礼物也会先产生这条送礼 IM。

字段	值
`MsgContent.Desc`	`room_gift_sent`
`Data.event_type`	`room_gift_sent`

Data 核心字段：

字段	类型	说明
`event_id`	string	房间事件 ID，用于去重。
`room_id`	string	房间 ID。
`room_version`	int64	房间版本。
`occurred_at_ms`	int64	事件发生时间。
`actor_user_id`	string/int64	送礼用户 ID。
`target_user_id`	string/int64	收礼用户 ID。
`gift_value`	int64	本次送礼房间价值/热度口径。
`room_heat`	int64	送礼后的房间热度。
`attributes.gift_id`	string	礼物 ID。
`attributes.pool_id`	string	幸运礼物奖池 ID；普通礼物可为空。
`attributes.gift_count`	string	礼物数量，字符串格式。
`attributes.billing_receipt_id`	string	钱包扣费回执。
`attributes.coin_spent`	string	本次实际消耗金币，字符串格式。
`attributes.gift_point_added`	string	主播礼物积分增量，字符串格式。
`attributes.price_version`	string	价格版本。

示例：

{
  "event_type": "room_gift_sent",
  "event_id": "room_event_xxx",
  "room_id": "lalu_room_001",
  "room_version": 14,
  "occurred_at_ms": 1779259000000,
  "actor_user_id": "10001",
  "target_user_id": "10002",
  "gift_value": 900,
  "room_heat": 123456,
  "attributes": {
    "gift_id": "rose",
    "pool_id": "super_lucky",
    "gift_count": "9",
    "billing_receipt_id": "receipt-lucky",
    "coin_spent": "900",
    "gift_point_added": "900",
    "price_version": "v1"
  }
}

3.2 幸运礼物开奖 IM

用途：房间公屏展示幸运礼物中奖结果、其他用户同步中奖表现。当前用户自己的余额以 HTTP 返回的 coin_balance_after 为准，不等这条 IM。

字段	值
`MsgContent.Desc`	`lucky_gift_drawn`
`Data.event_type`	`lucky_gift_drawn`