refactor: 收口 runtime client 请求骨架

docs/technical/【前端架构】RuntimeClientFamily收口计划-2026-06-03.md

@@ -0,0 +1,32 @@
+# 【前端架构】Runtime Client Family 收口计划
+
+## 背景
+
+多个小游戏 runtime client 都重复实现路径编码、JSON header / body、runtime guest token、认证影响策略和重试参数。重复逻辑分散在各玩法文件后，新增玩法容易遗漏 guest auth 或 retry 语义，也让测试必须逐玩法检查同一请求骨架。
+
+## 决策
+
+新增 `src/services/runtimeRequest.ts`，作为 Runtime Client Family 的请求 **Module**。其 **Interface** 包含：
+
+- `buildRuntimeApiPath(basePath, ...segments)`：统一对 runtime path segment 执行 `encodeURIComponent`。
+- `requestRuntimeJson(params)`：统一设置 method、JSON body、`Content-Type`、runtime guest `Authorization`、auth options 和 retry options。
+
+`match3dRuntimeClient.ts` 与 `squareHoleRuntimeClient.ts` 已迁入此 **Module**，并保留原有导出函数名、错误文案、返回契约和重试常量。点击 / 投入等玩法专属返回映射仍留在各自 client 内，避免把领域规则塞进通用请求 **Implementation**。
+
+## 约定
+
+- Runtime client 不再手写 `encodeURIComponent` 拼 path；应优先使用 `buildRuntimeApiPath`。
+- Runtime JSON 请求不再手写 `Content-Type`、guest `Authorization` 和 `buildRuntimeGuestAuthOptions` 合并；应优先使用 `requestRuntimeJson`。
+- 玩法专属 payload 归一化、返回值适配和中文错误文案仍属于各玩法 client。
+- 每迁移一个 client，必须保留原导出函数名与原调用方契约。
+
+## 后续深化
+
+下一批可迁移 Puzzle、Jump Hop、Visual Novel、Bark Battle 与 Big Fish runtime client。迁移顺序以测试覆盖和请求形状接近度为准，优先迁移已有 guest launch 或 client 单测覆盖的函数。
+
+## 验证
+
+- `npm run test -- src/services/runtimeRequest.test.ts src/services/recommendedRuntimeGuestLaunch.test.ts src/services/match3d-runtime/match3dRuntimeAdapter.test.ts`
+- `npm run typecheck`
+- `npm run check:encoding`
+- 针对变更文件执行 ESLint