|
|
@@ -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 请求日志。
|
