fix: 修复升级后整站无样式与点击特效失效

- 旧哈希静态资源随版本升级被删除，被缓存的 HTML 仍请求旧文件名导致
  FileNotFoundException 500，补 compat/assets 历史资源并在构建时合并
- postbuild 增加静态资源引用校验，缺失即构建失败
- ClickEffect 改为常驻配置节点 + data 属性驱动，避免配置未落库时静默失效；
  强制回流修正 transition 不触发；特效层挂到 body 下避免被导航栏遮挡
- 新增 scripts: postbuild/snapshot-assets/package/smoke-clickfx
- 版本 1.2.1

docs/changelog.md

@@ -1,5 +1,23 @@
 # 更新日志
 
+## v1.2.1
+
+### 问题修复
+
+- 🐛 **修复升级后整站没有样式**：Astro 会给 CSS/JS 加内容哈希，升级后旧文件被删除，被缓存的 HTML 仍请求旧文件名，
+  Halo 直接抛 `FileNotFoundException` 返回 500，样式全部丢失。主题现在会把各版本的哈希资源一并保留
+  （`compat/assets` 在构建时合并进 `templates/assets`，已覆盖 v1.1.7 起的所有版本）
+- 🐛 **避免页面出现 500**：新增构建期静态资源引用校验，模板引用的任一缺失资源都会让构建失败
+- 🐛 **修复鼠标点击效果开启后没有任何作用**：旧实现用 `th:if` 判断开关、且直接读取配置值，
+  一旦配置项未随版本写入（或被 Thymeleaf 整体移除属性）就读取为空，脚本直接跳过；
+  同时修复了多种特效在插入节点后随即改写 `transform` / `opacity`，导致浏览器把初态与终态合并、
+  transition 完全不触发的问题（表现为点了没反应）
+- 🐛 次要修复：点击特效节点统一挂载到 `body` 下的独立图层（`z-index: 12050`），不再被导航栏、页脚遮挡
+
+### 其他
+
+- 🧰 新增构建脚本：`pnpm snapshot`（历史资源快照）、`pnpm package`（打安装包）、`pnpm smoke`（点击特效冒烟测试）
+
 ## v1.2.0
 
 ### 主题配色系统

docs/faq.md

@@ -6,7 +6,7 @@
 
 检查以下几点：
 
-1. 确认 Halo 版本 >= 2.24.0
+1. 确认 Halo 版本 >= 2.26.0
 2. 确认主题已启用
 3. 清除浏览器缓存后重试（Ctrl+Shift+R 强制刷新）
 4. 检查 Halo 后台日志是否有报错
@@ -26,8 +26,32 @@ docker cp templates/ halo:/root/.halo2/themes/warm-island/
 docker restart halo
 ```
 
+### 升级主题后整站都没有样式？
+
+主题的 CSS / JS 文件名带内容哈希，每次构建都会变化。如果 Halo 页面缓存或前置反向代理
+（OpenResty、CDN 等）里还留着上一版本的 HTML，它请求的仍是已被删除的旧文件名，
+Halo 找不到文件时会返回 **500**（日志里能看到 `FileNotFoundException: .../templates/assets/Layout.xxxx.css`），
+于是样式全部失效。
+
+依次处理：
+
+1. Halo 后台执行一次「清理缓存」（设置 → 缓存，或直接重启 Halo / 容器）
+2. 刷新 CDN、反向代理缓存
+3. 浏览器强制刷新（Ctrl+Shift+R）
+
+v1.2.1 起安装包会保留各版本的哈希资源（v1.1.7 之后全部覆盖），
+即使缓存里的旧 HTML 被再次请求也不会 500，但最终仍建议清一次缓存以使用最新样式。
+
 ## 功能相关
 
+### 鼠标点击效果 / 拖尾效果开启了却没反应？
+
+1. 确认「总体样式 → 鼠标点击效果」开关已开启并点击了保存
+2. 确认「点击效果类型」没有选择「关闭」（选了关闭时即使开启开关也不会有任何特效）
+3. 清除浏览器缓存后重试；老版本的浏览器请更新到较新的 Chrome / Edge / Firefox / Safari
+
+若仍无效，打开浏览器控制台（F12）检查是否有 JS 报错 —— 第三方脚本报错会中断后续脚本执行。
+
 ### 搜索按钮不显示？
 
 搜索功能依赖 Halo 搜索插件：