69 lines
4.0 KiB
Markdown
69 lines
4.0 KiB
Markdown
<!-- spec-format: 2 -->
|
||
# blog-5m：热力图定稿萤火（4 只）落地正式开源页
|
||
|
||
- **slug**: 2026-11-05_blog-5m-heatmap-fireflies
|
||
- **日期**: 2026-11-05
|
||
- **状态**: 进行中
|
||
- Git integration branch：`spec/2026-11-05_blog-5m-heatmap-fireflies`
|
||
- 证据协议：evidence: runs
|
||
- **提案**: 用户在 /heatmap-preview/ 五案中选定方案五「萤火」并要求虫数 5→4。把萤火引擎落进正式 Heatmap.astro（换下 P1 贪吃蛇），删预览路由/五候选组件/lint 白名单，E2E 补萤火断言。
|
||
|
||
## 1. 问题定义
|
||
- **项目目标**: 开源页热力图动效从贪吃蛇切换为萤火（4 只，暖色游走、落格点亮），保持数据语义（ink 档位=密度）与无障碍兜底（reduced-motion 静态、无 JS 可读）不变；一次性预览资产全部退役。
|
||
- **目标用户**: 读者（更安静文气的动效）；站长（选定方案的落地闭环）
|
||
- **核心价值**: 选型闭环——预览页五案并陈→用户点选→落地删预览的工作流第三次跑通，站点只留定稿资产
|
||
|
||
## 2. 假设与待确认
|
||
|
||
### 2.1 已确认事实
|
||
- 萤火引擎已在预览页跑通（/heatmap-preview/ 方案五），视觉复核判词无硬伤、色向已转暖
|
||
- 官方 Heatmap.astro 现役结构：streak 行 + 蛇引擎（hm-head/hm-trail/eaten + 月柱 .on 联动）+ 月柱 + 图例 + 横滚锚定
|
||
- E2E 无蛇头断言（仅注释），补萤火断言无旧断言要改
|
||
|
||
### 2.2 关键假设
|
||
- 月柱在无「点亮联动」后仍有信息价值（静态高度=哪个月最忙），保留不删
|
||
- 萤火引擎的 offsetLeft/offsetTop 定位对官方组件的 11px/10px 双档网格同样成立（布局实测，零手算节距）
|
||
|
||
### 2.3 待确认问题
|
||
- [x] 虫数 4（用户明确：5→4）
|
||
- [x] 贪吃蛇整体退役（用户选新方案即换下，git 历史留档）
|
||
|
||
### 2.4 可选解释与取舍
|
||
- 五个候选组件目录整体删除而非保留：git 历史即档案，工作树不留死代码
|
||
- 月柱保留静态形态：删掉会丢「月度粗粒度」信息，联动点亮属蛇的语义，随蛇退役
|
||
|
||
### 2.5 已证伪路径
|
||
- 无（本包是纯落地，无新设计探索）
|
||
|
||
## 3. 功能范围
|
||
|
||
### 3.1 核心功能（MVP）
|
||
- [x] T1 萤火落地：Heatmap.astro 换引擎（4 虫、data-hm-fire 锚、hm-lit 样式、月柱转静态）、删预览路由+五候选组件+lint 白名单两处、E2E 补萤火断言
|
||
|
||
### 3.2 扩展功能
|
||
- 无
|
||
|
||
### 3.3 不在范围内
|
||
- 萤火参数再调（数量/速度/半径——用户未提，不为未发生的需求加工）
|
||
|
||
## 4. 最小实现路径
|
||
- 最简可行：Heatmap.astro 三处手术（浮层标记换 4 只 hm-fly、script 换萤火引擎、style 换 hm-fly/hm-lit+月柱静态）+ 删三类一次性资产 + E2E 一条断言
|
||
- 暂不引入: 虫数可配置化
|
||
- 不做的抽象: 「动效引擎注册表」（只有一种引擎，抽象无收益）
|
||
|
||
### 5.1 验证策略
|
||
- 范围级别：package
|
||
- 变更对象：开源页热力图组件与一次性预览资产
|
||
- 快速检查：`pnpm astro build` + `python3 scripts/build-perf/config-check.py .`
|
||
- 集成检查：E2E（含萤火新断言）+ content-lint 0/0/0 + grep 断言产物（无 heatmap-preview、无 hm-head、4 只 hm-fly）
|
||
- 全项目检查：生产部署后人工核验 /opensource/ 萤火在跑、/heatmap-preview/ 404；**升级条件**——仅当改动触及 BaseLayout 或构建链时才升级全站回归，本包不涉及
|
||
- 升级触发：开源页独立区块，升级为「该区块人工核验」即可
|
||
|
||
## 6. 成功标准与验证方式
|
||
- [x] 正式开源页萤火 4 只在跑、预览资产全退役 -> verify: task_0001
|
||
- [x] 生产 /opensource/ 人工核验 + /heatmap-preview/ 404 -> verify: task_0002（manual: 部署后人工核验）
|
||
|
||
## 7. 关联与风险
|
||
- 前序：v4 路径优化（P1 蛇）、v5 五案预览（44cd62e）
|
||
- 风险：萤火引擎在官方组件的 11px 移动档网格上包围盒内缩 6px 后可用幅度变小——若视觉过挤，回退方案是内缩降为 3px（本包不预设，部署后看）
|