商品类型与履约机制 (Product Types)
APayShop 是一套全场景的虚拟交易引擎。为了满足不同数字游民的售卖需求,系统在底层复用同一个 products 数据库表,通过核心字段 type 结合 metaData JSON 扩展,实现了 5 大差异化的商品类型与自动发货机制。
所有的履约(发货)逻辑均统一抽离在后端的 server/utils/fulfillment.ts 引擎中。
1. 卡密类 (key)
适用于:游戏点卡、软件激活码、账号密码。
- 工作机制: 商品需在后台关联“卡密池 (
cards表)”。用户付款成功后,履约引擎会自动从对应的卡密池中提取一条isUsed = false的卡密记录,将其标记为已用,并展示给买家。 - 缺货处理: 如果卡密池库存不足(Sold Out),用户依然可以下单(除非开启防超卖限制),但订单支付后状态会进入
processing(处理中),并提示管理员手动补货。
2. 数字文件 (file)
适用于:PDF电子书、网盘链接、视频教程压缩包。
- 工作机制: 管理员在创建商品时,在
metaData中配置好固定或动态的文件下载链接(Resource URL)或网盘提取码。 - 履约表现: 用户付款成功后,订单立即变更为
delivered状态,并在订单详情页的“履约结果”中直接展示这些隐藏的下载链接。
3. 周期性订阅 (subscription)
适用于:SaaS 包月会员、付费社群访问权。
- 工作机制: 这类商品代表一种持续性的服务状态。原有的
isPlan字段已废弃,现在完全由type='subscription'接管。 - 履约表现: 用户购买后,订单状态会直接变更为
active(活跃订阅中)。metaData中会记录该订阅的有效周期(如1_month,1_year,lifetime),便于第三方系统或管理员判断用户权益是否过期。
4. 人工服务/代充 (service)
适用于:游戏代肝、服务器代搭建、需要收集买家定制需求的非标服务。
- 工作机制: 该类型依赖强大的动态表单引擎。管理员在后台配置商品时,会在
metaData.form_schema中定义一段 JSON 数组(例如要求买家输入游戏区服、角色ID、服务器IP等)。 - 履约表现:
- 前端在结账 (Checkout) 时,会根据
form_schema自动渲染出输入框要求买家填写。 - 付款后,订单状态进入
processing(处理中)。 - 管理员在后台订单列表看到用户填写的表单数据,进行人工发货/代充操作后,手动将订单状态改为
delivered并可填写发货备注反馈给买家。
- 前端在结账 (Checkout) 时,会根据
5. 动态 API 额度 (dynamic_api)
适用于:AI 接口聚合售卖、数据查询 API 接口调用次数售卖。
- 工作机制: 专为极客开发者设计。后台配置商品时可设定每次购买赠送的
Quota(额度)。 - 履约表现: 买家付款后,系统自动通过底层加密算法生成一条唯一的
sk_...密钥,写入到api_keys资产表中,并分配购买的额度。用户可立即在订单中复制该 API Key,放入自己代码的 Authorization 头中调用您的系统 API。
💡 开发者提示
如果你正在基于 APayShop 进行二次开发,当你需要新增一种全新的售卖类型(比如线下电子门票核销
event),你只需要:
- 在
schema.ts的products.type中增加枚举。- 在
server/utils/fulfillment.ts中增加对应的switch case发货逻辑即可,完全不需要修改核心支付链路。