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 (部分页面)。

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 封装)。

封装方式: 所有接口挂载在全局 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 除外）。

通信方式:
1. 优先: window.uni.postMessage (UniApp WebView 标准)。
2. 降级: URL 拦截协议 (如 action://to_login/) 或注入对象 (如 window.share_wx)。
主要功能:
- 页面跳转: toHome, toLogin, back, appAction (通用跳转)。
- 功能调用: openMap, openMatch, shareWx, makePhoneCall 等。
日志管理: 同样集成了 Logger 工具，生产环境隐藏敏感信息（如 Token）。

功能: 展示用户当月的挑战进度（仪表盘）、积分/场地排行榜（领奖台 + 列表）。
逻辑:
- 优先加载当前月份数据。
- 如果当前月份无数据，会自动向前回溯 6 个月查找有数据的月份。
- 未登录处理: 新增了 renderGuestState，未登录用户显示随机头像和“去登录”提示。
- UI 调整: 针对移动端进行了适配，Header 区域紧凑化以腾出更多列表空间。

后端通过 getCardConfig 接口返回 configJson 字符串。
前端解析 JSON 后，动态应用：
- CSS: 注入自定义样式。
- 弹窗: 配置规则弹窗、消息弹窗的内容。
- UI 元素: 如 tabActiveColor, teamType 等。

API 返回结构待定:
- getCardUri
- getMatchFinishInfo
- redisRebuild
- 以上三个接口已在 api.js 和文档中占位，但 Mock 数据目前为空对象 {}，需根据后端实际返回进行更新。
生产环境部署:
- 上线前请确保 sdk/detail.html 等文件中的 env=mock 参数已移除或由 App 端正确控制。
- 建议服务器开启 Gzip 压缩以优化加载速度。
代码同步:
- sdk/api.js (原生版) 和 common/api.js (UniApp 版) 维护了两套类似的接口定义，修改时需注意同步（目前主要维护了 sdk/api.js）。