目录与快速上手
ZL-售卡系统是运行在 UniQQ 上的群聊卡密自动售卖插件:群友下单、渠道收款、验签出库、自动发货全程无人值守。本篇提供整套文档的阅读地图,并带你在几分钟内跑通一次完整购买流程。
📖 文档结构
| 篇章 | 主要内容 | 适合读者 |
|---|---|---|
| 安装与首次配置 | 安装、控制台、主人权限、群组开关、数据目录 | 首次安装者 |
| 商品与卡密库存 | 商品字段、定价、适用群、批量导入、库存状态 | 商品管理员 |
| 支付渠道配置 | 易支付、支付宝当面付、微信支付 API v2/v3 | 支付配置人员 |
| 邮箱与自动发货 | SMTP、发件昵称、模板、发货顺序与兜底 | 发货配置人员 |
| 群内指令与运营 | 用户与管理员指令、自定义触发词、欢迎语 | 群管理员 |
| 订单售后与安全 | 查单、补发、关闭订单、日志与安全原则 | 售后管理员 |
| 上线验收清单 | 0.01 元真实测试、上线检查、验收脚本 | 正式运营前必读 |
| 常见问题FAQ | 按错误现象排查支付、邮件、群消息与控制台 | 遇到问题时 |
| 控制台页面详解 | 后台每个页面、按钮与字段的用途 | 控制台管理员 |
| 更新记录 | 各版本新增、修复与升级注意事项 | 升级与维护人员 |
🌟 插件能做什么
| 能力 | 说明 |
|---|---|
| 群内商店 | 群友发送购买触发词即可看到商品、价格、库存、支付方式和下单格式 |
| 三类支付渠道 | 易支付、支付宝当面付、微信支付 API v2/v3 Native |
| 云端店铺 | 商品、卡密、订单与设置在插件与云端店铺间双向自动同步(0.0.8 起) |
| 安全出库 | 只有渠道验签成功且支付金额一致,才会分配卡密 |
| 邮箱优先发货 | 订单带邮箱时优先发邮件;群内订单无邮箱时直接通过群临时会话发货,买家无需加机器人好友 |
| 支付状态提示 | 支付成功后在原群提示,但绝不在群内公开卡密 |
| 二维码自动撤回 | 支付成功、订单取消或过期后,尽力撤回群内付款码消息 |
| 可视化控制台 | 商品、库存、订单、支付、邮件、指令、群组、云端同步和日志集中管理 |
🔄 一笔订单的完整流程
text
群友发送「购买」
↓
机器人展示当前群可购买商品
↓
群友发送「购买 1 支付宝 邮箱 user@example.com」
↓
插件创建待支付订单并生成二维码/支付链接
↓
支付渠道确认成功,插件验签并核对金额
↓
事务锁定一条未售出卡密,避免重复出库
↓
优先发到邮箱;群内订单无邮箱时直接群临时会话发货
↓
群内提示购买成功,撤回付款码,订单标记已发货🚀 五分钟快速上手
第 1 步:安装并打开控制台
- 将完整的
XiaoLin.ZLCardStorePlugin.uniqq插件包安装到 UniQQ; - 启动或重启 UniQQ,在插件管理中启用「ZL-售卡系统」;
- 点击插件设置,打开可视化控制台;
- 若提示找不到前端文件,确认使用的是完整插件包,并安装 Microsoft Edge WebView2 Runtime。
第 2 步:填写主人 QQ
进入「系统设置」,填写主人 QQ,确认全局开关已开启,点击右上角「保存配置」。主人可执行全局开关与高权限订单操作。
第 3 步:创建 0.01 元测试商品
进入「商品管理」新增商品:名称「测试商品」、分类「测试」、售价 0.01 元、库存预警 1,填写使用教程与售后说明后设为上架;再进入「卡密库存」导入两条测试卡密:
text
TEST-0001
TEST-0002第 4 步:只配置一个支付渠道
第一次不要同时启用三个渠道。选择已签约并有完整参数的渠道,按 支付渠道配置 填写并保存。
支付宝最容易填错的是公钥:控制台需要的是「支付宝公钥」,不是你自己生成的「应用公钥」。
第 5 步:配置邮箱
进入「邮箱设置」,选择邮箱预设,填写 SMTP 用户名和授权码,依次执行:
- 保存配置;
- 测试连接;
- 填写测试收件人;
- 发送测试邮件;
- 确认发件昵称、邮件标题与正文都正确。
第 6 步:配置目标群
进入「欢迎语与群组」,添加或选择目标群:
- 开启群售卡;
- 按需开启欢迎语;
- 开启支付成功群提示;
- 开启订单结束后撤回二维码;
- 测试阶段只允许显示测试商品。
第 7 步:完成真实验收
使用普通群成员账号发送:
text
购买
购买 1 支付宝 邮箱 你的邮箱@example.com付款后确认以下结果:
- 群里出现「支付成功 / 已发货」提示,原付款码消息被撤回;
- 邮箱收到卡密、使用教程和售后说明;
- 后台订单为「已发货」,库存减少 1 且卡密不会重复发放;
- 运行日志无持续
ERROR。
⚠️ 三条必须遵守的原则
- 不要跳过真实小额测试。 创建二维码成功不代表支付回调、查单、验签和发货全部正常。
- 不要手动确认来掩盖渠道配置错误。 先查商户后台和日志,确认订单号与金额一致。
- 不要泄露密钥。 应用私钥、商户 KEY、API v3 Key、证书私钥和邮箱授权码都不应截图发给别人。
📚 下一节:安装与首次配置
