cursor/plans/拆分风控基础需求_85a83d2b.plan.md

name, overview, todos, isProject

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

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

背景

主文档 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，需新建子目录承载拆分结果。

目标目录结构

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

迁入内容：

• §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

迁入内容：

• §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

迁入内容：

• §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

迁入内容：

• §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

简短索引 + 依赖图：

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 调整

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 次集中编辑即可完成。