蛙港点评 ShirogomaReview
白芝麻服玩家店铺点评插件使用说明 —— 开店流程、营业执照与广告券、点赞/踩评分、店铺状态、管理命令、贝叶斯综合评分
简介
ShirogomaReview（蛙港点评）是白芝麻服的玩家店铺插件：玩家可以用「营业执照」创建自己的店铺，设置传送点与介绍，其他玩家进入店铺后能点赞或踩，贝叶斯平均算法算出综合评分。管理员可以整顿违规店铺、审核重新开业申请、发放营业执照 / 广告券。
- 玩家侧：开店、看店列表、传送、点评、看店铺评分、提交开业申请、用广告券发布店铺广告
- 管理侧：营业执照 / 广告券发放、整顿店铺、审核开业申请、重载配置、添加展示物品预设
本插件为 Bukkit / Spigot / Paper 系插件（api-version 1.20），在 Youer 这类 NeoForge + Bukkit 混合端上运行于 Bukkit 侧。软依赖 PlaceholderAPI。
安装
- 将
ShirogomaReview-version.jar放入服务端plugins/文件夹 - 重启服务器（或
/shop reload） - 首次启动会生成
plugins/ShirogomaReview/config.yml与shops.yml
开店流程
| 步骤 | 操作 |
|---|---|
| ① 拿到营业执照 | 管理员 /shop givelicense 发放 |
| ② 创建店铺 | 手持营业执照执行 /shop create <店铺名>（最多 20 字符，消耗 1 张营业执照） |
| ③ 设置传送点 | 到店铺入口位置执行 /shop setpoint <店铺名> |
| ④ 设置介绍 | /shop setintro <店铺名> <介绍内容>（最多 50 字符） |
| ⑤ 展示物品（可选） | 在店铺管理界面（GUI）点击切换展示物品，或让管理员 /shop additem hand 加预设 |
| ⑥ 正式开业 | 完成以上步骤后店铺即为 OPEN 状态，在列表中可见 |
店铺创建后由店主个人所有（UUID 绑定），可以有多个店铺。
点评与综合评分
玩家在店铺详情界面可以点赞或踩一脚，同一玩家只保留最后一次评分（再赞就移除原来的踩，反之亦然；再次点击自己已赞/已踩的可以撤销）。
综合评分（贝叶斯平均）
插件不直接用 赞数 / (赞+踩)，而是采用带先验置信度的贝叶斯平均，避免只有极少评分的店铺被 100% 好评或 0% 好评极端化。
公式：
score = (m × default + avg × total) / (m + total)| 参数 | 值 | 含义 |
|---|---|---|
default | 10.0 | 默认基准分（无评分时店铺先拿 10 分） |
m | 3.0 | 置信常量（约 3 次评分的权重） |
avg | likes / total × 10 | 当前投票者的真实平均分 |
total | likes + dislikes | 总投票数 |
直观效果：
- 刚开店无人评分：
score = 10.0（默认分） - 只被 1 人赞：
(3×10 + 1×10) / (3+1) = 10.0 - 5 赞 1 踩：
(3×10 + 8.33×6) / (3+6) ≈ 8.89 - 20 赞 5 踩：
(3×10 + 8×25) / (3+25) ≈ 8.29
随着评分人数增加，最终会收敛到真实好评率 × 10。
广告券
店主可以用广告券（管理员 /shop giveticket [玩家] [数量] 发放）在店铺管理界面点击「发布店铺广告」突破每日一次的限频。
- 广告每日限频按20 分钟一个时段滚动（不是自然日），服务器不关也能持续按时段计数
- 广告券类型是
NAME_TAG，展示名为「广告券」，手持N张可连续发N次 - 识别只看材质 + 显示名，改 lore 不影响已发放的券
店铺状态
| 状态 | 说明 |
|---|---|
OPEN | 正常营业，在店铺列表可见，可被传送 / 评分 |
SUSPENDED | 被管理员整顿（带理由），不可访问，店主在管理界面看到申请入口 |
店主店铺被整顿后可提交重新开业申请（在店铺管理界面），管理员通过 /shop review 打开审核 GUI，批准后店铺自动回到 OPEN。
管理员命令
权限节点：
| 节点 | 作用 |
|---|---|
shirogoma.shop.admin | 通用管理员权限（默认 OP 拥有） |
shirogoma.shop.givelicense | 发放营业执照 / 广告券 |
shirogoma.shop.suspend | 整顿店铺 / 审核开业申请 |
shirogoma.shop.additem | 添加展示物品预设 |
shirogoma.shop.reload | 重载配置 |
命令表
| 命令 | 权限 | 说明 |
|---|---|---|
/shop create <名称> | 玩家 | 手持营业执照创建店铺 |
/shop list | 玩家 | 打开店铺列表 GUI（支持别名 /shops /zdianping） |
/shop setpoint <名称> | 店主 | 把该店铺的传送点设为你当前位置 |
/shop setintro <名称> <介绍> | 店主 | 设置店铺介绍（不超过 50 字） |
/shop remove <名称> | 店主 | 删除自己的店铺 |
/shop givelicense [玩家] | givelicense | 向在线玩家发放营业执照（默认自己） |
/shop giveticket [玩家] [数量] | givelicense | 向在线玩家发放广告券，默认 1 张 |
/shop suspend <名称> <理由> | suspend | 整顿任意店铺；店主在线时会收到通知 |
/shop review | suspend | 打开开业申请审核 GUI |
/shop additem hand · /shop additem <物品> | additem | 把手持物品或指定 Material 加入店铺展示物品预设 |
/shop reload | reload | 重载 config.yml + 店铺数据 |
/shop create 必须手持营业执照；/shop additem 是为店铺展示物品加预设，店主之后在 GUI 里才能从中选择。营业执照和广告券的发放都需要目标玩家在线。
配置（config.yml）
# 创建店铺是否需要付费（目前预留，需要接入经济插件后生效）
create-cost: 0.0
# 从店铺列表传送进入店铺的冷却时间（秒）
teleport-cooldown: 5create-cost目前仅读配置，扣款逻辑需要接入 Vault / Essentials 等经济后端后开启teleport-cooldown防频繁点击传送，冷却期间再次传送会提示剩余秒数
数据存储
- 所有店铺数据（名称、介绍、展示物品、传送点、状态、点评双方 UUID、店铺创建时间）存于
plugins/ShirogomaReview/shops.yml - 展示物品预设也保存在
shops.yml的preset-items列表里（由/shop additem动态修改，持久化） plugins/ShirogomaReview/config.yml存create-cost与teleport-cooldown
每次店铺创建 / 修改状态 / 点赞踩 / 调设置后，都会自动保存；管理员也可通过 /shop reload 从磁盘重读。
常见问题
Q：营业执照用完了？
管理员执行 /shop givelicense 给自己（或目标玩家）即可，hand 省略时默认发给命令发出者。
Q：店铺被整顿了怎么办？
店主在店铺管理界面点击「申请开业」，管理员用 /shop review 审核通过后自动恢复 OPEN。
Q：广告券怎么发？
/shop giveticket 玩家名 数量，该命令和营业执照共用同一个权限节点 shirogoma.shop.givelicense。
Q：贝叶斯分为什么和简单好评率不一样？ 店铺刚开门时评分会被「默认 10 分」拖向中间，需要有几位玩家打分后才会稳定反映真实口碑。这样做是为了避免只有 1 人给好评的店铺反而比被 20 人好评的店铺分更高。
Q：传送点不生效 / 传送失败？
检查两件事：① 是否用 /shop setpoint <店铺名> 重新设置了传送点（会显示精确坐标）；② 店铺状态是否为 OPEN（整顿状态不能传送）。
Q：改了 config.yml 不生效？
执行 /shop reload（或重启服务器）；该命令会同时重载 config.yml 和 shops.yml。
Q：预设物品里想加新的展示物品？
两种方式：① 手里拿着那个物品执行 /shop additem hand；② 直接给 Material 名字，/shop additem DIAMOND。/shop additem 支持 tab 补全 hand。
Q：评分数据怎么清？
直接编辑 shops.yml：把该店铺 liked-by / disliked-by 列表清空即可，保存后 /shop reload。