[point_gift]积分钱包热

插件质量报告

插件：point_gift

颜色说明：黄色表示有数据读写，红色表示 Hook 在系统循环中执行，浅蓝色表示有文件写入。“列表跳过”表示回调在列表路径会提前返回，“回调内”表示操作位于回调自身或其帮助函数的循环体内。“文件批处理”表示逐个处理用户一次提交的文件，属于必要操作，不标记修正。只有操作实际处于需要优化的循环路径时，才会标记“修正❗️”。

数据字典

plugin_point_gift_transactions

plugin_point_gift_redpackets

plugin_point_gift_claims

plugin_point_gift_topic_sources

版本 1.1.0 更新：
使用
用户：顶部快捷功能「我的钱包」→ 钱包页；或进入任意用户主页 → 「钱包」Tab → 转赠/发红包/领取
管理员：后台顶部 Tab「积分钱包」→ 配置参数、查询流水、调整余额
安全设计
转账与红包发送：事务内原子扣款（points>=? 条件更新），杜绝并发超扣
领取红包：原子条件更新（remain>=?），并发下先到先得，不会超发
红包金额完整发放：最后一份自动领取全部剩余积分（普通/拼手气均不滞留），红包状态为已领完时剩余恒为 0
过期退回防多退：退回金额在事务内重读（UPDATE status → 读 remain → 退积分），与并发领取竞争时按实际剩余退回
所有金额为正整数，服务端强校验；频率/额度限制默认关闭，后台可开启
封禁用户不可转出/领取（可收）；不能转赠给自己；不能领取自己发的红包
表单全部 CSRF 保护；附言长度限制；流水只增不删
表单字段避开 name="action"（该名称会被浏览器表单命名控件覆盖 form.action，官方插件用 invite_action 同理）
数据表
安装时创建 3 张表（卸载自动删除，零残留）：

表 用途
plugin_point_gift_transactions 收支流水（kind: transfer/send/receive/fee/expire_back/admin）
plugin_point_gift_redpackets 红包（类型/总额/剩余/份数/状态/过期时间）
plugin_point_gift_claims 领取记录（每人限领一份，唯一约束）
兼容性
要求 bbs1org v8.7.2+（PHP 8.0+）
数据库：MySQL 5.7 / 8.0、PostgreSQL、SQLite 均支持（表操作走官方 app_db_* 跨库 API；红包份数判定用标准 SQL 条件，不依赖数据库求值顺序）
无外部依赖、无 cron 需要，定时任务由核心调度（每小时检查过期红包）
余额直接使用核心 app_users.points，与签到、管理调整、个人页显示完全一致
更新日志
v1.1.0（2026-08-26）
修复：个人主页「钱包」Tab 一键转赠提交 404（表单字段误用 name="action"）
修复：普通/拼手气红包最后一份不全拿，剩余积分滞留（已领完但金额未发完）
修复：过期红包退回金额按事务外旧值计算，与并发领取竞争时可能多退
修复：管理员负数额度调整的流水金额方向丢失（后台表格/最近调整/钱包页均显示 ±）
新增：后台筛选/分页/每页条数/跳页全部静默刷新（无整页跳转、滚动位置不丢失），分页支持每页条数设置与页码跳转，收支流水与最近红包分页状态互不覆盖
美化：空状态卡片（SVG 图标）、表格间距/表头/hover、红包类型分段控件、最近调整信息卡片、分页条
兼容性与表结构不变，可直接覆盖升级
v1.0.0（首发）
钱包页：余额、流水、转赠、发红包、领红包
转赠：附言、快捷理由、比例手续费、原子扣款
红包：普通/拼手气、限领一份、过期自动退回
个人主页钱包 Tab、快捷功能入口
后台：参数配置、流水筛选查询、红包列表、余额调整、手动过期退回

该插件缺少两个标准插件头字段：

1. [第 1-14 行 (line 1)] 没有安全入口保护，导入器要求包含：

if (!defined('APP_ROOT')) exit;

2. manifest 缺少必填的 author 字段。即使补上入口保护，下一步也会提示“插件 manifest 不完整”。

建议改为：
<?php
if (!defined('APP_ROOT')) exit;

return [
'id' => 'point_gift',
'name' => '积分钱包',
'version' => '1.1.0',
'description' => '...',
'author' => '作者名或站点名',
// 其余字段不变
];

版本 1.1.0 更新：
合规：补齐标准插件头——if (!defined('APP_ROOT')) exit; 安全入口保护 + manifest author 字段，符合官方导入器要求

发出红包，应该给一个代码，可以复制红包到任意主题里面让大家打开红包。
参考微信红包在微信群的体验。

版本 1.5.3 更新：
一、功能总览
模块 能力
积分余额 钱包页顶部余额卡，今日转出 / 近 1 分钟次数 / 手续费实时统计
转赠 比例手续费（转出方支付，可配置 0-10%）、快捷理由下拉、附言双方可见、大额二次确认（可配置阈值）
发红包 普通（均分）/ 拼手气（随机）两种，实时费用预览，未领完过期自动退回发送者
帖内红包 发红包后复制 [redpacket=ID] 分享码，贴到任意帖子/回复正文即渲染为红包卡片，点击弹层拆包、动画显示到账金额
弹幕红包 弹幕消息里贴分享码，渲染为迷你红包 chip，点击直接弹层拆包；领取后 chip 原地灰化显示「已领」
领取明细 钱包列表「明细」按钮 / 帖子内点自己的红包 → 弹窗直查：谁领了多少、金额、时间（最近 100 条，更多走独立页）
收支流水 全量流水分页展示：转赠/发红包/领红包/手续费/过期退回/系统调整
我发出的红包 分页列表（每页 10 条），状态角标（进行中/已领完/已过期）、领取进度条、复制分享码、明细入口
个人主页 Tab 本人看余额与流水，他人可一键转赠
通知中心 双向通知：领取者收到「你领取了 X 的红包」；发送者每次收到「X 领取了你的红包（剩余 N 份）」；领完保留汇总
后台管理 参数配置、全量流水/红包查询、余额调整（记流水）、立即执行过期退回
二、用户使用指南
2.1 发红包（钱包页）
进入「积分钱包」（个人主页 Tab 或侧边栏入口）
「发红包」面板：选择类型
普通：总金额按份数均分，每人一份
拼手气：每份金额随机（≥ 配置的单份最小值），总金额由你设定
填总金额、份数、有效期（小时，默认 24）、附言（可选，用逗号分隔的快捷理由可下拉选择）
提交后列表出现该红包，点「复制代码」得到 [redpacket=ID]
2.2 帖内红包
把 [redpacket=ID] 贴进帖子/回复正文，发布后自动渲染为红包卡片：

别人看到：可拆状态 → 点击弹层「开」→ 拆包动画 → 显示到账金额
自己看到：显示「我的」角标，点击弹层显示「查看明细」→ 弹窗查看谁领了多少
2.3 领取规则
默认一人一份（重复领取返回「你已领取过该红包」）
后台开启「允许同一人重复领取」后，可按「每人份数上限」领取多份
2.4 弹幕红包
弹幕消息里直接输入 [redpacket=ID]，发送后实时滚动的弹幕里会出现绿色迷你红包 chip：

点击 chip → 弹层拆包
领取成功后 chip 变灰显示「已领」，不会重复领
2.5 领取明细
钱包页：我发出的红包每项有「明细」按钮 → 弹窗直查（最近 100 条）
帖子内：点自己的红包 → 弹层「查看明细」→ 同样弹窗
明细超过 100 条时弹窗提供「查看全部明细 →」跳独立分页页（每页 20 条）
权限：仅发送者本人与管理员可见
三、后台配置（管理后台 → 积分钱包）
3.1 转赠限制
参数 说明 默认
手续费 % 转出方支付，0-10 0
单笔转出上限 含手续费，0=不限 0
每日转出上限 0=不限 0
每分钟转出笔数上限 0=不限 0
大额转赠二次确认阈值 转赠达到该值需弹窗确认，0=关闭 1000
3.2 红包参数
参数 说明 默认
拼手气红包单份最小积分 随机分配的单份下限 1
红包总金额上限 0=不限 0
红包过期小时数 过期后剩余积分自动退回 24
允许同一人重复领取 勾选后同一人可领多份（默认一人一份） 关
重复领取时每人最多份数 仅允许重复领取时生效，0=不限 0
3.3 其他
功能 说明
全量流水 类型/用户/关键词筛选，分页（10-100 条/页），红包面板独立分页
余额调整 输入 UID + 增减积分（正加负减）+ 备注，记入流水
立即执行过期退回 手动触发过期红包退回（正常情况下每小时自动执行）
四、权限模型
操作 权限
领取红包 登录用户；一人一份（默认）或受个人上限约束
查看他人红包明细 发送者本人 + 管理员；接口对他人返回拒绝
后台配置/余额调整 管理员（need_admin）
发红包/转赠 登录用户，受限额/频率/余额约束
五、技术要点（开发者）
全部函数 point_gift_ 前缀；CSS/JS 类名 point-gift- / pg- 前缀，避免全局冲突
资产为静态构建（无动态数据），改动 CSS/JS 后由核心重建 app/assets/plugins.css|js（?v=hash 防缓存）
数据表（install 自动创建）：
plugin_point_gift_transactions（流水，索引 from_uid/to_uid/kind）
plugin_point_gift_redpackets（红包，索引 status+expires_at / from_uid）
plugin_point_gift_claims（领取记录，索引 packet_id+uid）
弹幕集成：danmaku_react payload 先整体 h() 转义，再经 point_gift_danmaku_chip_html() 把 [redpacket=ID] 替换为受控 chip HTML，前端 innerHTML 渲染安全；切勿在首屏面板再做二次转义
弹层为单视图模式（.pg-overlay-packet 一个容器，open/state 子元素切换），不存在多窗口叠影
中文截断用 point_gift_cut()（mbstring 按字符），无乱码
弹窗明细走 point_gift_claims_ajax（JSON），前端 DOM 构建（textContent），无 XSS
六、版本历史
版本 内容
v1.5.3 配色改绿白黑：卡片/拆包/到账/明细弹层统一绿系，白底白字黑字分层，「开」按钮白底绿字，明细弹层彻底浅色化（白底黑字绿强调），清除全部红金残留
v1.5.2 配色重设计（去土味）：统一正红系深浅递进，金色收敛为细点缀，到账弹层弃用橙棕底（该深色方案在 v1.5.3 被绿白黑取代）
v1.5.1 领取明细改弹窗直查：修复 v1.5.0「领取明细 →」外挂链接导致的布局错乱；钱包列表内嵌「明细」按钮，帖子 mine 弹层按钮变「查看明细」，AJAX 弹窗展示最近 100 条
v1.5.0 「我发出的红包」分页（每页 10 条，独立参数 sp）；新增领取明细页（分页 20/页）；弹幕 chip 领取后灰化「已领」；红包设置新增「允许同一人重复领取 + 每人份数上限」
v1.4.3 中文安全截断（mbstring 按字符）+ 复制按钮金色渐变实底 + 成功绿态
v1.4.2 弹层单视图化：删 info 视图与 🎁 大图标（根治「一个红包两个窗口」），状态文字图标化（我/过/完）
v1.4.1b 修复弹幕首屏双重转义（首屏直接输出 payload，不再二次 h()）
v1.4.1 弹幕红包 chip（[redpacket=ID] 渲染迷你红包）+ 红金 UI 重设计 + 卡片状态角标
v1.4.0 领取通知双向补全（领取者 + 发送者逐次通知 + 领完汇总）
v1.3.x 帖内红包分享码、微信风弹层、全量流水、闪屏/双窗系列修复

这次不错
[redpacket=1]

样式上面要用系统的颜色变量；否则在不同色系下面会有问题。

版本 1.5.6 更新：
版本 内容
v1.5.6 修复无表单页面（通知中心等）领取假报「请先登录后再领取」：前端原依赖页面 input[name="_csrf"] 取 CSRF token，无表单页面取不到即被拦截；弹层模板改为服务端注入 data-pg-csrf 与正确路由 URL（data-pg-claim-url/data-pg-claims-url），任意页面均可领取/查明细；弹幕 chip 领取地址由写死的伪路径 /point_gift_claim_ajax 改为 route_url() 生成（兼容子目录部署）
v1.5.5 帖内红包卡片改微信风竖版矩形（上红块 + 下白条，与微信红包同构）；统一红色（var(--danger)），状态靠角标/底部条/图标区分，失效态用系统灰；全部颜色改用系统 CSS 变量（透明度用 color-mix），换主题色系不失真；弹层/到账/明细/复制/明细按钮/chip 一并系统变量化

后台UI优化下

插件都开放任何用户可更新 觉得插件有需要优化改善的可以自行优化改善也可以提出来 看到有时间会进行维护

版本 1.7.2 更新：
一、功能总览
模块 能力
积分余额 钱包页顶部余额卡，今日转出 / 近 1 分钟次数 / 手续费实时统计
转赠 比例手续费（转出方支付，可配置 0-10%）、快捷理由下拉、附言双方可见、大额二次确认（可配置阈值）
发红包 普通（均分）/ 拼手气（随机）两种，实时费用预览，未领完过期自动退回发送者
帖内红包 发红包后复制 [redpacket=ID] 分享码，贴到任意帖子/回复正文即渲染为微信风竖版红包卡片（上红块 + 下白条），点击弹层拆包、动画显示到账金额
弹幕红包 弹幕消息里贴分享码，渲染为迷你红包 chip，点击直接弹层拆包；领取后 chip 原地灰化显示「已领」
领取明细 拆包成功即显示「共 N 人参与 + 前 5 人 + 查看全部」；钱包「明细」/ 帖子内点红包 → 弹窗直查谁领了多少（发送者/管理员/领取者均可看，最近 100 条，更多走独立页）
收支流水 全量流水分页展示：转赠/发红包/领红包/手续费/过期退回/系统调整
我发出的红包 分页列表（每页 5 条），状态角标（进行中/已领完/已过期）、领取进度条、复制分享码、明细入口
个人主页 Tab 本人看余额与流水，他人可一键转赠
通知中心 双向通知：领取者收到「你领取了 X 的红包」；发送者每次收到「X 领取了你的红包（剩余 N 份）」；领完保留汇总
后台管理 参数配置、全量流水/红包查询、余额调整（记流水）、立即执行过期退回
二、用户使用指南
2.1 发红包（钱包页）
进入「积分钱包」（个人主页 Tab 或侧边栏入口）
「发红包」面板：选择类型
普通：总金额按份数均分，每人一份
拼手气：每份金额随机（≥ 配置的单份最小值），总金额由你设定
填总金额、份数、有效期（小时，默认 24）、附言（可选，用逗号分隔的快捷理由可下拉选择）
提交后列表出现该红包，点「复制代码」得到 [redpacket=ID]
2.2 帖内红包（微信风竖版卡片）
把 [redpacket=ID] 贴进帖子/回复正文，发布后自动渲染为竖版矩形红包卡片（与微信红包同构）：

上部红块：白底图标（包/我/✓/过/完）、标题「来自 XX 的普通红包」、进度、动作按钮（白底红字）
下部白条：状态引导（点击领取 / 我的红包·查看 / 已领取 / 已领完 / 已过期）
状态区分：右上角小角标（我的/已领/领完/过期/失效）+ 底部条文案，红块颜色统一（失效态变灰）
别人看到：可拆状态 → 点击弹层「开」（白底红字）→ 拆包动画 → 显示到账金额
自己看到：显示「我的」角标，点击弹层显示「查看明细」→ 弹窗查看谁领了多少
2.3 领取规则
默认一人一份（重复领取返回「你已领取过该红包」）
后台开启「允许同一人重复领取」后，可按「每人份数上限」领取多份
2.4 弹幕红包
弹幕消息里直接输入 [redpacket=ID]，发送后实时滚动的弹幕里会出现绿色迷你红包 chip：

点击 chip → 弹层拆包
领取成功后 chip 变灰显示「已领」，不会重复领
2.5 领取明细
拆包即见：领取成功的结果视图实时显示「共 N 人参与」+ 前 5 人；超过 5 人提供「查看全部 N 人明细 →」入口
钱包页：我发出的红包每项有「明细」按钮 → 弹窗直查（最近 100 条）
帖子内：点自己的红包 → 弹层「查看明细」→ 同样弹窗
已领取的红包：点「已领取」卡片 → 弹层「查看明细」也能看到其他参与者
明细超过 100 条时弹窗提供「查看全部明细 →」跳独立分页页（每页 20 条）
权限：发送者本人、管理员、以及领取过该红包的人可见
三、后台配置（管理后台 → 积分钱包）
后台已按功能块拆分为独立面板：数据统计、参数设置（转赠限制 / 红包参数 / 快捷附言）、余额调整、最近调整、收支流水、最近红包，便于维护与扩展。

3.1 转赠限制
参数 说明 默认
手续费 % 转出方支付，0-10 0
单笔转出上限 含手续费，0=不限 0
每日转出上限 0=不限 0
每分钟转出笔数上限 0=不限 0
大额转赠二次确认阈值 转赠达到该值需弹窗确认，0=关闭 1000
3.2 红包参数
参数 说明 默认
拼手气红包单份最小积分 随机分配的单份下限 1
红包总金额上限 0=不限 0
红包过期小时数 过期后剩余积分自动退回 24
允许同一人重复领取 勾选后同一人可领多份（默认一人一份） 关
重复领取时每人最多份数 仅允许重复领取时生效，0=不限 0
3.3 其他
功能 说明
数据统计 后台顶部聚合面板：全站积分总额、红包总数（进行中/已领完/已过期）、累计发出红包与领取率、待领积分、转赠总额、红包领取次数、累计手续费、流水总笔数
全量流水 类型/用户/关键词筛选，分页（10-100 条/页），红包面板独立分页
余额调整 UID / 积分（正加负减）/ 备注 表单；「最近调整」独立表格面板展示最近 5 笔（ID / 用户 / 调整金额 / 备注 / 时间）
立即执行过期退回 手动触发过期红包退回（正常情况下每小时自动执行）
四、权限模型
操作 权限
领取红包 登录用户；一人一份（默认）或受个人上限约束
查看红包明细 发送者本人 + 管理员 + 领取过该红包的人；未领取者不可见
后台配置/余额调整 管理员（need_admin）
发红包/转赠 登录用户，受限额/频率/余额约束
五、技术要点（开发者）
全部函数 point_gift_ 前缀；CSS/JS 类名 point-gift- / pg- 前缀，避免全局冲突
颜色一律使用系统 CSS 变量（--danger/--inverse-text/--panel/--bg/--text-muted/--success/--backdrop/--shadow-base/--shadow-medium 等），透明度用 color-mix()，换主题色系不失真
资产为静态构建（无动态数据），改动 CSS/JS 后由核心重建 app/assets/plugins.css|js（?v=hash 防缓存）
数据表（install 自动创建）：
plugin_point_gift_transactions（流水，索引 from_uid/to_uid/kind）
plugin_point_gift_redpackets（红包，索引 status+expires_at / from_uid）
plugin_point_gift_claims（领取记录，索引 packet_id+uid）
弹幕集成：danmaku_react payload 先整体 h() 转义，再经 point_gift_danmaku_chip_html() 把 [redpacket=ID] 替换为受控 chip HTML，前端 innerHTML 渲染安全；切勿在首屏面板再做二次转义
弹层为单视图模式（.pg-overlay-packet 一个容器，open/state 子元素切换），不存在多窗口叠影
中文截断用 point_gift_cut()（mbstring 按字符），无乱码
拼手气随机分配采用二倍均值法（微信红包同款）：每份在 [min, 剩余均值×2] 内随机，且保证后续每份至少 min，分布均匀，避免「第一个人拿大头、后面人人 1 分」
进度条统一按份数（taken/count）计算，与「X / Y 份」一致（拼手气金额随机，不能用金额比例）
弹窗明细走 point_gift_claims_ajax（JSON），前端 DOM 构建（textContent），无 XSS
CSRF 与路由注入：弹层模板由服务端注入 data-pg-csrf（csrf_token）与领取/明细路由 URL，不依赖页面表单的 _csrf 隐藏域——通知中心等无表单页面也能正常领取与查明细；弹幕 chip 的领取地址由 route_url() 生成，兼容子目录部署
六、版本历史
版本 内容
v1.7.2 进度条统一按「份数」计算：后台「最近红包」进度条移到「领取」列，前端「可领红包」按剩余份数、「我发出的红包」按已领份数；修复拼手气红包因金额随机导致进度条参差不齐
v1.7.1 ①领取者也能查看红包领取明细——权限从「仅发送者/管理员」放宽到「发送者/管理员/领取过的人」，已领取卡片点击可看明细；②大红包明细优化——结果视图只展示前 5 人 + 「查看全部 N 人明细」入口，明细弹层滚动 + 详情页 20 条/页分页
v1.7.0 ①后台「最近调整」改表格列表并新增「备注」列；②拼手气红包改「二倍均值法」（微信同款，分布更均匀，修复「第一个人拿大头、后面人人 1 分」）；③拆包成功结果视图新增参与明细（谁领了多少，最多 100 条）；④后台表单输入框高度统一并修正垂直对齐
v1.6.0 后台排版重构：功能块拆为独立面板（数据统计 / 参数设置 / 余额调整 / 最近调整 / 收支流水 / 最近红包），参数设置三组配置各自独立卡片；新增「数据统计」面板（全站积分、红包总数/发出/待领/领取率、转赠/领取/手续费、流水笔数）；功能逻辑不变
v1.5.6 修复无表单页面（通知中心等）领取假报「请先登录后再领取」：前端原依赖页面 input[name="_csrf"] 取 CSRF token，无表单页面取不到即被拦截；弹层模板改为服务端注入 data-pg-csrf 与正确路由 URL（data-pg-claim-url/data-pg-claims-url），任意页面均可领取/查明细；弹幕 chip 领取地址由写死的伪路径 /point_gift_claim_ajax 改为 route_url() 生成（兼容子目录部署）
v1.5.7~v1.5.17 后台「最近调整 / 余额调整」面板的多次美化重构（列表化、表格化、双栏、统计卡、独立面板等）——最终按用户要求整体回退到 v1.5.6，仅保留历史记录
v1.5.5 帖内红包卡片改微信风竖版矩形（上红块 + 下白条，与微信红包同构）；统一红色（var(--danger)），状态靠角标/底部条/图标区分，失效态用系统灰；全部颜色改用系统 CSS 变量（透明度用 color-mix），换主题色系不失真；弹层/到账/明细/复制/明细按钮/chip 一并系统变量化

不得不说，这个插件做的很辛苦，用心

版本 1.7.3 更新：
修复打开红包页面变窄的BUG！

版本 1.7.4 更新：
v1.7.4 主题列表页新增「红包」标识：含红包分享码（正文或回复贴了 [redpacket=ID]）的主题标题后显示红色「红包」徽标（内联 SVG 红包图标 + 文字，与标题保持间距）；topic.index_data.loaded 一次性批量 IN 查询 + 静态缓存，逐行渲染仅 O(1) 集合查找，零循环查询（避免 N+1）
v1.7.3 修复打开红包弹层时页面变窄：核心已用 html{overflow-y:scroll;scrollbar-gutter:stable} 固定滚动条沟槽，滚动条不会消失；移除锁滚动时多余的 padding-right 补偿，避免双倍预留挤窄内容

版本 1.8.0 更新：
新增限流复合索引：(from_uid, kind, created_at)。
主题红包标签改为来源映射表；只记录今后新建或编辑的主题/回复，旧数据不会回填或扫描。
Markdown 红包卡片按 ID 去重后批量读取红包、发送者和当前用户领取状态。
过期任务按 ID 每次最多处理 100 条，后续 cron 自动继续。
后台统计增加 60 秒文件缓存。
已移除流水附言关键词筛选及其 %LIKE% 查询。
编辑、删除主题/回复会同步维护映射记录。

版本 1.8.1 更新：
更新红包界面

版本 1.8.1 更新：
优化界面和入口链接

版本 1.8.1 更新：
已修复。允许重复领取时，第二次领取成功后会更新已是 claimed 状态的卡片，不再只更新首次的 open 卡片。
现在 6 份红包领到第 2 份后会显示 2/6 已领取 · 剩余 4

真是不错啊