active

plans/sdk_taskprogress_封装_5c8676e2.plan.md

@@ -1,81 +0,0 @@
----
-name: SDK taskProgress 封装
-overview: 将 slot_sdk（或你们的 SDK 仓库）加入工作区后，可按现有 Wallet Client 模式直接实现 `player-task/task-progress` 的调用封装；wallet 侧接口文档已就绪，可作为契约来源。
-todos:
-  - id: add-sdk-workspace
-    content: 用户将 slot_sdk 加入 Cursor 工作区并告知仓库路径
-    status: completed
-  - id: explore-sdk-patterns
-    content: 阅读 SDK 现有 Wallet Client / HTTP 封装与错误处理约定
-    status: completed
-  - id: implement-client
-    content: 新增 taskProgress 方法、路径常量、请求/响应类型（对齐 player-task-progress-api.md）
-    status: completed
-  - id: add-tests-or-example
-    content: 按 SDK 惯例补单测或调用示例（若项目有测试目录）
-    status: completed
-isProject: false
----
-
-# SDK 工作区加入后的直接开发方案
-
-## 结论
-
-**可以。** 当前工作区只有 [slot-wallet](file:///Users/ray/Documents/project/www/ray/slot-wallet)，已具备接口契约文档 [doc/player-task-progress-api.md](doc/player-task-progress-api.md) 与实现对照（`PlayerTaskController`、`PlayerTaskQueryService` 等）。把 **SDK 仓库** 作为第二个根目录（或 monorepo 子目录）加入工作区后，我可以：
-
-1. 阅读 SDK 里现有 Wallet/HTTP Client 的命名、基类、错误处理、DTO 约定；
-2. 新增 `taskProgress`（或团队统一命名）方法、路径常量、请求/响应类型；
-3. 若有单测/示例，补一条调用示例或 Feature 测试；
-4. 保证字段 **snake_case** 与 HTTP JSON 一致，成功判定 `code === 0`。
-
-```mermaid
-flowchart LR
-  subgraph workspace [Cursor Workspace]
-    Wallet[slot-wallet]
-    SDK[slot_sdk]
-  end
-  Doc[player-task-progress-api.md]
-  Wallet --> Doc
-  SDK -->|reads patterns| SDK
-  Doc -->|contract| SDK
-  SDK -->|POST player-task/task-progress| Wallet
-```
-
-## 你需要做的准备
-
-| 项 | 说明 |
-|----|------|
-| 加入工作区 | Cursor：**File → Add Folder to Workspace**，选中 SDK 仓库根目录 |
-| 告知路径 | 例如 `company/ray/slots/slot_sdk`（与你们实际目录一致即可） |
-| 语言确认 | 若是 PHP `slot_sdk`、Go、TS 等，我会跟现有 Client 语言一致，不另起一套风格 |
-
-无需改 wallet 代码即可开始 SDK 开发；wallet 接口已实现完毕。
-
-## 我会按什么写（预期产出）
-
-以 SDK 现有 Wallet Client 为模板（具体类名需打开 SDK 后确认），典型改动：
-
-- **路径常量**：`player-task/task-progress`
-- **请求**：`uid`, `currency`（可选统一附带 `trace_id` 若其他接口都有）
-- **响应模型**：`summary` + `bonus_tasks[]` + `deposit_tasks[]`，字段与 [doc/player-task-progress-api.md](doc/player-task-progress-api.md) §5 一致
-- **错误**：复用 SDK 已有 `WalletApiError` / `code !== 0` 处理
-
-## 跨仓库发布（团队规范）
-
-按 [`.cursor/rules/slot-wallet-layers-and-delivery.mdc`](file:///Users/ray/Documents/project/www/ray/slot-wallet/.cursor/rules/slot-wallet-layers-and-delivery.mdc) §8–9：
-
-1. **先在 SDK 仓库** `commit` → `push`；
-2. 消费方（如 slot-wallet 若通过 composer 依赖 SDK）再 `composer update` 并锁 `composer.lock`。
-
-当前 [composer.json](file:///Users/ray/Documents/project/www/ray/slot-wallet/composer.json) **尚未**声明 `slot_sdk` 依赖，说明 SDK 可能独立发布或由其他服务引用——这不影响我在 SDK 仓库内直接编码。
-
-## 建议的确认项（加入工作区后第一条消息说明即可）
-
-1. SDK 仓库在本机的**绝对路径**或文件夹名；
-2. 方法命名偏好：`taskProgress` / `getPlayerTaskProgress` / 与现有 `wallet()` 等方法对齐；
-3. 是否需要 **foundation 常量**（如 `source_type`）进 SDK，还是仅透传 int。
-
-## 不在本次默认范围
-
-- 修改 wallet 服务端实现（已满足 PRD §26.1）；
-- 自动 `composer update` 到其他服务（除非你明确要求并给出目标仓库）。