# 用户登录流程

本文档基于 `docs/petsHeroAI_client_guide.md` 中的登录态接口，整理客户端登录顺序与数据处理要求。

---

## 1. 整体顺序

1. **设备快速登录**：`POST /v1/user/fast_login`，拿到 `userToken` 和用户信息。
2. **保存登录态与用户信息**：保存 token、积分、userId、头像、昵称、国家码等；**首次登录**记录为注册日期。
3. **归因上报**：`POST /v1/user/referrer`，将归因数据（如从 Adjust 获取的 digest）上报。
4. **获取用户通用信息**：`GET /v1/user/common_info`，拉取通用配置并保存（含 `surge` 中 `enable_third_party_payment` 等）。

登录成功后，后续所有请求需在 Header 中携带 `knight`（即 `User_token` / userToken）。

---

## 2. 设备快速登录 `POST /v1/user/fast_login`

- **鉴权**：需要（Header 需带 `portal`，首次无 `knight` 可空或按文档处理）。
- **说明**：用设备 ID + 签名做设备登录，返回用户 token 及基础信息。

### 请求

| 位置   | 字段（映射后） | 说明 |
|--------|----------------|------|
| Query  | portal         | 应用包名（必填） |
| Query  | crest          | 渠道号（可选） |
| Query  | accolade       | 类型（可选） |
| Body   | digest         | 归因信息，如 utm_source=googleplay（可与 Adjust 一致） |
| Body   | resolution     | 签名：**MD5(deviceId) 大写 32 位** |
| Body   | origin         | 设备 ID（deviceId） |

### 响应（解密后 data / sidekick）

| 字段（映射后） | 说明 |
|----------------|------|
| reevaluate     | **userToken**，后续请求 Header 的 `knight` |
| asset           | **userId**，用户 ID |
| reveal          | **credit**，积分余额 |
| realm           | 头像 URL |
| terminal        | 用户名 |
| navigate        | 国家代码 |
| surge           | 客户端界面配置（extConfig），JSON 字符串，需按需解析 |
| equip           | 是否首次注册（firstRegister） |
| 其他            | 见接口文档 sidekick 结构 |

### 客户端必做

- 保存并设置 **userToken**（如写入请求头 `knight`）。
- 保存并更新 **积分**（reveal）、**用户信息**（userId、头像、昵称、国家码等）。
- **首次登录**：将该次登录日期记为**注册日期**（用于归因/统计）；可本地标记“已注册”避免重复上报。

---

## 3. 归因上报 `POST /v1/user/referrer`

- **鉴权**：需要（Header 带 `portal`、`knight`）。
- **说明**：登录成功后调用，上报归因数据；**digest 从 Adjust 取**。

### 请求

| 位置   | 字段（映射后） | 说明 |
|--------|----------------|------|
| Query  | sentinel       | 应用标识（必填） |
| Query  | asset          | 用户 ID（userId） |
| Query  | accolade       | 类型（可选） |
| Query  | portal         | 应用包名（必填） |
| Body   | digest         | **归因信息，从 Adjust 获取** |
| Body   | origin         | 设备 ID（deviceId） |

### 响应

- code=0 表示成功；可解析 msg / data 做提示或日志。
- **调用成功后建议增加日志输出**，便于排查归因是否上报成功。

---

## 4. 获取用户通用信息 `GET /v1/user/common_info`

- **鉴权**：需要（Header 带 `portal`、`knight`）。
- **说明**：登录成功后调用，拉取通用配置并**保存到全局/本地**。

### 请求

| 位置   | 字段（映射后） | 说明 |
|--------|----------------|------|
| Query  | sentinel       | 应用标识（必填） |
| Query  | asset          | 用户 ID（userId） |
| Query  | shield / crest / item / origin / gauntlet / portal | 按需传，见接口文档 |

### 响应（解密后 data / sidekick）

- 与 fast_login 的 data 结构类似，含 **surge**（extConfig）、积分、用户信息等。
- **surge**：字符串，为 JSON；需 **先 JSON 解析再使用**。
  - 解析后的对象中，包含 **enable_third_party_payment** 等字段，用于控制第三方支付等能力。
- 其他字段（reveal、realm、terminal、navigate 等）按需保存到全局变量或状态。

### 客户端必做

- 调用 common_info 并将结果**保存到全局/状态**。
- 对 **surge** 做 **JSON decode**，得到对象后读取并保存 **enable_third_party_payment** 等配置。

---

## 5. 流程小结

```
APP 启动
  → 获取 deviceId，计算 sign = MD5(deviceId) 大写 32 位
  → 可选：从 Adjust 获取归因 digest
  → POST /v1/user/fast_login（body: digest, resolution, origin；query: portal, crest, accolade）
  → 若成功：
      1. 保存 userToken（knight）、userId（asset）、积分（reveal）、头像/昵称/国家码等
      2. 若首次登录：记录注册日期并标记已注册
      3. POST /v1/user/referrer（body: digest 从 Adjust 取, origin；query: sentinel, asset, portal）
         → 成功后打日志
      4. GET /v1/user/common_info（query: sentinel, asset）
         → 将结果保存到全局
         → 对 data.surge 做 JSON decode，保存 enable_third_party_payment 等
  → 之后所有请求 Header 带 knight = userToken
```

接口的 V2 请求体/响应体、加解密与字段映射以 **petsHeroAI_client_guide.md** 为准。