本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：8月12日的备份/update/14/README-部署说明.md。

SoSite 勋章中心插件更新包（2026-08-11）

本目录包含 1 个新增插件目录（16 文件）+ 3 个修改 的文件，按原目录结构放置。

覆盖方式：将本目录内所有文件按相同路径上传覆盖到站点根目录（如 D:/phpstudy_pro/WWW 或服务器对应路径）。

生成环境：PHP 8.2 / MySQL 5.7.26。

一、本包功能说明

勋章中心插件（plugins/medal/）：后台定义勋章、自动/手动颁发、用户佩戴 1-3 枚并展示在帖子楼层 / 个人主页 / 右栏发帖人信息栏。

1. 勋章定义：名称 / 图标（内置 icon map 名 + 颜色，无图时兜底显示）/ 描述 / 获取条件 / 排序 / 启停；支持 image 图片字段（图片放 assets/medals/ 目录，后台填文件名如 medal1.gif，按上传原尺寸显示，不裁剪成圆形/方形）
2. 获取方式：

• 后台手动颁发 / 回收（按用户名，防 IDOR，CSRF 校验）
• 自动规则 3 种：发帖数 ≥ N、回帖数 ≥ N、注册满 N 天、积分 ≥ N（condition_type 后台可选，幂等颁发，已有则跳过）

1. 佩戴机制：用户在 /medal 勋章墙勾选最多 3 枚保存佩戴（AJAX + CSRF，超限/未获得拦截），展示位只显示佩戴的勋章
2. 展示位置（controller_view_before 批量注入，避免 N+1）：

• 帖子详情页主帖/回帖用户名旁
• 帖子/博客详情页右栏"发帖人信息栏"用户名旁
• 个人主页（user_profile）up-badges 处

1. 入口：前台"应用"面板"勋章中心"（带 __nav_uri 激活判断，跳转 /medal）；后台侧边栏"勋章管理"

二、数据库变更（3 张新表，激活时幂等创建，无需手动执行）

• medals：勋章定义（name/icon/color/description/condition_type/condition_value/sort/status/image/created_at）
• user_medals：用户持有（user_id/medal_id/source auto|manual/created_at，唯一键防重复颁发）
• user_medal_wears：佩戴位（user_id/medal_id/wear_sort 1-3，唯一键防同勋章重复佩戴）

建表由 Plugin::activate() 与 hook/init_after.php 双保险幂等执行（CREATE TABLE IF NOT EXISTS）；uninstall() 删表。

三、覆盖前必须做的事

备份服务器现状

把服务器上以下文件/目录整体备份一份（zip 即可）：

• plugins/medal/（若已存在）
• app/Views/thread/show.php
• app/Views/_components/right_sidebar.php
• plugins/user_profile/views/front.php
• plugins/plugins_cache.php（运行时产物，若存在）

四、本包包含的文件清单

新增插件（plugins/medal/，16 文件）

plugins/medal/plugin.json
plugins/medal/Plugin.php                      （建表/勋章 CRUD/颁发回收/佩戴/自动规则/渲染）
plugins/medal/MedalController.php             （前台：勋章墙 + 佩戴保存 AJAX）
plugins/medal/AdminMedalController.php        （后台：CRUD + 手动颁发/回收）
plugins/medal/hook/route_register.php         （/medal、/medal/wear）
plugins/medal/hook/admin_route_register.php   （/admin/medals 系列）
plugins/medal/hook/init_after.php             （懒建表 + 已登录用户惰性核对自动规则）
plugins/medal/hook/thread_create_after.php    （发帖后核对）
plugins/medal/hook/post_create_after.php      （回帖后核对）
plugins/medal/hook/auth_register_after.php    （注册后核对）
plugins/medal/hook/controller_view_before.php （批量注入佩戴勋章数据）
plugins/medal/hook/nav_plugin_links.php       （前台"应用"入口）
plugins/medal/hook/admin_sidebar_links.php    （后台侧边栏入口）
plugins/medal/views/index.php                 （勋章墙：我的勋章 + 佩戴选择 + 全部勋章）
plugins/medal/views/admin.php                 （后台：CRUD + 颁发/回收 + 编辑弹窗）
plugins/medal/assets/style.css                （.mn-medal 勋章化样式 + 勋章墙/后台样式）

修改（3）

五、部署步骤（推荐顺序）

1. 备份（见第三节）
2. 上传本 update 包全部文件，按路径覆盖
3. 删除 plugins/plugins_cache.php（插件缓存无 mtime 校验，不删 hooks 不生效）
4. 进入后台"插件管理"启用「勋章中心」（或确认本地已验证的 activated: true 状态）
5. 进入后台"勋章管理"（/admin/medals）添加勋章、配置自动条件、按需手动颁发
6. 浏览器回归验证（见下）

六、回归验证清单

七、注意事项

• 插件缓存：部署后必须删 plugins/plugins_cache.php，否则 hooks 不生效（本插件 9 个 hook）
• PDO 铁律：controller_view_before 批量查询用 IN (1,2,3) 内联整数（无占位符复用）；SHOW TABLES LIKE 用 quote() 内联（init_after）
• 自动规则触发点：发帖/回帖/注册钩子 + 登录用户每请求惰性核对（init_after），勋章页访问也会核对；手动勋章仅后台颁发
• controller_view_before 只处理 3 个目标模板（thread/show、blog/detail、plugins/user_profile/front），其余页面零开销
• 展示位模板改动依赖注入的 wearingMedals 数据；插件停用时模板 ?? '' 兜底，不影响页面
• 图标名沿用核心 TemplateCompiler::icon() map（trophy/award/crown/coins/star-fill/shield-alt 等）；image 字段可留空
• 勋章图片存放：放 assets/medals/（不要放 assets/uploads/——后台"清理孤儿附件"只扫 uploads 目录，会误删无数据库记录的勋章图）；后台"图片文件名"填 medal1.gif（插件自动拼 /assets/medals/ 前缀）
• 卸载插件会 DROP 三张表（勋章与持有/佩戴数据一并删除），请谨慎

本包由 2026-08-11 会话生成（勋章中心插件：定义/自动+手动颁发/佩戴展示 + 三处展示位模板）。