插件功能:在帖子详情页随机显示彩蛋，点击彩蛋弹窗显示奖励，支持按板块开启、切换挂载位置、设置图标大小。
效果演示: https://www.hycode.eu.cc/
功能简介:

📌 基本信息

插件名称：帖子彩蛋
插件ID：post-easter-egg
版本：1.0.0
作者：kingkare

🎨 前端功能

帖子页面随机位置显示彩蛋
点击彩蛋弹出奖励行为/后台可设置彩蛋行为
增加或者减少积分明细可查看
一个帖子可以领取一次也可以多次

⚙️后台功能

是否启用彩蛋
每个帖子只能领取一次
随机出现概率 (这里的概率是指全局门槛,简单点来说就是这里设置是判断所有帖子出现的概率,建议设置为100%)
挂载位置(默认的就行)
彩蛋图标大小 单位是px
开启彩蛋的节点/分类 (可以设置哪个节点不开启彩蛋 不勾选默认全部开启)
彩蛋列表 (增加删除彩蛋) 每行一个彩蛋。彩蛋行为：输入数字即可，如 5 表示+5积分，-10 表示-10积分，0 或空表示谢谢惠顾,图标地址可用本地或者图片链接。
保存功能 一键保存所有更改

🔧 技术特点

架构设计

• 客户端驱动 + 服务端轻量。服务端插槽不在 SSR 阶段做重逻辑，只通过 inlineScripts（Next.js 官方字段）注入引导脚本，真正的彩蛋判断和 DOM 渲染全在浏览器端完成。规避了主程序 AddonSlotRenderer 不传 props 导致服务端拿不到帖子信息的问题。

• 公开接口分离关注点：bootstrap（判断是否显示彩蛋 + 下发 token）和 claim（消费 token + 积分发放）拆成两个独立 API，token 作为一次性凭证防止重复领取和篡改。

容错与兼容

• 4 槽位同时注册，配置化切换。同时注册 post.body.before/after、post.author.row.after、post.sidebar.top 四个插槽，未命中 mountSlot 配置的返回 null，后台切换即时生效无需重启。

• 多层获取用户 ID。getCurrentUserId 尝试 5 个候选路径（currentUser、user、session.user、actor、getCurrentUser()），适配不同版本和上下文。

• 多层解析帖子 slug。从 context.pathname、context.request.url、referer header 三个来源尝试提取 /posts/<slug>，任一命中即可。

• 中文文件名跨平台兼容。normalizeIconPath + replaceChineseFilename 自动处理原始中文名、URL 编码中文名、各种历史错误前缀写法，保证 Windows 打包 ZIP 部署到 Linux 后图标仍可访问。

积分安全

• 使用官方 context.points.adjust()，而非手动 SQL。事务内同时更新余额 + 写入积分日志/审计表，前台积分记录可追溯。

• token 防重放。bootstrap 生成随机 token 写入 pending 表，claim 消费后立即删除，2 小时自动过期清理。

• oncePerPost 限流。每人每个帖子只能领一次，claims 表 (user_id, post_id) 联合索引查重。

前端交互

• 随机位置静态显示（absolute 定位），不浮动但保留 postEggWiggle 摆动动画，hover 放大 + 高亮。

• 弹窗有状态反馈：获得积分（绿色）、扣除积分（红色）、谢谢惠顾（默认色），入场弹跳动画 + 退场淡出，6 秒自动关闭。

• SPA 路由感知。劫持 history.pushState/replaceState + 监听 popstate，用户通过客户端导航切换帖子时自动重新评估彩蛋。

配置灵活性

• 图标大小统一控制（8~200px 滑块 + 快捷按钮）+ 挂载位置切换 + 按节点/分类启用。

• 彩蛋行为简化：直接填数字（5 = +5 分，-10 = -10 分，0/空 = 谢谢惠顾），同时兼容旧 points:5 和 points:1-5 格式。

• 权重抽选：按概率权重随机选蛋，非百分比而是比例制，使用更直观。

📂 插件文件结构

ts
post-easter-egg/
├── addon.json                         # 插件清单
├── assets/                            # 静态资源（对外可通过 /_addons/post-easter-egg/ 访问）
│   ├── post-easter-egg.css            #   页面级样式（命名空间 .post-easter-egg-*）
│   ├── post-easter-egg-admin.js       #   后台设置页 React 客户端组件
│   └── svg/                           #   彩蛋图标
│       ├── amber.svg                  #     琥珀彩蛋
│       ├── amethyst.svg               #     紫晶彩蛋
│       ├── crimson.svg                #     绯红彩蛋
│       ├── jade.svg                   #     翡翠彩蛋
│       └── morning-dew.svg            #     晨露彩蛋
└── dist/                              # 服务端代码（ES Module）
    ├── server.mjs                     #   入口，注册插槽、API、后台页面
    ├── controller.mjs                 #   核心逻辑，处理请求和渲染
    ├── model.mjs                      #   数据层，配置、数据库、图标路径规整
    └── views.mjs                      #   后台页面渲染入口，委托 controller