# 天卡开放平台 · 接口对接文档

> 项目：as-daycard-openapi | 端口：8084 | 更新：2026-07-22

---

## 一、统一规范

### 返回格式（所有接口统一）

```json
{"code": 0, "msg": "success", "data": {...}}
```
- `code=0` 成功，非0失败
- `data` 业务数据，统一放在 data 字段内
- 错误时：`{"code": 错误码, "msg": "错误信息", "data": {}}`

### 接口分类

| 分类 | 路径前缀 | 鉴权 | 请求头 | 调用方 |
|------|---------|------|--------|--------|
| 管理后台 | `/manage/**`、`/sys/login` | JWT | `token` | 浏览器前端 |
| 第三方开放 | `/openapi/partner/**` | appKey签名 | `appKey`/`timestamp`/`nonce`/`sign` | 第三方EPG |
| APK设备 | `/api/jst/**` | 设备sign | `sign` | 我们APK |
| 支付回调 | `/openapi/payment/**`、`/openapi/settle/**` | 无 | - | 微信服务器 |

---

## 二、管理后台接口（JWT鉴权）

**鉴权**：请求头 `token: <登录返回的token>`  
**登录**：`POST /sys/login`（免鉴权）返回 token  
**返回**：`{code:0, msg:"success", data:{...}}`

### 2.1 登录鉴权

| 路径 | 方法 | 说明 |
|------|------|------|
| `POST /sys/login` | POST | 登录（username/password/uuid/captcha），返回token+refreshToken |
| `POST /sys/refresh` | POST | 刷新token（refreshToken） |
| `POST /sys/logout` | POST | 退出登录 |
| `GET /captcha.jpg` | GET | 验证码图片（参数uuid） |

### 2.2 用户管理 `/manage/user`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/user/list` | GET | 用户列表（分页） |
| `/manage/user/info` | GET | 当前登录用户信息 |
| `/manage/user/info/{userId}` | GET | 用户详情 |
| `/manage/user/save` | POST | 保存用户 |
| `/manage/user/update` | POST | 修改用户 |
| `/manage/user/delete` | POST | 删除用户 |
| `/manage/user/password` | POST | 修改密码 |

### 2.3 角色管理 `/manage/role`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/role/list` | GET | 角色列表 |
| `/manage/role/select` | GET | 角色下拉 |
| `/manage/role/info/{roleId}` | GET | 角色详情（含menuIdList） |
| `/manage/role/save` | POST | 保存角色 |
| `/manage/role/update` | POST | 修改角色 |
| `/manage/role/delete` | POST | 删除角色 |

### 2.4 菜单管理 `/manage/menu`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/menu/nav` | GET | 当前用户菜单+权限 |
| `/manage/menu/list` | GET | 菜单列表 |
| `/manage/menu/select` | GET | 菜单下拉 |
| `/manage/menu/info/{menuId}` | GET | 菜单详情 |
| `/manage/menu/save` | POST | 保存菜单 |
| `/manage/menu/update` | POST | 修改菜单 |
| `/manage/menu/delete/{menuId}` | POST | 删除菜单 |

### 2.5 组织管理 `/manage/org`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/org/list` | GET | 组织列表（树） |
| `/manage/org/tree` | GET | 组织树（下拉） |
| `/manage/org/all-tree` | GET | 组织树（含门店） |
| `/manage/org/list-data` | GET | 组织列表（扁平） |
| `/manage/org/channels` | GET | 渠道列表 |
| `/manage/org/channel/{channelId}/agent-tree` | GET | 渠道下代理树 |
| `/manage/org/{orgId}/card-stats` | GET | 组织卡统计 |
| `/manage/org/card-type-detail-stats` | GET | 卡类型明细统计 |
| `/manage/org/card-overview` | GET | 组织卡概览 |
| `/manage/org/{orgId}/same-channel-orgs` | GET | 同渠道组织树 |
| `/manage/org/info/{id}` | GET | 组织详情 |
| `/manage/org/save` | POST | 保存组织 |
| `/manage/org/update` | POST | 修改组织 |
| `/manage/org/delete` | POST | 删除组织 |

### 2.6 门店管理 `/manage/store`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/store/list` | GET | 门店列表 |
| `/manage/store/list-by-agent/{agentOrgId}` | GET | 按代理商列门店 |
| `/manage/store/search` | GET | 门店搜索（分页） |
| `/manage/store/{storeOrgId}/cards` | GET | 门店绑定卡列表 |

### 2.7 合同权益 `/manage/contract`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/contract/by-store` | POST | 按门店查权益激活码 |

### 2.8 天卡激活码 `/manage/daycard/activation-code`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/daycard/activation-code/list/{storeOrgId}` | GET | 按门店查激活码 |
| `/manage/daycard/activation-code/generate` | POST | 生成激活码 |
| `/manage/daycard/activation-code/{id}/regenerate` | POST | 重新生成code |
| `/manage/daycard/activation-code/{id}/status` | PUT | 启用/禁用 |
| `/manage/daycard/activation-code/{id}` | DELETE | 删除激活码 |

### 2.9 天卡管理 `/manage/daycard`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/daycard/pool/list` | GET | 天卡池列表 |
| `/manage/daycard/pool/stats` | GET | 库存统计 |
| `/manage/daycard/pool/import` | POST | 导入天卡卡密 |
| `/manage/daycard/order/list` | GET | 天卡订单列表 |
| `/manage/daycard/list` | GET | 天卡订单列表 |
| `/manage/daycard/info/{orderNo}` | GET | 订单详情 |
| `/manage/daycard/benefits/{deviceId}` | GET | 设备天卡权益 |
| `/manage/daycard/device/unbind` | POST | 解绑设备天卡 |
| `/manage/daycard/device/unbind-org` | POST | 设备组织解绑 |

### 2.10 天卡定价 `/manage/price`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/price/list` | GET | 定价策略列表 |
| `/manage/price/info/{id}` | GET | 定价详情 |
| `/manage/price/effective` | GET | 生效中定价（门店>渠道>平台） |
| `/manage/price/save` | POST | 新增定价 |
| `/manage/price/update` | POST | 修改定价 |
| `/manage/price/delete` | POST | 删除定价 |

### 2.11 天卡退款 `/manage/refund`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/refund/list` | GET | 退款记录列表 |
| `/manage/refund/info/{refundNo}` | GET | 退款详情 |
| `/manage/refund/apply` | POST | 发起退款（orderNo+reason） |

### 2.12 分润规则 `/manage/profit-rule`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/profit-rule/list` | GET | 分润规则列表 |
| `/manage/profit-rule/info/{id}` | GET | 规则详情（含items） |
| `/manage/profit-rule/save` | POST | 新增分润规则 |
| `/manage/profit-rule/update` | POST | 修改分润规则 |
| `/manage/profit-rule/delete` | POST | 删除分润规则 |
| `/manage/profit-rule/preview` | POST | 分润试算（超30%告警） |

### 2.13 分账查询 `/manage/profit-sharing`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/profit-sharing/list` | GET | 分账单列表（含details） |
| `/manage/profit-sharing/info/{id}` | GET | 分账单详情 |
| `/manage/profit-sharing/stats` | GET | 分账统计（按日期/组织） |

### 2.14 分账接收方 `/manage/profit-receiver`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/profit-receiver/list` | GET | 接收方列表 |
| `/manage/profit-receiver/info/{id}` | GET | 接收方详情 |
| `/manage/profit-receiver/save` | POST | 新增接收方 |
| `/manage/profit-receiver/delete` | POST | 删除接收方 |
| `/manage/profit-receiver/sync/{id}` | POST | 同步到微信 |

### 2.15 设备管理 `/manage/device`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/device/list` | GET | 设备列表 |
| `/manage/device/info/{id}` | GET | 设备详情 |
| `/manage/device/save` | POST | 新增设备 |
| `/manage/device/update` | POST | 修改设备 |
| `/manage/device/delete` | POST | 删除设备 |
| `/manage/device/bindStore` | POST | 绑定门店 |

### 2.16 支付配置 `/manage/payconfig`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/payconfig/list` | GET | 支付配置列表 |
| `/manage/payconfig/info/{id}` | GET | 配置详情 |
| `/manage/payconfig/save` | POST | 新增配置 |
| `/manage/payconfig/update` | POST | 修改配置 |
| `/manage/payconfig/delete` | POST | 删除配置 |

### 2.17 统计看板 `/manage/stats`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/stats/overview` | GET | 总览看板 |
| `/manage/stats/orders` | GET | 订单趋势（startDate/endDate） |
| `/manage/stats/pool` | GET | 库存统计 |
| `/manage/stats/channels` | GET | 渠道统计 |

### 2.18 橘视厅媒资 `/manage/jetsen-media`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/jetsen-media/nav` | GET | 首页导航 |
| `/manage/jetsen-media/tags` | GET | 栏目标签（parentid） |
| `/manage/jetsen-media/catalog-tree` | GET | 栏目树（一级+二级） |
| `/manage/jetsen-media/list` | GET | 内容列表（catalogid必填） |
| `/manage/jetsen-media/search` | GET | 搜索（keyword） |
| `/manage/jetsen-media/export` | GET | 导出Excel |

### 2.19 合作伙伴管理 `/manage/partner`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/partner/list` | GET | 合作伙伴列表 |
| `/manage/partner/info/{id}` | GET | 合作伙伴详情 |
| `/manage/partner/save` | POST | 新增（自动生成appKey/appSecret） |
| `/manage/partner/update` | POST | 修改 |
| `/manage/partner/delete` | POST | 删除 |

### 2.20 内容包管理 `/manage/content-package`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/content-package/list` | GET | 内容包列表 |
| `/manage/content-package/info/{id}` | GET | 内容包详情 |
| `/manage/content-package/info-by-partner/{partnerId}` | GET | 按partner查内容包 |
| `/manage/content-package/save` | POST | 新增内容包 |
| `/manage/content-package/update` | POST | 修改内容包 |
| `/manage/content-package/delete` | POST | 删除内容包 |

### 2.21 天卡采购 `/manage/partner-card`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/manage/partner-card/purchase` | POST | 采购天卡（partnerId+quantity） |
| `/manage/partner-card/stock` | GET | partner库存查询 |
| `/manage/partner-card/list` | GET | 池子记录分页 |

---

## 三、第三方开放接口（appKey签名鉴权）

### 鉴权说明

**签名算法**：`sign = MD5(appKey + timestamp + nonce + appSecret).toUpperCase()`

**请求头**：

| 请求头 | 说明 |
|--------|------|
| appKey | 平台分配的应用Key |
| timestamp | 毫秒时间戳（5分钟有效） |
| nonce | 随机串（5分钟防重放） |
| sign | 签名（大写MD5） |

**返回**：`{code:0, msg:"", data:{...}}`  
**鉴权失败**：HTTP 401 `{code:401, msg:"错误描述"}`

### 3.1 媒资接口 `/openapi/partner/media`

**三级授权**：CONTENT(单部内容) > CATALOG(栏目) > FULL(全量)

| 路径 | 方法 | 参数 | 说明 |
|------|------|------|------|
| `/openapi/partner/media/package` | GET | 无 | 查看授权范围 |
| `/openapi/partner/media/catalog-tree` | GET | 无 | 栏目树（按授权过滤） |
| `/openapi/partner/media/list` | GET | catalogid,pageindex,pagesize | 内容列表（按授权过滤） |
| `/openapi/partner/media/search` | GET | keyword,pageindex,pagesize | 搜索（按授权过滤） |

### 3.2 天卡代销 `/openapi/partner/card`

| 路径 | 方法 | 参数 | 说明 |
|------|------|------|------|
| `/openapi/partner/card/consume` | POST | body:{mac,deviceUid,deviceSn,channelOrgId} | 消耗天卡：分配1张绑定设备+异步激活 |
| `/openapi/partner/card/stock` | GET | 无 | 我的可用天卡库存 |

**consume返回**：
```json
{"code":0,"msg":"","data":{"deviceId":123,"thirdCardNo":"xxx","cardCode":"xxx","expireAt":"...","status":"ACTIVE"}}
```

---

## 四、APK设备接口（设备sign鉴权）

### 鉴权说明
- **sign获取**：`POST /api/jst/init` 返回sign（在data内）
- **sign校验**：后续请求头携带 `sign`
- **免sign接口**：`POST /api/jst/init`
- **返回**：`{code:0, msg:"success", data:{...}}`

### 4.1 设备接口 `/api/jst`

| 路径 | 方法 | 鉴权 | 说明 |
|------|------|------|------|
| `/api/jst/init` | POST | 无 | 设备初始化，返回sign。**代销模式**：不传activationCode时按设备标识查找已注册设备 |
| `/api/jst/checkBenefits` | POST | sign | 查询天卡权益（ACTIVE返回thirdCardNo/UNBOUND） |
| `/api/jst/price` | POST | sign | 查询天卡价格（3层匹配） |
| `/api/jst/daycard/create` | POST | sign | 创建天卡订单（返回codeUrl二维码） |
| `/api/jst/daycard/status/{orderNo}` | GET | sign | 查询支付状态 |
| `/api/jst/heartBeat` | POST | sign | 心跳续期sign |
| `/api/jst/refreshSign` | POST | sign | 刷新sign（旧sign失效） |

**init请求体**：
```json
{"activationCode":"激活码(代销模式不传)","mac":"设备MAC","deviceUid":"设备标识","deviceSn":"序列号"}
```

**init返回**：
```json
{"code":0,"msg":"success","data":{"device":{"deviceId":123,"roomNo":"001"},"sign":"xxx"}}
```

### 4.2 UI数据接口 `/api/jst`

| 路径 | 方法 | 说明 |
|------|------|------|
| `/api/jst/topButtons` | POST | 顶栏按钮（logo/搜索/帮助） |
| `/api/jst/filter/tags` | POST | 筛选分类（栏目/类型/地区/年代） |
| `/api/jst/filter/content` | POST | 筛选内容列表 |
| `/api/jst/config` | GET | 独立配置（logoUrl+loginBg） |

### 4.3 APK调用流程

```
正常模式：init(activationCode) -> checkBenefits -> 无权益则price+create+支付+status -> checkBenefits拿thirdCardNo播放
代销模式：第三方consume消耗天卡 -> APK init(免activationCode,传设备标识) -> checkBenefits拿thirdCardNo播放
```

---

## 五、支付回调接口（微信服务器调用）

| 路径 | 方法 | 说明 |
|------|------|------|
| `/openapi/payment/wechat/notify` | POST | 微信支付回调（验签+发卡） |
| `/openapi/payment/notify` | POST | 微信支付回调（旧路径兼容） |
| `/openapi/payment/refund/notify` | POST | 微信退款回调 |
| `/openapi/payment/wechat/profit-sharing/notify` | POST | 微信分账回调（明细级） |
| `/openapi/settle/notify` | POST | 微信分账回调（结算级） |

---

## 六、路径变更对照表（前端适配用）

| 旧路径 | 新路径 |
|--------|--------|
| `/sys/user/**` | `/manage/user/**` |
| `/sys/role/**` | `/manage/role/**` |
| `/sys/menu/**` | `/manage/menu/**` |
| `/sys/org/**` | `/manage/org/**` |
| `/sys/store/**` | `/manage/store/**` |
| `/sys/contract/**` | `/manage/contract/**` |
| `/sys/jetsen-media/**` | `/manage/jetsen-media/**` |
| `/openapi/partner/list` | `/manage/partner/list` |
| `/openapi/partner/info/**` | `/manage/partner/info/**` |
| `/openapi/partner/save` | `/manage/partner/save` |
| `/openapi/partner/update` | `/manage/partner/update` |
| `/openapi/partner/delete` | `/manage/partner/delete` |
| `/openapi/daycard/pool/**` | `/manage/daycard/pool/**`（已有，DayCardPoolController已删） |
| `/sys/login` | `/sys/login`（不变） |
| `/sys/refresh` | `/sys/refresh`（不变） |
| `/sys/logout` | `/sys/logout`（不变） |

## 七、返回格式变更对照

| 接口类型 | 旧格式 | 新格式 |
|---------|--------|--------|
| APK设备 | `{code:200, msg:"success", data:{...}}` | `{code:0, msg:"success", data:{...}}` |
| APK UI | `{retCode:"00000000", data:{...}}` | `{code:0, msg:"success", data:{...}}` |
| APK init | `{code:200,...,data:{device:{}},sign:"xxx"}` | `{code:0,...,data:{device:{},sign:"xxx"}}` |
| 管理后台 | `{code:0, msg:"success", page:{...}}` | `{code:0, msg:"success", data:{page:{...}}}` |