Steam 信息展示

本版本带来两项核心改进——Steam 数据缓存定时预热架构与游戏元数据补全，并对公开 REST API 的响应结构做了规范化调整。

⚠️ REST API 破坏性变更

自本版本起，公开 REST API（/profile、/games、/recent、/badges）的响应字段统一从 Steam 原始的 snake_case 改为 camelCase，并裁剪了内部字段、补充了格式化字段（如 headerImageUrl、delisted、playtimeFormatted 等）。已通过 REST API 调用这些接口的主题或自定义前端需要同步更新 ，Finder API 不受影响。

完整字段定义请参考 README - REST API 与 使用指南 - API 接口，或 Halo 后台的 OpenAPI（Swagger）文档。

✨ 新功能

• 缓存定时预热：新增活跃信息（资料 / 最近游玩）与库藏信息（游戏库 / 徽章）两条独立预热通道，可分别配置刷新间隔；前端页面只读缓存，预热失败时用上一次数据兜底，避免页面空白
• 游戏元数据补全：通过 IStoreBrowseService/GetItems 为库外游戏或 Steam API 暂未返回名称的游戏补全本地化名称、真实封面与商店链接（新发布游戏的封面带内容哈希，已无法靠 AppID 拼接）
• 富文本游戏卡片支持 「不可用」标识：已下架 / 区域限制 / App ID 无效的游戏不再误显示为「加载失败」，判定口径与游戏库同源
• 新增配置项：活跃 / 库藏信息刷新间隔、游戏显示语言、游戏图片 CDN 域名重写

⚡ 优化

• 改进 appdetails 接口 success:false 的处理：先用 GetItems 的 visible=false 二次确认是否真的不可见，避免接口限流时把正常游戏误判为下架
• 不可用游戏的判定结果纳入详情缓存，命中缓存期间不再重复请求 Steam API
• headerImageUrl 行为调整：无真实封面时改为返回 null（旧版返回 appId 拼接路径，对新游戏本就是 404）。

📚 文档

• 更新 Steam API 技术参考：补充 appdetails 的 success 字段语义、修正 header_image 示例地址，完善 GetItems 行为说明
• 更新使用指南与 README：补充缓存预热行为、新增配置项、富文本卡片「不可用」处理、REST API 字段调整

✨ 新功能

• 最近游玩列表支持库外游戏标识，不在当前 Steam 游戏库中的游戏会显示「库外」徽标
• 最近游玩接口新增 inLibrary 字段，可用于判断最近游玩的游戏是否存在于当前游戏库

⚡ 优化

• 最近游玩列表支持通过 Store API 补全缺失的游戏名称
• 优化 Steam API 返回不完整数据时的页面展示效果

📚 文档

• 新增 Steam API 技术参考文档：docs/steam-api-reference.md
• 更新 README，补充最近游玩功能说明
• 更新最近游玩 REST API 示例，补充 inLibrary 字段

---

Generated from v0.4.0

本次更新带来Steam 游戏卡片编辑器扩展，支持在文章中直接插入游戏信息卡片，并新增多项实用功能。

✨ 新功能

• 新增Steam 游戏卡片编辑器扩展，支持通过 App ID 或商店链接插入游戏卡片
• 游戏卡片支持多语言（自动检测或手动指定简中、繁中、英语、日语、韩语等）
• 新增 Store 图片 CDN 域名替换配置，可自定义图片 CDN 加速访问
• 热力图支持自定义 ECharts CDN 地址，改用内置 visualMap 图例

🐛 修复

• 修复 Store 图片 CDN 未配置时的 NPE 问题
• 修复 Reactor 响应式流 null-safety 问题

⚙️ CI/CD

• 使用 Node.js 22 和 pnpm 9
• 添加 ui-path: ui 配置参数
• 与官方 halo-sigs/reusable-workflows@v3 配置对齐

📚 文档

• 新增完整的 REST API 文档（README）
• 完善使用指南，新增游戏卡片和编辑器配置说明

---

Generated from v0.3.0

本次更新带来全新的游戏时长热力图功能，并对统计逻辑与体验进行全面优化。

✨ 新功能

• 新增游戏时长热力图，可视化展示每日游玩情况
• 支持自动定时追踪与手动触发追踪
• 新增热力图相关配置项（追踪间隔、保留天数、功能开关）

⚡ 优化

• 重构时长统计算法，提升热力图数据连续性
• 资源命名规范化，提升长期稳定性
• 设置页面体验优化

🐛 修复

• 修复单元测试 NPE 问题
• 修复热力图相关按钮/路由失效问题

📚 文档

• 使用指南：docs/usage-guide.md
• API 文档（使用指南内）：REST API

⚠️ 重要提示

• 本版本规范化资源命名，旧热力图数据不会继续显示 如需保留旧数据，可参考 beta.2 的迁移说明： v0.2.0-beta.2 Release

---

Generated from v0.2.0

本次更新包含 核心算法重构 与 资源命名规范化，旨在彻底解决时长统计异常问题并提升插件的长期稳定性。

⚠️ 重要升级提示

由于对 Custom Resource Group 进行了规范化修正（steam.halo.run →steam.timxs.com），本次更新将重置所有历史统计数据。
升级后，插件将基于新算法重新开始记录游戏时长与热力图数据，旧数据虽然保留在数据库中但不再显示。建议在升级后手动点击控
制台的「刷新缓存」按钮。
也可以在升级前通过数据工厂导出模型 DailyPlaytimeRecord 与模型 PlaytimeSnapshot 记录，批量修改 "apiVersion": "steam.halo.run/v1alpha1" → "apiVersion": "steam.timxs.com/v1alpha1" 即可保留数据。

🐛 问题修复 (Bug Fixes)

• 重构游戏时长统计算法（智能平滑处理）

  • 修复了因 服务中断 或 定时任务漏跑（如 Halo 重启、网络波动）导致的数据堆积问题。
  • 旧版行为：当检测间隔跨越多个日期时（例如插件停机两天后恢复），累积时长会全部记在恢复当天，导致单日数据虚高
    且中间日期断层。
  • 新版行为：引入 时间窗口加权算法，自动检测时间跨度，将累积时长按比例平滑分配给期间的每一天，确保热力图数据的连续性与合理性。

• 修复 API 路由与资源命名不规范

  • 将所有 API 路由域名统一修正为 api.steam.timxs.com。
  • 修正了 CRD Group 定义，符合 Halo 插件开发的最佳实践。

• 修复前端页面与设置项的死链

  • 修复了设置页面的「验证配置」、「刷新缓存」、「手动追踪」按钮因 API 地址变更失效的问题。
  • 修复了 steam.html 模板中热力图数据加载失败的问题。

⚡ 改进与优化 (Improvements)

• 新增异常数据熔断保护

  • 当检测到数据跨度超过 60天（如长期弃坑后回归）时，系统将跳过每日明细生成，仅更新总时长快照。这有效防止了极端脏数据破坏热力图的可读性。

• 提升系统健壮性

  • 增强了 PlaytimeTrackingService 对异常时间窗口（如负数时间差）的防御性检查。

---

Generated from v0.2.0-beta.2

本次更新主要带来了全新的游戏时长热力图功能，支持自动追踪 Steam 游戏时长变化并以 GitHub 风格的热力图进行展示。同时优化了后台设置页面的 UI 体验。

✨ 新特性 (New Features)

• 游戏时长热力图 (Playtime Heatmap)
  • 类似于 GitHub 贡献图，可视化展示每日的游戏时长投入。
  • 支持自定义热力图颜色主题（Steam 蓝、GitHub 绿、火焰橙、紫色梦幻）。
  • 支持配置显示最近 30 ~ 730 天的数据。
  • 支持鼠标悬停查看每日具体游戏时长详情。
• 自动时长追踪
  • 新增定时任务，默认每小时自动记录游戏时长变化。
  • 数据持久化存储，支持配置数据保留天数（默认 365 天）。
  • 支持在后台手动触发一次立即追踪（便于测试）。
• 更多配置选项
  • 新增 隐藏的游戏 选项，允许控制是否统计免费游戏（如 CS2、Dota 2）。
  • 热力图功能支持单独开关。

⚠️ 注意事项 (Notes)

1. 历史数据说明：Steam API 不提供历史每日数据，热力图数据只能从开启功能后开始记录。
2. 首次使用：开启“启用游戏时长追踪”后，需等待至少 1 小时（或手动点击“手动追踪时长”按钮）才会产生第一笔数据。
3. 数据准确性：如果在服务器停机期间玩游戏，这部分时长将在服务器恢复并进行下一次追踪时被一次性记录，可能会导致该时间段的数据出现峰值。

---

Generated from v0.2.0-beta.1

新功能

• 支持自定义系统徽章图片，可在「徽章配置」中添加 Badge ID 与图片 URL 映射

优化

• Finder 层统一 9 秒超时，确保在 Halo 框架超时前返回结果
• API 请求超时默认值从 10 秒改为 8 秒
• 模板区分 API 失败（显示错误提示）与空数据（显示空状态）
• 统计栏在 API 失败时显示 - 而非 0

修复

• 修复代理配置表单字段切换时值错位的问题

---

Generated from v0.1.1

🎮 首个版本发布！

✨ 功能特性

• 展示 Steam 用户资料（头像、昵称、在线状态、等级、上次在线时间）
• 展示游戏库列表（支持分页、按游玩时长排序）
• 展示最近游玩的游戏（可选显示成就进度）
• 展示统计数据（游戏总数、总游玩时长、最近两周游玩时长）
• 展示徽章信息（徽章列表、经验值、等级进度）
• 数据缓存机制，减少 API 调用
• 支持 Steam API 代理配置
• 支持自定义图片 CDN 加速
• 提供独立的 Steam 页面（/steam）
• 提供 Finder API，方便主题集成
• 提供 REST API，支持前端异步获取数据

📋 环境要求

• Halo >= 2.22.1
• JDK 21

📦 安装方式

下载 plugin-steam-0.1.0.jar，在 Halo 后台 → 插件 → 安装插件 → 上传并启用

🔧 配置说明

1. 获取 Steam API Key
2. 获取 Steam ID（17位数字格式）
3. 在插件设置中填写配置并验证

---

Generate from v0.1.0