初始化天卡开放平台后端项目
包含完整功能模块： - 设备激活（直销激活码模式 + 代销免激活码模式） - 微信支付 + 天卡订单 - 天卡池管理 + 异步橘视厅SDK激活 - 第三方合作伙伴接口（代销模式） - 签名鉴权（appKey/appSecret + nonce防重放） - 天卡消耗（事务 + 幂等 + 并发控制） - 媒资接口（三级授权过滤） - 审计日志 - 定价策略（3层：门店 > 渠道 > 平台） - 分账（微信分账 + 分润规则） - Docker部署（含Redis容器）
This commit is contained in:
zhaogd
258
第三方App测试需求.md
Normal file
258
第三方App测试需求.md
Normal file
@@ -0,0 +1,258 @@
|
||||
# 第三方合作伙伴 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"）
|
||||
Reference in New Issue
Block a user