unipay/README.md

3.1 KiB
Raw Blame History

unipay — 统一支付模块

多渠道统一支付:微信支付(Native/H5)、支付宝、PayPal、Stripe、银行转账码。 凭据全部走环境变量(不落库、不进 git),渠道初始化失败自动降级为 disabled,不影响宿主启动。

数据表(models/*.json)

表 说明 关键字段
paychannel 支付渠道 id, name, enabled_date, expired_date
payfee 支付费率(挂渠道) id, channelid, fee_rate, enabled_date, expired_date
payment_log 支付流水 id, customerid, channelid, channel_trade_id, payment_name, amount_total, pay_feerate, pay_fee, currency, payment_status, init_timestamp, payed_timestamp, cancel_timestamp, userid, payer_client_ip
transfercode 银行转账码(线下打款对账) id, customerid, amount, tcode, curtime, curdate, status

CRUD 定义在 json/(paychannel/payfee/payment_log/transfercode),由宿主 build.sh 的 xls2ui 生成页面。

环境变量凭据(CONF_ENV 映射,unipay/init.py)

渠道 环境变量
wechat WXP_MCHID、WXP_SERIAL(证书序列号)、WXP_PRIVKEY(私钥 pem 文件路径)、WXP_API_V3_KEY
alipay ALIPAY_APPID、ALIPAY_PRIV(应用私钥文件路径)、ALIPAY_PUB(支付宝公钥文件路径)
paypal PP_ID、PP_SECRET(sandbox=True 为静态默认)
stripe STRIPE_KEY
transfer 无凭据(转账码为平台自管)

缺失凭据的渠道在 load_unipay() 里初始化为 None(disabled),运行期调用会得到明确的渠道不可用错误。

注册到 ServerEnv 的函数(宿主/dspy 调用面)

load_unipay()(unipay/init.py:244)向 ServerEnv 注册:

  • get_paychannels() / get_pay_feerate(sor, channelid) / get_pay_fee(providerid, amount) / sor_get_pay_fee(...) — 渠道与费率查询(payfee.py)
  • create_payment / query_payment / refund_payment — 支付生命周期(core.py)
  • PaymentLog — 流水记录类(paylog.py)
  • PROVIDERS — 渠道实例字典 {transfer, wechat, paypal, alipay, stripe}

另有 add_startup(setup_callback_path) 注册回调路径(notify.py:get_provider_channel(name)、get_provider(name, conf))。

前端入口(wwwroot/)

  • recharge.ui/.dspy、user_recharge.dspy — 用户充值
  • manual_recharge.ui/.dspy、transfer_check.dspy、transfer_info.ui — 转账码人工核对(手动按钮触发,不自动轮询)
  • refund.ui/.dspy — 退款
  • usermenu.ui — 用户菜单挂载

providers/ 下按渠道一个文件:wechat.py、alipay.py、paypal.py、stripe.py、transfer.py。

宿主集成

  • build.sh 第 5/6 步:clone + pip install pkgs/unipay/(普通 install 非 editable,改代码后必须重装)
  • 宿主 init() 里调用 load_unipay();wwwroot symlink 由 build.sh 第 8 步统一挂

部署注意

  • 凭据文件(私钥 pem)路径由环境变量给出,文件本身不入仓库
  • payment_log 金额字段落库前经 payfee 计算(费率×金额),改费率逻辑需回归 get_pay_fee
  • 转账码核对是人工动作(manual_recharge),不要恢复自动轮询