# 一物一码抽奖插件功能逻辑说明该插件基于芸众商城框架开发可以用芸众商城免费版插件完美配合运行且商用奖品类型完美融合了实物商城里的产品商城积分 商城余额 商城各种兑换码充值码微信红包 商城优惠券自动发放奖品支持线下核销实物类奖品~ 文档用途用于产品、运营、测试、开发统一理解当前插件能力与业务逻辑。 适用版本当前仓库已实现版本含防伪查询、码库管理、虚拟码、H5/小程序双端。## 1. 插件定位一物一码防伪抽奖 是一个面向 芸众商城SaaS 场景的一物一码营销插件支持- 活动抽奖九宫格/转盘、多种参与模式- 防伪查询可独立运行不依赖抽奖活动- 一码双用同一批码可配置为仅防伪/仅活动/防伪活动- 多端使用小程序 H5核心目标同一套系统兼容三类客户场景- 仅做防伪- 仅做活动抽奖- 防伪与抽奖同时做---## 2. 后台菜单结构当前生效插件菜单一物一码抽奖下主要入口- 活动管理- 码库管理- 奖品管理- 虚拟码库管理- 码数据管理- 中奖数据/核销- 核销记录- 防伪设置- 防伪查询日志- 红包设置- 插件设置说明- 码库管理 位于活动管理下面支持全局建批次不关联活动。- 部分页面是功能子路由新增/编辑/导入/导出/进度页不在侧栏重复显示。---## 3. 核心业务对象## 3.1 活动Activity- 定义活动基础信息、时间、状态、页面模板、参与模式、次数限制等。- 支持抽奖模式- 普通模式免费次数- 余额模式扣余额- 积分模式扣积分- 抽奖码模式手动输入码- 扫码模式URL 自动带码## 3.2 码库批次CodeBatch每个批次可配置- 所属活动可为空- 批次生成规则前缀、长度、数量、单码次数- 生效时间段- 指定中奖奖品可选- **码作用 usage_scene**- 1 仅防伪- 2 仅活动- 3 防伪活动约束- 仅防伪批次允许 activity_id0不关联活动- 仅活动/防伪活动批次必须关联活动## 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_anti1 时会先调用防伪设置接口决定是否跳防伪页。---## 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 接入与小程序一致的防伪落地逻辑