本文由 FlintHub 开发文档归档发布。原始文档日期见标题前缀，来源：WWW/plugins/red_packet/说明.md。
积分红包（red_packet）插件说明
版本：1.10.0 ｜ 作者：SoSite ｜ 状态：⏸️ 停用（默认未启用）
功能：用户消耗积分创建红包，其他用户可以抢，抢到的积分自动加到账户（含过期退款）
一、功能简介
- 创建红包：用户消耗积分创建红包，设置总积分与份数
- 抢红包：其他用户可抢，每次抢到随机金额（
calculatePoints按剩余/份数算法分配） - 防重抢：
red_packet_claims表 UNIQUE(packet_id, user_id) + 事务捕获冲突，一人只能抢一次 - 过期退款：红包过期未抢完自动退还剩余积分给创建者（
refundExpired，访问触发懒清理） - 红包详情页：查看领取记录、剩余金额、过期倒计时
二、目录结构
plugins/red_packet/
├── plugin.json # 插件清单（hooks: init_after / route_register / nav_plugin_links）
├── Plugin.php # 生命周期（activate 建表 / uninstall 删表）
├── RedPacketController.php # 控制器（index/create/detail/grab/calculatePoints/refundExpired）
├── hook/
│ ├── init_after.php # 懒建表（含缓存文件初始化）
│ ├── route_register.php # 路由（/redpacket 系列）
│ └── nav_plugin_links.php # "应用"下拉"积分红包"入口
├── assets/
│ ├── style.css # 红包样式
│ └── script.js # 抢红包交互
└── views/
├── index.php # 红包列表（可创建/可抢）
└── detail.php # 红包详情（领取记录/剩余/过期）三、数据表（2 张）
| 表 | 用途 |
|---|---|
red_packets | 红包（creator_id / total_points / remaining_points / count / remaining_count / expires_at / status，idx_creator / idx_expires） |
red_packet_claims | 领取记录（packet_id / user_id / points / created_at，UNIQUE(packet_id, user_id) 防重抢） |
- 建表：
activate()+init_after懒建（幂等） - 卸载：
uninstall()删除两张表
四、Hooks
| Hook | 用途 |
|---|---|
init_after | 懒建表 + 初始化缓存文件 |
route_register | 前台路由（/redpacket） |
nav_plugin_links | "应用"下拉"积分红包"入口 |
五、路由
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /redpacket | 红包列表（可抢/可创建） |
| POST | /redpacket/create | 创建红包 |
| GET | /redpacket/{id} | 红包详情 |
| POST | /redpacket/{id}/grab | 抢红包（JSON：抢到积分/失败原因） |
六、核心逻辑
public function grab() // 事务内：INSERT claims（UNIQUE 防重）→ 扣减 remaining → 派奖
public function calculatePoints() // 随机分配：按剩余金额/人数算法
public function refundExpired() // 扫描过期 active 红包 → 事务退回剩余 → 改状态七、注意事项
- 防重抢：
UNIQUE(packet_id, user_id)唯一约束，INSERT 捕获 Duplicate entry → "你已经抢过了" - 抢红包在事务内完成（begin → 校验 → 扣减 → 记录 → commit），异常 rollback
- 过期退款为访问触发懒清理（grab 前或列表页触发
refundExpired），无需 cron - 卸载删表会丢失红包与领取记录，请谨慎
