# petsHeroAI 接口调用流程说明

## 一、整体流程

```
┌─────────────────────────────────────────────────────────────────┐
│                        客户端请求流程                              │
└─────────────────────────────────────────────────────────────────┘

  业务参数(原始字段)
        │
        ▼
  ┌─────────────┐
  │ 字段名映射   │  body / params / headers 中的原始字段 → V2 字段
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │ V2 包装     │  将 body 包装为 arsenal/vault/tome/codex/grimoire/sanctum 结构
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │ JSON 序列化 │
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │ AES+Base64  │  AES-128-ECB, PKCS5Padding 加密
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │ 构造代理请求 │  填入 hero_class, pet_species, power_level 等参数
  └─────────────┘
        │
        ▼
  POST {baseUrl}/quester/defender/summoner
```

## 二、响应处理流程

```
  POST 代理入口响应
        │
        ▼
  ┌─────────────┐
  │ 提取密文     │  从响应中获取加密字段
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │ Base64 解码  │
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │ AES 解密    │  AES-128-ECB 解密
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │ JSON 解析   │
  └─────────────┘
        │
        ▼
  ┌─────────────┐
  │ 字段逆映射   │  V2 字段 → 原始字段 (便于业务使用)
  └─────────────┘
        │
        ▼
  业务数据 (code/msg/data)
```

## 三、接口分类与调用顺序

### 3.1 登录与用户

| 顺序 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 1 | `/v1/user/fast_login` | POST | 设备快速登录，获取 userToken |
| 2 | `/v1/user/common_info` | GET | 获取用户通用信息（含积分、头像等） |
| 3 | `/v1/user/account` | GET | 获取用户账户信息 |
| 4 | `/v1/user/referrer` | POST | 归因上报 |
| 5 | `/v1/user/delete` | GET | 注销账户 |

### 3.2 支付

| 顺序 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 1 | `/v1/payment/getGooglePayActivities` | GET | 获取 Google 商品列表 |
| 2 | `/v1/payment/getApplePayActivities` | GET | 获取 Apple 商品列表 |
| 3 | `/v1/payment/createPayment` | POST | 创建支付订单 |
| 4 | `/v1/payment/googlepay` | POST | Google 支付结果回调 |
| 5 | `/v1/payment/applepay` | POST | Apple 支付结果回调 |
| 6 | `/v1/payment/getPaymentDetailList` | GET | 获取支付订单列表 |

### 3.3 图片生成

| 顺序 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 1 | `/v1/image/prompt/recomends` | GET | 获取推荐提示词 |
| 2 | `/v1/image/txt2img_tags` | GET | 获取文生图标签 |
| 3 | `/v1/image/txt2img_prompts` | POST | 获取文生图提示词模板 |
| 4 | `/v1/image/txt2img_create` | POST | 创建文生图任务 |
| 5 | `/v1/image/progress` | GET | 查询图片生成进度 |

### 3.4 图转视频

| 顺序 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 1 | `/v1/image/img2Video_pose_template` | GET | 获取图转视频姿态模板 |
| 2 | `/v1/image/img2video_pose_task` | POST | 创建图转视频姿态任务 |
| 3 | `/v1/image/progress` | GET | 查询任务进度 |

### 3.5 换衣 / 换脸

| 顺序 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 1 | `/v1/image/clothes_template` | GET | 获取换衣模板 |
| 2 | `/v1/image/clothes_swap_ex` | POST | 创建换衣任务 |
| 3 | `/v1/image/faceswap_task` | POST | 创建换脸任务 |
| 4 | `/v1/image/video_facewap_task` | POST | 创建视频换脸任务 |

### 3.6 其他

| 接口 | 方法 | 说明 |
|------|------|------|
| `/v1/image/category-list` | GET | 获取分类列表 |
| `/v1/log/appevent` | POST | App 事件打点上报 |
| `/v1/image/getCreditsPageInfo` | GET | 获取积分页面信息 |
| `/v1/log/uploadUrl` | POST | 获取预签名上传 URL |

## 四、通用请求头

登录后所有请求需携带：

| 原始字段 | V2 字段 | 说明 |
|----------|---------|------|
| pkg | portal | 应用包名，必填，如 `com.petsheroai.app` |
| User_token | knight | 用户登录 token |

## 五、通用响应结构

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

## 六、错误码

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