商品类型与履约机制 (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等)。
  • 履约表现:
    1. 前端在结账 (Checkout) 时,会根据 form_schema 自动渲染出输入框要求买家填写。
    2. 付款后,订单状态进入 processing(处理中)。
    3. 管理员在后台订单列表看到用户填写的表单数据,进行人工发货/代充操作后,手动将订单状态改为 delivered 并可填写发货备注反馈给买家。

5. 动态 API 额度 (dynamic_api)

适用于:AI 接口聚合售卖、数据查询 API 接口调用次数售卖。

  • 工作机制: 专为极客开发者设计。后台配置商品时可设定每次购买赠送的 Quota(额度)。
  • 履约表现: 买家付款后,系统自动通过底层加密算法生成一条唯一的 sk_... 密钥,写入到 api_keys 资产表中,并分配购买的额度。用户可立即在订单中复制该 API Key,放入自己代码的 Authorization 头中调用您的系统 API。

💡 开发者提示

如果你正在基于 APayShop 进行二次开发,当你需要新增一种全新的售卖类型(比如线下电子门票核销 event),你只需要:

  1. 在 schema.ts 的 products.type 中增加枚举。
  2. 在 server/utils/fulfillment.ts 中增加对应的 switch case 发货逻辑即可,完全不需要修改核心支付链路。