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