xnx_gift 积分赠送

管理员后台赠送积分给用户的小工具插件，支持按 UID 或用户名定位接收者、记录完整赠送历史、可选发送站内通知，并通过 hook 留出 xnx_feeds 动态联动扩展点。

功能特性

• 后台赠送积分：管理员在后台填写接收者（UID 或用户名自动识别）、积分类型、数量、原因，一键赠送
• 三种积分类型：支持 credits（积分）、golds（金币）、rmbs（人民币）三类积分
• 接收者智能解析：纯数字输入按 UID 查询，否则按用户名匹配（user_read_by_username）
• 赠送记录列表：分页展示所有赠送历史，包含赠送管理员、接收者、积分类型、数量、原因、时间
• 按用户筛选记录：在记录页输入用户名或 UID，可筛选该用户作为赠送方或接收方的所有记录（OR 条件）
• 站内通知：赠送成功后可选调用 notify_create() 给接收者发通知
• xnx_feeds 动态联动：通过 xnx_gift_send_end.php hook 标记留出扩展点，由 xnx_feeds 插件自行挂载推送逻辑（可选，未安装 xnx_feeds 不影响主流程）
• 配置开关：后台「插件设置」提供 enable_feed / enable_notify 两个开关，默认均开启
• CSRF 防护：所有 POST 操作经 CsrfService::check() 校验

安装说明

1. 将插件目录放入 plugin/xnx_gift/
2. 进入后台「插件管理」找到「积分赠送」点击安装，自动建 1 张日志表并初始化默认配置（enable_feed=1, enable_notify=1）
3. 安装后通过 model_inc_file.php hook 自动加载 GiftService，通过 admin_index_route_case_end.php hook 注册后台路由，通过 admin_sidebar_end.htm hook 注入侧边栏菜单
4. 卸载时会 DROP TABLE xnx_gift_log 并清理 setting 中的 xnx_gift 配置

使用指南

后台赠送流程

1. 登录后台，左侧菜单点击「积分赠送」（由 admin_sidebar_end.htm hook 注入）
2. 在「赠送积分」Tab 填写表单：

- 积分类型：积分 / 金币 / 人民币 - 数量：正整数，最小为 1 - 原因：选填，赠送说明

1. 点击「确认赠送」，系统调用 GiftService::send() → CreditsService::add() 给接收者增加积分，并写入 xnx_gift_log 日志
2. 赠送结果以 alert-success / alert-danger 横幅提示

赠送记录查询

• 切换到「赠送记录」Tab，分页浏览全部赠送历史（每页 20 条，按 id 倒序）
• 顶部筛选框输入用户名或 UID，可查询该用户涉及的所有记录（同时匹配 from_uid 和 to_uid）
• 表格展示赠送管理员、接收者的头像与用户名（按组着色）、积分类型徽章、数量、原因、时间

插件设置

访问 /admin/plugin-setting-xnx_gift，配置两个开关：

| 开关 | 用途 | |---|---| | enable_feed | 赠送后是否触发 xnx_feeds 动态推送（需 xnx_feeds 插件挂载 xnx_gift_send_end.php hook） | | enable_notify | 赠送后是否给接收者发送站内通知 |

设置页仅超级管理员（gid=1）可访问。

技术细节

权限控制

• setting.php 显式限制 $gid != 1 报「无权限」，仅超级管理员可改配置
• route/admin_gift.php 依赖后台 admin/index.inc.php 统一的权限校验与 CSRF 校验，未再重复检查

积分增加（CreditsService）

GiftService::send() 通过 include_once APP_PATH . 'lib/CreditsService.php' 守卫加载 CreditsService 类，实例化后调用：

$creditsService->add($to_uid, $credits_type, $amount, 'gift:' . $reason, 0, true);

• 第 4 参数 reason 加 gift: 前缀，第 6 参数 reasonIsRaw=true，由 CreditsService 内部加 raw: 前缀
• 事务由 CreditsService 内部保证，add 失败直接返回错误信息，不写日志
• add 成功后才 db_insert('xnx_gift_log', ...) 写赠送日志，返回 last_insert_id 供 hook 使用

xnx_feeds 联动（可选）

GiftService::send() 在写完日志后留有 hook 标记 xnx_gift_send_end.php（代码中为注释占位）。xnx_feeds 插件可通过实现该 hook 文件读取 $gift_log_id / $to_uid / $amount 等上下文自行推送动态。本插件自身不直接调用 xnx_feeds API，因此未安装 xnx_feeds 也不影响赠送主流程。

接收者解析

if ($to_input !== '' && ctype_digit($to_input)) {
    $to_user = user_read(intval($to_input));   // 纯数字 → 按 UID
} else {
    $to_user = user_read_by_username($to_input); // 否则 → 按用户名
}

用户不存在时返回 ['ok'=>false, 'message'=>'用户不存在']。

路由注入

通过 3 个 hook 与核心解耦：

• model_inc_file.php：把 model/GiftService.php 加入 model 加载列表
• admin_index_route_case_end.php：在后台路由 switch 中注入 case 'xnx_gift'，指向 route/admin_gift.php
• admin_sidebar_end.htm：在后台侧边栏追加「积分赠送」菜单项，自动高亮当前路由

用户信息批量加载

GiftService::getLogs() 收集日志中出现的所有 from_uid / to_uid，调用 user_find_by_uids(implode(',', $uids)) 一次性批量获取用户信息（自动走 user_format），避免列表页 N+1 查询。

分页 URL 构建

记录页分页 URL 手动拼接 query string 保留 filter_input 筛选条件，{page} 占位符交给 pagination() 函数替换。前端表单提交通过 JS 拦截 submit 事件重建 URL，避免 GET 表单覆盖路由参数。

数据表

| 表名 | 用途 | 关键字段 | |---|---|---| | xnx_gift_log | 赠送日志 | id, from_uid, to_uid, credits_type(varchar 10), amount, reason(varchar 255), create_date, ip；KEY from_uid / to_uid / create_date |

使用 InnoDB / utf8mb4 字符集。建表语句使用 IF NOT EXISTS 保证幂等。

兼容性

• Xiuno X 1.1+（bbs_version: 1.1）
• PHP 8.x
• Bootstrap 5
• 依赖核心 CreditsService（位于 lib/CreditsService.php）
• 依赖核心 notify_create() 函数（发送站内通知）
• xnx_feeds 联动为可选项，未安装不影响主功能
• 通过 hook 与核心解耦，核心代码无硬编码插件名

版本历史

• 1.0.0 (2026-07-31)：首版发布，包含后台赠送积分、赠送记录查询与筛选、站内通知、xnx_feeds hook 扩展点、enable_feed / enable_notify 配置开关

版本 1.0.0 | 兼容 Xiuno 1.1+