---
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` 到其他服务（除非你明确要求并给出目标仓库）。