30198c7191
包含完整功能模块： - 设备激活（直销激活码模式 + 代销免激活码模式） - 微信支付 + 天卡订单 - 天卡池管理 + 异步橘视厅SDK激活 - 第三方合作伙伴接口（代销模式） - 签名鉴权（appKey/appSecret + nonce防重放） - 天卡消耗（事务 + 幂等 + 并发控制） - 媒资接口（三级授权过滤） - 审计日志 - 定价策略（3层：门店 > 渠道 > 平台） - 分账（微信分账 + 分润规则） - Docker部署（含Redis容器）
96 lines
5.7 KiB
Markdown
96 lines
5.7 KiB
Markdown
# 后端项目交接文档
|
||
|
||
## 项目信息
|
||
- 路径：/Users/zhaoguodong/Desktop/as-daycard-openapi
|
||
- 启动：`./start.sh -Dspring-boot.run.profiles=dev`（端口8084，JDK17路径在start.sh里）
|
||
- 本地打包：`export JAVA_HOME=/Users/zhaoguodong/Library/Java/JavaVirtualMachines/jbr-17.0.14/Contents/Home && mvn clean package -DskipTests`
|
||
- MySQL：/opt/homebrew/Cellar/mysql@8.0/8.0.42/bin/mysql -uroot -pr2356510 dev-0418
|
||
- 接口文档：API_DOC.md（完整）+ THIRD_PARTY_API.md（第三方对接）
|
||
- DDL：db/full-schema.sql（52个表，完整表结构，从dev-0418导出）
|
||
|
||
## 云服务器部署
|
||
- 服务器：宝塔面板，IP见用户确认
|
||
- 数据库：jstopenapi（已建库+导入full-schema.sql+schedule-timeout-task.sql）
|
||
- MySQL权限：设为"所有人"（允许Docker容器通过host.docker.internal访问）
|
||
- Docker部署：docker-compose.yml已配好（DB_URL/REDIS_HOST用host.docker.internal，JWT/API签名密钥已生成）
|
||
- application-prod.yml：已创建（和dev相同配置，环境变量由docker-compose传入）
|
||
- Dockerfile：已改为multi-stage（JDK17），但服务器上用的是简单版（本地打包jar上传+COPY）
|
||
- 部署方式：本地mvn打包 -> scp上传jar -> docker-compose build/up
|
||
- **已知问题**：MySQL的max_connect_errors封锁Docker容器IP，需 `mysql -uroot -p -e "FLUSH HOSTS;"` 解除后重启容器
|
||
- **部署状态**：jar已上传，application-prod.yml已包含，正在解决MySQL连接封锁问题
|
||
|
||
## 已完成的功能
|
||
|
||
### 1. 橘视厅媒资接口（/manage/jetsen-media/**，JWT鉴权）
|
||
- catalog-tree/list/search/export/nav/tags
|
||
- 栏目树（一级+二级），list必须用二级栏目id（如472=3221条）
|
||
- orderinfo:"1"必须带
|
||
|
||
### 2. 第三方开放接口（/openapi/partner/**，appKey签名鉴权）
|
||
- PartnerSignFilter：MD5(appKey+timestamp+nonce+appSecret).toUpperCase()，5分钟有效+nonce防重放
|
||
- 媒资接口（/openapi/partner/media/）：package/catalog-tree/list/search
|
||
- 三级授权：CONTENT(单部内容)>CATALOG(栏目)>FULL(全量)，按open_api_content_package配置判定
|
||
- 天卡代销（/openapi/partner/card/）：consume(消耗天卡绑定设备)/stock(库存)
|
||
- 调用日志：open_api_call_log
|
||
|
||
### 3. 代销模式
|
||
- 采购：POST /manage/partner-card/purchase（平台卡池UNUSED->RESERVED，记入partner池子AVAILABLE）
|
||
- 消耗：POST /openapi/partner/card/consume（partner池子取1张，绑定设备，RESERVED->USED，异步激活橘视厅）
|
||
- 回退：POST /manage/partner-card/revert（AVAILABLE的天卡回退，RESERVED->UNUSED，partner池子DISABLED）
|
||
- 免activationCode init：/api/jst/init不传activationCode时按设备标识查找已注册设备（代销模式）
|
||
- APK流程：consume消耗天卡 -> APK init(免activationCode) -> checkBenefits拿thirdCardNo -> 播放
|
||
|
||
### 4. 内容包管理（/manage/content-package/**，JWT鉴权）
|
||
- CRUD + fetch-contents（从橘视厅拉内容预览）+ save-from-selection（勾选内容一键保存）
|
||
- info/info-by-partner返回contentList（解析后的内容数组）
|
||
- save-from-selection支持传id覆盖更新
|
||
|
||
### 5. 接口风格统一
|
||
- 所有接口返回：{code:0, msg:"success", data:{...}}
|
||
- APK设备接口原code:200已改0，sign从顶层移入data
|
||
- UI接口原retCode:"00000000"已改{code:0,msg,data}
|
||
- 管理后台R.ok().put()全部改R.dataSuccess()（数据在data内）
|
||
- 路径统一：/sys/管理接口移到/manage/（仅login/refresh/logout保留/sys/）
|
||
- 合作伙伴管理从/openapi/partner移到/manage/partner（JWT鉴权）
|
||
- 删除冗余DayCardPoolController（和DayCardManageController冲突）
|
||
|
||
### 6. 审计日志
|
||
- audit_log表已重建（字段对齐AuditLogEntity）
|
||
- 46个@AuditAction审计点（资金/资产/设备/组织写操作）
|
||
- AuditLogAspect切面自动记录
|
||
|
||
## 数据库关键表
|
||
- 合作伙伴：open_api_partner（appKey/appSecret）
|
||
- 内容包：open_api_content_package（partnerId/catalogIds/contentCodes）
|
||
- partner天卡池：open_api_partner_card_pool（partnerId/poolId/cardCode/status）
|
||
- 调用日志：open_api_call_log
|
||
- 审计日志：audit_log（已重建）
|
||
- 天卡池：day_card_pool（UNUSED->RESERVED->USED->REUSABLE）
|
||
- 设备：device（含androidId/manufacturer/model/brand扩展字段）
|
||
|
||
## 测试验证状态
|
||
- ✅ 媒资接口（4个）+ appKey签名鉴权 + 三级授权过滤
|
||
- ✅ 采购天卡 + 消耗天卡 + 回退天卡
|
||
- ✅ 内容包配置（fetch-contents + save-from-selection）
|
||
- ✅ 禁用合作伙伴 -> 鉴权失败
|
||
- ✅ 删除内容包 -> FULL全量fallback
|
||
- ✅ 管理后台前端已适配新路径和返回格式
|
||
|
||
## 待处理事项
|
||
1. **服务器部署**：解决MySQL连接封锁后重启Docker容器，验证启动成功
|
||
2. **直营模式**（方式2）：EPG调开放订单接口 -> 微信支付 -> 自动发卡（未开发）
|
||
3. **旧代码清理**：DayCardSettleController(旧分账)/MediaController(桩)/ContractServiceImpl(桩)等废弃代码
|
||
4. **Nginx反代+HTTPS**：宝塔配反代，第三方用域名调用
|
||
5. **前端菜单**：合作伙伴管理/内容包管理/天卡池管理的菜单页面
|
||
|
||
## 关键配置
|
||
- docker-compose.yml：DB_URL=jstopenapi, REDIS_HOST=host.docker.internal, JWT_SECRET=2F064BA10037477FBB3A1BF9D508AE96, API_SIGN_SECRET=5F2A2DD8BFBA4DA1B87EFBB405671B3D
|
||
- application-prod.yml：和dev相同，环境变量传入
|
||
- Druid wall filter：dev和prod都禁用（不兼容SKIP LOCKED）
|
||
- Lombok：1.18.24，必须用JDK17编译（JDK21+不兼容）
|
||
|
||
## 合作伙伴测试数据（本地dev-0418）
|
||
- 华住酒店：partnerId=0f91ea23961e4983, appKey=b9f9542e1e044466, appSecret=d117d67429b941c1bc0e0f6044e39d62
|
||
- 测试合作伙伴：partnerId=1, appKey=71df57e7e47a4a88, appSecret=512f147432124bb48b313365ee31b87b
|
||
- 内容包：id=3, name=高分3部, catalogIds=472, contentCount=3, CONTENT级别
|