# ColorMapRun H5 Card 风格重制与迁移实验总结 (Style Remake & Migration Experiment)

本文档总结了将原有的 `sdk/index.html` 和 `sdk/detail.html` 迁移至 `sdk/test/` 目录，并在保持原有业务逻辑不变的前提下，重新设计为 **“运动竞技风 (Sporty Tech)”** 的全过程。这份文档可作为未来类似 UI 重构或风格迁移任务的操作流程模板。

## 1. 实验目标

*   **核心任务**: 在不改变任何 JS 逻辑功能（API 调用、交互流程）的前提下，完全重写 UI 样式。
*   **目标风格**: 运动竞技风 (Sporty Tech) —— 暗色背景、荧光配色、斜切几何图形、动感排版。
*   **输出产物**: `sdk/test/` 目录下的完整可运行代码。

## 2. 操作流程 (SOP)

### 2.1 环境准备 (Preparation)
1.  **创建独立工作区**:
    *   新建目录 `sdk/test/`，避免污染主线代码。
    *   新建子目录 `sdk/test/css/` 和 `sdk/test/js/`。
2.  **复制核心依赖**:
    *   确保所有 JS 逻辑库和 CSS 库都已就位。
    *   **关键动作**: 复制 `api.js`, `bridge.js`, `mock_flutter.js` 到 `sdk/test/`。
    *   **关键动作**: 复制 `js/multiavatar.min.js` 到 `sdk/test/js/`。
    *   **关键动作**: 复制 `css/all.min.css` 到 `sdk/test/css/`。
    *   **易错点**: **务必复制 `webfonts/` 目录**！FontAwesome 图标依赖于此，否则图标会显示为空白。

### 2.2 逻辑迁移 (Migration)
1.  **读取原文件**: 读取原始 `index.html` 和 `detail.html` 的完整代码。
2.  **提取 JS 逻辑**: 将 `<script>` 标签内的所有业务逻辑（包括 `Logger` 封装、API 调用、数据处理、事件监听）完整提取出来。
3.  **保持引用**: 确保新文件头部引用的 JS/CSS 路径 (`./bridge.js`, `./api.js` 等) 与新目录结构一致。

### 2.3 样式重写 (Re-design)
1.  **定义主题变量 (`:root`)**:
    *   设立新的色彩系统（如 `--sport-bg`, `--sport-accent`）。
    *   统一字体栈。
2.  **重构 HTML 结构**:
    *   根据新设计调整 DOM 结构（例如将 Dashboard 的进度条从线性改为网格状）。
    *   **原则**: 尽量复用原有的 ID (`id="dashBadge"`, `id="rankList"`)，这样原有的 JS 逻辑可以直接操作 DOM，无需修改 JS。
3.  **编写 CSS**:
    *   应用新的视觉风格（斜切 `transform: skewX`, 动态背景, 荧光边框）。
    *   **适配移动端**: 注意 `env(safe-area-inset-top)` 和 `bottom` 的适配。

### 2.4 调试与微调 (Refinement)
1.  **图标与字体检查**: 确认 FontAwesome 图标是否正常显示（检查 `webfonts` 路径）。
2.  **布局适配**:
    *   **卡片圆角**: 对于透明背景的卡片，使用 `clip-path: inset(0 round 16px)` 往往比 `border-radius` 更可靠，尤其是在 WebView 环境下。
    *   **全屏适配**: 确保详情页 (`detail.html`) 占满全屏，使用 `height: 100%; overflow: hidden;` 固定框架，内部列表使用 `flex: 1; overflow-y: auto;` 滚动。
    *   **状态栏避让**: 顶部导航栏增加 `padding-top: max(30px, env(safe-area-inset-top))` 防止遮挡。
3.  **文本本地化**: 检查是否有硬编码的英文占位符，将其替换回中文（如 "Loading..." -> "加载中..."）。

## 3. 关键注意事项 (Best Practices)

### 3.1 逻辑与视图分离
*   **ID 锚点**: 在重写 HTML 时，**必须**保留原有 JS 逻辑所依赖的 `id` 和 `class`（如果 JS 通过 class 选择）。例如 `rankList` 容器、`myRankNum` 文本节点等。
*   **JS 零修改**: 理想情况下，直接复制粘贴原有的 `<script>` 块即可运行。如果必须改 JS，说明 HTML 结构变动过大，需谨慎评估。

### 3.2 WebView 兼容性
*   **背景透明**: 在做圆角卡片时，`html` 和 `body` 必须设为 `background-color: transparent !important;`。
*   **圆角裁剪**: 推荐使用 `clip-path` 强制裁剪，以防止子元素（如绝对定位的背景图）溢出圆角。
*   **滚动穿透**: 全屏页面务必锁定 `body` 滚动，只允许特定容器内部滚动。

### 3.3 WebView 兼容性与透明圆角 (重点更新)
*   **H5 透明度极限**: H5 页面本身无法直接控制 WebView 宿主控件的背景色透明度。
*   **圆角裁剪区域的颜色**: 如果 `html` 和 `body` 都已设置为 `background-color: transparent !important;`，但圆角裁剪掉的部分仍显示颜色（如灰色），则该颜色来自**WebView 控件自身的默认背景色**。
*   **原生透明度配置**: 要实现真正的透明圆角，**必须在 Native App (如 Flutter) 端配置 WebView 控件的背景色为透明**（例如 Flutter 的 `WebView(backgroundColor: Colors.transparent)`）。
*   **H5 替代方案**: 如果无法修改 Native App 配置，H5 端可以通过将 `html` 或 `body` 的背景色强制设置为与 App 背景色一致的颜色（如白色），来视觉上“模拟”透明效果，以达到无缝融合。

### 3.4 资源完整性
*   **FontAwesome**: 仅仅复制 CSS 文件是不够的，必须同步复制 `webfonts` 字体文件目录，且保持相对路径一致。

## 4. 沟通模板 (用于后续任务)

如果您希望继续进行类似的风格重制任务，可以使用以下模板指令：

> “请在 `[目标目录]` 下创建一个基于 `[原文件]` 的新版本。
> 风格要求：`[描述风格，如：赛博朋克/极简/复古]`。
> 核心要求：**保持所有 JS 业务逻辑不变**，仅重写 HTML/CSS。
> 注意事项：
> 1. 确保所有依赖文件（JS/CSS/Fonts）都已正确复制。
> 2. 保持原有的 DOM ID 以兼容 JS。
> 3. 适配移动端安全区域和圆角效果。”

---
*Generated by Gemini based on "Sporty Edition" experiment.*