本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：WWW/plugins/dice/说明.md。

摇骰子（dice）插件说明

版本：1.0.0 ｜ 作者：SoSite ｜ 状态：⛔ 未启用

功能：三颗骰子押大小的积分小游戏——押「大」「小」，赢则返还 2 倍投注额，豹子通吃。

一、功能简介

• 玩法：三颗六面骰（random_int(1,6) × 3），总和 total = 3 ~ 18
• 押 大：total >= 11 即赢
• 押 小：total <= 10 即赢
• 豹子（三颗相同）：无论押什么都算输，本金不退（庄家优势 = 6/216 ≈ 2.78%）
• 赔付：1:1 —— 赢则 Points::award($userId, $betAmount * 2)，即返还本金 + 等额奖金
• 限额：单次投注额有上下限；每日游玩次数有上限，超限拒绝
• 记录：投注一条流水 + 中奖追加一条流水，全部写插件独立库（不再直查核心 points_log）
• 排行榜：按累计盈亏（SUM(points)）聚合，取用户名/头像经 User::batchGetUsers() 批量补全
• 侧栏：/dice 页面右栏输出「排行榜 + 我的记录」两块面板（桌面端走钩子，移动端走视图内兜底）
• 前端交互：htmx 局部刷新（HX-Request 时返回 HTML 片段，否则返回 JSON），零内联 JS

二、目录结构

plugins/dice/
├── plugin.json                      # 插件清单（5 个钩子；无 admin_url / permissions）
├── Plugin.php                       # 主类：建表、流水写入、日次数、排行榜、记录查询、生命周期
├── DiceController.php               # 前台：游戏页 / 投注结算（htmx + JSON 双通道）
├── hook/
│   ├── init_after.php               # 幂等建表兜底（缓存标记 data/.dice_table_cache）
│   ├── route_register.php           # 前台路由注册
│   ├── nav_main_links.php           # 【空文件】已停用主导航入口
│   ├── nav_plugin_links.php         # 应用下拉菜单入口（唯一入口）
│   └── right_sidebar_after.php      # 右栏「排行榜 / 我的记录」（仅 /dice 前缀页面输出）
├── views/
│   └── index.php                    # 游戏页（骰子 / 投注表单 / 结果区 / 记录表）
├── assets/
│   ├── style.css                    # 样式（零硬编码颜色，全用 --mn-* 变量）
│   ├── script.js                    # 金额与类型切换、htmx:afterSwap 回填结果（零内联）
│   └── images/1.gif ~ 6.gif         # 六面骰面图
├── data/                            # dice.sqlite（独立库）+ .htaccess / web.config
└── lang/                            # zh.php / en.php / zh_tw.php（各 28 键，三语零差异）

三、数据表

插件独立库：plugins/dice/data/dice.sqlite

• 索引：idx_dice_records_user（user_id, created_at）、idx_dice_records_day（user_id, date(created_at)）
• reason 取值由常量定义：REASON_BET = '摇骰子投注'、REASON_WIN = '摇骰子中奖'
• 一条投注必写一条（points 为负）；中奖再追加一条（points 为正），与核心 points_log 结构对齐
• 建表：activate() + init_after 双保险；卸载：uninstall() 删表

四、路由

本插件无后台页，故 plugin.json 不声明 admin_url 与 permissions（二者均为可选字段）。

五、核心规则

投注校验顺序（DiceController::play()）

① 登录校验（requireLogin）
② CSRF 校验（Csrf::verifyOrDie）
③ 押注类型合法（big / small）
④ 投注额区间（betMin ~ betMax）
⑤ 每日次数上限（先查次数，再扣分，避免白扣）
⑥ 扣积分（Points::deduct，自带事务锁防并发透支）
⑦ 掷骰 → 判定 → 中奖则 Points::award
⑧ 写流水（投注一条；中奖追加一条）

配置项（核心 settings 表，惰性默认）

未落库时自动使用上表默认值，无需初始化。

双通道响应

• 请求头含 HX-Request（htmx）→ 返回 <div class="dice-result-box" data-*> HTML 片段，

由 assets/script.js 监听 htmx:afterSwap 读 data-dice / data-balance / data-count 回填

• 普通请求 → 返回 JSON（success / dice / total / result / pointsChange / balance）

六、注意事项

• ⚠️ 需要登录才能游玩，游客访问 /dice 会被 requireLogin() 重定向
• ⚠️ 依赖核心积分体系：Points::deduct() / Points::award() / Points::getSummary()
• ⚠️ 豹子是庄家通吃（押大押小都输），这是刻意的赌场设计，不是 bug
• ⚠️ nav_main_links.php 是空文件（仅保留注释），入口只在「应用下拉菜单」与左栏「应用」面板；

修改导航位置时不要误以为主入口在顶部主导航

• ⚠️ 建表缓存标记在 data/.dice_table_cache（与 points_mall / qa / quiz_duel 放在 protected/ 下不一致），

手工删表后需一并删该标记才会重建

• ⚠️ 版本号不一致：Plugin.php 与 init_after.php 的文件头注释写 @version 1.1.0，

而 plugin.json 为 1.0.0。功能以 plugin.json 为准（插件版本号是独立语义版本，不跟站点版本）

• ⚠️ 视图与右栏钩子用字符串 '中奖' 判定记录类型（strpos($reason, '中奖')），

而 Plugin.php 已定义常量 REASON_WIN。若日后修改常量文案，这两处判定会失效，建议统一改用常量

• 当前状态：dice_records 11 行；插件未启用（activated: false）