# 一物一码抽奖插件功能逻辑说明
该插件基于芸众商城框架开发，可以用芸众商城免费版+插件完美配合运行，且商用
奖品类型完美融合了，实物（商城里的产品）商城积分 商城余额 商城各种兑换码，充值码，微信红包 商城优惠券，自动发放奖品，支持线下核销实物类奖品~
> 文档用途：用于产品、运营、测试、开发统一理解当前插件能力与业务逻辑。
> 适用版本：当前仓库已实现版本（含防伪查询、码库管理、虚拟码、H5/小程序双端）。
## 1. 插件定位
`一物一码，防伪抽奖` 是一个面向 芸众商城SaaS 场景的一物一码营销插件，支持：
- 活动抽奖（九宫格/转盘、多种参与模式）
- 防伪查询（可独立运行，不依赖抽奖活动）
- 一码双用（同一批码可配置为仅防伪/仅活动/防伪+活动）
- 多端使用（小程序 + H5）
核心目标：同一套系统兼容三类客户场景：
- 仅做防伪
- 仅做活动抽奖
- 防伪与抽奖同时做
---
## 2. 后台菜单结构（当前生效）
插件菜单（`一物一码抽奖`）下主要入口：
- 活动管理
- 码库管理
- 奖品管理
- 虚拟码库管理
- 码数据管理
- 中奖数据/核销
- 核销记录
- 防伪设置
- 防伪查询日志
- 红包设置
- 插件设置
说明：
- `码库管理` 位于活动管理下面，支持全局建批次（不关联活动）。
- 部分页面是功能子路由（新增/编辑/导入/导出/进度页），不在侧栏重复显示。
---
## 3. 核心业务对象
## 3.1 活动（Activity）
- 定义活动基础信息、时间、状态、页面模板、参与模式、次数限制等。
- 支持抽奖模式：
- 普通模式（免费次数）
- 余额模式（扣余额）
- 积分模式（扣积分）
- 抽奖码模式（手动输入码）
- 扫码模式（URL 自动带码）
## 3.2 码库批次（CodeBatch）
每个批次可配置：
- 所属活动（可为空）
- 批次生成规则（前缀、长度、数量、单码次数）
- 生效时间段
- 指定中奖奖品（可选）
- **码作用 usage_scene**
- `1` 仅防伪
- `2` 仅活动
- `3` 防伪+活动
约束：
- 仅防伪批次允许 `activity_id=0`（不关联活动）
- 仅活动/防伪+活动批次必须关联活动
## 3.3 码实例（Code）
- 真实码值记录，包含状态、可用次数、已用次数、最近使用人/时间等。
- 码状态：
- 作废（invalid）
- 可用（available）
- 用尽（used_up）
## 3.4 奖品（Prize）
奖品类型：
- 谢谢参与
- 实物奖品
- 虚拟码
- 积分
- 余额
- 优惠券
- 微信红包
## 3.5 防伪查询日志（AntiQueryLog）
记录每次防伪查询：
- 查询结果（首次/多次/超限/无效）
- 查询后累计次数
- 查询身份（会员ID 或 IP+设备）
- 查询时间、IP、UA 等
---
## 4. 码作用与可用范围（关键）
## 4.1 仅防伪
- 可用于防伪查询
- 不可参与抽奖（抽奖校验直接拦截）
## 4.2 仅活动
- 可参与抽奖
- 不可用于防伪查询（按无效码逻辑处理）
## 4.3 防伪+活动
- 防伪与抽奖都可用
---
## 5. 抽奖逻辑
## 5.1 抽奖前校验
- 活动状态与时间有效
- 会员参与限制（总上限/日上限/中奖上限）
- 码模式下必须码有效、批次启用、在批次时间内
- 余额/积分模式检查余额积分是否足够
- 幂等键防重复提交
## 5.2 抽奖执行
- 先按“批次指定中奖奖品”优先命中
- 否则按奖品概率权重随机
- 有库存的奖品才可发放
## 5.3 抽奖后处理
- 扣减库存、记录抽奖日志
- 码 `used_times + 1`，达到上限后标记 `used_up`
- 生成中奖记录并按奖品类型自动发奖
## 5.4 发奖规则（按奖品类型）
- 积分：加积分
- 余额：加余额
- 优惠券：发券并写优惠券日志
- 微信红包：走红包服务（公众号红包/小程序红包）
- 虚拟码：从虚拟码库锁定一条未使用码发放
- 实物：进入领奖/核销流程，不做自动余额类发放
---
## 6. 防伪查询逻辑
## 6.1 防伪设置范围
- 全局一套配置（非按活动）
- 通过设置中的 `bind_batch_id` 指定当前防伪使用哪个码批次
- 可选关联 `bind_activity_id`，用于“去抽奖”按钮跳转
## 6.2 查询结果判定
- 码不存在：无效
- 码批次不支持防伪或批次停用：无效
- 首次查询：`first`
- 多次查询：`multi`
- 超限查询：`over_limit`
- 已作废码：按无效/超限文案返回（依当前次数情况）
## 6.3 查询次数上限与失效
- 使用独立防伪日志计数，不复用抽奖 `used_times`
- 配置 `query_limit_times > 0` 且超过后：
- 当前查询结果为超限
- 自动将码状态写库为作废（invalid）
## 6.4 身份判定
- 开启强制登录：按会员ID判定首查人
- 关闭强制登录：按 `IP + UA哈希` 判定
## 6.5 查询历史显示
- 后台配置项 `show_history_count`
- 当前系统强制上限为 **2 条**
- 前端显示“最近N条”
## 6.6 去抽奖按钮逻辑
- 仅在以下同时满足时展示入口：
- 绑定了活动ID
- 当前码批次支持抽奖
- 查询结果为首次/多次
- 按钮是否可点击由剩余次数决定：
- 剩余 > 0：可点击，显示“您有X次抽奖机会”
- 剩余 = 0：禁用，显示“您的抽奖次数已使用”
---
## 7. 前端落地逻辑（小程序/H5）
## 7.1 扫码落地顺序
- 若防伪功能开启：先进入防伪页
- 若防伪关闭：直接进入抽奖页
该逻辑在小程序与 H5 都已接入。
## 7.2 小程序页面
- 抽奖页：
- 防伪页：
- 领奖详情页：`
防伪页特性：
- 使用小程序原生导航标题，不再重复内页标题条
- 红色双行“点击去抽奖”按钮（含禁用态）
- 查询时间与历史时间统一按有效时间戳显示
## 7.3 H5 页面
- 抽奖页：`/
- 防伪页：`/
- 记录页：`/
- 领奖页：`/
H5 抽奖页在带 `code` 且非 `from_anti=1` 时，会先调用防伪设置接口决定是否跳防伪页。
---
## 8. 码库管理（无活动场景）
为解决“仅防伪客户无活动无法建码”的问题，已实现：
- 菜单 `码库管理` 可直接进入（无需活动ID）
- 新建批次可选择“不关联活动（仅防伪）”
- 码数据导入/导出/查看支持无活动批次
适用方式：
1. 进入码库管理创建“仅防伪”批次（不关联活动）
2. 生成码并导出
3. 防伪设置中绑定该批次ID即可使用防伪查询
---
## 9. 虚拟码奖品逻辑
- 虚拟码库支持文本/文件导入
- 支持 `txt/csv/xls/xlsx` 导入
- 提供导入模板下载（xls）
- 发奖时从虚拟库锁行取码，写入中奖记录 `receive_info.virtual_code`
- 前台领奖页支持“查看码/复制虚拟码”
- 后台中奖记录详情与导出可带出虚拟码
---
## 10. 二维码与链接
- H5 扫码入口：`addons/yun_shop/qr.php`
- 小程序码保存目录：`static/upload/new-lucky-draw/wxacode`
- 小程序 scene 约定：`a={activity_id}&c={code}`
---
## 11. 关键配置建议（运营）
- 仅防伪项目：
- 批次设置为“仅防伪”
- 防伪设置中活动ID可留空/0
- 防伪+抽奖项目：
- 批次设置为“防伪+活动”
- 绑定对应活动ID与批次ID
- 查询历史建议：
- 保持 1~2 条，避免页面拥挤（系统上限2）
- 查询上限建议：
- 按品牌防伪策略设置，超限即自动作废
---
## 12. 当前实现边界说明
- “码库管理”已支持全局建码，但“奖品管理”仍是活动维度管理（符合当前产品结构）
- 仅防伪批次不参与抽奖，相关按钮会自动禁用/隐藏
- 防伪查询日志为独立计数体系，不影响抽奖用码次数计数
---
## 13. 主要代码入口（开发定位）
- 菜单配置：`src/common/services/MenuConfigService.php`
- 抽奖服务：`src/common/services/DrawService.php`
- 发奖服务：`src/common/services/RewardService.php`
- 码库管理：`src/admin/controllers/CodeBatchController.php`
- 码数据管理：`src/admin/controllers/CodeDataController.php`
- 防伪设置：`src/admin/controllers/AntiSettingController.php`
- 防伪日志：`src/admin/controllers/AntiLogController.php`
- 防伪接口：`src/frontend/AntiController.php`
- 防伪核心逻辑：`src/common/services/AntiQueryService.php`
- 小程序防伪页：
- H5 防伪页：
---
## 14. 更新记录（本轮重点）
- 新增防伪查询全链路（配置、查询、日志、前后端页面）
- 新增码作用三态（仅防伪/仅活动/防伪+活动）
- 新增码库管理支持无活动建批次
- 防伪历史展示上限收敛为2条
- 防伪查询时间戳显示问题修复
- 防伪页“去抽奖”按钮改为动态剩余次数与禁用态
- H5 接入与小程序一致的防伪落地逻辑
扫一扫
1387
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
