ok

2026-05-29 17:23:17 +08:00
parent f71a5c59af
commit 1bcb6120dd
139 changed files with 4229 additions and 523 deletions
--- a/plans/拆分风控基础需求_85a83d2b.plan.md
+++ b/plans/拆分风控基础需求_85a83d2b.plan.md
@@ -0,0 +1,184 @@
+---
+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 次集中编辑即可完成。