Files
multiPay/README.md
T

141 lines
6.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MultiPay 本地聚合支付平台
一个使用 **Bun + SQLite** 的本地一体化支付服务,提供电脑端扫码收银台、支付宝当面付、微信 Native 支付、业务回调、充值记录和对账明细。
## 已实现
- 公开收银台:必须传入有效用户 ID,支持充值套餐、积分展示和近六个月充值记录。
- 支付通道:本地模拟支付、支付宝电脑网站支付官方收银台二维码、可选当面付、微信支付 APIv3 Native 下单。
- 安全校验:支付宝/微信请求签名、平台回调验签、金额复核、幂等处理。
- 业务通知:HMAC-SHA256 签名、失败自动重试、手动重试、完整通知日志。
- 管理后台:数据概览、用户管理、充值套餐、充值记录、按渠道/状态/分类/时间查询、对账明细、网关配置。
- 本地存储:SQLite WAL 模式;支付密钥使用 AES-256-GCM 加密后入库。
- 管理员安全:Argon2id 密码哈希、HttpOnly 会话、同源请求校验、审计日志。
## 启动
本机已安装 Bun 时:
```powershell
bun install
Copy-Item .env.example .env
bun run start
```
当前机器可直接使用:
```powershell
& 'C:\Users\11937\.bun\bin\bun.exe' install
& 'C:\Users\11937\.bun\bin\bun.exe' run start
```
- 收银台:<http://localhost:3000/pay>
- 管理后台:<http://localhost:3000/admin>
- 初始账户:`admin`
- 初始密码:`admin123456`
首次登录后请立即在“系统设置”中修改密码。正式部署前,请在环境变量中设置固定的 `PAY_MASTER_KEY` 和外部可访问的 `APP_BASE_URL`,并使用 HTTPS 反向代理。
## 业务系统发起支付
把用户重定向到:
```text
http://localhost:3000/pay?user_id=USER10001&merchant_order_no=ORDER202610310001&subject=账户充值&notify_url=https%3A%2F%2Fmerchant.example.com%2Fpayment%2Fnotify&return_url=https%3A%2F%2Fmerchant.example.com%2Fresult
```
参数:
| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `user_id` | 是 | 后台已创建且启用的用户 ID;不存在时收银台拒绝进入 |
| `amount` | 否 | 用于预选同金额的后台套餐;没有匹配项时默认选择第一个可用套餐 |
| `merchant_order_no` | 是 | 6-32 位字母、数字、`_`、`-`,需唯一 |
| `subject` | 否 | 订单标题 |
| `category` | 否 | `recharge`、`purchase`、`service`、`other` |
| `notify_url` | 否 | 业务系统异步通知地址 |
| `return_url` | 否 | 支付完成后的返回地址 |
| `timestamp` / `sign` | 开启订单签名后必填 | 防止金额和回调地址被篡改 |
### 外部订单签名
在后台开启“强制校验外部订单签名”后:
```text
content = amount={服务端格式化为两位小数的套餐金额}&merchant_order_no={订单号}&notify_url={回调地址}&package_id={套餐ID}&timestamp={Unix秒}&user_id={用户ID}
sign = HMAC-SHA256(merchant_secret, content).hex()
```
时间戳有效期为 5 分钟。签名必须由业务服务端生成,不能把密钥放在网页代码里。
## 支付成功业务回调
支付页只轮询本平台订单状态,不直接修改业务数据。支付宝、微信等渠道经服务端查单或验签通知确认实付成功后,服务端先按订单绑定的用户 ID 原子增加 PostgreSQL `users.quota`;只有积分入账成功,订单才会变为 `paid` 并返回充值成功。业务入账使用独立的唯一订单流水表 `multipay_recharge_credits`,重复通知和重复轮询不会重复增加积分。
平台向 `notify_url` 发送 JSON:
```json
{
"event": "payment.succeeded",
"event_id": "evt_pay_xxx",
"order_id": "pay_xxx",
"merchant_order_no": "ORDER202610310001",
"user_id": "USER10001",
"package_id": 2,
"points": 520,
"channel": "wechat",
"amount": "99.00",
"status": "paid",
"provider_trade_no": "420000...",
"paid_at": "2026-10-31T08:00:00.000Z"
}
```
请求头:
- `X-Pay-Timestamp`: Unix 秒
- `X-Pay-Signature`: `HMAC-SHA256(merchant_secret, timestamp + "." + 原始请求体).hex()`
- `X-Pay-Event-Id`: 幂等事件 ID
业务系统应校验签名与时间戳、按事件 ID 幂等处理,并返回任意 `2xx` 状态码。
## 用户与充值套餐
- 后台“用户管理”用于创建和停用本地用户,并查看积分余额、成功充值次数和累计金额。
- 后台“充值套餐”可配置套餐名称、显示金额、到账积分、启用状态和展示顺序。
- 支付渠道确认成功后,服务端将套餐积分增加到 PostgreSQL `users.quota`;入账成功后才向支付页返回成功。
- 每个支付订单只允许生成一条业务入账流水;支付平台重复通知和页面重复轮询不会重复增加积分。
- 收银台默认展示该用户最近六个月的成功充值记录。
- 初始演示用户为 `demo-user`,仅用于本地验收,正式使用时请创建业务用户并停用演示用户。
## 后台退费
- 充值记录中的已支付订单可以由管理员发起原路全额退款。
- 管理员可选择是否回退积分;默认回退该订单充值时到账的积分,也可以填写其他非负整数。
- 支付渠道确认退款后,服务端按订单绑定的用户 ID 从 PostgreSQL `users.quota` 扣减积分,网页不会直接操作业务数据库。
- 退款请求号与积分回退流水均按订单保持唯一;重复点击、网络重试或渠道重复响应不会重复退款、重复扣减积分。
- 微信退款处于处理中时,可在充值记录中点击“查询退款”继续确认状态。
## 官方支付配置
### 支付宝
后台新增支付宝网关,填写 AppID、商户 PID、应用 RSA2 私钥和支付宝公钥。使用电脑网站支付时,服务端会打开支付宝官方收银台并提取其真实付款二维码展示在本站扫码区,不向用户提供收银台跳转链接;二维码会定时刷新。正式应用需开通“电脑网站支付”,仅在选择 `precreate` 时需要开通“当面付”。
### 微信支付
后台新增微信网关,填写 AppID、直连商户号、商户证书序列号、商户 API 私钥、微信支付公钥和 32 字节 APIv3 密钥。商户需开通 Native 支付。
回调地址必须能被支付平台通过公网 HTTPS 访问;本地联调可使用安全的隧道服务,并将 `APP_BASE_URL` 设置为该公网地址。
## 个人与企业主体说明
后台可将网关标注为“个人/个体主体”或“企业主体”。真实的服务端下单和自动回调仍要求支付宝或微信审核通过的商户资质与对应产品权限;普通个人收款码没有可靠的官方服务端通知,本项目不实现不安全的“个人免签监听”。
## 数据与备份
- 数据库:`data/multipay.sqlite`
- 自动生成的本地加密主密钥:`data/.master-key`
备份时必须同时备份数据库和主密钥。丢失 `.master-key` 后,已保存的支付网关密钥无法解密。