充值活动

docs/前端交付/README.md

@@ -4,6 +4,7 @@
 
 ## 首充活动提交（2026-11-12）
 
+- [首充活动返回多个－前端修改单](首充活动返回多个-前端修改单.md)：`GET /api/promotion/firstDeposit` 原来只在 `activity` 里返回一个首充活动；新增 `activities` 数组，返回当前平台全部可参加的首充活动，每项带自己的 `first_deposit_offer` 和 `selected`。旧字段 `activity`、`first_deposit_offer` 保留，等于第一个。
 - [首充活动提交－前端修正单](首充活动提交-前端修正单.md)：提示「请刷新首充活动并确认参加」是因为提交「参加」时没带 `first_deposit_offer`。首笔充值到账前可以随时修改；提交「参加」都要带上最近一次接口返回的 `first_deposit_offer`。已参加的会员再提交「参加」不带凭据也会保持原选择。
 
 ## 公司营业报表（2026-11-12）

docs/前端交付/首充活动提交-前端修正单.md

@@ -29,13 +29,11 @@
 ```js
 // 打开充值页 / 活动弹窗时
 const res = await getFirstDeposit({ platform })       // GET /api/promotion/firstDeposit
-this.firstDeposit = res.data
-this.offer = res.data.first_deposit_offer            // 存下来，后面提交「参加」时用
+this.firstDeposit = res.data                         // res.data.activities 里每项都有 first_deposit_offer
 
-// 每次保存选择之后，用返回的数据刷新
-const saved = await saveFirstDepositChoice({ platform, join, first_deposit_offer: this.offer })
-this.firstDeposit = saved.data
-this.offer = saved.data.first_deposit_offer
+// 会员选中某个活动参加：传这一项的凭据
+const saved = await saveFirstDepositChoice({ platform, join: 1, first_deposit_offer: item.first_deposit_offer })
+this.firstDeposit = saved.data                       // 返回结构同上，activities 已经刷新
 ```
 
 ### 2. 提交规则
@@ -44,10 +42,11 @@ this.offer = saved.data.first_deposit_offer
 
 | 场景 | 接口 | 参数 |
 |---|---|---|
-| 勾选「参加」 | `POST /api/promotion/firstDepositChoice` | `platform`、`join=1`、`first_deposit_offer` |
+| 选中某个活动参加 | `POST /api/promotion/firstDepositChoice` | `platform`、`join=1`、所选活动的 `first_deposit_offer` |
+| 改为参加另一个活动 | `POST /api/promotion/firstDepositChoice` | `platform`、`join=1`、另一个活动的 `first_deposit_offer` |
 | 取消，改为「不参加」 | `POST /api/promotion/firstDepositChoice` | `platform`、`join=0` |
-| 不参加后又改回「参加」 | `POST /api/promotion/firstDepositChoice` | `platform`、`join=1`、`first_deposit_offer`（用上一次返回里的值） |
-| 充值下单时一起提交「参加」 | `POST /api/wallet/recharge`、`/api/wallet/createPay`、`/api/wallet/paymentOrder` | `join_first_deposit=1`、`first_deposit_offer` |
+| 不参加后又改回「参加」 | `POST /api/promotion/firstDepositChoice` | `platform`、`join=1`、所选活动的 `first_deposit_offer`（用上一次返回里的值） |
+| 充值下单时一起提交「参加」 | `POST /api/wallet/recharge`、`/api/wallet/createPay`、`/api/wallet/paymentOrder` | `join_first_deposit=1`、所选活动的 `first_deposit_offer` |
 | 充值下单时一起提交「不参加」 | 同上 | `join_first_deposit=0` |
 | 充值下单，不改动之前的选择 | 同上 | 两个参数都不传 |
 

docs/前端交付/首充活动返回多个-前端修改单.md

@@ -0,0 +1,96 @@
+# 首充活动返回多个－前端修改单（2026-11-12）
+
+## 问题
+
+活动页能看到两个首充活动，但充值页的接口 `GET /api/promotion/firstDeposit` 只返回一个：`activity` 是一个对象，后端只放了第一个可参加的活动。
+
+## 修改
+
+`GET /api/promotion/firstDeposit?platform=PC` 新增 **`activities` 数组**，返回当前平台**全部**可参加的首充活动。每个活动带自己的 `first_deposit_offer`（参加时用的凭据）和 `selected`（是否就是会员当前参加的活动）。
+
+```json
+{
+  "has_deposited": false,
+  "can_choose": true,
+  "joined": true,
+  "selection": {"activity_id": 3, "rules": {…}},
+  "activities": [
+    {
+      "activity_id": 5,
+      "title": "首充送60",
+      "image": "https://…/5.png",
+      "min_deposit": "200",
+      "reward_amount": "60",
+      "turnover_ratio": "3",
+      "start_time": 1793289600,
+      "end_time": null,
+      "selected": false,
+      "first_deposit_offer": "5.PC.0c1f…"
+    },
+    {
+      "activity_id": 3,
+      "title": "首充奖励",
+      "image": "https://…/3.png",
+      "min_deposit": "100",
+      "reward_amount": "25",
+      "turnover_ratio": "2",
+      "start_time": 1793289600,
+      "end_time": 1824825599,
+      "selected": true,
+      "first_deposit_offer": "3.PC.5e88…"
+    }
+  ],
+  "first_deposit_offer": "5.PC.0c1f…",
+  "activity": {"activity_id": 5, "title": "首充送60", "min_deposit": "200", "reward_amount": "60", "turnover_ratio": "3", "start_time": 1793289600, "end_time": null},
+  "forbidden_categories": [{"value": "third:2", "label": "电子"}],
+  "notice": "参加首充活动后，活动期间在完成首充奖励打码量前不能投注：电子",
+  "restrictions": []
+}
+```
+
+`activities[]` 字段：
+
+| 字段 | 说明 |
+|---|---|
+| `activity_id` | 首充活动 ID |
+| `title` | 标题，按请求头 `lang` 返回 |
+| `image` | 活动图片 |
+| `min_deposit` | 最低充值金额 |
+| `reward_amount` | 奖励金额 |
+| `turnover_ratio` | 打码倍数 |
+| `start_time` / `end_time` | 秒级时间戳，`null` 表示长期 |
+| `selected` | 是否就是会员当前参加的活动 |
+| `first_deposit_offer` | 这个活动的凭据，会员选这个活动参加时原样提交；已有充值记录时为 `null` |
+
+其他说明：
+- 没有可参加的活动时，`activities` 是空数组，`can_choose=false`。
+- 排序和活动列表一致。
+- 禁止的游戏大类对全部首充活动统一，所以 `forbidden_categories`、`notice` 仍然只有一份，放在外层。
+- **旧字段保留**：`activity`、`first_deposit_offer` 等于 `activities[0]`，前端改完之前不会报错。新页面改用 `activities`，不要再用这两个旧字段。
+
+## PC 和 H5 数量不同是正常的
+
+活动按后台设置的**发布平台**过滤。比如一个活动只勾了 PC，传 `platform=H5` 时就不会返回它，所以会出现 PC 两个、H5 一个。如果 H5 也要显示，在后台把这个活动的发布平台勾上 H5。
+
+## 前端要改的
+
+1. 充值页的首充区域改成按 `activities` 渲染列表，每项显示标题、图片、最低充值、奖励、打码倍数。
+2. 会员只能参加**其中一个**活动（单选），`selected=true` 的那项显示为已参加。
+3. 提交「参加」时，传**所选那一项**的 `first_deposit_offer`：
+
+```json
+POST /api/promotion/firstDepositChoice
+{"platform": "PC", "join": 1, "first_deposit_offer": "3.PC.5e88…"}
+```
+
+充值下单时一起提交也一样：`join_first_deposit=1`，加上所选活动的 `first_deposit_offer`。
+
+4. 想换成另一个活动，直接用另一项的 `first_deposit_offer` 再提交一次；不参加就传 `join=0`。
+5. `firstDepositChoice` 返回的结构和 `firstDeposit` 相同，用返回的数据刷新列表即可，不用再调一次 `firstDeposit`。
+
+## 验收
+
+1. PC 上有两个首充活动时，`activities` 返回两个；H5 只返回发布在 H5 的活动。
+2. 选第二个活动参加，返回里这一项 `selected=true`，`selection.activity_id` 是它的 ID。
+3. 改选第一个活动，`selected` 跟着变。
+4. 首笔充值到账后，`can_choose=false`，每项的 `first_deposit_offer` 为 `null`。

docs/前端接口/独立活动/首充活动参加与禁止游戏-会员接入.md

@@ -6,7 +6,7 @@
 
 ## 1. 充值页读取首充状态
 
-`GET /api/promotion/firstDeposit?platform=H5`
+`GET /api/promotion/firstDeposit?platform=PC`
 
 `platform` 必填，取 `PC/H5/APP`。
 
@@ -18,8 +18,9 @@
 | `can_choose` | 是否显示“参加首充活动”选项：没有充值记录且当前有可参加的首充活动时为 `true` |
 | `joined` | 当前保存的选择，默认 `false`（不参加） |
 | `selection` | 已确认的选择 `{activity_id, rules}`，未确认时为 `null`。用 `rules` 展示已经确认的充值门槛、奖励、打码倍数和禁投大类 |
-| `first_deposit_offer` | 本页展示的活动凭据。会员确认参加时原样回传，无可参加活动时为 `null` |
-| `activity` | 当前首充活动，无可参加活动时为 `null`。字段：`activity_id/title/min_deposit/reward_amount/turnover_ratio/start_time/end_time`，时间为秒级时间戳，`null` 表示长期 |
+| `activities` | **当前平台全部可参加的首充活动**（数组，可能有多个），会员选其中一个参加，见下表；没有可参加的活动时为空数组 |
+| `first_deposit_offer` | 旧字段，等于 `activities[0].first_deposit_offer`。新前端用 `activities` 里每项自己的凭据 |
+| `activity` | 旧字段，等于 `activities[0]`（不含 `image`、`selected`、`first_deposit_offer`），没有时为 `null`。新前端用 `activities` |
 | `forbidden_categories` | 参加后活动期间禁止投注的游戏大类，数组 `[{value,label}]`，`label` 按请求头语言返回；没有限制时为空数组 |
 | `notice` | 按请求头语言返回的限制提示文字，没有限制时为空字符串 |
 | `restrictions` | 已领到首充奖励、当前仍在限制中的记录，见下表；不在限制中为空数组 |
@@ -35,6 +36,20 @@
 | `completed_flow` | 已完成打码量 |
 | `remaining_flow` | 剩余打码量 |
 
+`activities[]`：
+
+| 字段 | 说明 |
+|---|---|
+| `activity_id` | 首充活动 ID |
+| `title` | 标题，按请求头语言 |
+| `image` | 活动图片 |
+| `min_deposit` / `reward_amount` / `turnover_ratio` | 最低充值、奖励金额、打码倍数 |
+| `start_time` / `end_time` | 秒级时间戳，`null` 表示长期 |
+| `selected` | 是否就是会员当前参加的活动 |
+| `first_deposit_offer` | 这个活动的凭据，会员选这个活动参加时原样回传；已有充值记录时为 `null` |
+
+活动按发布平台过滤（`platform` 传 PC 和 H5 结果可能不同），排序和活动列表一致。禁止的游戏大类是全部首充活动统一的设置，所以 `forbidden_categories`、`notice` 只有一份。
+
 以上金额为字符串：整数不带小数，小数保留两位。
 
 示例：
@@ -45,8 +60,12 @@
   "can_choose": true,
   "joined": false,
   "selection": null,
-  "first_deposit_offer": "3.H5.5e884898da28047151d0e56f8dc62927",
-  "activity": {"activity_id": 3, "title": "首充奖励", "min_deposit": "100", "reward_amount": "25", "turnover_ratio": "2", "start_time": 1793289600, "end_time": 1824825599},
+  "activities": [
+    {"activity_id": 5, "title": "首充送60", "image": "https://…/5.png", "min_deposit": "200", "reward_amount": "60", "turnover_ratio": "3", "start_time": 1793289600, "end_time": null, "selected": false, "first_deposit_offer": "5.PC.0c1f…"},
+    {"activity_id": 3, "title": "首充奖励", "image": "https://…/3.png", "min_deposit": "100", "reward_amount": "25", "turnover_ratio": "2", "start_time": 1793289600, "end_time": 1824825599, "selected": false, "first_deposit_offer": "3.PC.5e88…"}
+  ],
+  "first_deposit_offer": "5.PC.0c1f…",
+  "activity": {"activity_id": 5, "title": "首充送60", "min_deposit": "200", "reward_amount": "60", "turnover_ratio": "3", "start_time": 1793289600, "end_time": null},
   "forbidden_categories": [{"value": "third:2", "label": "电子"}, {"value": "self:lottery", "label": "F1彩票"}],
   "notice": "参加首充活动后，活动期间在完成首充奖励打码量前不能投注：电子、F1彩票",
   "restrictions": []
@@ -82,7 +101,7 @@
 
 | 取值 | 含义 |
 |---|---|
-| `1` | 确认参加，同时传 `first_deposit_offer` |
+| `1` | 确认参加，同时传所选活动的 `first_deposit_offer` |
 | `0` | 不参加 |
 | 不传 | 不改动之前保存的选择 |
 
@@ -107,7 +126,7 @@
 |---|---|
 | `platform` | `PC/H5/APP` |
 | `join` | `1` 参加，`0` 不参加 |
-| `first_deposit_offer` | `join=1` 时必传，从同一 `platform` 的首充状态接口取值 |
+| `first_deposit_offer` | `join=1` 时必传，传会员所选活动在 `activities[]` 里的凭据（同一 `platform`） |
 
 成功返回与 `GET /api/promotion/firstDeposit` 相同的结构。已有充值记录时返回失败，`msg` 为 `已有充值记录，不能再选择首充活动`。