# petsHeroAI 接口调用流程说明

本文档说明客户端请求的加解密与代理流程，以及**按业务场景**的接口调用顺序。具体字段以 **petsHeroAI_client_guide.md** 为准。

---

## 一、请求流程（所有接口统一）

```
  业务参数（V2 字段名）
        │
        ▼
  ┌─────────────┐
  │ V2 包装     │  body → arsenal/vault/tome/codex/grimoire/sanctum
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │ JSON 序列化 │  headers / queryParams / body 分别序列化
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │ AES+Base64  │  各字段 AES-128-ECB、PKCS5 填充后 Base64
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │ 构造代理请求 │  hero_class, pet_species(path), power_level(method),
  │             │  quest_rank(headers), battle_score(queryParams),
  │             │  loyalty_index(body) + 噪音字段
  └─────────────┘
        │
        ▼
  POST {baseUrl}/quester/defender/summoner
```

- **path**（如 `/v1/user/fast_login`）加密后放在 **pet_species**。
- **method**（GET/POST）加密后放在 **power_level**。
- 登录后 **knight**（userToken）由 ProxyClient 自动写入请求头并参与加密。

---

## 二、响应处理流程

```
  POST 代理入口响应（密文 body）
        │
        ▼
  Base64 解码 → AES 解密 → JSON 解析
        │
        ▼
  取 vault.tome.codex.grimoire.sanctum
        │
        ▼
  helm → code, rampart → msg, sidekick → data
        │
        ▼
  ApiResponse(code, msg, data)
```

---

## 三、按业务场景的接口调用顺序

### 3.1 应用启动与登录（AuthService.init）

| 顺序 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 1 | `/v1/user/fast_login` | POST | 设备快速登录；body: digest, resolution(sign), origin(deviceId)。返回 reevaluate(userToken)、asset(uid)、reveal(积分) 等。 |
| 2 | （保存 token、用户信息到 UserState；首次登录打点 register） | — | — |
| 3 | `/v1/user/referrer` | POST | 归因上报；query: sentinel, asset(uid), portal；body: digest, origin。 |
| 4 | `/v1/user/common_info` | GET | 获取用户通用信息；query: sentinel, asset(uid)。解析 data 写入 UserState，并解析 surge 中 enable_third_party_payment 等。 |

**调用处**：`lib/core/auth/auth_service.dart`（init，登录成功后顺序执行）。

---

### 3.2 充值 / 支付

| 场景 | 顺序 | 接口 | 方法 | 说明 |
|------|------|------|------|------|
| 进入充值页 | 1 | `/v1/payment/getGooglePayActivities` 或 `/v1/payment/getApplePayActivities` | GET | 按平台获取商品列表；data.summon 为列表，单项含 helm(商品ID)、warrior(activityId)、guardian、curriculum、forge 等。 |
| 用户点 Buy（第三方支付开） | 2 | `/v1/payment/get-payment-methods` | POST | body: warrior(activityId), vambrace(国家可选)。返回 data.renew 支付方式列表。 |
| 用户选支付方式后 | 3 | `/v1/payment/createPayment` | POST | query: sentinel, asset(userId)；body: sentinel, asset, warrior, resource, ceremony。返回 federation(订单ID)、convert(payUrl)。 |
| 若选中 Google Pay | 4 | 调起 Google Play 内购，成功后 | — | 使用 serverVerificationData 作为 merchant。 |
|  | 5 | `/v1/payment/googlepay` | POST | body: merchant(凭据), federation(订单ID), asset(userId)。 |
| 若选其他支付方式 | — | 打开 createPayment 返回的 convert(payUrl) | — | 在外部浏览器完成支付。 |
| 用户点 Buy（第三方支付关） | — | 不调 2、3，直接调起 Google Play 内购（商品 ID = helm） | — | 无 createPayment / googlepay。 |

**调用处**：`lib/features/recharge/recharge_screen.dart`、`PaymentApi`、`GooglePlayPurchaseService`。详见 **docs/payment_flow.md**。

---

### 3.3 生成视频（图生视频）

| 顺序 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 1 | `/v1/image/upload-presigned-url` | POST | 获取上传 URL；body: gateway(fileName1), action(fileName2), pauldron(contentType), stronghold(expectedSize)。返回的 URL 用于**直接 PUT 上传图片**（不经过代理）。 |
| 2 | （客户端 PUT 上传图片到 presigned URL） | PUT | 不经过代理，请求头按接口要求设置。 |
| 3 | `/v1/image/create-task` | POST | query: asset；body: commission(srcImg1Url 等)、guild(分辨率) 等。返回任务信息。 |
| 4 | `/v1/image/progress` | GET | query: sentinel, tree(taskId), asset。进度页**轮询**（如每 1s），直到 state 为 3(完成)/4/5/6。 |
| 5 | （生成完成后）`/v1/user/account` | GET | 刷新用户积分。 |

**调用处**：`lib/features/generate_video/generate_video_screen.dart`（1→2→3）、`generate_progress_screen.dart`（4、5）。

---

### 3.4 首页与图库

| 场景 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 首页分类/列表 | `/v1/image/img2video/categories` | GET | 获取图转视频分类。 |
|  | `/v1/image/img2video/tasks` | GET | 获取图转视频任务列表；可选 query: insignia(categoryId)。 |
| 图库「我的」 | `/v1/image/my-tasks` | GET | 获取我的任务列表；query: sentinel, trophy/heatmap/platoon 等。 |

**调用处**：`lib/features/home/home_screen.dart`、`lib/features/gallery/gallery_screen.dart`。

---

### 3.5 其他

| 接口 | 方法 | 说明 |
|------|------|------|
| `/v1/user/account` | GET | 获取账户信息（积分等）；个人页、生成视频完成后刷新积分时调用。 |
| `/v1/image/getCreditsPageInfo` | GET | 获取积分页信息。 |
| `/v1/image/prompt/recomends` | GET | 获取推荐提示词。 |
| `/v1/image/txt2img_create` | POST | 创建文生图任务。 |
| `/v1/image/img2Video_pose_template` | GET | 获取图转视频姿态模板。 |
| `/v1/image/img2video_pose_task` | POST | 创建图转视频姿态任务。 |

---

## 四、接口路径与客户端封装对照

| 接口路径 | 方法 | 客户端封装（lib/core/api/services/） |
|----------|------|--------------------------------------|
| /v1/user/fast_login | POST | UserApi.fastLogin |
| /v1/user/referrer | POST | UserApi.referrer |
| /v1/user/common_info | GET | UserApi.getCommonInfo |
| /v1/user/account | GET | UserApi.getAccount |
| /v1/payment/getGooglePayActivities | GET | PaymentApi.getGooglePayActivities |
| /v1/payment/getApplePayActivities | GET | PaymentApi.getApplePayActivities |
| /v1/payment/get-payment-methods | POST | PaymentApi.getPaymentMethods |
| /v1/payment/createPayment | POST | PaymentApi.createPayment |
| /v1/payment/googlepay | POST | PaymentApi.googlepay |
| /v1/image/img2video/categories | GET | ImageApi.getCategoryList |
| /v1/image/img2video/tasks | GET | ImageApi.getImg2VideoTasks |
| /v1/image/my-tasks | GET | ImageApi.getMyTasks |
| /v1/image/upload-presigned-url | POST | ImageApi.getUploadPresignedUrl |
| /v1/image/create-task | POST | ImageApi.createTask |
| /v1/image/progress | GET | ImageApi.getProgress |
| /v1/image/getCreditsPageInfo | GET | ImageApi.getCreditsPageInfo |
| /v1/image/prompt/recomends | GET | ImageApi.getPromptRecommends |
| /v1/image/txt2img_create | POST | ImageApi.createTxt2Img |
| /v1/image/img2Video_pose_template | GET | ImageApi.getImg2VideoPoseTemplates |
| /v1/image/img2video_pose_task | POST | ImageApi.createImg2VideoPose |

---

## 五、通用请求头（登录后）

| 原始字段 | V2 字段 | 说明 |
|----------|---------|------|
| pkg | portal | 应用包名，必填；ProxyClient 自动带。 |
| User_token | knight | 用户 token；登录成功后 ProxyClient 自动带。 |

---

## 六、通用响应结构（解密后业务层）

```json
{
  "code": 0,      // helm，0=成功
  "msg": "",      // rampart，消息
  "data": {}      // sidekick，业务数据
}
```

---

## 七、错误码

| code | 说明 |
|------|------|
| 0 | 成功 |
| -1 | 系统错误 |
| -2 | 未登录 |
| -3 | 无权限 |
| -4 | 请求过于频繁 |
| -5 | 参数错误 |
| 1001 | 积分不足 |
| 1002 | 免费次数已用完 |
| 1003 | 免费次数和积分均已用完 |