API_SERVER.md 19 KB
ColorMapRun 后端 API 接口文档
本文档描述了 H5 页面需要调用的后端接口。
1. 基础说明
- 接口域名:
- 开发环境:
https://t-mapi.colormaprun.com/api/card/ - 生产环境:
https://colormaprun.com/api/card/
- 开发环境:
- OSS 资源域名:
http://oss-card.colormaprun.com/card/ - 请求方式:
POST - Content-Type:
application/x-www-form-urlencoded - 鉴权: 所有接口需要在 Header 中携带
token。
1.1 请求头 (Headers)
| 参数名 | 必选 | 说明 | 示例 |
|---|---|---|---|
Content-Type |
是 | 固定值 | application/x-www-form-urlencoded |
token |
是 | 用户身份令牌 | 96ba3c924394934f7d30fa869a94ce0d |
1.2 响应结构 (Response)
所有接口返回 JSON 格式数据：
{
"code": 0, // 0 表示成功，非 0 表示失败
"message": "成功", // 提示信息
"data": { ... } // 业务数据，下文中的“返回数据”均指此 data 字段的内容
}
2. API 封装方法 (调用 window.API 对象)
2.1 获取 OSS 资源基础地址
- API 方法:
API.getOssUrl() - 说明: 获取图片、视频等静态资源的访问基础 URL。第三方开发者可自行拼接完整资源路径。
- 参数: 无
- 返回:
string(OSS 基础 URL)
2.2 接口列表
1. 卡片与配置
1.1 卡片基本信息查询
- API 方法:
API.getCardBase(ecId) - 参数:
ecId(int) - 返回数据:
json { "ecName": "活动名称", "ecDesc": "活动描述", "beginSecond": 1700000000, // 开始时间戳 "endSecond": 1700090000, // 结束时间戳 "secondCardName": "跳转页面名称" }
- API 方法:
1.2 卡片通用配置查询
- API 方法:
API.getCardConfig(ecId, pageName) - 参数:
ecId(int): 卡片/活动 IDpageName(string): 页面名称 (如 "all", "rankList", "index")
- 返回数据:
json { "configJson": "{\"css\": \"string\", \"tabActiveColor\": \"string\", \"popupRuleConfig\": {...}, \"popupRuleList\": [...]}" }* configJson 字段说明 (示例): *css:string，动态注入到页面的 CSS 样式。 *tabActiveColor:string，Tab 栏选中颜色，如 "#FF5733"。 *teamType:int，队伍类型 (0:默认, 1:学生/家长)。 *popupRuleConfig:object，规则弹窗组件的样式配置，如{ "height": "500px", "theme": "light" }。 *popupMessageConfig:object，消息弹窗组件的样式配置。 *popupHelpConfig,popupWarnConfig,popupExchgConfig:object，其他类型弹窗的配置。 *popupRuleList:array<object|string>，规则弹窗的内容列表，元素可以是{ "type": 1, "data": { "title": "标题", "content": "HTML 内容", "logo": {"src": "...", "width": "..."} } }，也可以是字符串 "default" 或 "default2" (表示加载预设内容)。 *popupExchgList,popupHelpList:array<object>，其他类型弹窗的内容列表。 *popupDataList:array<object|string>，通用弹窗内容列表，用于显示自定义弹窗信息，支持default/default2关键字加载预设内容。 * 注意：configJson结构灵活，字段是动态的，取决于后台配置，开发者应做好判空处理。
- API 方法:
1.3 用户个性化配置查询
- API 方法:
API.getUserConfig(ecId, pageName) - 参数:
ecId(int),pageName(string) - 返回数据:
json { "configJson": "{\"tplInfo\": {...}, \"mapInfo\": [...], \"popupRuleList\": [...]}" }* configJson 字段说明 (示例): *tplInfo:object，模板信息，如{ "tplTypeId": 1, "ssctId": 1 }。 *mapInfo:array<object>，地图相关信息，如[{"activityList": [{"showName": "路线名称", "point": {"longitude": 117, "latitude": 36}}]}]。 *popupRuleList:array<object>，用户专属规则弹窗内容。 * 注意：结构灵活，字段是动态的，取决于后台配置，开发者应做好判空处理。
- API 方法:
2. 活动与报名
2.1 卡片对应活动或赛事详情查询
- API 方法:
API.getCardDetail(ecId) - 参数:
ecId(int) - 返回数据:
json { "mcId": 101, "mcName": "赛事名称", "mcType": 1, // 1:普通 2:线下 3:线上 "beginSecond": 1700000000, "endSecond": 1700090000, "teamNum": 0, // 0:个人, >0:团队 "coiId": 1, // 已报名单位ID "coiName": "已报名单位名称", "ocaId": 201 // 关联活动详情ID (用于跳转) }
- API 方法:
2.2 用户是否已报名卡片对应赛事查询
- API 方法:
API.getUserJoinStatus(ecId) - 参数:
ecId(int) - 返回数据:
json { "isJoin": true // true: 已报名, false: 未报名 }
- API 方法:
2.3 线上赛报名 (重新分组)
- API 方法:
API.signUpOnline(mcId, coiId, selectTeam, nickName) - 参数:
mcId(int),coiId(opt),selectTeam(opt),nickName(opt) - 返回数据:
{}(空对象表示成功)
- API 方法:
2.4 是否允许重新分组（报名）
- API 方法:
API.isAllowMcSignUp(ecId) - 参数:
ecId(int) - 返回数据:
json { "allowSignUp": true }
- API 方法:
2.5 线上赛报名页面信息详情
- API 方法:
API.getOnlineMcSignUpDetail(ecId, mcId) - 参数:
ecId(int),mcId(int) - 返回数据: ```json { "teamList": [ // 可选的团队列表 { "teamId": 1, "teamName": "红队" }, { "teamId": 2, "teamName": "蓝队" } ], "signupFields": [ // 报名所需字段，示例 { "name": "phone", "label": "手机号", "type": "text", "required": true } ] }
- API 方法:
2.6 卡片对应线上赛多个活动查询 (用户赛事结果详情)
- API 方法:
API.getMatchRsDetail(ecId, ocaId) - 参数:
ecId(int),ocaId(int) - 返回数据: (Array) - 返回用户在卡片关联的各个赛事中的具体成绩详情
json [ { "mcId": 101, "mcName": "赛事名称", "mcType": 1, "beginSecond": 1700000000, "endSecond": 1700090000, "status": 1, // 状态 "nickName": "用户昵称", // 用户在赛事中的昵称 "totalNum": 10, // 总场次/次数 "totalDistanct": 5000, // 总距离 (米) "totalDistanctRankNum": 5, // 总距离排名 "totalCp": 20, // 总打点数 "totalCpRankNum": 3, // 总打点数排名 "totalSysPoint": 100, // 总积分/百味豆 "totalSysPointRankNum": 10, // 总积分排名 "fastPace": 300, // 最快配速 (秒/公里) "fastPaceRankNum": 8 // 最快配速排名 } }
- API 方法:
2.7 用户在卡片对应赛事是否新用户
- API 方法:
API.isNewUserInCardComp(ecId) - 参数:
ecId(int) - 返回数据:
json { "isNew": true // true: 是新用户, false: 不是 }
- API 方法:
3. 排名与成就
3.1 排名查询
- API 方法:
API.getRankDetail(mcIdListStr, mcType, ocaId, dispArrStr) - 参数:
mcIdListStr(string),mcType(int),ocaId(int),dispArrStr(string) - 返回数据:
json { "totalRankRs": [ // 总榜 { "nickName": "张三", "score": 10000, "headUrl": "http://...", "rankNum": 1 } ], "teamRankRs": [], // 队伍榜 "inTeamRs": [] // 队内榜 }
- API 方法:
3.1.1 月挑战排名查询 (月榜)
- API 方法:
API.getMonthRankDetail(year, month, dispArrStr) - 参数:
year(int): 年份，如 2025month(int): 月份，1-12dispArrStr(string): 固定传grad,mapNum（分别返回个人榜、场地榜）
示例:
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \ -d "year=2025&month=11&dispArrStr=grad,mapNum" \ https://colormaprun.com/api/card/MonthRankDetailQuery- 返回数据:
json { "gradRs": [ { "userName": "张三", "rankNum": 1, "inRankNum": 264, "isSelf": 0, "isInGame": 0 }, ... ], "mapNumRs": [ { "userName": "Q", "rankNum": 1, "inRankNum": 1, "isSelf": 0, "isInGame": 0 }, ... ] }说明: 部分环境允许不带 token 访问月榜；若需鉴权同样在 Header 携带token。
- 返回数据:
- API 方法:
3.2 卡片用户当前排名查询
- API 方法:
API.getUserCurrentRank(ecId) - 参数:
ecId(int) - 返回数据:
json { "rankNum": 5 // 当前排名，0表示未上榜 }
- API 方法:
3.3 玩家所有月挑战记录查询
- API 方法:
API.getMonthlyChallenge() - 参数: 无
- 返回数据: (Array)
json [ { "year": "2023", "monthRs": [ { "month": 10, "realNum": 5, // 实际完成 "targetNum": 10 // 目标 } ] } ]
- API 方法:
3.4 玩家活动成就查询
- API 方法:
API.getAchievement() - 参数: 无
- 返回数据: (Array)
json [ { "year": "2023", "aiRs": [ { "aiName": "完赛奖牌", "aiTime": 1700000000, "iconUrl": "http://..." } ] } ]
- API 方法:
3.5 赛事总成绩统计查询
- API 方法:
API.getCompStatistic(mcId) - 参数:
mcId(int) - 返回数据:
json { "totalDistance": 123.45, // 总里程 "totalPeople": 1000, // 总参与人数 "totalRightAnswerNum": 500, // 总正确答题数 "totalAnswerNum": 800, // 总答题数 "totalCp": 2000, // 总打点数 "totalSysPoint": 5000 // 总积分/百味豆 }
- API 方法:
3.6 玩家当前月挑战记录查询
- API 方法:
API.getCurrentMonthlyChallenge(year, month) - 参数:
year(int): 可选，默认当年month(int): 可选，默认当月
- 返回数据:
json { "month": 11, "realNum": 10, // 实际完成次数 "targetNum": 20 // 目标次数 }
- API 方法:
4. 积分与兑换
4.1 卡片内可用积分查询
- API 方法:
API.getScore(ecId) - 参数:
ecId(int) - 返回数据:
json { "score": 880, "extTime": 1700000000 // 过期时间 }
- API 方法:
4.2 积分可兑换商品列表查询
- API 方法:
API.getGoodsList(ecId) - 参数:
ecId(int) - 返回数据: (Array)
json [ { "goodsId": 1, "goodsName": "商品A", "goodsPic": "/static/...", // 需拼接 OSS Url "goodsLeftNum": 99, "corrScore": 100 } ]
- API 方法:
4.3 积分兑换商品
- API 方法:
API.exchangeGoods(ecId, goodsId, exchNum) - 参数:
ecId(int),goodsId(int),exchNum(int, 可选, 默认1) - 返回数据:
{}(成功)
- API 方法:
4.4 玩家兑换记录查询
- API 方法:
API.getExchangeList() - 参数: 无
- 返回数据: (Array)
json [ { "exchangeId": 123, "goodsName": "商品A", "createTime": 1700000000, "status": 1 // 1:成功 } ]
- API 方法:
4.5 玩家兑换详情查询
- API 方法:
API.getExchangeDetail(oarId) - 参数:
oarId(int) - 返回数据:
json { "exchangeId": 1, "goodsName": "商品名称", "createTime": 1700000000, "status": 1, "address": "收货地址", "receiver": "收件人", "phone": "联系电话" }
- API 方法:
4.6 积分可兑换商品详情
- API 方法:
API.getGoodsDetail(ecId, goodsId) - 参数:
ecId(int),goodsId(int) - 返回数据:
json { "goodsId": 1, "goodsName": "商品名称", "goodsPic": "http://...", "corrScore": 500, // 所需积分 "goodsLeftNum": 99, // 剩余库存 "goodsUnit": "个", // 单位 "goodsDesc": "HTML描述内容", "exchDesc": "HTML兑换说明", "exchLimit": 3 // 个人兑换上限 }
- API 方法:
5. 消息与通知
5.1 未读消息列表查询
- API 方法:
API.getUnReadMessages(relationId, relationType) - 参数:
relationId(int),relationType(int) - 返回数据: (Array)
json [ { "mqId": 1, "mqType": 1, // 1:成就, 3:系统 "mqTitle": "标题", "mqMessage": "内容", "iconUrl": "http://..." } ]
- API 方法:
5.2 警告列表查询
- API 方法:
API.getWarnMessage(ecId) - 参数:
ecId(int) - 返回数据: (Array)
json [ { "warnType": 1, "warnTitle": "黄牌警告", "warnMessage": "您违规了...", "iconUrl": "http://..." } ]
- API 方法:
5.3 标记消息已读
- API 方法:
API.readMessage(mqIdListStr) - 参数:
mqIdListStr(string) - 消息ID列表字符串，如 "1,2,3" - 返回数据:
{}(成功)
- API 方法:
6. 网格游戏
- 6.1 网格卡片信息查询
- API 方法:
API.getGrids(ecId) - 参数:
ecId(int) - 返回数据:
json { "compId": 101, "compName": "网格赛", "widthNum": 3, "heightNum": 3, "maskImgPic": "http://...", "actualImgPic": "http://...", "state": 2, // 1:未开始 2:进行中 3:已结束 "detailRs": [ { "orderNum": 1, // 格子序号 "isComplete": 1, // 1:点亮 0:未点亮 "showName": "格子1", "relationType": 1, // 1:活动详情 2:活动列表 3:地图列表 "ocaId": 201, // 关联活动ID (relationType=1时有效) "mapId": 0, // 关联地图ID (relationType=2时有效) "description": "描述信息", "popupImg": "http://...", // 弹窗图片 "longitude": 117.0, "latitude": 36.0 } ] }
- API 方法:
7. 电子证书
7.1 查询电子证书样式
- API 方法:
API.getCertStyle(certStyleType) - 参数:
certStyleType(int) - 返回数据:
json { "styleId": 1, "styleName": "默认样式", "templateUrl": "http://...", // 证书模板图片 URL "elements": [ { "type": "text", "field": "userName", "x": 100, "y": 200, "fontSize": 20, "color": "#000" } // 更多元素配置，如位置、字体、颜色 ] }
- API 方法:
7.2 查询电子证书成就对应用户基本信息
- API 方法:
API.getUserBaseInCertificate(oarId) - 参数:
oarId(int) - 返回数据:
json { "userName": "用户名称", "activityName": "活动名称", "completionTime": 1700000000 // 完成时间戳 }
- API 方法:
7.3 根据成就信息确认生成电子证书
- API 方法:
API.createCertificate(nickName, oarId) - 参数:
nickName(string): 用户昵称oarId(int): 订单活动记录ID
- 返回数据:
json { "certUrl": "http://example.com/generated_cert.png" // 生成的证书图片 URL }
- API 方法:
8. 其他辅助接口
- 8.1 用户基本信息查询
- API 方法:
API.getUserInfo() - 参数: 无
- 返回数据:
json { "nickName": "用户昵称", "headUrl": "http://..." }
- API 方法:
8.2 卡片对应地图列表详情查询
- API 方法:
API.getMapList(mcId) - 参数:
mcId(int) - 返回数据: (Array)
json [ { "mapId": 1, "mapName": "奥体中心", "latitude": 36.666, "longitude": 117.123, "activityList": [ { "ocaId": 101, "showName": "迷你跑" } ] } ]
- API 方法:
8.3 卡片URL查询
- API 方法:
API.getCardUrl(actId, matchType) - 参数:
actId(int),matchType(int) - 返回数据:
json { "url": "http://example.com/card/detail.html?id=123" // 卡片对应的H5页面URL }
- API 方法:
8.4 赛事完赛信息查询
- API 方法:
API.getMatchFinishInfo(actId, matchType) - 参数:
actId(int),matchType(int) - 返回数据:
{}(待定)
- API 方法:
8.5 Redis 重建 (管理接口)
- API 方法:
API.redisRebuild(compId) - 参数:
compId(int) - 返回数据:
{}(待定)
- API 方法: