jiecheng-business/盛阳等三方支付EPG传参App开发需求.md

盛阳等三方支付EPG传参App开发需求.md

一、项目概述

开发一款基于橘视厅 SDK 的视频点播 App，部署于酒店 IPTV 机顶盒（Android 4.2+）。支持两种入口：EPG 调起直接播放 和 App 内浏览点播。媒资列表、详情、分集、播放地址全部由橘视厅 SDK 提供，不依赖后端。

二、页面结构与流转（核心）

2.1 流转图

EPG Intent 调起                         App 独立启动
(含设备标识 + 节目编码)                   (无节目编码)
        │                                     │
        ▼                                     ▼
┌───────────────────────────────────────────────────┐
│                   启动页                           │
│  1. 解析 Intent 传参                               │
│  2. 调 init 接口 -> 获取 sign                      │
│  3. 调 checkBenefits -> 获取 thirdCardNo           │
│  4. 初始化橘视厅 SDK                               │
└───────────────────────┬───────────────────────────┘
                        │
           ┌────────────┴────────────┐
           │                         │
    有 programCode             无 programCode
           │                         │
           ▼                         ▼
   ┌───────────────┐        ┌───────────────┐
   │    播放页      │        │   媒资列表页   │
   │ (直接获取地址  │        │ (SDK 提供数据) │
   │  全屏播放)     │        └───────┬───────┘
   └───────┬───────┘                │
           │                         ▼
           │ 返回            ┌───────────────┐
           └──────────────► │    详情页      │
                            │ (SDK 提供数据)  │
                            │ 选集/介绍/播放  │
                            └───────┬───────┘
                                    │ 点击播放
                                    ▼
                            ┌───────────────┐
                            │    播放页      │
                            │ (全屏播放)     │
                            └───────┬───────┘
                                    │ 返回/播完
                                    ▼
                              回到详情页或列表页
                              用户可选其他影片

2.2 页面职责

页面	数据来源	职责
启动页	后端 init/checkBenefits	设备初始化、权益校验、SDK 初始化
媒资列表页	橘视厅 SDK	栏目分类、影片海报网格、分页加载
详情页	橘视厅 SDK	影片介绍、电视剧选集列表、播放入口
播放页	橘视厅 SDK + MediaPlayer	获取播放地址、全屏播放、遥控器控制

三、EPG Intent 接收（核心入口）

3.1 Intent 注册

<activity android:name=".LaunchActivity" android:exported="true">
    <intent-filter>
        <action android:name="com.pukka.mediaapp.PARTNER_LAUNCH" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

3.2 Intent 参数

参数	类型	必填	说明
mac	String	否*	设备 MAC
wifiMac	String	否	WiFi MAC
deviceSn	String	否	设备 SN
deviceUid	String	否*	设备唯一标识
programCode	String	否	节目编码。有值=直接播放，无值=进入列表

*mac 和 deviceUid 至少传一个，用于后端 init 接口识别设备。优先级：EPG 传入 > 本地采集。

3.3 启动分支逻辑

收到 Intent
  │
  ├─ 步骤1：收集设备标识（优先 EPG 传入，兜底本地采集）
  ├─ 步骤2：调 init 接口 -> 获取 sign
  ├─ 步骤3：调 checkBenefits -> 获取 thirdCardNo + status
  ├─ 步骤4：用 thirdCardNo 初始化橘视厅 SDK
  │
  ├─ 有 programCode？
  │   ├─ YES -> 调 SDK 获取播放地址 -> 跳转播放页（全屏）
  │   └─ NO  -> 跳转媒资列表页
  │
  └─ 播放页返回后 -> 进入媒资列表页（用户可继续浏览）

四、init 与 checkBenefits 接口

4.1 设备初始化接口

POST http://{后端地址}/api/jst/init
Content-Type: application/json

请求体：
{
    "mac": "EC:F7:2B:03:1F:97",
    "deviceUid": "TEST-UID-001"
}

响应体：
{
    "code": 0,
    "msg": "success",
    "sign": "OToxNzg1...",           // 鉴权凭证，后续接口 Header 携带
    "data": {
        "device": { "deviceId": 9 }
    }
}

4.2 权益查询接口

POST http://{后端地址}/api/jst/checkBenefits
Header: sign: {init 返回的 sign}
Content-Type: application/json

响应体：
{
    "code": 0,
    "msg": "success",
    "data": {
        "status": "ACTIVE",           // ACTIVE=已激活 / UNBOUND=未绑定
        "thirdCardNo": "DbzgHwPRK18pDKVZIS3AdBfQw",  // 橘视厅 SDK uid 参数
        "cardNo": "7D9AFE7677A758CD",
        "expireAt": "2026-07-29 17:25:05"
    }
}

4.3 心跳续期接口

POST http://{后端地址}/api/jst/heartBeat
Header: sign: {init 返回的 sign}

// 每 30 分钟调用一次，sign 过期后需重新调 init

后端只负责以上三个接口。媒资、详情、分集、播放地址全部由橘视厅 SDK 提供。

五、橘视厅 SDK 能力（媒资+播放，全部 SDK 提供）

5.1 SDK 初始化

checkBenefits 返回 thirdCardNo 后，初始化 SDK：

JetsenxSdk.init(
    agcode,      // thirdCardNo（checkBenefits 返回）
    mac,         // 设备 MAC
    uid,         // thirdCardNo（checkBenefits 返回）
    "huashitv",  // tenant（固定值）
    secret,      // 密钥（由橘视厅分配）
    accesser,    // 访问者标识（由橘视厅分配）
    2,           // utype（固定值）
    "",          // extendJson
    ""           // comboCode
);

5.2 SDK 提供的能力

能力	SDK 方法	说明
媒资列表	SDK 提供	栏目分类、影片列表、海报、分页
内容详情	SDK 提供	影片介绍、演员、评分等
电视剧分集	SDK 提供	选集列表，每集 contentcode
播放地址（付费）	JetsenxSdk.getVideoUrls(productCode, programCode, callback)	返回 VideoInfo[]，含 720P/1080P 地址
播放地址（免费）	JetsenxSdk.getFreeVideoUrls(programCode, callback)	parentContentType="8" 时调用
产品定价	JetsenxSdk.getAllAssetPrices(accesser, secret, callback)	获取 productCode（packageCode 字段）

5.3 播放地址获取要点

1. productCode = getAllAssetPrices() 返回的第一个 packageCode
2. 根据 parentContentType 选择接口：
   - "8" -> getFreeVideoUrls(programCode)
   - 其他 -> getVideoUrls(productCode, programCode)
3. 返回 VideoInfo[]，按 format 字段区分清晰度
4. programCode 必须是分集级编码（非电视剧父级编码）

六、播放页

6.1 技术方案

使用系统原生 MediaPlayer + SurfaceView（兼容 Android 4.2，不用 ExoPlayer）：

• 支持 HLS（.m3u8）格式
• 全屏横屏播放
• 遥控器控制：OK键暂停/播放、左右键快进快退、返回键退出
• 播放地址带时效性 auth_key

6.2 播放完成流转

播放完成 / 用户按返回
  ├── EPG 直接播放进入的 -> 返回媒资列表页
  └── 详情页进入的 -> 返回详情页（可继续选集播放）

七、技术约束（Android 4.2 兼容）

依赖	版本	原因
minSdk	17	Android 4.2
Retrofit	2.6.0	2.9+ 传递依赖 OkHttp 3.14 不兼容
OkHttp	3.12.0（force）	3.12.1+ 含 Android10Platform，VerifyError
Gson	2.8.6	2.9+ 含 ReflectionHelper，VerifyError
Coroutines	1.6.4	1.7+ 要求 minSdk 21
视频播放	MediaPlayer	ExoPlayer 2.14+ 不兼容
主题	AppCompat	MaterialComponents 主 dex 方法数超限
multidex	启用	主 dex 保留 androidx.appcompat.** / kotlinx.coroutines.** / retrofit2.**

八、参考代码

测试阶段已验证的代码在 partner-test-app/ 目录：

文件	作用
JetsenxSdkUtil.kt	SDK 封装：init + getVideoUrls + getFreeVideoUrls
PartnerSignManager.kt	后端接口：init + checkBenefits + heartBeat
PartnerApiService.kt	Retrofit 接口定义
VideoPlayerActivity.kt	MediaPlayer + SurfaceView 播放实现
multidex-config.pro	Android 4.2 multidex 配置