feat: implement third-party order sync

docs/payment-integration.md

@@ -0,0 +1,348 @@
+# 支付功能接入文档
+
+本文用于指导后续接入微信、支付宝或其他聚合支付渠道。当前项目尚未实现支付功能，开发时应先把订单、支付单、回调日志和履约流程的边界预留好，避免后续重构订单主链路。
+
+## 接入目标
+
+- 订单创建后先进入待支付状态。
+- 用户或管理员发起支付，后端创建支付单。
+- 支付渠道异步回调后，后端验签并更新支付状态。
+- 支付成功后触发订单履约：
+  - 第三方商品：服务端调用第三方下单接口。
+  - 自营商品：只写入本地数据库，生成本地交付记录。
+- 支持后续退款、支付状态主动查询、回调补偿和支付审计。
+
+## 推荐订单状态
+
+订单主状态建议拆成支付状态和履约状态，不要只用一个 `status` 混合表达全部含义。
+
+支付状态 `payment_status`：
+
+| 状态 | 说明 |
+| --- | --- |
+| `unpaid` | 未支付，订单刚创建 |
+| `paying` | 已创建支付单，等待渠道结果 |
+| `paid` | 已支付成功 |
+| `pay_failed` | 支付失败 |
+| `closed` | 支付超时或订单关闭 |
+| `refunding` | 退款中 |
+| `refunded` | 已退款 |
+| `partial_refunded` | 部分退款 |
+
+履约状态 `fulfillment_status`：
+
+| 状态 | 说明 |
+| --- | --- |
+| `pending` | 等待支付或等待履约 |
+| `submitting` | 正在提交第三方或生成本地交付 |
+| `submitted` | 已提交第三方或已生成交付 |
+| `processing` | 第三方或本地处理中 |
+| `completed` | 已完成 |
+| `failed` | 履约失败 |
+| `canceled` | 已取消 |
+
+## 推荐数据表
+
+### `orders`
+
+订单主表，保存业务订单。
+
+建议字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 本地订单 ID |
+| `order_no` | 本地订单号，展示和支付使用 |
+| `user_id` | 下单用户 |
+| `source_type` | `third_party` 或 `self_owned` |
+| `provider` | 第三方供应商标识，自营可为空 |
+| `total_amount` | 订单金额 |
+| `payable_amount` | 应付金额 |
+| `paid_amount` | 实付金额 |
+| `payment_status` | 支付状态 |
+| `fulfillment_status` | 履约状态 |
+| `remark` | 备注 |
+| `created_at` | 创建时间 |
+| `updated_at` | 更新时间 |
+
+### `order_items`
+
+订单明细表，保存商品快照，避免商品改价影响历史订单。
+
+建议字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 明细 ID |
+| `order_id` | 订单 ID |
+| `product_id` | 商品 ID |
+| `product_name` | 商品名称快照 |
+| `source_type` | 商品来源 |
+| `external_product_id` | 第三方商品 ID，自营为空 |
+| `unit_price` | 单价 |
+| `quantity` | 数量 |
+| `total_amount` | 明细金额 |
+| `payload` | 下单扩展信息，敏感字段入库前加密或脱敏 |
+
+### `payments`
+
+支付单表。一个订单可以有多次支付尝试，但同一时间只允许一个有效待支付支付单。
+
+建议字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 支付单 ID |
+| `payment_no` | 本地支付单号 |
+| `order_id` | 订单 ID |
+| `order_no` | 本地订单号冗余 |
+| `channel` | 支付渠道，如 `wechat`、`alipay`、`manual` |
+| `amount` | 支付金额 |
+| `currency` | 默认 `CNY` |
+| `status` | `created`、`paying`、`paid`、`failed`、`closed`、`refunded` |
+| `channel_trade_no` | 渠道交易号 |
+| `channel_payload` | 渠道创建支付返回，敏感字段脱敏 |
+| `paid_at` | 支付成功时间 |
+| `expired_at` | 支付过期时间 |
+| `created_at` | 创建时间 |
+| `updated_at` | 更新时间 |
+
+### `payment_events`
+
+支付事件表，保存支付回调、主动查询、退款回调等原始事件。
+
+建议字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 事件 ID |
+| `payment_id` | 支付单 ID |
+| `order_id` | 订单 ID |
+| `channel` | 支付渠道 |
+| `event_type` | `notify`、`query`、`refund_notify` |
+| `event_no` | 渠道事件号或渠道交易号，用于幂等 |
+| `status` | 处理状态 |
+| `raw_payload` | 原始回调内容，注意脱敏或加密 |
+| `verify_result` | 验签结果 |
+| `error_message` | 处理失败原因 |
+| `created_at` | 创建时间 |
+
+### `refunds`
+
+退款单表，后续退款功能使用。
+
+建议字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 退款单 ID |
+| `refund_no` | 本地退款单号 |
+| `payment_id` | 支付单 ID |
+| `order_id` | 订单 ID |
+| `amount` | 退款金额 |
+| `reason` | 退款原因 |
+| `status` | `created`、`processing`、`succeeded`、`failed` |
+| `channel_refund_no` | 渠道退款单号 |
+| `refunded_at` | 退款完成时间 |
+
+## 后端接口设计
+
+### 创建订单
+
+`POST /api/orders`
+
+职责：
+
+- 校验商品、价格、库存、上下架状态。
+- 创建 `orders` 和 `order_items`。
+- 设置 `payment_status=unpaid`。
+- 设置 `fulfillment_status=pending`。
+- 返回订单号和应付金额。
+
+注意：
+
+- 第三方商品在订单创建阶段不要把 `uid`、`key` 返回给前端。
+- 学生账号和密码等敏感信息必须由服务端保存，并在展示时脱敏。
+
+### 创建支付单
+
+`POST /api/payments`
+
+请求示例：
+
+```json
+{
+  "orderNo": "ORD202606060001",
+  "channel": "wechat",
+  "returnUrl": "https://example.com/orders/ORD202606060001"
+}
+```
+
+职责：
+
+- 校验订单存在且未支付。
+- 校验订单金额和当前商品金额是否允许支付。
+- 创建 `payments`。
+- 调用支付渠道统一下单接口。
+- 返回前端支付参数，例如二维码、跳转链接或小程序支付参数。
+
+### 支付回调
+
+`POST /api/payments/notify/:channel`
+
+职责：
+
+- 获取原始请求体。
+- 按渠道验签。
+- 写入 `payment_events`。
+- 校验本地支付单号、金额、币种、渠道交易号。
+- 幂等更新 `payments.status=paid`。
+- 幂等更新 `orders.payment_status=paid`。
+- 触发履约流程。
+- 返回渠道要求的成功响应。
+
+必须保证：
+
+- 重复回调不会重复提交第三方订单。
+- 金额不一致时不能标记为已支付。
+- 验签失败只记录事件，不更新支付成功。
+
+### 主动查询支付状态
+
+`GET /api/payments/:paymentNo/query`
+
+职责：
+
+- 调用渠道查询接口。
+- 写入 `payment_events`。
+- 如果渠道显示已支付，走同一套支付成功处理逻辑。
+
+### 申请退款
+
+`POST /api/refunds`
+
+职责：
+
+- 校验订单已支付且允许退款。
+- 创建 `refunds`。
+- 调用渠道退款接口。
+- 更新订单为 `refunding`。
+
+### 退款回调
+
+`POST /api/payments/refund-notify/:channel`
+
+职责：
+
+- 验签。
+- 写入 `payment_events`。
+- 幂等更新退款单和订单支付状态。
+
+## 支付成功后的履约流程
+
+支付成功处理函数建议抽成后端服务方法，例如：
+
+```ts
+async function handlePaymentSucceeded(paymentNo: string) {
+  // 1. 开启事务
+  // 2. 锁定 payment 和 order
+  // 3. 如果 payment/order 已处理过，直接返回
+  // 4. 标记 payment=paid、order.payment_status=paid
+  // 5. 根据 order.source_type 触发履约
+  // 6. 提交事务
+}
+```
+
+第三方商品：
+
+- 将订单履约状态改为 `submitting`。
+- 调用第三方 `act=add`。
+- 成功后保存第三方订单 ID 和响应摘要。
+- 将履约状态改为 `submitted` 或 `processing`。
+- 失败时改为 `failed`，保留失败原因，后台可手动重试。
+
+自营商品：
+
+- 将订单履约状态改为 `submitting`。
+- 生成本地交付记录或待处理任务。
+- 自动交付商品可直接改为 `completed`。
+- 人工处理商品改为 `processing`。
+
+## 幂等与事务
+
+必须使用幂等键：
+
+- 本地订单号 `order_no` 唯一。
+- 本地支付单号 `payment_no` 唯一。
+- 渠道交易号 `channel_trade_no` 唯一。
+- 支付事件 `event_no` 或原始回调哈希唯一。
+
+建议处理顺序：
+
+1. 回调进入后先验签。
+2. 写入 `payment_events`，重复事件直接返回成功。
+3. 开启数据库事务。
+4. 锁定支付单和订单。
+5. 校验金额和状态。
+6. 更新支付单和订单。
+7. 创建履约任务或直接履约。
+8. 提交事务。
+
+第三方下单如果耗时较长，建议支付事务内只创建 `order_fulfillments` 任务，事务外由 BullMQ 异步提交第三方，避免支付回调超时。
+
+## 环境变量建议
+
+```env
+PAYMENT_DEFAULT_CHANNEL=wechat
+
+WECHAT_PAY_MCH_ID=
+WECHAT_PAY_APP_ID=
+WECHAT_PAY_API_V3_KEY=
+WECHAT_PAY_PRIVATE_KEY=
+WECHAT_PAY_CERT_SERIAL_NO=
+WECHAT_PAY_NOTIFY_URL=
+
+ALIPAY_APP_ID=
+ALIPAY_PRIVATE_KEY=
+ALIPAY_PUBLIC_KEY=
+ALIPAY_NOTIFY_URL=
+ALIPAY_RETURN_URL=
+```
+
+生产环境要求：
+
+- 支付私钥和商户密钥不得提交仓库。
+- `.env` 不提交。
+- 私钥建议使用部署平台 Secret 或 KMS。
+- 回调地址必须是 HTTPS。
+
+## 前端页面建议
+
+- 订单确认页：展示商品、来源、价格、账号信息摘要、应付金额。
+- 支付页：展示支付方式、二维码/跳转按钮、倒计时、支付状态轮询。
+- 订单详情页：展示支付状态、履约状态、第三方提交状态或自营交付状态。
+- 后台支付管理：支付单列表、回调日志、主动查询、异常标记。
+- 后台退款管理：退款申请、退款结果、退款回调日志。
+
+## 测试清单
+
+- 创建订单后状态为 `unpaid` 和 `pending`。
+- 创建支付单后状态为 `paying`。
+- 正常回调可把支付单和订单标记为已支付。
+- 重复回调不会重复履约。
+- 金额不一致不会标记成功。
+- 验签失败不会更新订单。
+- 第三方商品支付成功后只提交一次第三方订单。
+- 自营商品支付成功后不调用第三方接口。
+- 支付超时后订单可关闭。
+- 退款成功后订单状态正确更新。
+
+## 与第三方商品的关系
+
+支付渠道和第三方课程接口是两套外部系统，不要混在一个服务里：
+
+- 支付服务只负责收钱、验签、退款和支付事件。
+- 第三方课程服务只负责 `getcate`、`getclass`、`get`、`add`、`orders` 等接口。
+- 订单服务负责协调支付成功后的履约分流。
+
+这样后续新增支付渠道或新增自营商品时，不需要改动第三方接口调用核心逻辑。