195 lines
8.2 KiB
Markdown
195 lines
8.2 KiB
Markdown
# 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 | 免费次数和积分均已用完 |
|