zhaogd/as-daycard-openapi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
73d0d42e8fcf38e2a664a36adfa218198239448d
as-daycard-openapi/HANDOVER.md
zhaogd 30198c7191 初始化天卡开放平台后端项目 
包含完整功能模块：
- 设备激活（直销激活码模式 + 代销免激活码模式）
- 微信支付 + 天卡订单
- 天卡池管理 + 异步橘视厅SDK激活
- 第三方合作伙伴接口（代销模式）
  - 签名鉴权（appKey/appSecret + nonce防重放）
  - 天卡消耗（事务 + 幂等 + 并发控制）
  - 媒资接口（三级授权过滤）
  - 审计日志
- 定价策略（3层：门店 > 渠道 > 平台）
- 分账（微信分账 + 分润规则）
- Docker部署（含Redis容器）
2026-07-26 12:34:13 +08:00

5.7 KiB
Raw Blame History

后端项目交接文档

项目信息

  • 路径：/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级别