tradecenter 系统设计与接口文档

更新时间：2026-05-01。Markdown 源文档：docs/system.md。

系统定位

tradecenter 是交易中心与 EPay 兼容网关。它一方面提供原生交易订单接口，另一方面兼容彩虹易支付 V1 风格的 submit.php、mapi.php、api.php。

当前模式live

当前 EPay provideralipay_page

底层支付宝接口alipay.trade.page.pay

可用 provider：shouqianba、alipay、alipay_page。其中 alipay 是订单码支付，alipay_page 是电脑网站支付。

文档与测试入口

类型	路径	说明
系统文档	`/docs`	当前页面
收钱吧测试页	`/test/pay`	原生交易订单 + 二维码测试
支付宝测试页	`/test/alipay`	原生支付宝预下单测试
EPay 测试页	`/test/epay`	EPay submit.php 流程测试
健康检查	`/healthz` 或 `/api/healthz`	服务状态

测试页和 /api/epay/test/* 是调试入口，不属于正式对外接口。

配置说明

配置	说明
`app.mode`	`mock` 为本地模拟，`live` 为真实 provider。
`app.docs_enabled`	是否允许打开 `/docs`。
`easypay.enabled`	是否启用 EPay 兼容网关。
`easypay.provider`	`shouqianba`、`alipay`、`alipay_page`。
`easypay.pid` / `easypay.key`	分配给上游业务系统的商户号和 MD5 签名密钥。
`alipay.gateway_url`	支付宝正式网关为 `https://openapi.alipay.com/gateway.do`。
`alipay.notify_url`	支付宝异步通知地址，真实支付必须是公网 URL。
`alipay.return_url`	支付宝浏览器同步回跳地址。

分层逻辑

外部系统 / 测试页
  -> Flask 路由层
     - app/web.py: 页面、EPay V1 兼容路径、收银台
     - app/api.py: JSON API、provider 回调、测试辅助接口
  -> 应用服务层
     - EPayService: EPay 验签、建单、商户通知、回跳
     - OrderService: 原生交易订单建单、查询、状态更新
  -> 支付网关适配层
     - MockGateway
     - LiveGateway: 收钱吧
     - AlipayGateway: precreate / page.pay / query / notify 验签
  -> 数据访问层
     - repositories.py
     - models.py
  -> 数据库 SQLite / MySQL

EPay + 支付宝电脑网站支付链路

业务系统
  -> /submit.php 或 /mapi.php
  -> EPayService 校验 pid/sign/money/out_trade_no
  -> epay_orders 建单
  -> AlipayGateway 生成 alipay.trade.page.pay 跳转 URL
  -> 用户进入支付宝收银台支付
  -> 支付宝异步通知 /api/payments/alipay/notify
  -> tradecenter 更新 epay_orders 为 paid
  -> tradecenter 按 EPay V1 字段 POST 商户 notify_url
  -> 商户返回 success

浏览器同步回跳只用于用户体验，不能作为到账依据。

正式 EPay V1 兼容接口

GET/POST `/submit.php`

页面跳转支付。成功后进入 tradecenter 收银台或跳转到支付宝电脑网站收银台。

参数	必填	说明
`pid`	是	商户号
`type`	否	支付方式；当前 `alipay_page` 只支持 `alipay`
`out_trade_no`	是	商户订单号，同一 pid 下唯一
`notify_url`	是	商户异步通知地址
`return_url`	是	商户浏览器回跳地址
`name`	是	商品名称
`money`	是	金额，单位元
`param`	否	扩展参数，通知时原样返回
`sign`	是	MD5 签名
`sign_type`	是	固定 `MD5`

GET/POST `/mapi.php`

API 接口支付，返回 JSON。必填参数比 submit.php 多 clientip，且 type 必填。

{
  "code": 1,
  "msg": "success",
  "trade_no": "EP2026050107374812300784B169",
  "payurl": "https://openapi.alipay.com/gateway.do?..."
}

GET/POST `/api.php?act=query`

商户信息查询：/api.php?act=query&pid={pid}&key={key}。

GET/POST `/api.php?act=order`

单个订单查询，可按 out_trade_no 或 trade_no 查询。

{
  "code": 1,
  "msg": "查询订单号成功！",
  "trade_no": "EP2026050107374812300784B169",
  "out_trade_no": "order-10001",
  "api_trade_no": "202605012200...",
  "type": "alipay",
  "pid": "1001",
  "name": "VIP",
  "money": "0.01",
  "status": 1,
  "param": ""
}

签名规则

取所有非空参数。
排除 sign 和 sign_type。
按参数名 ASCII 升序排序。
拼接为 a=b&c=d，参数值不做 URL 编码。
末尾追加商户密钥后计算 MD5 小写值。

Provider 回调接口

方法	路径	说明
POST	`/api/payments/shouqianba/notify`	收钱吧异步通知
GET/POST	`/api/payments/alipay/notify`	支付宝异步通知
GET	`/api/payments/alipay/return`	支付宝同步回跳

tradecenter 向商户 notify_url 和 return_url 发送 EPay V1 字段：pid、trade_no、out_trade_no、type、name、money、trade_status、param、sign、sign_type。异步通知成功要求商户返回裸文本 success。

原生交易订单接口

方法	路径	说明
POST	`/api/orders/precreate`	创建原生交易单并请求 provider 预下单
GET	`/api/orders/{client_sn}`	查询原生订单
POST	`/api/orders/{client_sn}/query`	主动刷新订单
GET	`/api/orders/{client_sn}/qr.png`	获取二维码图片

{
  "user_id": "user-1001",
  "amount": "9.90",
  "subject": "标准套餐（月付）",
  "payment_method": "alipay",
  "business_time": "2026-05-01T12:00:00"
}

运维与调试接口

方法	路径	说明
GET	`/api/healthz`	API 健康检查
GET	`/api/payments/shouqianba/status`	收钱吧配置状态
POST	`/api/payments/shouqianba/activate`	收钱吧终端激活
POST	`/api/payments/shouqianba/checkin`	收钱吧签到
GET	`/api/payments/alipay/status`	支付宝配置状态
GET	`/api/epay/status`	EPay 兼容层配置状态

数据表 ER 关系

trade_orders 1 -- 0..1 trade_payment_orders
trade_orders 1 -- 0..N payment_status_transitions
trade_orders 1 -- 0..N payment_callback_logs
epay_orders  1 -- 0..N payment_callback_logs (按 trade_no/out_trade_no 关联)

trade_orders
  PK id
  UK client_sn
  user_id, business_time, subject, total_amount, payment_method, status

trade_payment_orders
  PK id
  UK trade_order_sn
  provider_order_no, provider_trade_no, qr_code, raw_* 响应

epay_orders
  PK id
  UK trade_no
  UK merchant_pid + out_trade_no
  cashier_token, provider_order_no, provider_trade_no
  notify_url, return_url, merchant_notified

payment_callback_logs
  PK id
  client_sn, shouqianba_sn, payload, verified, processed

payment_status_transitions
  PK id
  client_sn, from_status, to_status, reason, source

完整 Mermaid ER 图在 docs/system.md 中维护。

状态流转

原生交易订单

created -> pay_success -> rights_granted
created -> pay_failed

EPay 订单

pending -> paid -> merchant_notified=true
pending -> cancelled / failed / expired

迭代记录

2026-05-01

新增支付宝电脑网站支付 provider：alipay_page。
alipay_page 使用 alipay.trade.page.pay，适配已开通的支付宝产品。
保留支付宝订单码 provider：alipay，继续使用 alipay.trade.precreate。
新增 EPay V1 标准路径 /mapi.php。
新增 EPay V1 查询路径 /api.php?act=query 和 /api.php?act=order。
EPay MD5 签名校验调整为 V1 标准规则。
更新本文档，加入接口、测试入口、ER、分层逻辑和迭代记录。

2026-04-30

初版 tradecenter：原生交易订单、收钱吧预下单、回调和测试页面。
新增 EPay submit.php 页面跳转兼容层。
新增支付宝订单码支付验证页面。