kernel-quick-start.md

最小内核验证

:::warning 不是支付 Quick Start 本页只验证当前状态页所列的本地 Provider 契约内核。示例不会连接 Vext、支付渠道或数据库，也不能证明真实资金链路可用。 :::

前提条件

• Node.js >=18
• 在本仓库根目录执行

先运行项目自带证据：

npm test
npm run smoke

最小 Provider

创建一个临时 ESM 文件，使用当前根入口：

import { PayPlex, defineProvider } from './index.js'

const createLocalProvider = defineProvider({
  meta: {
    name: 'local-test',
    regions: ['TEST'],
    currencies: ['USD'],
    settlementModes: ['manual'],
    capabilities: {
      payment: true,
      refund: true,
      webhook: true,
      signatures: [],
    },
  },
  create() {
    return {
      async createOrder(params) {
        return {
          orderId: params.orderId ?? 'order_001',
          providerOrderId: 'provider_order_001',
          status: 'pending',
          provider: 'local-test',
          raw: {},
        }
      },
      async queryOrder(orderId) {
        return {
          orderId,
          providerOrderId: 'provider_order_001',
          status: 'paid',
          amount: 100,
          currency: 'usd',
          provider: 'local-test',
          raw: {},
        }
      },
      async refund(params) {
        return {
          refundId: params.refundId,
          providerRefundId: 'provider_refund_001',
          status: 'success',
          amount: params.amount,
          provider: 'local-test',
          raw: {},
        }
      },
      async verifyWebhook(payload) {
        return {
          type: 'payment.success',
          providerEventType: 'local.success',
          orderId: payload.orderId,
          providerOrderId: 'provider_order_001',
          provider: 'local-test',
          raw: payload,
        }
      },
    }
  },
})

const pay = new PayPlex({ defaultProvider: 'local-test' })
pay.useProvider(createLocalProvider())

const event = await pay.handleWebhook({
  providerName: 'local-test',
  payload: { orderId: 'order_001' },
  signature: 'fixture-only',
})

console.log(event.type)

预期输出为 payment.success。

这个示例没有证明什么

• signature: 'fixture-only' 没有执行加密验签。
• handleWebhook() 没有持久化、去重、金额复核、快速 2xx 或异步任务。
• Provider 返回值来自本地 fixture，不是渠道网络响应。
• 示例没有平台认证、租户隔离、幂等、账务、对账或风控。

真实平台能力必须在对应运行时、集成测试和沙箱证据存在后另行提供 Quick Start。