as-daycard-openapi/第三方App测试需求.md

# 第三方合作伙伴 App 测试需求

## 1. 目标

验证代销模式完整链路：EPG启动App -> init -> checkBenefits -> SDK初始化 -> 获取播放地址 -> 播放

## 2. App 定位

Android TV 应用，由第三方 EPG 通过 Intent 传参启动。App 不负责支付，仅负责：
- 设备初始化（获取 sign）
- 查询天卡权益（获取 thirdCardNo）
- 橘视厅 SDK 初始化
- 内容浏览与播放

## 3. 启动方式

### 3.1 EPG 传参启动（Intent）

```
Intent action: com.pukka.mediaapp.PARTNER_LAUNCH
Extras:
  - mac        (String, 设备MAC)
  - wifiMac    (String, WiFi MAC, 可选)
  - deviceSn   (String, 设备SN, 可选)
  - deviceUid  (String, 设备UID, 可选)
```

至少传一个设备标识（mac/wifiMac/deviceSn/deviceUid）。

### 3.2 手动输入模式（调试用）

App 提供一个输入页面，可手动输入设备标识，方便无 EPG 环境时测试。

## 4. 后端接口

### 4.1 配置

```
后端地址: http://58.220.83.58:8084 (可配置)
```

### 4.2 设备初始化

```
POST /api/jst/init
Content-Type: application/json
Body: { "mac": "xx", "wifiMac": "xx", "deviceSn": "xx", "deviceUid": "xx" }
  (不传 activationCode -> 代销模式)

成功返回:
{
  "code": 0,
  "msg": "success",
  "data": { "device": { "deviceId": 9, "roomNo": null } },
  "sign": "Base64编码的sign字符串"
}

失败返回:
{
  "code": 400,
  "msg": "设备未注册，请先通过合作伙伴天卡消耗接口激活设备",
  "data": {}
}
```

### 4.3 查询天卡权益

```
POST /api/jst/checkBenefits
Header: sign: <上一步获取的sign>

成功返回:
{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "ACTIVE",        // ACTIVE=已激活  UNBOUND=未绑定/激活中
    "thirdCardNo": "DKMMqjJKgpdwUahip5l4hGzjS",  // 播放凭证
    "cardNo": "CEB6258DB4AD6B06",
    "expireAt": "2026-07-24 19:33:14"
  }
}
```

### 4.4 轮询策略

checkBenefits 可能返回 `status: "UNBOUND"`（异步激活未完成），需要轮询：
- 轮询间隔：2秒
- 轮询超时：5分钟
- 收到 `ACTIVE` 后停止轮询

### 4.5 心跳续期（可选）

```
POST /api/jst/heartBeat
Header: sign: <sign>
```
建议每 30 分钟调用一次，防止 sign 过期（24小时有效）。

## 5. 橘视厅 SDK 初始化

### 5.1 SDK 配置

```
AGCODE = "1100101010200492358120169"
TENANT = "huashitv"
ACCESSER = "JSTASJD"
SECRET = "kMeWsBu0QsTXpnft"
SERVICE_COMBO_CODE = "1100121010200494755850172"
```

### 5.2 初始化流程

checkBenefits 返回 `ACTIVE` 后，用 `thirdCardNo` 作为 uid 初始化 SDK：

```kotlin
JetsenxSdk.init(
    context,
    agcode = AGCODE,
    mac = <设备MAC>,
    uid = thirdCardNo,     // 关键：用 thirdCardNo 作为 uid
    tenant = TENANT,
    secret = SECRET,
    accesser = ACCESSER,
    utype = "2",           // uid非MAC格式时用"2"，MAC格式用"3"
    "",
    serviceComboCode = SERVICE_COMBO_CODE,
    callback = ...
)
```

### 5.3 SDK 库文件

```
app/libs/
  - JetsenxSdk-api-future-release-v1.23.aar
  - NewTVSDK-v4.0.3-app-lite.jar
  - arm64-v8a/libnewtvsdk.so
  - armeabi-v7a/libnewtvsdk.so
```

## 6. 内容浏览与播放

### 6.1 内容列表（可选）

可调后端媒资接口获取内容列表：
```
GET /openapi/partner/media/list?catalogid=xxx&pageindex=1&pagesize=20
Header: appKey/timestamp/nonce/sign (合作伙伴签名鉴权)
```

或直接用橘视厅媒资接口（App 已有 ApiConfig 配置）。

### 6.2 获取播放地址

SDK 初始化成功后，用节目 code 获取播放地址：

```kotlin
// 1. 获取 productCode
JetsenxSdk.getAllAssetPrices(accesser, secret, callback)

// 2. 获取播放地址
JetsenxSdk.getVideoUrls(productCode, programCode, callback)
// 或免费内容
JetsenxSdk.getFreeVideoUrls(programCode, callback)
```

### 6.3 播放

用获取到的 videoUrl 播放（可用 ExoPlayer 或项目中已有的 HyMediaPlayer）。

## 7. 页面结构（最小化）

```
页面1: 启动页/输入页
  - 显示传入的设备标识（或手动输入）
  - "初始化"按钮
  - 显示 init 结果（sign, deviceId）

页面2: 权益查询页
  - 自动轮询 checkBenefits
  - 显示 status (ACTIVATING -> ACTIVE)
  - 显示 thirdCardNo, expireAt
  - ACTIVE 后自动初始化 SDK
  - 显示 SDK init 结果

页面3: 播放测试页
  - 输入 programCode（或从内容列表选择）
  - "获取播放地址"按钮
  - 显示播放地址
  - "播放"按钮
  - 视频播放区域
```

## 8. 测试场景

### 场景1: 完整流程（正常）

```
前置: 第三方已调 consume 接口，设备已绑定天卡

1. EPG传参启动App (mac=AA:BB:CC:DD:EE:01)
2. App调 init -> 返回 sign
3. App调 checkBenefits -> 返回 ACTIVE + thirdCardNo
4. App用 thirdCardNo 初始化 SDK -> 成功
5. App获取播放地址 -> 成功
6. App播放视频 -> 正常播放
```

### 场景2: 异步激活等待

```
前置: 第三方刚调完 consume，异步激活尚未完成

1. App调 init -> 返回 sign
2. App调 checkBenefits -> 返回 UNBOUND
3. App轮询 (每2秒)
4. N秒后 checkBenefits -> 返回 ACTIVE + thirdCardNo
5. App用 thirdCardNo 初始化 SDK -> 成功
```

### 场景3: 设备未注册

```
前置: 第三方未调 consume

1. App调 init -> 返回 400 "设备未注册"
2. App显示错误提示
```

### 场景4: 天卡过期

```
前置: 天卡已过期

1. App调 init -> 返回 sign
2. App调 checkBenefits -> 返回 UNBOUND
3. App显示"天卡已过期，请联系第三方续费"
```

## 9. 本次测试凭证

```
后端地址: http://58.220.83.58:8084
设备标识: mac=AA:BB:CC:DD:EE:01, deviceSn=TEST-SN-001, deviceUid=TEST-UID-001
deviceId: 9
sign: (通过 init 动态获取)
thirdCardNo: DKMMqjJKgpdwUahip5l4hGzjS
expireAt: 2026-07-24 19:33:14
```

## 10. 关键注意事项

1. **不传 activationCode**：代销模式 init 不传 activationCode，后端按设备标识查找
2. **设备标识一致性**：consume 和 init 必须用相同的设备标识，否则找不到设备
3. **thirdCardNo 不暴露给第三方**：thirdCardNo 由 App 通过 checkBenefits 获取，不经过 EPG
4. **sign 24小时有效**：长时间运行需定期心跳续期
5. **SDK utype**：uid 为 MAC 格式用 "3"，非 MAC 格式用 "2"（thirdCardNo 通常是非 MAC 格式 -> "2"）