ok
This commit is contained in:
ray zhou
127
plans/注册活动列表_game_id_2136b4fb.plan.md
Normal file
127
plans/注册活动列表_game_id_2136b4fb.plan.md
Normal file
@@ -0,0 +1,127 @@
|
||||
---
|
||||
name: 注册活动列表 game_id
|
||||
overview: 在 C 端活动列表（type=7 注册活动）透出 `game_id` 供前端展示/进游戏；同时从领取接口 `POST /api/gift/receive` 移除 `game_id` 字段，复用现有 `RegisterRewardLogic` 与 `ext_config.game_ids` 配置。
|
||||
todos:
|
||||
- id: list-game-id
|
||||
content: ActivityConfigEntity::getGiftItemsByActivity type=7 分支调用 RegisterRewardLogic 写入 game_id
|
||||
status: completed
|
||||
- id: remove-receive-game-id
|
||||
content: ActivityConfigEntity::receive 移除注册活动 game_id 逻辑
|
||||
status: completed
|
||||
- id: logic-stable-pick
|
||||
content: RegisterRewardLogic 增加 pickGameIdForUser（稳定随机）并更新注释
|
||||
status: completed
|
||||
- id: phpdoc-tests
|
||||
content: GiftController PHPDoc 调整 + RegisterRewardLogicTest 补充用例
|
||||
status: completed
|
||||
isProject: false
|
||||
---
|
||||
|
||||
# 注册活动列表透出 game_id，领取不再返回
|
||||
|
||||
## 需求变更（相对初版）
|
||||
|
||||
| 接口 | 原行为 | 目标行为 |
|
||||
|------|--------|----------|
|
||||
| `POST /api/gift/getActivityList` | 注册活动无 `game_id` | type=7 项增加可选 `game_id` |
|
||||
| `POST /api/gift/receive`（type=7） | 成功时随机返回 `game_id` | **仅** `gift_coin`、`gift_bonus` |
|
||||
|
||||
后台 `ext_config.game_ids` 配置与 [`RegisterRewardLogic`](slot_console/app/api/logic/RegisterRewardLogic.php) 过滤已上架游戏逻辑**保持不变**，仅调整调用位置。
|
||||
|
||||
## 数据流
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
Client->>GiftController: getActivityList
|
||||
GiftController->>GiftService: getUserActivityList
|
||||
GiftService->>ActivityConfigEntity: getGiftItemsByActivity type=7
|
||||
ActivityConfigEntity->>RegisterRewardLogic: pickGameId from ext_config.game_ids
|
||||
ActivityConfigEntity-->>Client: activity item with optional game_id
|
||||
|
||||
Client->>GiftController: receive id=activityId
|
||||
GiftController->>ActivityConfigEntity: receive ACTIVITY_TYPE_REG
|
||||
ActivityConfigEntity-->>Client: gift_coin, gift_bonus only
|
||||
```
|
||||
|
||||
## 实现（仅 slot_console）
|
||||
|
||||
### 1. 活动列表组装：增加 `game_id`
|
||||
|
||||
文件：[`slot_console/app/entity/activity/ActivityConfigEntity.php`](slot_console/app/entity/activity/ActivityConfigEntity.php)
|
||||
|
||||
在 `getGiftItemsByActivity()` 的 `switch ($activityType)` 中新增 `ACTIVITY_TYPE_REG` 分支（与首充/兑换码同级，约在 340 行附近）：
|
||||
|
||||
- 用已有 `normalizeExtConfig($activity['ext_config'])` 读取 `game_ids`
|
||||
- 调用 `RegisterRewardLogic` 得到 `game_id`
|
||||
- 仅当非 `null` 时写入 `$activityInfo['game_id']`（与领取侧旧约定一致：**省略字段**而非 `0`）
|
||||
|
||||
`$activity` 来自 `getActiveList()` 的 DB 模型，已含 `ext_config`；`ActivityConfigEntity` 在 `GiftService::getUserActivityList()` 中已通过 `setUid` / `setSource` 设置 `_modelId`。
|
||||
|
||||
**列表随机策略（建议默认）**：同一用户、同一活动多次拉列表应看到同一款游戏，避免卡片闪烁。在 `RegisterRewardLogic` 增加例如 `pickGameIdForUser(?array $extConfig, int $gameModelId, int $uid, int $activityId): ?int`：
|
||||
|
||||
- 复用 `parseGameIds` + `GameApiModel::publishedGameIds`
|
||||
- 对 `published` **排序**后，用 `crc32("{$uid}:{$activityId}") % count` 取下标（非 `array_rand`）
|
||||
|
||||
列表与领取不再需要对齐，但稳定随机对仅列表展示更友好。若产品希望每次刷新换游戏，可继续用现有 `pickRandomGameId`。
|
||||
|
||||
### 2. 领取分支：移除 `game_id`
|
||||
|
||||
同一文件 `receive()`：
|
||||
|
||||
- 删除 `ACTIVITY_TYPE_REG` 内读取 `ext_config`、`RegisterRewardLogic::pickRandomGameId` 及 `$registerRewardGameId` 变量
|
||||
- 删除返回数组末尾对 `game_id` 的合并（约 763–765 行）
|
||||
|
||||
注册发奖、`sendRegisterGiftWagerTask`、`setActivityFinishById` **不动**。
|
||||
|
||||
### 3. Controller PHPDoc
|
||||
|
||||
[`GiftController.php`](slot_console/app/api/controller/GiftController.php)：
|
||||
|
||||
- `receive()`：去掉 `game_id` 说明，仅 `gift_coin` / `gift_bonus`
|
||||
- 可选：为 `getActivityList()` 补充一行说明——type=7 且配置了有效 `game_ids` 时，对应项含 `game_id`（int）
|
||||
|
||||
### 4. Logic 注释与单测
|
||||
|
||||
[`RegisterRewardLogic.php`](slot_console/app/api/logic/RegisterRewardLogic.php)：类注释改为「活动列表推荐进游戏」；保留 `pickRandomGameId` 或改为对外暴露 `pickGameIdForUser`（二选一，避免死代码）。
|
||||
|
||||
[`RegisterRewardLogicTest.php`](slot_console/tests/Unit/RegisterRewardLogicTest.php)：为 `pickGameIdForUser` 增加确定性用例（相同 uid+activityId 同结果；无候选返回 null）。
|
||||
|
||||
## 响应示例
|
||||
|
||||
**活动列表**（type=7 片段）：
|
||||
|
||||
```json
|
||||
{
|
||||
"gift_id": 123,
|
||||
"type": 7,
|
||||
"title": "注册奖励",
|
||||
"gift_coin": "10.00",
|
||||
"gift_bonus": "0.00",
|
||||
"game_id": 205,
|
||||
"data": [{ "goods_id": -1, "gift_coin": "10.00", ... }]
|
||||
}
|
||||
```
|
||||
|
||||
无有效 `game_ids` / 无上架游戏：与现网其它活动项一致，**无 `game_id` 字段**。
|
||||
|
||||
**领取**：
|
||||
|
||||
```json
|
||||
{
|
||||
"gift_coin": "10.00",
|
||||
"gift_bonus": "0.00"
|
||||
}
|
||||
```
|
||||
|
||||
## 验证
|
||||
|
||||
1. 后台 type=7 活动配置 `ext_config.game_ids`（已有 admin 能力）。
|
||||
2. `getActivityList`：未领取用户可见注册活动且含 `game_id`（在候选有效时）。
|
||||
3. `receive`：成功响应**不含** `game_id`。
|
||||
4. `game_ids` 为空或均未上架：列表无 `game_id`，领取正常。
|
||||
5. Docker 内跑单测：`RegisterRewardLogicTest.php`。
|
||||
|
||||
## 不涉及
|
||||
|
||||
- slot_admin / admin_vue（配置已具备）
|
||||
- 前端仓库（由 C 端自行改列表消费、去掉领取后对 `game_id` 的依赖）
|
||||
Reference in New Issue
Block a user