# 后端项目交接文档

## 项目信息
- 路径：/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级别