sdk upd

card/sdk/API_SERVER.md

@@ -538,3 +538,19 @@
             }
         ]
         ```
+
+*   **8.3 卡片URI查询**
+    *   **API 方法**: `API.getCardUri(ecId)`
+    *   **参数**: `ecId` (int)
+    *   **返回数据**: `{}` (待定)
+
+*   **8.4 赛事完赛信息查询**
+    *   **API 方法**: `API.getMatchFinishInfo(ecId)`
+    *   **参数**: `ecId` (int)
+    *   **返回数据**: `{}` (待定)
+
+*   **8.5 Redis 重建 (管理接口)**
+    *   **API 方法**: `API.redisRebuild(ecId)`
+    *   **参数**: `ecId` (int)
+    *   **返回数据**: `{}` (待定)
+

card/sdk/PROJECT_INSIGHTS.md

@@ -0,0 +1,93 @@
+# ColorMapRun H5 Card 项目开发备忘录 (Project Insights)
+
+这份文档汇总了 AI 助手 (Gemini) 在协助开发过程中对项目的理解、架构分析以及关键技术细节。旨在帮助开发者快速上手或在不同环境间同步上下文。
+
+## 1. 项目概况
+
+*   **项目名称**: ColorMapRun Mobile H5 Card
+*   **核心功能**: 为 ColorMapRun App 提供嵌入式的 H5 卡片页面，用于展示活动详情、排行榜、报名、游戏互动等功能。
+*   **技术栈**:
+    *   **前端框架**: Vue.js (UniApp 风格，但在 SDK 模式下使用了原生 HTML/JS/CSS)。
+    *   **构建环境**: 似乎是基于 UniApp 的工程结构，但在 `sdk/` 目录下维护了一套独立的、无框架依赖的原生 H5 页面，用于嵌入 App。
+    *   **通信协议**: 自定义 JSBridge (`bridge.js`) 与 Native App (Flutter) 交互。
+    *   **样式**: CSS3, Flexbox, FontAwesome (部分页面)。
+
+## 2. 核心目录结构
+
+*   **`sdk/`**: **(核心关注点)** 包含可以直接在浏览器或 WebView 中运行的原生 HTML 页面。
+    *   `detail.html`: 核心页面之一，用于展示月度挑战赛详情、排行榜等。
+    *   `index.html`: 入口卡片页。
+    *   `api.js`: 封装了所有后端 API 请求，包含 Mock 数据机制。
+    *   `bridge.js`: 封装了与 App 的通信逻辑 (JSBridge)。
+    *   `API_SERVER.md`: 详细的后端接口文档（由 AI 维护更新）。
+*   **`pages/`**: UniApp 的页面源码目录，包含各种业务模块的 Vue 组件。
+    *   `tpl/`: 通用模板 (style1, style2, style3...)，包含活动首页、排行榜、报名页。
+    *   `mytz/`: 每月挑战 (Monthly Challenge) 模块。
+    *   `game/`: 游戏模块 (如 Grid 网格拼图)。
+    *   `bm/`: 报名 (BaoMing) 相关模块。
+    *   `jbs/`: 锦标赛 (JinBiaoSai) 模块。
+*   **`common/`**: 公共工具库，如 `tools.js` (工具函数), `api.js` (UniApp 版 API 封装)。
+
+## 3. API 交互机制 (`sdk/api.js`)
+
+*   **封装方式**: 所有接口挂载在全局 `window.API` 对象上。
+*   **Mock 模式**:
+    *   通过 URL 参数 `?env=mock` 开启。
+    *   开启后，`API.request` 会拦截请求并返回 `api.js` 内部定义的 `MOCK_DB` 数据。
+    *   日志输出会详细打印 `[API-Mock] Request` 和 `[API-Mock] Response`。
+*   **正式模式**:
+    *   默认请求 `https://colormaprun.com/api/card/` (Base URL)。
+    *   请求头包含 `Content-Type: application/x-www-form-urlencoded` 和 `token`。
+    *   自动处理 `401 Unauthorized`，调用 `Bridge.toLogin()` 跳转登录。
+*   **日志管理**:
+    *   引入了 `Logger` 工具。
+    *   仅在 `env=mock` 时输出 `Logger.log` 和 `Logger.warn`，生产环境静默（`Logger.error` 除外）。
+
+## 4. Bridge 交互机制 (`sdk/bridge.js`)
+
+*   **通信方式**:
+    1.  **优先**: `window.uni.postMessage` (UniApp WebView 标准)。
+    2.  **降级**: URL 拦截协议 (如 `action://to_login/`) 或注入对象 (如 `window.share_wx`)。
+*   **主要功能**:
+    *   页面跳转: `toHome`, `toLogin`, `back`, `appAction` (通用跳转)。
+    *   功能调用: `openMap`, `openMatch`, `shareWx`, `makePhoneCall` 等。
+*   **日志管理**: 同样集成了 `Logger` 工具，生产环境隐藏敏感信息（如 Token）。
+
+## 5. 关键业务模块与逻辑
+
+### 5.1 月度挑战赛 (`sdk/detail.html`)
+*   **功能**: 展示用户当月的挑战进度（仪表盘）、积分/场地排行榜（领奖台 + 列表）。
+*   **逻辑**:
+    *   优先加载当前月份数据。
+    *   如果当前月份无数据，会自动向前回溯 6 个月查找有数据的月份。
+    *   **未登录处理**: 新增了 `renderGuestState`，未登录用户显示随机头像和“去登录”提示。
+    *   **UI 调整**: 针对移动端进行了适配，Header 区域紧凑化以腾出更多列表空间。
+
+### 5.2 游戏/网格挑战 (`pages/game/grid`)
+*   **功能**: 九宫格拼图游戏，点亮格子解锁奖励。
+*   **数据结构**: 依赖 `getGrids` 接口，返回 `detailRs` 包含格子的状态、关联活动 (`ocaId`) 或地图 (`mapId`)。
+
+### 5.3 动态配置 (`CardConfigQuery`)
+*   后端通过 `getCardConfig` 接口返回 `configJson` 字符串。
+*   前端解析 JSON 后，动态应用：
+    *   **CSS**: 注入自定义样式。
+    *   **弹窗**: 配置规则弹窗、消息弹窗的内容。
+    *   **UI 元素**: 如 `tabActiveColor`, `teamType` 等。
+
+## 6. 待办与注意事项 (TODOs)
+
+1.  **API 返回结构待定**:
+    *   `getCardUri`
+    *   `getMatchFinishInfo`
+    *   `redisRebuild`
+    *   以上三个接口已在 `api.js` 和文档中占位，但 Mock 数据目前为空对象 `{}`，需根据后端实际返回进行更新。
+2.  **生产环境部署**:
+    *   上线前请确保 `sdk/detail.html` 等文件中的 `env=mock` 参数已移除或由 App 端正确控制。
+    *   建议服务器开启 Gzip 压缩以优化加载速度。
+3.  **代码同步**:
+    *   `sdk/api.js` (原生版) 和 `common/api.js` (UniApp 版) 维护了两套类似的接口定义，修改时需注意同步（目前主要维护了 `sdk/api.js`）。
+
+## 7. 常用调试指令
+
+*   **开启 Mock**: 在 URL 后追加 `?env=mock`。
+*   **查看完整日志**: 开启 Mock 模式后，控制台会输出详细的 Bridge 调用和 API 请求日志。

card/sdk/api.js

@@ -64,7 +64,9 @@
             beginSecond: Date.now() / 1000 - 86400 * 2,
             endSecond: Date.now() / 1000 + 86400 * 5,
             teamNum: 0,
-            coiName: '个人组'
+            coiId: 1, // Mocked coiId
+            coiName: '个人组',
+            ocaId: 201 // Mocked ocaId
         },
         'MatchRsDetailQuery': [
             { id: 1, name: '[Mock]活动1', status: 1 },
@@ -105,10 +107,15 @@
             configJson: JSON.stringify({
                 css: ".custom-header { background-color: #f0f8ff; }",
                 tabActiveColor: "#007bff",
+                teamType: 0, // Mocked teamType
                 popupRuleConfig: { height: "60%", theme: "light" },
+                popupMessageConfig: {}, // Mocked popupMessageConfig
                 popupRuleList: [
                     { type: 1, data: { title: '规则1', content: '这是<b>Mock</b>的活动规则内容。' } },
                     { type: 1, data: { title: '规则2', content: '第二条规则。', logo: { src: 'https://picsum.photos/100/50', width: '100px', height: '50px' } } }
+                ],
+                popupDataList: [ // Mocked popupDataList
+                    { type: 1, data: { title: '通用弹窗1', content: '通用弹窗内容1。' } }
                 ]
             })
         },
@@ -184,7 +191,10 @@
                 { orderNum: 1, isComplete: 1, showName: '完成1', relationType: 1, ocaId: 10, longitude: 117.1, latitude: 36.6, popupImg: 'https://picsum.photos/100/100?random=19' },
                 { orderNum: 2, isComplete: 0, showName: '未完2', relationType: 1, ocaId: 11, longitude: 117.2, latitude: 36.7, popupImg: 'https://picsum.photos/100/100?random=20' }
             ]
-        }
+        },
+        'CardUriQuery': {}, // 暂无 Mock 结构
+        'MatchFinishInfoQuery': {}, // 暂无 Mock 结构
+        'RedisRebuild': {} // 暂无 Mock 结构
     };
 
     var API = {
@@ -348,7 +358,16 @@
         getUserInfo: function() { return this.request('UserBasicInformationQuery', {}); },
 
         // 32. 网格卡片信息查询
-        getGrids: function(ecId) { return this.request('GridsQuery', { ecId: ecId }); }
+        getGrids: function(ecId) { return this.request('GridsQuery', { ecId: ecId }); },
+
+        // 33. 卡片URI查询
+        getCardUri: function(ecId) { return this.request('CardUriQuery', { ecId: ecId }); },
+
+        // 34. 赛事完赛信息查询
+        getMatchFinishInfo: function(ecId) { return this.request('MatchFinishInfoQuery', { ecId: ecId }); },
+
+        // 35. Redis 重建 (管理接口)
+        redisRebuild: function(ecId) { return this.request('RedisRebuild', { ecId: ecId }); }
     };
 
     window.API = API;