59 lines
3.1 KiB
Markdown
59 lines
3.1 KiB
Markdown
# 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），不要恢复自动轮询
|