---
name: 拆分风控基础需求
overview: 将 [game_gateway_risk_prd_v_2.md](docs/requirements/game_gateway_risk_prd_v_2.md) 中 3.1 第 1–4 项拆成 4 份可独立评审/开发的子需求文档，放在 `docs/requirements/game_gateway/` 下，并精简主文档为索引 + 交叉引用。
todos:
  - id: create-subdir-readme
    content: 新建 docs/requirements/game_gateway/ 与 README.md（索引 + 依赖图 + 实施顺序）
    status: completed
  - id: doc-01-launch
    content: 编写 01_launch_session.md：迁移 §4.1/4.2、§8.1、3.1-12、相关验收
    status: completed
  - id: doc-02-callback
    content: 编写 02_provider_callback_log.md：迁移 §8.2、§5.1 相关行、callback 主链路步骤、§15.4-1
    status: completed
  - id: doc-03-tx
    content: 编写 03_provider_tx.md：迁移 §8.4、§7.2、§10、tx 流程片段、§15.1
    status: completed
  - id: doc-04-round
    content: 编写 04_game_round.md：迁移 §2.3、§4.4.1、§7.1、§8.3、round 流程、§15.2
    status: completed
  - id: slim-master-prd
    content: 精简 game_gateway_risk_prd_v_2.md：§3.1 改链接、删重复 DDL/章节、更新 §14/§15/§16
    status: completed
isProject: false
---

# 拆分 Game Gateway 风控 PRD（3.1 项 1–4）

## 背景

主文档 [`docs/requirements/game_gateway_risk_prd_v_2.md`](docs/requirements/game_gateway_risk_prd_v_2.md) 第 3.1 节「第一期必须实现」前 4 项为**基础数据与链路能力**，彼此有依赖但可分期交付：

| 3.1 序号 | 能力 | 核心表 | 主文档现有章节 |
|---------|------|--------|----------------|
| 1 | 游戏启动 Session 记录 | `game_launch_session` | 4.1、4.2、8.1；3.1-12 |
| 2 | Provider 原始回调日志 | `game_provider_callback_log_01` | 5.1（原始回调落库）、8.2 |
| 3 | Provider Tx 幂等交易表 | `game_provider_tx_01` | 4.3/4.4（tx 部分）、7.2、8.4、10、15.1 |
| 4 | Round 聚合状态表 | `game_round_01` | 2.3、4.3/4.4（round 部分）、4.4.1、7.1、8.3、15.2 |

当前 `docs/requirements/` 仅有这一份 PRD，需新建子目录承载拆分结果。

## 目标目录结构

```text
docs/requirements/
├── game_gateway_risk_prd_v_2.md          # 总览 PRD（保留全局原则、5–16 章）
└── game_gateway/
    ├── README.md                         # 子需求索引与依赖关系
    ├── 01_launch_session.md
    ├── 02_provider_callback_log.md
    ├── 03_provider_tx.md
    └── 04_game_round.md
```

命名约定：`{序号}_{英文表名/能力}.md`，便于与建表、代码模块对齐。

## 子文档统一模板（每份独立可交付）

每份子需求包含以下固定章节（从主文档**迁移**而非重写业务含义）：

1. **文档信息**：标题、版本、父文档链接、依赖子文档
2. **目标与范围**：对应 3.1 单项 + In/Out of scope
3. **依赖与边界**：slot-pwa / wallet / risk 职责（摘录主文档 §2 相关原则）
4. **业务流程**：该能力专属流程图/步骤
5. **状态定义**：仅该表相关状态（如 Round §7.1、Provider Tx §7.2）
6. **数据表设计**：完整 DDL + 字段说明 + 索引/幂等约束
7. **与主链路衔接**：在 BET/WIN 中的写入时机（引用主文档 §4，不重复全文）
8. **验收标准**：从 §15 拆出与本能力相关的条目
9. **第一期 Out of scope**：明确不属于本子需求的表/能力（交叉引用主文档 §3.2）

## 各子文档内容映射

### [`01_launch_session.md`](docs/requirements/game_gateway/01_launch_session.md)

**迁入内容：**

- §4.1 游戏启动 Launch 流程（含 `game_gateway_control` / `game_user_risk_profile_01` 检查表）
- §4.2 用户退出流程 + 过期 SQL
- §8.1 `game_launch_session` 完整 DDL
- 3.1 第 12 条：退出只关 Session、不触发资金结算
- 验收：§15.2 第 4 条（退出不触发 Round Final）

**接口提示（文档级，非实现）：**

- Launch 创建 Session、`POST /slot-game/session/close`
- Redis 短窗口防重复 Launch（`uid + provider_code + game_code + 5~10s`）

**依赖说明：** 不依赖 callback_log / provider_tx / round；可被后续回调通过 `session_id` 关联（若主链路需要，在子文档中写「可选关联字段」占位，不扩表）。

---

### [`02_provider_callback_log.md`](docs/requirements/game_gateway/02_provider_callback_log.md)

**迁入内容：**

- §8.2 `game_provider_callback_log_01` 完整 DDL + 「不加唯一键、幂等由 provider_tx 负责」说明
- §5.1 表中「原始回调落库」「验签 / IP 校验」「参数解析」三行及原因
- 主链路第一步：`Provider * callback → 同步写 callback_log`（从 §4.3、§4.4 摘取，各类型回调通用）
- BALANCE 只记 callback_log、不进 provider_tx（§8.4 说明）
- 验收：§15.4 第 1 条（资金交易可追溯到原始回调）

**依赖：** 被 `03_provider_tx` 通过 `callback_log_id` 引用。

---

### [`03_provider_tx.md`](docs/requirements/game_gateway/03_provider_tx.md)

**迁入内容：**

- §8.4 `game_provider_tx_01` 完整 DDL + 幂等键 `provider_code + provider_tx_id + tx_type`
- §7.2 Provider Tx 状态
- §4.3 / §4.4 中与 `game_provider_tx_01` 相关的步骤（创建/查询、状态更新、BET 成功后 status）
- §10 wallet 超时与补偿（全文；与 tx 强绑定）
- §3.2 不建 `game_wallet_call_log_01` 的原因（wallet 结果记在 provider_tx）
- 验收：§15.1 全部 + §15.4 第 2 条

**依赖：** 必须先有 `02`（`callback_log_id`）；与 `04` 并行更新 round。

---

### [`04_game_round.md`](docs/requirements/game_gateway/04_game_round.md)

**迁入内容：**

- §2.3 Round Final 才能做最终任务结算（原则）
- §4.4.1 Round 结算模式（`AGGREGATE_FINAL` / `TX_REALTIME_FINALIZE` + wallet 调用类型）
- §7.1 Round 状态
- §8.3 `game_round_01` 完整 DDL
- §4.3 BET 成功后 round 字段更新；§4.4 WIN/FINAL 后 round 更新（摘取）
- §9 中 `game_round_final_settled_event` 事件说明（仅 round final 相关段落）
- 验收：§15.2 全部

**依赖：** 与 `03` 在回调主链路中协同；不重复写 wallet 补偿细节（链接 `03`）。

---

### [`README.md`](docs/requirements/game_gateway/README.md)

简短索引 + 依赖图：

```mermaid
flowchart LR
  launch[01_launch_session]
  callback[02_provider_callback_log]
  tx[03_provider_tx]
  round[04_game_round]
  callback --> tx
  tx --> round
  launch -.->|Launch准入| callback
```

建议实施顺序：`02 → 03 → 04` 可同迭代；`01` 可与 `02` 并行。

## 主文档 [`game_gateway_risk_prd_v_2.md`](docs/requirements/game_gateway_risk_prd_v_2.md) 调整

1. **§3.1 第 1–4 条**改为链接列表，例如：
   - `1. [游戏启动 Session](game_gateway/01_launch_session.md)`
   - …
2. **删除或收缩**已迁入子文档的重复正文：
   - §4.1、§4.2 → 保留 1 段摘要 + 链接
   - §8.1–§8.4 → 改为表名清单 + 链接（DDL 只在子文档保留一份）
   - §7.1、§7.2 → 移至子文档；主文档 §7 仅保留 §7.3 熔断状态（属 3.1-5）
   - §10 → 移至 `03`；主文档保留一句「见 provider_tx 子需求」
   - §15.1、§15.2 部分条目 → 子文档各持一份；主文档 §15 保留汇总 checklist 并链接子文档
3. **§4.3、§4.4** 保留端到端主链路（便于理解全局），但表字段/SQL/状态机细节改为「详见子需求」引用，避免双份维护。
4. **§14 建表清单**：前 4 张表标注对应子文档路径。
5. **§16 总结**：保留一句话架构；补充子需求目录说明。

**不拆分范围（仍留主文档）：** 3.1 第 5–12 项及 §8.5 以后、§11–§13、熔断/RTP/风险画像/MQ 等。

## 交叉引用规范

- 子文档文首：`> 父文档：[Game Gateway 游戏风控需求 V1.0](../game_gateway_risk_prd_v_2.md)`
- 主文档与子文档互相使用相对路径 Markdown 链接
- 涉及 wallet/risk 的段落写「行为以父文档 §2 为准」，不在 4 份子文档重复整章原则

## 质量检查

- 4 份子文档均含完整 DDL，与当前主文档 §8 SQL **逐字一致**（仅拆位置，不改语义）
- 主文档通读无断链；§3.1 1–4 在子文档有对应验收标准
- `README.md` 列出推荐开发顺序与表依赖

## 工作量说明

纯文档重构，不涉及代码与迁移脚本；预计 4 份子文档 + 1 索引 + 主文档瘦身，约 1 次集中编辑即可完成。