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 中 lucky 等。 |
调用处：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 自动带。 |
六、通用响应结构（解密后业务层）
{
"code": 0, // helm，0=成功
"msg": "", // rampart，消息
"data": {} // sidekick，业务数据
}
七、错误码
| code |
说明 |
| 0 |
成功 |
| -1 |
系统错误 |
| -2 |
未登录 |
| -3 |
无权限 |
| -4 |
请求过于频繁 |
| -5 |
参数错误 |
| 1001 |
积分不足 |
| 1002 |
免费次数已用完 |
| 1003 |
免费次数和积分均已用完 |
