独角发卡独立应用
详情介绍
独角发卡（Dujiao）插件使用文档
作者：kuakeba.cn · 版本：1.0.0 · 适用：Zsens Admin 3.0（PHP 8.2+ / ThinkPHP 8）
一、插件简介
「独角发卡」是一款自包含的数字商品发卡商城插件，参考 Dujiao-Next 的商品销售与交付模式：支持数字卡密、账号、会员码、虚拟服务等虚拟商品的展示、下单、支付与自动/人工交付。
核心特性：
- 商品管理：分类、封面、副标题、售价/划线价、限购数量、上架状态、排序、销量统计
- 卡密管理：按商品导入卡密，一行一条，自动去重；未售卡密可按商品筛选、批量删除
- 双支付方式：站内金币支付（对接社区金币账户）与在线支付（对接支付中心插件，支持支付宝/微信等渠道）
- 自动交付：自动商品支付成功后按购买数量锁定并发放卡密，卡密售罄自动转为「待人工交付」
- 人工交付：商品可配置人工交付收集字段（如手机号、账号、区服），付款后台可查看买家填写信息并手动发货
- 订单体系：订单号查询、我的订单列表、待支付轮询、超时自动关单、后台补单/关单
- 站内通知：支付成功、卡密发放、人工待交付时通过消息插件通知买家（未装消息插件自动跳过）
- 独立域名：可绑定二级/独立域名，该域名根路径即商城首页；未绑定时走
/dujiao - 零侵入：不修改任何宿主文件；前台通过插件资源注入样式与导航入口，后台走独立菜单与页面
二、依赖说明
| 依赖 | 是否必需 | 说明 |
|---|---|---|
| 社区插件（community） | 必需 | 提供前台登录会话、会员身份与金币账户；前台页面需社区前台处于开启状态 |
| 支付中心插件（payment） | 可选 | 启用「在线支付」时需要；未安装或未启用时前台自动隐藏在线支付 |
| 消息插件（message） | 可选 | 用于发送支付/发货站内通知；未安装时静默跳过，不影响下单与交付 |
金币支付仅在社区插件已启用时可用；在线支付仅在支付中心插件已安装并启用时可用。
三、安装与卸载
- 进入后台「应用中心 → 插件」，找到「独角发卡」点击安装；
- 安装时自动创建
dujiaoproduct、dujiaocard、dujiao_order三张数据表（自动加站点表前缀），并注册后台菜单； - 安装完成后进入后台菜单 独角发卡 → 设置 检查开关与参数；
- 卸载插件会删除上述三张表与后台菜单，数据不可恢复，卸载前请先导出卡密与订单。
安装后前台入口：
- 商城首页：
/dujiao（若站点开启伪静态后缀，会自动带后缀） - 商品详情：
/dujiao/detail?id=商品ID - 订单详情：
/dujiao/order?order_no=订单号 - 我的订单：
/dujiao/orders - 超时关单：
/dujiao/cron?key=定时任务密钥 - 绑定独立域名后，上述路径去掉
/dujiao前缀（如/、/detail、/orders、/cron）
四、后台功能
后台菜单「独角发卡」下包含四个页签：
| 页面 | 功能 |
|---|---|
| 商品列表 | 新增/编辑/下架/删除商品，查看库存与销量 |
| 卡密列表 | 按商品筛选卡密、查看已售状态、批量导入、删除未售卡密 |
| 订单列表 | 按订单号/商品名/支付单号搜索，按状态与支付方式筛选，查看详情、人工发货、关单、标记已收款 |
| 设置 | 插件开关、导航入口、金币/在线支付开关、汇率、超时关单、密钥与购买须知 |
4.1 商品配置要点
- 交付类型：
自动发货需要提前导入卡密；人工交付无需卡密，付款后由后台填写交付内容。 - 单次最少/最多购买：最少默认 1，最多为 0 表示不限（同时存在 100 件的单笔上限保护）。
- 人工交付收集字段：每行一个字段，格式
字段名|提示文字，例如：
游戏账号|请输入需要充值的账号
手机号码|用于接收发货短信最多解析 6 个字段，买家下单时必填，后台订单详情可查看。
4.2 卡密导入
进入 卡密列表 → 批量导入，选择商品后粘贴卡密：一行一条，单次最多 1000 条，重复内容自动跳过。导入后库存即时更新。
卡密内容支持任意文本（账号密码、激活码、兑换链接等），多件购买时按「卡密 1：…」「卡密 2：…」逐条展示。
4.3 订单处理
- 待支付订单可「关闭」，关闭前会自动向支付中心确认是否已支付，已支付则转为交付流程；
- 已支付订单若为人工交付，填写内容后「发货」即完成订单并通知买家；
- 买家线下付款等特殊情况，可使用「标记已收款」进行补单，补单后同样进入交付流程。
五、插件设置项
| 配置项 | 说明 |
|---|---|
| 启用独角发卡 | 总开关。关闭后前台商城不可访问，已生成订单不受影响 |
| 显示前台导航入口 | 在站点顶部导航栏注入「独角发卡」入口 |
| 导航名称 | 导航与首页标题显示的名称，默认「独角发卡」 |
| 导航图标 | Remix Icon 类名，默认 ri-shopping-bag-3-line |
| 独立域名 | 可留空。填写如 mall.example.com，DNS 解析到本站后该域名根路径即商城首页；不能填写主站域名 |
| 允许金币支付 | 按金币汇率把商品人民币价格折算为金币扣款 |
| 允许在线支付 | 依赖支付中心插件；未就绪时前台自动隐藏 |
| 金币汇率 | 1 元 = N 金币；留空则沿用支付中心配置的汇率，仍未配置时默认 10 |
| 待支付超时（分钟） | 超过该时长未支付的订单由定时任务自动关闭，0 表示不自动关闭 |
| 定时任务密钥 | 访问 /dujiao/cron?key=密钥 执行超时关单；留空则禁用 Web 入口 |
| 全局购买须知 | 显示在商城首页与商品详情页，提示虚拟商品售后规则 |
独立域名绑定
- 将目标域名（如
mall.example.com）的 DNS A/CNAME 解析到本站服务器，并在站点/面板中完成域名绑定； - 后台「独角发卡 → 设置 → 独立域名」填写该域名并保存；
- 该域名下根路径即为商城首页，其余路径为
/detail、/order、/orders、/buy、/cron、/api/*； - 主站
/dujiao入口保持可用，两种访问方式共用同一套商品与订单数据； - 绑定域名时，前台链接、分页、登录回跳会自动使用根路径写法；后台「前台商城」按钮会优先打开绑定域名。
说明：插件按 imgbox 的绑定机制实现——后台保存域名后，路由层为该域名单独注册根路径规则，请求主机命中该域名时自动切换根路径路由与 URL 生成。
注意事项：
- 不能填写主站主域名，保存时会校验并拒绝；
- 自动忽略
www.前缀差异，mall.example.com与www.mall.example.com视为同一主机； - 独立域名下的登录依赖社区插件，会话与登录在哪个域名访问就在哪个域名生效，建议主站与绑定域名均保持社区前台开启；
- 使用在线支付时，请在支付中心把绑定域名加入回调/同步跳转地址白名单；
- 若站点开启了路由缓存/CDN，保存域名后请清理一次缓存再访问。
- 绑定域名的关单地址为
https://绑定域名/cron?key=你的密钥，可在设置页直接看到完整提示。
六、定时任务（超时关单）
- 在插件设置中填写「定时任务密钥」并保存；
- 在服务器计划任务中定时请求（建议每 5 分钟）：
curl -s "https://你的域名/dujiao/cron?key=你的密钥"返回 JSON：{"code":1,"msg":"已关闭 N 个超时订单"}。单次最多处理 200 笔，量大的站点可缩短执行间隔。
密钥为空时该入口不可用，避免被外部随意触发；请勿使用过于简单的密钥。
七、支付流程说明
金币支付：下单时校验余额并在事务内扣减金币、生成订单、立即交付；金币流水类型记录为「发卡购买」。汇率优先取本插件设置，其次取支付中心汇率，最后使用默认 10。
在线支付：下单后调用支付中心创建支付单（业务类型 dujiao_order，业务 ID 为发卡订单 ID），前台展示渠道列表；支付完成后：
- 前台订单页/我的订单页会轮询
/dujiao/order/status，插件主动向支付中心同步查单； - 支付中心确认已支付后，本插件执行交付（发放卡密或转人工），全程幂等，重复回调不会重复发货；
- 支付中心开启 沙箱模式 时，订单页会显示「模拟支付」按钮，便于本地联调（非沙箱不显示、接口也会拒绝）。
交付逻辑完全由本插件处理，支付中心仅负责收款与查单，双方通过 biztype/bizid 关联。
八、数据结构
| 表名（含站点前缀） | 用途 |
|---|---|
dujiao_product | 商品：分类/标题/封面/价格/交付类型/收集字段/上下架/销量 |
dujiao_card | 卡密：所属商品、卡密内容、售卖状态、成交订单 |
dujiao_order | 订单：订单号、买家、商品快照、金额、支付方式、支付单号、交付内容与状态、买家填写信息 |
九、常见问题
Q：前台访问 /dujiao 提示 404 或 503？
A：请确认插件已启用，且社区插件的前台已开启（本插件复用社区前台登录体系）；刚安装时可清理框架缓存后重试。
Q：商品详情页看不到金币/在线支付选项？
A：金币支付需社区插件启用并登录；在线支付需支付中心插件已安装、启用且配置了可用渠道。
Q：自动商品付款后提示「待人工交付」？
A：说明该商品可用卡密不足。请到卡密列表补充库存，再在订单列表人工发货或让买家联系客服处理。
Q：支付成功但订单仍是待支付？
A：前台订单页会自动轮询同步；若渠道异步通知未到达，请检查支付中心回调配置。也可在后台确认收款后使用「标记已收款」补单。
Q：绑定独立域名后访问根路径仍是社区首页或 404？
A：请确认域名已解析并绑定到本站、插件设置里已填写独立域名且不是主站域名；若使用了 CDN/缓存，清理后再试。
Q：可以自定义前台样式吗？
A：可以修改 plugins/Dujiao/static/dujiao.css；插件会按需同步到 public/static/Dujiao/，升级前请备份自定义样式。
十、更新日志
1.0.0（2026-11-05）
- 首个版本：商品/卡密/订单管理，金币与在线支付，自动卡密与人工交付，超时关单，站内通知，独立域名绑定。
由 kuakeba.cn 为 Zsens Admin 开发
更新记录 （1）
-
v1.0.0
2026-11-05
正式发布
微信客服
QQ官方交流群