PayPlex

⚠️ Design draft / 设计草案：PayPlex npm 包当前版本为 v0.0.4，仍处于 API 与文档设计阶段；根包入口是占位实现，尚不可作为可运行 SDK 集成到生产或开发项目中。

PayPlex 的目标是成为面向 Node.js 的统一支付中间层：默认内置 Stripe，并通过 defineProvider() 插件规范接入更多支付渠道，同时为 ID/幂等、订阅、分账、对账、风控、结算、公共签名与 monSQLize 持久化提供统一的类型契约。

当前状态

• 当前 index.js 仅为占位入口，暂未导出 PayPlex、defineProvider()、stripeProvider() 等 API。
• 站点文档中的代码示例用于说明目标接口形态与类型契约，不代表已发布可执行能力。
• npm 包版本为 v0.0.4；当前需求/技术方案草案已更新到 v0.0.8 口径，站点文档按 v0.0.8 的目标契约维护。
• payplex/stripe、payplex/signatures、payplex/capabilities、payplex/persistence、payplex/webhooks 等子路径导出尚未实现。
• CJS require() 支持是设计目标，需等条件导出与构建产物完成后才可使用。

关键设计口径

• PayPlex 默认生成 orderId；业务系统订单号使用可选 merchantOrderId 表达。
• 操作级幂等使用 idempotencyKey；下单、退款、Webhook 去重都需要明确幂等语义。
• 生产推荐默认 persistent 模式并传入 monSQLize db；只有显式 persistenceMode: 'stateless' 时才允许无数据库降级运行。
• Provider 插件能力来自 PayPlex 契约和契约测试；本地文件、workspace 包、私有仓库、npm 包都可以承载插件，npm 只是可选分发方式。

文档站点

站点文档位于 website/docs，使用 Rspress 构建。

本地预览

PayPlex 运行时目标为 Node.js >= 18；当前站点依赖的 Rspress/Rsbuild 版本要求 Node.js >= 20.19（或 >= 22.12）。

cd website
npm install
npm run dev

构建站点

cd website
npm run build

贡献说明

• 修改文档示例时，请同步核对 website/docs/api/types.md 中的目标类型契约。
• 修改需求或方案中的公开 API、ID 模型、插件形态、持久化模式、错误模型时，请同步检查 website/docs。
• 如果 API 尚未实现，请使用“设计草案”“目标接口”“计划支持”等措辞，避免写成已发布能力。
• 当实现代码落地后，应同步更新 package.json 的 exports、根入口、README、站点安装指南与所有示例。

License

Apache-2.0