本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：暂存20260913/docs/骰子插件说明.md。
摇骰子游戏插件 — 说明文档
文件结构
plugins/dice/
├── plugin.json # 插件配置（已启用）
├── Plugin.php # 激活/停用、建表、排行榜查询
├── DiceController.php # 游戏逻辑控制器
├── hook/
│ ├── init_after.php # 初始化建表（带缓存）
│ ├── route_register.php # 注册路由 /dice 和 /dice/play
│ ├── nav_main_links.php # 顶部导航栏链接（带激活状态）
│ └── nav_plugin_links.php # 应用下拉菜单链接
├── assets/
│ ├── style.css # 骰子 3D 动画 + 游戏样式
│ └── script.js # 前端投注交互
└── views/ # （已废弃，视图已移到 app/Views/plugins/dice/）app/Views/plugins/dice/
└── index.php # 游戏页面视图玩法规则
| 项目 | 说明 |
|---|---|
| 赌具 | 3 颗骰子，点数 1-6 |
| 押大 | 三颗骰子和值 11-17（不含豹子） |
| 押小 | 三颗骰子和值 4-10（不含豹子） |
| 豹子 | 三颗骰子相同，押大小都输 |
| 赔率 | 1:1 |
| 投注范围 | 10 ~ 600（后台设置 dice_bet_min / dice_bet_max） |
| 每日限制 | 默认 20 次（后台设置 dice_daily_limit） |
积分系统
使用主积分系统（app\Helpers\Points）：
- 扣分：
Points::deduct()— 带FOR UPDATE行锁，防止并发透支 - 加分：
Points::award()— 中奖后发放 - 记录在
points_log表，原因标记为摇骰子投注/摇骰子中奖
数据库表
dice_records (
id INT AUTO_INCREMENT PRIMARY KEY,
user_id INT NOT NULL,
bet_type VARCHAR(10) NOT NULL, -- big / small
bet_amount INT NOT NULL DEFAULT 0,
dice1 INT NOT NULL DEFAULT 1,
dice2 INT NOT NULL DEFAULT 1,
dice3 INT NOT NULL DEFAULT 1,
total INT NOT NULL DEFAULT 0,
is_triple TINYINT(1) NOT NULL DEFAULT 0,
result VARCHAR(10) NOT NULL, -- win / lose / triple
points_change INT NOT NULL DEFAULT 0,
balance_after INT NOT NULL DEFAULT 0,
created_at DATETIME NOT NULL,
INDEX idx_user_id (user_id),
INDEX idx_created_at (created_at)
)当前存在的问题
1. 插件导致网站崩溃（关键问题）
现象：将 plugins/dice/ 目录放入 plugins/ 后，整个网站无法访问。
错误日志：
Plugin hook path security violation [dice:init_after]:
D:\phpstudy_pro\WWW\app\Helpers/../../plugins/dice/hook/init_after.php原因：app/Helpers/Plugin.php 中 hook() 方法对钩子文件做了安全路径校验：
$hookFile = self::$pluginDir . '/' . $name . '/' . ltrim($config['hooks'][$hookName], '/');
$realHook = realpath($hookFile);
$realPluginDir = realpath(self::$pluginDir . '/' . $name);
$realPluginDirSafe = $realPluginDir !== false ? rtrim($realPluginDir, '/\\') . DIRECTORY_SEPARATOR : '';
if ($realHook === false || $realPluginDirSafe === '' || strpos($realHook, $realPluginDirSafe) !== 0) {
error_log("Plugin hook path security violation ...");
continue;
}self::$pluginDir 为 __DIR__ . '/../../plugins'，即 app/Helpers/../../plugins。realpath() 对带 ../../ 的路径解析失败返回 false，导致所有钩子被跳过。
但安全校验失败只是跳过钩子，理论上不应该导致网站崩溃。其他插件（如 daily_checkin）路径格式完全一样，却能正常工作。怀疑是 plugins_cache.php 缓存文件多次重建/删除过程中，某个中间状态导致了 realpath() 对 dice 插件路径返回 false。
临时解决：将 plugins/dice/ 移出 plugins/ 目录，删除 plugins/plugins_cache.php 强制重建缓存，网站即可恢复。
2. 视图文件路径问题（已修复）
问题：DiceController.php 调用 $this->view('plugins/dice/index')，模板编译器会从 app/Views/plugins/dice/index.php 查找。文件最初放在了 plugins/dice/views/index.php，导致 404 错误。
修复：将视图文件移到 app/Views/plugins/dice/index.php。
3. 自建积分字段问题（已修复）
问题：Plugin.php 的 activate() 方法中尝试 ALTER TABLE users ADD COLUMN dice_points，使用独立积分字段。
修复：改用主积分系统 Points::deduct() 和 Points::award()。
功能清单
- [x] 三颗骰子 3D 动画展示
- [x] 押大/押小选择
- [x] 多档位投注金额（10/50/100/500/全押）
- [x] 积分实时结算
- [x] 每日投注次数限制
- [x] 投注金额范围限制
- [x] 盈亏排行榜
- [x] 个人投注记录
- [x] 顶部导航栏链接（带激活状态）
- [x] 应用下拉菜单入口
- [ ] 网站无法正常加载（需排查）
