# MediaApp 核心业务逻辑文档 ## 一、系统架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ MediaApp (Android) │ │ │ │ HomeActivity ──→ DetailActivity ──→ VideoPlayerActivity │ │ │ │ │ │ │ │ ├─ PaymentViewModel │ │ │ │ ├─ JetsenxSdkUtil │ │ │ │ └─ DayCardApiService │ │ └───────┼───────────────┼────────────────────┘ │ │ │ │ ▼ ▼ ▼ ┌──────────────────────────────┐ ┌───────────────────────────┐ │ as-daycard-openapi (后端) │ │ 橘视厅/捷成平台 │ │ 端口: 8084 │ │ api.future.jetsentv.com │ │ │ │ │ │ ├─ 天卡订单管理 │ │ ├─ UMS用户系统 │ │ ├─ 天卡池管理 │ │ ├─ 卡密激活 │ │ ├─ 微信/Mock支付 │ │ ├─ VIP订购关系 │ │ ├─ 异步卡密激活 │──│──→ ├─ 视频地址分发 │ │ ├─ 权益查询(thirdCardNo) │ │ └─ 媒资管理 │ │ └─ 媒资/播放权限 │ │ │ │ │ │ │ │ 数据库: MySQL (dev-0418) │ │ │ │ 缓存: Redis │ │ │ └──────────────────────────────┘ └───────────────────────────┘ ``` --- ## 二、完整播放流程 ### 流程图 ``` 用户点击播放 │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Step 1: 检查天卡播放权限 │ │ App → GET /openapi/media/play-permission/{mediaId} │ │ ?deviceId=1 │ │ 后端: 查 day_card_pool 表 │ │ status=USED AND expire_at > NOW() │ │ │ │ ┌─ 有权限 ──→ HasPermission ──→ 跳到 Step 3 │ │ └─ 无权限 ──→ 进入支付流程 │ └─────────────────────────────────────────────────────────┘ │ (无权限) ▼ ┌─────────────────────────────────────────────────────────┐ │ Step 2: 天卡支付流程 │ │ │ │ 2a. 创建订单 │ │ App → POST /openapi/daycard/create │ │ 后端: Redis防重锁 → SELECT FOR UPDATE SKIP LOCKED │ │ 抢一张UNUSED卡 → 卡状态UNUSED→RESERVED │ │ → 创建订单(CREATED) │ │ │ │ 2b. 支付 │ │ App → POST /openapi/payment/mock-pay/{orderNo} │ │ 后端: 订单→PAID, 卡→USED, expire_at=24h兜底 │ │ → @Async asyncActivateCard() │ │ │ │ 2c. 轮询支付状态 │ │ App → GET /openapi/daycard/status/{orderNo} │ │ 直到返回 PAID │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Step 2d: 后端异步激活卡密 (3步HTTP调用橘视厅API) │ │ │ │ ① getToken(device, thirdCardNo) │ │ POST api.future.jetsentv.com/ums_api/api/v1/ │ │ third/login │ │ 参数: uid=thirdCardNo, mac, accesser, businessLine │ │ 签名: RSA(jushitingLoginRsaPublicKey) │ │ 返回: token + memberCode │ │ │ │ ② activateCard(deviceId, cardCode, memberCode, token) │ │ POST api.future.jetsentv.com/ccms_api/hswj/api/ │ │ card/activate │ │ 参数: activateCode=cardCode, memberCode │ │ 签名: MD5(activateCode&memberCode×tamp&key) │ │ 返回: status=true + expireTime │ │ ★ 此时橘视厅平台建立了 thirdCardNo→用户→订购关系 │ │ │ │ ③ queryVipExpireTime(thirdCardNo) [仅②未返回expireTime] │ │ POST api.future.jetsentv.com/ums_api/member/uid/ │ │ queryVipInfo │ │ 返回: vipExpireTime │ │ │ │ 激活完成: day_card_pool.activate_status=SUCCESS │ │ expire_at = 真实到期时间 │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Step 3: 查询天卡权益获取 thirdCardNo │ │ App → GET /openapi/daycard/benefits/{deviceId} │ │ 后端: 查 day_card_pool │ │ status=USED AND expire_at > NOW() │ │ 返回: { thirdCardNo, hasBenefits, cardCode, expireAt } │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Step 4: SDK初始化 (用 thirdCardNo 作为用户身份) │ │ JetsenxSdkUtil.init(ctx, thirdCardNo, callback) │ │ │ │ SDK内部: GET api.future.jetsentv.com/ums_api/openapi/ │ │ init?uid=thirdCardNo&utype=2 │ │ 参数: agcode, accesser=JSTASJD, mac, tenant=huashitv │ │ secret, serviceComboCode │ │ 返回: memberCode (用于后续视频地址获取) │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Step 5: 获取视频地址 │ │ JetsenxSdkUtil.getAllVideoUrl(parentContentType, │ │ programCode) │ │ │ │ SDK内部流程: │ │ 5a. getAllAssetPrices → 获取 productCode │ │ 5b. parentContentType=="8" → getFreeVideoUrls (免费) │ │ parentContentType!="8" → getVideoUrls (付费) │ │ 5c. getVideoUrls: │ │ GET api.future.jetsentv.com/bms_api/openapi/ │ │ orderAuth?memberCode&uid&productCode&programCode│ │ 有订购→返回VideoInfo[] (1080p/720p地址) │ │ 无订购→-110错误 │ │ 5d. -110时回退getFreeVideoUrls │ └─────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Step 6: 播放 │ │ 跳转 VideoPlayerActivity │ │ ExoPlayer 播放视频URL │ └─────────────────────────────────────────────────────────┘ ``` --- ## 三、防重复消费机制 ### 三层防护确保不会浪费卡密 | 防护层 | 机制 | 位置 | 效果 | |--------|------|------|------| | 第1层 | App端 checkPermission | PaymentViewModel Step1 | 24小时内重复点击不创建订单 | | 第2层 | 后端 Redis防重锁 | createOrder() 第1步 | 同一设备订单超时时间内只能一个订单 | | 第3层 | 定时任务释放超时订单 | DayCardOrderTimeoutTask | 订单超时未支付，卡密回收为UNUSED | ### 权益有效期 - 天卡支付成功后获得 **24小时** 播放权益 - 期间无限次播放不额外消耗卡密 - 权益过期后再次播放需要重新支付 --- ## 四、关键配置项 ### 4.1 SDK配置 (JetsenxSdkUtil.kt) | 参数 | 值 | 说明 | |------|-----|------| | AAR包 | `JetsenxSdk-api-future-release-v1.23.aar` | 生产域名 api.future.jetsentv.com | | AGCODE | `1100101010200492358120169` | 渠道号 | | TENANT | `huashitv` | 租户 | | ACCESSER | `JSTASJD` | 合作方标识（生产环境） | | SECRET | `kMeWsBu0QsTXpnft` | 秘钥（生产环境） | | SERVICE_COMBO_CODE | `1100121010200494755850172` | 业务组合编码 | ### 4.2 后端橘视厅平台配置 (sys_config: JST_PLATFORM_CONFIG) | 参数 | 值 | |------|-----| | jushitingBaseUrl | `https://api.future.jetsentv.com` | | vipQueryBaseUrl | `https://api.future.jetsentv.com` | | jushitingTenant | `huashitv` | | jushitingAccesser | `JSTASJD` | | jushitingBusinessLine | `4100450011381755998420012` | | jushitingServiceComboCode | `1100121010200494755850172` | | jushitingLoginRsaPublicKey | (RSA公钥) | | jushitingActivateSignKey | `hhDEHY1qC4r` | | vipQuerySignKey | `c25svtwbTyCE` | ### 4.3 thirdCardNo 生成规则 | 项目 | 规则 | 示例 | |------|------|------| | as-daycard-openapi | `D` + 24位随机(0-9A-Za-z) | `D00BB8E623D9280D1ACABE803` | | as-partner-backend | 24位随机(0-9A-Za-z) | `A3f9Kp2m...`（无前缀） | `D` 前缀确保两个项目的 thirdCardNo 空间完全隔离，不会碰撞。 --- ## 五、关键文件索引 ### MediaApp (Android端) | 文件 | 作用 | |------|------| | `ui/DetailActivity.kt` | 详情页，播放流程入口 | | `ui/VideoPlayerActivity.kt` | ExoPlayer播放器 | | `ui/HomeActivity.kt` | 首页，媒资列表 | | `sdk/JetsenxSdkUtil.kt` | SDK封装：初始化+获取视频地址 | | `network/DayCardApiService.kt` | 天卡后端API接口定义 | | `network/DayCardRetrofitClient.kt` | Retrofit客户端 | | `viewmodel/PaymentViewModel.kt` | 天卡支付流程状态机 | | `viewmodel/DetailViewModel.kt` | 详情页数据 | | `model/daycard/DayCardModels.kt` | 天卡数据模型 | | `config/DayCardConfig.kt` | 天卡配置(设备ID/金额) | | `config/ApiConfig.kt` | 媒资API配置 | ### as-daycard-openapi (后端) | 文件 | 作用 | |------|------| | `daycard/controller/DayCardOrderController.java` | 订单/权益接口 | | `daycard/service/impl/DayCardOrderServiceImpl.java` | 订单核心逻辑+异步激活 | | `daycard/service/impl/DayCardPoolServiceImpl.java` | 天卡池管理+thirdCardNo生成 | | `daycard/task/DayCardOrderTimeoutTask.java` | 超时订单清理 | | `jst/service/impl/JushitingApiServiceImpl.java` | 橘视厅API调用 | | `media/service/impl/MediaServiceImpl.java` | 播放权限检查 | | `openapi/filter/PartnerSignFilter.java` | 签名鉴权过滤器 | | `openapi/sign/impl/PartnerSignServiceImpl.java` | HMAC-SHA256签名 | --- ## 六、项目环境信息 ### 6.1 目录结构 ``` /Users/zhaoguodong/Desktop/ ├── jiecheng_business/ # 工作目录（本项目） │ ├── MediaApp/ # Android客户端 (Kotlin) │ ├── MediaApp核心业务逻辑文档.md # 本文档 │ └── README.md ├── as-daycard-openapi/ # 本项目后端 (Spring Boot, 端口8084) │ └── src/main/resources/mapper/sys/SysConfigDao.xml # ★手动创建的MyBatis映射 └── as-partner-backend/ # 生产环境后端 (仅参考，端口8083，不在本项目中) ``` ### 6.2 构建环境 | 项目 | 构建命令 | 说明 | |------|----------|------| | MediaApp | `JAVA_HOME=.../jbr-17.0.14 && cd MediaApp && ./gradlew assembleDebug` | APK输出: `MediaApp/app/build/outputs/apk/debug/app-debug.apk` | | as-daycard-openapi | `cd as-daycard-openapi && mvn spring-boot:run -Dspring-boot.run.profiles=dev` | 端口8084 | | JAVA_HOME | `/Users/zhaoguodong/Library/Java/JavaVirtualMachines/jbr-17.0.14/Contents/Home` | JDK 17 | | 安装到设备 | `adb install -r app-debug.apk` | | ### 6.3 后端数据库 | 项目 | 值 | |------|-----| | MySQL | `127.0.0.1:3306` | | 数据库 | `dev-0418` | | 用户/密码 | `root / r2356510` | | mysql路径 | `/opt/homebrew/Cellar/mysql@8.0/8.0.42/bin/mysql` | | Redis | `127.0.0.1:6379` database 0 | ### 6.4 API基础地址 | 项目 | 地址 | |------|------| | 天卡后端 (as-daycard-openapi) | `http://172.16.100.67:3002` (通过nginx代理到8084) | | 橘视厅平台 | `https://api.future.jetsentv.com` | | 媒资API | 橘视厅SDK内部调用，域名同上 | ### 6.5 测试设备 | 项目 | 值 | |------|-----| | deviceId | `1` (数据库device表id=1) | | MAC | `CC:8C:DA:C6:E9:9B` | | 测试卡密 | cardCode=`4009B1C3926DF480`, thirdCardNo=`D00BB8E623D9280D1ACABE803` | | 卡密状态 | USED, activate_status=SUCCESS, expire_at=2026-07-14 18:23:58 | | 合作伙伴 | partnerId=1, appKey=`71df57e7e47a4a88` | --- ## 七、API签名鉴权机制 App与天卡后端的所有 `/openapi/**` 接口（除 `/openapi/partner/**` 和 `/openapi/payment/notify`）都需要签名鉴权： **签名格式**: `Base64URL(appKey:timestamp:nonce:HMAC-SHA256(appKey:timestamp:nonce, appSecret))` **请求头**: | Header | 说明 | |--------|------| | `X-App-Key` | appKey | | `X-Timestamp` | 毫秒时间戳 | | `X-Nonce` | 随机字符串 | | `X-Sign` | 签名值 | **校验规则**: HMAC比对 + 时间戳5分钟有效期 + Redis nonce防重放 --- ## 八、PaymentViewModel 状态机 ``` Idle ↓ startPaymentFlow() CheckingPermission ──→ HasPermission ──→ fetchVideoUrlAndPlay() ↓ (无权限) CreatingOrder ──→ OrderCreated ──→ (用户确认支付) ↓ Paying ──→ Polling ──→ PaymentSuccess ──→ fetchVideoUrlAndPlay() ↓ (任意失败) ↓ Error Error ``` **防重复跳转**: `DetailActivity.isFetchingVideoUrl` 标志位，在 `HasPermission`/`PaymentSuccess` 时置true，跳转播放器后不会因 `repeatOnLifecycle(STARTED)` 重新触发。点击播放按钮时重置为false。 --- ## 九、已知限制与待办 | 项目 | 说明 | |------|------| | 设备ID硬编码 | `DayCardConfig.DEVICE_ID = 1L`，多设备需要改为动态获取 | | Mock支付 | 当前用 `mock-pay` 接口测试，生产需切换微信支付 | | 单内容测试 | 仅验证了单个媒资播放，未测试列表翻页、搜索等 | | 签名证书 | MediaApp未配置release签名，打release包时需要配置 | | 后端签名校验 | App端API调用需实现HMAC签名（当前可能在Retrofit拦截器中） | --- ## 十、踩坑记录 | 问题 | 原因 | 解决方案 | |------|------|----------| | 详情页闪退 | onCreate中调用SDK初始化，native库加载异常 | 改为点击播放时按需初始化 | | 16KB对齐警告 | exoplayer-ffmpeg-extension中的.so未对齐 | 移除未使用的FFmpeg扩展库 | | NoClassDefFoundError: LogProducerConfig | 缺少火山引擎TLS日志库 | 添加tls-android-producer依赖 | | 支付对话框闪退 | HasPermission时关闭对话框后SDK回调无法显示 | 保持对话框打开直到视频地址获取完成 | | SDK返回-110未订购 | uid="test_user"无效 | 从benefits接口获取真实thirdCardNo | | 后端激活失败: SysConfigDao.queryByKey not found | 缺少MyBatis XML映射 | 创建SysConfigDao.xml | | SDK返回604 | SDK用external域名(测试)，后端用api域名(生产) | 换用api-future AAR包 | | memberCode不一致 | 两个域名指向不同服务器，用户数据不互通 | 统一使用api.future.jetsentv.com |