Typecho评论抽奖插件

插件说明

在同一篇文章中创建多个限时抽奖活动，支持一轮结束后继续新增活动，也支持多个活动同时进行。每个活动截止后独立从本文符合其时间范围的顶层评论者中随机抽取 1 人，公示中奖昵称；无合格参与者则流局。支持实体和虚拟奖品：实体奖品邮件邀请中奖者填写收货地址，虚拟奖品将预设的兑换码、下载地址或说明直接发送到中奖邮箱。

安装与使用

1. 下载仓库，将文件夹命名为 CommentLottery，放到 Typecho 的 usr/plugins/ 下。也可在 Typecho 根目录执行：

   git clone https://github.com/jkjoy/CommentLottery.git usr/plugins/CommentLottery

2. 后台「控制台 → 插件」启用 CommentLottery，进入设置，填写 SMTP 服务器、端口、加密方式、用户名、密码或授权码、发件邮箱及名称。在「测试发件」中填写自己的收件邮箱，点击「发送测试邮件」，查看页面反馈及收件箱、垃圾邮件。测试使用页面当前填写的设置，可在保存前验证；确认收到后，再点击「保存设置」。设置中的「排除历史中奖者」默认开启，排除方式默认「按邮箱」，也可改为「按评论」或关闭排除；保存后影响后续尚未开奖的活动。
3. 使用管理员或编辑账号编辑文章，点击正文编辑器工具栏的 礼物 SVG 图标「设置评论抽奖」，打开抽奖设置。在活动列表中选择已有活动，或点击「新增活动」创建下一场。启用活动，填写活动名称、开始和截止时间、奖品类型及奖品名称。奖品名称留空时使用活动名称。时间按 Typecho 站点时区 解释，与服务器或浏览者电脑时区无关。
4. 如果选择「虚拟物品」，在弹窗的「发放内容」中填写兑换码、下载地址及使用说明，该字段标有「仅中奖者可见」。此内容随文章或草稿独立保存，发布虚拟奖品活动前必须填写；不要写入文章正文。单份发放内容最多 60000 字节，编辑框最多 20000 字符。
5. 点击「应用并插入」，启用活动时在光标位置插入展示标记；已有标记时按钮改为「应用设置」，不会重复插入。需要调整展示位置时，可移动正文中的这一行：

[comment-lottery]

6. 应用后，还需保存草稿或发布文章，设置才会持久保存。再次打开弹窗可查看所有活动，修改尚未开始的活动，或继续新增活动；「取消」或按 Esc 会放弃本次弹窗修改。开启文章评论并发布为无密码的公开文章。保存草稿只保存配置，发布才统一创建或更新所配置的活动。不插入标记时，活动自动显示在正文末尾。一个 标记展示本文全部已启用活动，无需为每个活动重复插入。
7. 按下文配置每分钟执行的计划任务。截止后，插件固定开奖结果并尝试发送中奖邮件，文章活动区域公示中奖昵称。管理页保留「手动开奖」，自动处理未及时执行时可使用。

抽奖设置通过独立数据表保存，不需要填写 Typecho 自定义字段。每个活动开始后，其设置独立锁定，私密发放内容不再载入编辑页面；其他未开始的活动仍可修改，也可新增下一场。新增活动保留之前的中奖记录、邮件状态和收货信息。

活动区域包含「等待开始」「正在进行」「等待开奖」「已开奖」「已流局」状态，同时显示奖品名称和类型。浏览器会读取最新状态，开奖后可自动更新公示，无需刷新整个文章。列表摘要及 RSS 中不会嵌入活动区域。

管理员可在插件设置页随时重新测试 SMTP。测试成功表示邮件已提交给 SMTP 服务器，最终是否收到请以收件邮箱为准。测试邮件独立发送，保留当前活动、中奖记录、奖品和收货信息，也不会自动保存配置。

自动开奖

PHP 插件本身不能在没有请求时后台常驻运行。需要配置服务器计划任务，才能在无人访问网站时照常开奖。 每分钟运行一次时，通常在截止后一分钟内处理；服务器停机或调度延迟时，会在恢复执行后补开，不会纳入截止后的评论。

Linux crontab 示例（替换 PHP 和站点的绝对路径）：

* * * * * /usr/bin/php /path/to/typecho/usr/plugins/CommentLottery/cron.php

Windows 任务计划程序：新建任务，触发器选择每 1 分钟重复；操作的程序填写实际 php.exe 路径，参数填写 "D:\path\to\typecho\usr\plugins\CommentLottery\cron.php"。PHP 需与站点使用相同的数据库驱动及扩展。cron.php 仅供 CLI 执行。

如果托管环境只能使用 HTTP 调度，在插件设置中配置或获取「计划任务令牌」，每分钟向调度路由发起 POST 请求，并在 X-Comment-Lottery-Token 请求头中携带令牌：

curl --fail --request POST \
  --header 'X-Comment-Lottery-Token: YOUR_SECRET_TOKEN' \
  'https://example.com/index.php/action/comment-lottery?do=cron'

请使用站点实际 index 路径：启用伪静态时可能为 https://example.com/action/comment-lottery?do=cron，子目录安装时需包含子目录。令牌不要写在 URL 查询参数中，HTTP 调度接口不接受匿名请求。通过 HTTPS 调用，并保持该接口不被缓存。

插件也在网站访问时触发到期处理，作为计划任务的补充。仅依靠访问时，会在截止后的下一次请求才处理；没有访问就会延迟，不能保证准时。管理页的手动开奖同样只处理已经截止的活动，不会提前开奖，也不会重新抽取已固定的中奖者。

奖品发放与收货地址

实体物品

• 中奖邮件包含奖品名称、文章链接和专属领奖链接。中奖者通过链接填写收货人、联系电话、完整收货地址，无需登录 Typecho。
• 收货信息分别最多 80、30、500 字符，提交时检查必填项和基本格式。首次有效提交保存后，专属链接显示「已提交」，不能再次覆盖地址。
• 管理员进入「管理 → 评论抽奖」，在活动的「奖品 / 领奖信息」中查看已填写的收货地址并安排寄送。插件负责收集地址，不对接快递发货。
• 领奖链接仅发送到中奖邮箱，不显示在文章公示中。链接没有时间期限，并绑定该次活动；之后新增活动不会影响旧领奖链接。文章需保持公开、活动和插件需保持启用。请妥善保管链接；更换 Typecho 站点密钥会使旧链接失效。
• 地址只在管理员管理面板中显示，不在文章、公开状态接口或已提交后的领奖页面回显。

虚拟物品

• 预设内容在开奖后自动发送给唯一中奖者。单个活动对应一份虚拟奖品，可填写兑换码、下载链接、账号领取说明等纯文本。
• 活动开始前，可在文章编辑页，或管理员「管理 → 评论抽奖 → 修改发放内容」调整私密内容。活动开始后奖品类型、名称和发放内容锁定。
• 文章只显示奖品名称和类型。私密发放内容不会嵌入文章 HTML、公开状态响应或 Typecho 自定义字段；开始后管理列表显示「发放内容已配置」。
• 虚拟奖品不收集地址。邮件发送失败不会换人或消耗另一份奖品；重试发送同一份预设内容。

有效评论规则

• 每篇文章可以有多个活动，每个活动各抽取一名评论者。活动按各自的开始和截止时间独立统计；时间重叠时，符合条件的评论可以参与多个活动，同一邮箱在每个活动中各计一次。
• 插件设置中的「排除历史中奖者」默认开启，排除方式默认「按邮箱」：已经中奖的邮箱不再参与本文其他活动；更换昵称或提交新评论不会恢复资格。依据本文已保存中奖记录中的邮箱过滤，忽略邮箱大小写和首尾空格。
• 可将排除方式改为「按评论」，仅排除本文已经中奖的评论记录（coid）；同一邮箱的其他合格评论仍可参与
• 关闭「排除历史中奖者」后，历史中奖者符合时间、审核和邮箱规则时，仍可参与本文其他活动。开关和排除方式在实际开奖时生效，影响后续尚未开奖活动；已经保存的历史开奖结果保留，不重新抽取。同一篇文章同时开奖时逐场确定结果，按当前排除方式过滤后续活动。公开规则、文章编辑器和管理页显示当前设置。
• 仅统计当前文章的顶层评论，即状态为正常（已审核）的评论。子评论、待审核评论、垃圾评论、回响不参与。
• 评论提交时间必须满足 开始时间 ≤ 提交时间 < 截止时间。开始前及截止时刻起提交的评论无效，即使实际开奖较晚也不会纳入。
• 审核状态以实际开奖时读取的状态为准。在活动时间内提交、开奖前才审核为正常的评论可以参与；开奖时仍待审核或已被标记为垃圾的评论不能参与。
• 邮箱须有效。同一邮箱忽略大小写、去掉首尾空格后只计一次，使用该邮箱最早一条合格评论的昵称。昵称相同但邮箱不同的人各计一次。
• 通过 PHP random_int() 在去重后的参与者中等概率抽取；无合格参与者时保存「流局」，不发邮件。
• 活动开始后，标题、时间、启用状态及奖品配置锁定。文章正文仍可编辑；已开奖不会因编辑、刷新、邮件失败或重复操作重新抽人。继续抽奖时在同一篇文章点击「新增活动」，新活动使用独立配置和开奖结果；旧活动不会重置或覆盖。
• 禁用插件保留活动、中奖快照、收货信息及邮件状态，重新启用后继续处理。

同 IP 多邮箱提示

管理员「管理 → 评论抽奖」中，有同一 IP 使用多个有效邮箱的活动会显示折叠的「同 IP 多邮箱，需人工核对」。展开后可查看 IP、邮箱与评论数量、相关邮箱和评论编号；评论编号链接到后台对应评论，方便人工审查。没有此类记录的活动不显示提示。

统计使用本活动时间内当前已审核的顶层评论，在历史中奖者排除和邮箱去重之前生成，因此可能包含当前已被中奖规则排除的邮箱；报告基于当前记录，并非开奖时的风险快照。IP 只使用 Typecho 已记录的评论地址，同一 IP 可能对应共用网络。提示不会自动封禁、取消资格或改变开奖结果。IP、邮箱和风险详情仅管理员管理页显示，不进入文章公示、公开接口或文章编辑器。