# 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 格式数据：

```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": "跳转页面名称"
        }
        ```

*   **1.2 卡片通用配置查询**
    *   **API 方法**: `API.getCardConfig(ecId, pageName)`
    *   **参数**:
        *   `ecId` (int): 卡片/活动 ID
        *   `pageName` (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` 结构灵活，字段是动态的，取决于后台配置，开发者应做好判空处理。*

*   **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>`，用户专属规则弹窗内容。
        *   *注意：结构灵活，字段是动态的，取决于后台配置，开发者应做好判空处理。*

#### 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 (用于跳转)
        }
        ```

*   **2.2 用户是否已报名卡片对应赛事查询**
    *   **API 方法**: `API.getUserJoinStatus(ecId)`
    *   **参数**: `ecId` (int)
    *   **返回数据**:
        ```json
        {
            "isJoin": true // true: 已报名, false: 未报名
        }
        ```

*   **2.3 线上赛报名 (重新分组)**
    *   **API 方法**: `API.signUpOnline(mcId, coiId, selectTeam, nickName)`
    *   **参数**: `mcId` (int), `coiId` (opt), `selectTeam` (opt), `nickName` (opt)
    *   **返回数据**: `{}` (空对象表示成功)

*   **2.4 是否允许重新分组（报名）**
    *   **API 方法**: `API.isAllowMcSignUp(ecId)`
    *   **参数**: `ecId` (int)
    *   **返回数据**:
        ```json
        {
            "allowSignUp": true
        }
        ```

*   **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 }
            ]
        }


*   **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 // 最快配速排名
            }
        }
        ```

*   **2.7 用户在卡片对应赛事是否新用户**
    *   **API 方法**: `API.isNewUserInCardComp(ecId)`
    *   **参数**: `ecId` (int)
    *   **返回数据**:
        ```json
        {
            "isNew": true // true: 是新用户, false: 不是
        }
        ```

#### 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": []    // 队内榜
          }
          ```

*   **3.1.1 月挑战排名查询 (月榜)**
    *   **API 方法**: `API.getMonthRankDetail(year, month, dispArrStr)`
    *   **参数**:
        *   `year` (int): 年份，如 2025
        *   `month` (int): 月份，1-12
        *   `dispArrStr` (string): 固定传 `grad,mapNum`（分别返回个人榜、场地榜）
    *   **示例**:
        ```bash
        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`。

*   **3.2 卡片用户当前排名查询**
    *   **API 方法**: `API.getUserCurrentRank(ecId)`
    *   **参数**: `ecId` (int)
    *   **返回数据**:
        ```json
        {
            "rankNum": 5 // 当前排名，0表示未上榜
        }
        ```

*   **3.3 玩家所有月挑战记录查询**
    *   **API 方法**: `API.getMonthlyChallenge()`
    *   **参数**: 无
    *   **返回数据**: (Array)
        ```json
        [
            {
                "year": "2023",
                "monthRs": [
                    {
                        "month": 10,
                        "realNum": 5, // 实际完成
                        "targetNum": 10 // 目标
                    }
                ]
            }
        ]
        ```

*   **3.4 玩家活动成就查询**
    *   **API 方法**: `API.getAchievement()`
    *   **参数**: 无
    *   **返回数据**: (Array)
        ```json
        [
            {
                "year": "2023",
                "aiRs": [
                    {
                        "aiName": "完赛奖牌",
                        "aiTime": 1700000000,
                        "iconUrl": "http://..."
                    }
                ]
            }
        ]
        ```

*   **3.5 赛事总成绩统计查询**
    *   **API 方法**: `API.getCompStatistic(mcId)`
    *   **参数**: `mcId` (int)
    *   **返回数据**:
        ```json
        {
            "totalDistance": 123.45, // 总里程
            "totalPeople": 1000, // 总参与人数
            "totalRightAnswerNum": 500, // 总正确答题数
            "totalAnswerNum": 800, // 总答题数
            "totalCp": 2000, // 总打点数
            "totalSysPoint": 5000 // 总积分/百味豆
        }
        ```

*   **3.6 玩家当前月挑战记录查询**
    *   **API 方法**: `API.getCurrentMonthlyChallenge(year, month)`
    *   **参数**: 
        *   `year` (int): 可选，默认当年
        *   `month` (int): 可选，默认当月
    *   **返回数据**:
        ```json
        {
            "month": 11,
            "realNum": 10, // 实际完成次数
            "targetNum": 20 // 目标次数
        }
        ```

#### 4. 积分与兑换

*   **4.1 卡片内可用积分查询**
    *   **API 方法**: `API.getScore(ecId)`
    *   **参数**: `ecId` (int)
    *   **返回数据**:
        ```json
        {
            "score": 880,
            "extTime": 1700000000 // 过期时间
        }
        ```

*   **4.2 积分可兑换商品列表查询**
    *   **API 方法**: `API.getGoodsList(ecId)`
    *   **参数**: `ecId` (int)
    *   **返回数据**: (Array)
        ```json
        [
            {
                "goodsId": 1,
                "goodsName": "商品A",
                "goodsPic": "/static/...", // 需拼接 OSS Url
                "goodsLeftNum": 99,
                "corrScore": 100
            }
        ]
        ```

*   **4.3 积分兑换商品**
    *   **API 方法**: `API.exchangeGoods(ecId, goodsId, exchNum)`
    *   **参数**: `ecId` (int), `goodsId` (int), `exchNum` (int, 可选, 默认1)
    *   **返回数据**: `{}` (成功)

*   **4.4 玩家兑换记录查询**
    *   **API 方法**: `API.getExchangeList()`
    *   **参数**: 无
    *   **返回数据**: (Array)
        ```json
        [
            {
                "exchangeId": 123,
                "goodsName": "商品A",
                "createTime": 1700000000,
                "status": 1 // 1:成功
            }
        ]
        ```

*   **4.5 玩家兑换详情查询**
    *   **API 方法**: `API.getExchangeDetail(oarId)`
    *   **参数**: `oarId` (int)
    *   **返回数据**:
        ```json
        {
            "exchangeId": 1,
            "goodsName": "商品名称",
            "createTime": 1700000000,
            "status": 1,
            "address": "收货地址",
            "receiver": "收件人",
            "phone": "联系电话"
        }
        ```

*   **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 // 个人兑换上限
        }
        ```

#### 5. 消息与通知

*   **5.1 未读消息列表查询**
    *   **API 方法**: `API.getUnReadMessages(relationId, relationType)`
    *   **参数**: `relationId` (int), `relationType` (int)
    *   **返回数据**: (Array)
        ```json
        [
            {
                "mqId": 1,
                "mqType": 1, // 1:成就, 3:系统
                "mqTitle": "标题",
                "mqMessage": "内容",
                "iconUrl": "http://..."
            }
        ]
        ```

*   **5.2 警告列表查询**
    *   **API 方法**: `API.getWarnMessage(ecId)`
    *   **参数**: `ecId` (int)
    *   **返回数据**: (Array)
        ```json
        [
            {
                "warnType": 1,
                "warnTitle": "黄牌警告",
                "warnMessage": "您违规了...",
                "iconUrl": "http://..."
            }
        ]
        ```

*   **5.3 标记消息已读**
    *   **API 方法**: `API.readMessage(mqIdListStr)`
    *   **参数**: `mqIdListStr` (string) - 消息ID列表字符串，如 "1,2,3"
    *   **返回数据**: `{}` (成功)

#### 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
                }
            ]
        }
        ```

#### 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" }
                // 更多元素配置，如位置、字体、颜色
            ]
        }
        ```

*   **7.2 查询电子证书成就对应用户基本信息**
    *   **API 方法**: `API.getUserBaseInCertificate(oarId)`
    *   **参数**: `oarId` (int)
    *   **返回数据**:
        ```json
        {
            "userName": "用户名称",
            "activityName": "活动名称",
            "completionTime": 1700000000 // 完成时间戳
        }
        ```

*   **7.3 根据成就信息确认生成电子证书**
    *   **API 方法**: `API.createCertificate(nickName, oarId)`
    *   **参数**:
        *   `nickName` (string): 用户昵称
        *   `oarId` (int): 订单活动记录ID
    *   **返回数据**:
        ```json
        {
            "certUrl": "http://example.com/generated_cert.png" // 生成的证书图片 URL
        }
        ```

#### 8. 其他辅助接口

*   **8.1 用户基本信息查询**
    *   **API 方法**: `API.getUserInfo()`
    *   **参数**: 无
    *   **返回数据**:
        ```json
        {
            "nickName": "用户昵称",
            "headUrl": "http://..."
        }
        ```
*   **8.2 卡片对应地图列表详情查询**
    *   **API 方法**: `API.getMapList(mcId)`
    *   **参数**: `mcId` (int)
    *   **返回数据**: (Array)
        ```json
        [
            {
                "mapId": 1,
                "mapName": "奥体中心",
                "latitude": 36.666,
                "longitude": 117.123,
                "activityList": [
                    { "ocaId": 101, "showName": "迷你跑" }
                ]
            }
        ]
        ```

*   **8.3 卡片URL查询**
    *   **API 方法**: `API.getCardUrl(actId, matchType)`
    *   **参数**: `actId` (int), `matchType` (int)
    *   **返回数据**:
        ```json
        {
            "url": "http://example.com/card/detail.html?id=123" // 卡片对应的H5页面URL
        }
        ```

*   **8.4 赛事完赛信息查询**
    *   **API 方法**: `API.getMatchFinishInfo(actId, matchType)`
    *   **参数**: `actId` (int), `matchType` (int)
    *   **返回数据**: `{}` (待定)

*   **8.5 Redis 重建 (管理接口)**
    *   **API 方法**: `API.redisRebuild(compId)`
    *   **参数**: `compId` (int)
    *   **返回数据**: `{}` (待定)