中国 帮助

支付管理

官方 付费 插件

Wujies 无界平台(wujies.cn)的支付应用,一个插件一个仓库:

v1.0.4 1 次安装 本季度 1 次

<p> <a href="https://wujies.cn" target="_blank" rel="nofollow"> <img width="100" src="https://wujies.cn/brand/logo-stacked.svg" alt="Wujies 无界 logo"> </a> </p>

<p><b>支付管理</b>,支付应用、支付渠道(支付宝 / 微信 / 余额)、支付订单与退款单。</p> <p> <a rel="nofollow"><img alt="应用版本" src="https://img.shields.io/badge/app-1.0.4-111111?style=flat-square"></a> <a rel="nofollow"><img alt="应用编码" src="https://img.shields.io/badge/code-pay-0057FE?style=flat-square"></a> <a rel="nofollow"><img alt="License" src="https://img.shields.io/badge/license-commercial-orange?style=flat-square"></a> <br> <a rel="nofollow">功能特性</a> <a rel="nofollow">预览</a> <a rel="nofollow">安装</a> <a rel="nofollow">设置</a> <a rel="nofollow">常见问题</a> <a href="https://docs.wujies.cn/docs/wujies/5.x/platform/plugin" rel="nofollow">插件开发</a> <a href="https://gitee.com/wujies" rel="nofollow">Gitee</a> </p>


Wujies 无界平台(wujies.cn)的支付应用,一个插件一个仓库:

  • 后台:应用市场装上后多一个「支付管理」菜单,四个页面(支付应用、支付渠道、支付订单、退款订单), 前端是远程应用(frontend/,16 个文件)。
  • 渠道与策略:PayChannelEnum 十一种 code(wx_pub / wx_lite / wx_app / wx_native / wx_h5、 alipay_pc / alipay_wap / alipay_app / alipay_qr、mock、wallet),由 PayStrategyFactory 分派到 AlipayStrategy / WechatPayStrategy / WalletPayStrategy 三个实现。
  • 回调:PayNotifyController 的两颗匿名接口 —— POST /pay/notify/{channelCode}/{channelId} 与 POST /pay/notify/refund/{channelCode}/{channelId},都带 @SaIgnore(第三方回调没有登录态)。
  • 与会员的耦合:钱包支付要在同一进程内扣会员余额,WalletPayStrategy 注入 cn.wujies.common.plugin.sdk.MemberServiceLocator 拿到 IMemberService 的动态代理(实现体在会员插件里), pom 因此把 wujies-member-plugin 声明为 provided。会员应用没装时钱包渠道给出「请到应用市场安装」的 提示,而不是宿主启动即失败。
  • 前台:没有直出的公开页,本仓库不放 site-templates/。

应用编码 pay | 应用版本 1.0.4 | 后端构件 wujies-pay-plugin

✨ 功能特性

  • 💳 支付应用 — 应用编码、终端类型(pc / h5 / mini / app)、业务类型、可用渠道与默认渠道、支付/退款回调地址。
  • 🏦 支付渠道 — 十一种渠道 code 统一登记,渠道 config 必须是合法 JSON(保存时校验);系统内置余额渠道不允许删除。
  • 🧾 支付订单 — 下单、查询、关闭、删除(已支付订单不允许删除),商户订单号与支付单号各自唯一。
  • ↩️ 退款单 — 退款申请与状态(等待 / 成功 / 失败),带渠道退款单号与失败原因。
  • 🔔 结果回调 — 两颗匿名回调接口,支付宝走 AlipaySignature.rsaCheckV1 验签,微信走 SDK 解密验签。
  • 🔁 回调重试 — 支付成功后由 PayOrderListener 异步建 pay_notify_task,PayNotifyJob 每 30 秒扫一遍待跑任务。
  • 👛 余额支付 — 同进程扣会员余额、写余额流水(消费 2 / 退款 3),退款把余额加回去。
  • ⏱️ 定时任务 — 过期订单关单(每分钟,单次最多 100 条)、未支付订单主动查单同步(每 2 分钟,只查创建满 2 分钟且未过期的)。
  • 🧩 策略工厂 — 按 code 前缀回退(wx_* → 微信策略、alipay_* → 支付宝策略),新增渠道只注册不改调用方。
  • 🔐 多租户 — 五张表都带 tenant_id,与平台其它应用同一套租户口径。

📸 预览

支付管理主界面

![支付管理主界面](docs/screenshots/pay.png)

🚀 安装

环境要求

| 项 | 要求 | |---|---| | 平台版本 | &gt;=5.6.2 &lt;6.0.0(app.json 的 engine) | | 后端构建 | JDK 17+(父 POM 的 java.version 为 17) | | 前端构建 | Node.js 18+(建议 20 LTS 及以上),npm | | 依赖应用 | 钱包渠道要先装 member(app.json 的 dependencies);只跑支付宝 / 微信可以不装 | | 安装方式 | 管理端「应用市场 → 本地安装」上传 zip,或由上架中心(wujies-market)发布后拉取 |

从应用市场安装

  1. 打开管理端「应用市场 → 本地安装」,上传打包好的 zip;或经上架中心发布后由平台拉取。
  2. 安装时自动执行 migrations/ 下的脚本(建表 + 示例种子)。
  3. 装完刷新菜单,出现「支付管理」即成功。
  4. 钱包渠道要用就把会员应用一起装上(见「这个应用是什么」的耦合那一条与「常见问题」)。

包里两个产物的路径由 app.json 的 assets 决定: frontend → frontend/index.js | backend → backend/wujies-pay-plugin-1.0.4.jar。

从源码构建

在本仓库根打包(三条命令各管一段,都在本仓库根执行):

powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -CheckOnly   # ① 打包前检查:清单/产物/迁移/菜单/密钥,几秒返回
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -Dev         # ② 开发包:不签名,落 ..\.plugin-dist\pay\dev
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1              # ③ 正式包:构建 + 用 keys\private.pem 签名

关于上面三条命令的取值口径:

  • 判据是「脚本所在仓库根有没有 app.json」,所以在本仓库里不要传 -Plugin(它按子目录找清单, 会报「找不到插件目录」);-FrontendProject / -FrontendDist 也不用传 —— 独立布局的前端工程固定就是 本仓库 frontend/、产物 frontend/dist,脚本自己跑 npm run build(首次先 cd frontend &amp;&amp; npm install, 缺依赖时脚本会把这条命令直接报给你)。只想复用现成产物就加 -SkipBuild。
  • -SkipFrontend 只用于没有前端的纯后端应用:带前端时它会连「复制前端产物」一起跳过, 出的包只有 app.json,装上去没有界面。
  • -CheckOnly 打出的 CHECK|级别|项|说明 行就是管理端「开发工具 → 插件开发 → 打包」抽屉里那份体检清单, 两边跑的是同一套检查;有 ERROR 时正式打包会被直接拦下。签名密钥在本仓库 keys/ (private.pem + public.pem,已在 .gitignore 里),生成或更换用 -Keygen (覆盖已有密钥要显式加 -KeygenForce,旧钥先整份备份进 keys\backup\&lt;时间戳&gt;\)。 参数全表与产物结构见文档站「打包应用」与「密钥与签名」两页。

手工构建(本插件的 pom 依赖会员插件的构件,两个仓库要按顺序各构建一次;下面假设两仓库同级):

cd ../wujies-member-plugin &amp;&amp; mvn -B -o install -DskipTests   # 先装出 provided 依赖的构件
cd ../wujies-pay-plugin &amp;&amp; mvn -B -o package -DskipTests       # 再构建本仓库
cd frontend &amp;&amp; npm install &amp;&amp; npm run build                     # 前端,产物 dist/index.js + assets/pay-app.css

最快的开发路子不用打包、不用重启宿主:启动平台宿主,打开管理端「开发工具 → 插件开发」, 找到 pay 这一行点「启动后端」(自动编译并加载 target/classes,同时开启监听)与「启动前端」 (常驻 vite build --watch,保存源码即重建,刷新页面生效,没有 HMR)。全流程见 文档站「插件开发」。

升级与卸载

  • 升级:换 app.json 的 version 后重新打包上传;已执行的迁移脚本不可改内容, 要改表结构一律加新编号脚本。
  • 卸载:管理端「应用市场」里卸载,平台按 migrations/ 里 CREATE TABLE 的清单清理数据表 —— 本仓是五张:pay_app / pay_channel / pay_order / pay_refund / pay_notify_task。 历史上的 pay_notify_log 刻意没写进脚本:全仓库没有任何代码引用它,写进去就等于宣称这张表归支付应用所有。

⚙️ 设置

运行期配置分三层,改错层就不生效:

| 配置 | 放哪 | 生效 | |---|---|---| | 支付应用(业务回调地址、可用渠道) | 后台「支付管理 → 支付应用」 | 保存即生效;回调地址必须是绝对 http(s),否则保存报「格式不正确」 | | 渠道开关与渠道参数 | 后台「支付管理 → 支付渠道」,config 是一段 JSON | 支付宝的 serverUrl / appId / privateKey / publicKey / signType 从这里读 | | 微信支付凭据 | 宿主配置 pay.wechat.*(yml 或环境变量) | 见「支付凭据放在哪」,改数据库那一行不会生效 |

菜单入口

| 菜单 | 路径 | 组件键 | 权限前缀 | |---|---|---|---| | 支付应用 | pay/app | remote:pay/pay/app | pay:app:* | | 支付渠道 | pay/channel | remote:pay/pay/channel | pay:channel:* | | 支付订单 | pay/payOrder | remote:pay/pay/order | pay:order:* | | 退款订单 | pay/refund | remote:pay/pay/refund | pay:refund:* |

按钮权限(menu_type='F')随清单一起声明:应用 / 渠道 / 退款各 query add edit remove, 订单另有 pay:order:submit。前缀与 app.json 里的 perms 逐字对应,改名会让已授权角色失效。

公开回调(没有登录态,也不该有):

| 路径 | 用途 | |---|---| | POST /pay/notify/{channelCode}/{channelId} | 支付结果回调 | | POST /pay/notify/refund/{channelCode}/{channelId} | 退款结果回调 |

🧩 依赖与插件支持

| 项 | 说明 | |---|---| | 依赖插件 | member(app.json 的 dependencies,未标 optional):只有钱包渠道需要 | | 第三方 SDK | alipay-sdk-java / wechatpay-java / weixin-java-mp 在本 pom 里是 provided,由宿主 wujies-admin 显式引入(合计约 36MB,其中支付宝是 ALL 包) | | 平台存储 | 不使用;本插件不落文件、不存密钥文件 | | 公共 API | 前端走打进包内的 @wujies/api-client,运行时由宿主 import map 提供 vue / element-plus / @wujies/ui-shared 单例 |

支付渠道与策略

| code | 渠道 | 实现 | |---|---|---| | wx_pub / wx_lite / wx_app / wx_native / wx_h5 | 微信 JSAPI / 小程序 / App / Native / H5 | WechatPayStrategy | | alipay_pc / alipay_wap / alipay_app / alipay_qr | 支付宝 PC / Wap / App / 扫码 | AlipayStrategy | | mock | 模拟支付 | 调试用 | | wallet | 系统内置余额支付 | WalletPayStrategy |

PayStrategyFactory 先按完整 code 找实现,找不到再按前缀回退(wx_ / alipay_), 所以新增一个 wx_xxx 变体不需要改工厂。每个实现都有同一组动作: unifiedOrder / refund / queryOrder / closeOrder / queryRefund / processNotify。

支付凭据放在哪

  • 运行期签名用的不是数据库里那行。 WechatPayStrategy 的 appId / merchantId / merchantSerialNumber / privateKey / apiV3Key 全部由 @Value("${pay.wechat.*}") 从宿主配置注入(WechatPayStrategy.java:59-72), 而 getConfig(channel.getConfig())(同文件 :322-335)把渠道 JSON 里的同名字段读出来后根本没用, 真正被读的只有退款/查询路径里的 mchId(:219、:242)。所以凭据要放宿主 yml 或环境变量,别指望改库生效。
  • 证书不需要填路径:微信侧用 RSAAutoCertificateConfig(凭 apiV3Key 自动下载平台证书), 仓库与数据库里都不该出现证书文件;只认 pay.wechat.privateKey 那串私钥。
  • 支付宝相反:AlipayStrategy.getClient()(:260-272)从渠道 config JSON 读 serverUrl / appId / privateKey / publicKey / signType,回调验签也只用 publicKey + signType。
  • migrations/02-create-pay-seed-data.sql 里不许出现真凭据。 2026-11-02 之前那行 wx_lite 的 config 带的是真实商户私钥与 APIv3 密钥,而本仓库是公开的 —— 现已改成 &lt;你的…&gt; 占位与空串。 ⚠️ 私钥已经公开过,改文件不等于止损:先去微信支付商户平台轮换,再按 wujies-platform/script/sql/update/pay_seed_secret_repair.sql 清迁移账本里 02 那一行 (内容变了摘要就对不上,AppMigrationService.java:113-116 会直接拒绝执行、升级失败), 最后在后台「支付通道」页面填新值。存量库那行不会被种子的 INSERT IGNORE 覆盖。

回调地址与重试

  • 回调地址只写占位或相对路径:种子里的 pay_app 用的是 http://localhost:8080/app/pay/notify 这类本地示例,交付时在「支付应用」页换成 ${你的域名}/...;第三方平台那侧配的就是这个地址。
  • 回调进来先按 channelId 回库取渠道、校验 channelCode 与行上一致,再交给策略验签;验签失败只回 failure,不抛异常(抛出去会被当作 5xx 让第三方一直重推)。
  • 支付成功不在这里做业务:PayOrderListener 监听 common-core 的 PaySuccessEvent(扁平 POJO,只带单号), 按单号回查完整实体后建 pay_notify_task,由 PayNotifyJob 每 30 秒重试 —— 业务方超时也能补上。
  • 事件类必须在父加载器(wujies-common-core):跨插件事件按「事件对象的 Class」匹配, 跟发布方插件走就会出现「订阅方永远收不到且不报错」。

开发环境

git clone git@gitee.com:wujies/wujies-pay-plugin.git
cd wujies-pay-plugin

打包脚本:本仓库自带完整的 package.ps1(母本在 wujies-plugins 仓库根,各仓用 node scripts/sync-package-script.mjs 同步过来),clone 下来就能在本仓库根直接体检、构建、签名、出包、 生成密钥,不需要回到单体仓库,也不需要手工传产物路径。

前端 SDK:已迁到已发布的 @wujies/* SDK(ui-shared / components / api-client / ui-plugin-bundler-kit)。frontend/vite.config.ts 只声明 defineRemoteApp({ appCode, root }), 共享依赖一律 external、运行期由宿主 import map 兜到同一份实例;宿主独有工具与业务模块 (@/utils/wujies、@/api/system/*、UserSelect/MemberSelect 等)按原样复制进了 frontend/src/, proxy?.$modal / useDict / download 与 ImageUpload/UserDetail/Module*Settings 由宿主运行时提供。 本仓库前端可独立构建;要直接落位到宿主,构建前设 WUJIES_FRONTEND_DIST=/app-market-dist/remote-apps。

仓库布局

| 位置 | 内容 | |---|---| | pom.xml | Maven 模块(父 pom = cn.wujies.plugins:wujies-plugins-parent,` 已置空;wujies-member-plugin 与三个第三方 SDK 都是 provided`) | | app.json | 应用清单,打包器读的唯一事实来源(code / version / menus / assets) | | src/ | Java 源码(49 个文件):controller / core(策略与工厂)/ domain / enums / job / listener / mapper / service / util | | src/main/resources/mapper/pay/ | 四个 Mapper XML(应用 / 渠道 / 订单 / 退款) | | migrations/ | 2 个脚本:01 建五张表、02 示例种子(全 INSERT IGNORE,⚠️ 代价是它也吞 NOT NULL / 外键那类插入错误) | | frontend/ | 远程应用源码(src/ 16 个文件),入口 frontend/src/index.ts | | docs/screenshots/pay.png | 预览图 |

❓ 常见问题

Q:陌生人 clone 后 mvn package 报找不到 wujies-plugins-parent 或 wujies-member-plugin? 父 pom、wujies-common-* 与兄弟插件构件目前只有本地 mvn install 出来的版本,还没发布到 Maven 仓库。全新机器要先在 wujies-member-plugin 跑一次 mvn -B -o -DskipTests install,再构建本仓库。 本机实测 mvn -B -o package -DskipTests 通过。

Q:为什么三个支付 SDK 不打进插件包? 做成「插件自带」要 shade,而 wechatpay-java 传递依赖 BouncyCastle(签名 jar),shade 进去会报 signer information does not match(得额外排除 META-INF/*.SF|*.RSA|*.DSA,还要处理 META-INF/services 合并),插件包也会从 88KB 涨到几十 MB。代价是「没装支付应用的部署也带着这几个 SDK」。

Q:钱包支付报「请到应用市场安装」? 会员应用没装或没启用。装上 member 后无需重启宿主,钱包渠道下次调用就能拿到代理实现 (MemberServiceLocator.proxy(...) 每次调用都反查)。

Q:改了「支付渠道」页面里的微信参数,为什么没生效? 因为微信签名用的不是库里那行(见「支付凭据放在哪」)。appId / merchantId / merchantSerialNumber / privateKey / apiV3Key 都从宿主 pay.wechat.* 读,改库不生效。

Q:回调一直被第三方重推? 先看 pay_notify_task 有没有堆起来(业务回调由 PayNotifyJob 每 30 秒重试),再看渠道 config 里的支付宝 publicKey / signType 是否正确 —— 验签失败只回 failure,不会进业务。

Q:打包时提示「找不到插件目录」? 在本仓库根不要传 -Plugin —— 脚本按「仓库根有没有 app.json」判定布局,传了它就去找子目录清单。

Q:升级时提示迁移脚本「已被修改」? 已执行过的脚本不能改内容(checksum 对不上直接拒绝执行)。01 曾经连种子数据一起写, 拆出 02 的存量部署要先跑 wujies-platform/script/sql/update/app_market_app_seed_split_repair.sql 清账本,再升级。

🔒 隐私与外部资源

  • 不收集、不上报任何遥测;支付单、退款单、回调任务都只存本平台数据库。
  • 本仓库不含任何真实商户号、私钥、APIv3 密钥或 appId:migrations/02 里只有 &lt;你的…&gt; 占位与空串, 运行期凭据来自宿主配置或部署侧环境变量。
  • 签名密钥只在本机 keys/(已 gitignore);公钥由部署侧注入,不在仓里给默认值。
  • 外呼只有支付网关本身(微信 / 支付宝)与业务方的回调地址,没有其它第三方上报。

📄 许可证与致谢

商业授权:需要一枚覆盖本应用的有效授权凭证才允许安装与加载(条文见仓库根目录 LICENSE, Copyright (c) 2026 Wujies 无界平台 — 保留所有权利)。清单 app.json 里 license 为 UNLICENSED、 licenseRequired 为 true;三档口径见官网文档「授权与版本」。

💬 反馈与建议

参考

wujies-hello-plugin(已按新布局跑通前端独立构建的样板)、 wujies-ui(npm 上 @wujies/* 四件套的源码仓)、 wujies-member-plugin(钱包渠道依赖的会员构件)、 文档站「插件开发」章节。

v1.0.4 2026-11-08 平台 >=5.6.2 <6.0.0 172 KB

修复

  • 同步公钥检查——开源仓 yml 只有环境变量占位符时改比部署仓 keys/package-public.pem

其他

  • pay 1.0.4 —— 版本号与包内 jar 名同步
v1.0.2 2026-10-01 平台 >=5.6.2 <6.0.0 172 KB

这个版本没有写更新日志。

v1.0.0 2026-10-01 平台 >=5.6.2 <6.0.0 172 KB

这个版本没有写更新日志。

评论区需要浏览器启用 JavaScript 才能加载。