承信租 V4 文档

Appearance

概述 ​

交易组件是支付宝小程序提供的订单管理功能，支持订单创建、修改、查询、履约状态同步等。本文档详细介绍交易组件的架构、流程和开发细节。 (现在已经弃用,被租赁行业交易替代)

架构设计 ​

核心组件 ​

TradeComponentServices (交易组件服务)
├── orderCreate()              # 交易组件订单创建
├── orderModify()              # 交易组件订单修改
├── orderDeliveryModify()      # 履约状态变更
├── orderQuery()               # 交易组件订单查询
├── orderInstallmentCreate()   # 订单分期创建
├── orderBuyout()              # 买断/违约金/赔付金
├── orderInstallmentClose()    # 关闭分期
├── orderDeliverySend()        # 发货（物流信息同步）
├── orderDeliveryReceive()     # 确认收货
└── getDeliveryId()            # 获取阿里物流编码

代码来源：app/services/alipay/TradeComponentServices.php

调用流程 ​

用户下单
  ↓
交易组件订单创建 (orderCreate)
  ↓
订单分期创建 (orderInstallmentCreate)
  ↓
发货 (orderDeliverySend)
  ↓
确认收货 (orderDeliveryReceive)
  ↓
买断/归还 (orderBuyout / orderDeliveryModify)
  ↓
关闭分期 (orderInstallmentClose)

开发指南 ​

交易组件订单创建 ​

php
// 交易组件订单创建（含分期计划/商品/地址）
$tradeServices = app()->make(TradeComponentServices::class);
$result = $tradeServices->orderCreate($orderId, $sourceId, $path);

参数说明：

  • $orderId — 订单ID
  • $sourceId — 追踪ID
  • $path — 商家小程序对应的订单详情页路径地址

返回值：

  • 成功：返回订单创建结果（含 trade_component_order_id）
  • 失败：抛出异常

代码来源：app/services/alipay/TradeComponentServices.php:63

交易组件订单修改 ​

php
// 交易组件订单修改（分期计划/金额调整）
$result = $tradeServices->orderModify($orderId, $params);

参数说明：

  • $orderId — 订单ID
  • $params — 修改参数

返回值：

  • 成功：返回修改结果
  • 失败：抛出异常

代码来源：app/services/alipay/TradeComponentServices.php:236

履约状态变更 ​

php
// 履约状态变更接口（商家确认/租完即送/归还）
$result = $tradeServices->orderDeliveryModify($orderId, $status);

参数说明：

  • $orderId — 订单ID
  • $status — 履约状态

返回值：

  • 成功：返回变更结果
  • 失败：抛出异常

代码来源：app/services/alipay/TradeComponentServices.php:342

交易组件订单查询 ​

php
// 交易组件订单查询
$result = $tradeServices->orderQuery($orderId);

参数说明：

  • $orderId — 订单ID

返回值：

  • 成功：返回订单信息
  • 失败：抛出异常

代码来源：app/services/alipay/TradeComponentServices.php:396

订单分期创建 ​

php
// 订单分期（预授权代扣前创建分期）
$result = $tradeServices->orderInstallmentCreate($orderId, $num, $amount);

参数说明：

  • $orderId — 订单ID
  • $num — 分期期数
  • $amount — 分期金额

返回值：

  • 成功：返回分期创建结果
  • 失败：抛出异常

代码来源：app/services/alipay/TradeComponentServices.php:438

买断/违约金/赔付金 ​

php
// 买断/违约金/赔付金（交易组件）
$result = $tradeServices->orderBuyout($orderId, $type, $amount);

参数说明：

  • $orderId — 订单ID
  • $type — 类型（买断/违约金/赔付金）
  • $amount — 金额

返回值：

  • 成功：返回处理结果
  • 失败：抛出异常

代码来源：app/services/alipay/TradeComponentServices.php:530

关闭分期 ​

php
// 交易组件关闭分期
$result = $tradeServices->orderInstallmentClose($orderId);

参数说明：

  • $orderId — 订单ID

返回值：

  • 成功：返回关闭结果
  • 失败：抛出异常

代码来源：app/services/alipay/TradeComponentServices.php:611

发货（物流信息同步） ​

php
// 发货（物流信息同步）
$result = $tradeServices->orderDeliverySend($orderId, $deliveryInfo);

参数说明：

  • $orderId — 订单ID
  • $deliveryInfo — 物流信息

返回值：

  • 成功：返回发货结果
  • 失败：抛出异常

代码来源：app/services/alipay/TradeComponentServices.php:653

确认收货 ​

php
// 确认收货
$result = $tradeServices->orderDeliveryReceive($orderId);

参数说明：

  • $orderId — 订单ID

返回值：

  • 成功：返回确认结果
  • 失败：抛出异常

代码来源：app/services/alipay/TradeComponentServices.php:720

获取阿里物流编码 ​

php
// 获取阿里物流编码
$result = $tradeServices->getDeliveryId($expressCompany);

参数说明：

  • $expressCompany — 快递公司名称

返回值：

  • 成功：返回物流编码
  • 失败：抛出异常

代码来源：app/services/alipay/TradeComponentServices.php:757

订单同步 ​

订单信息同步 ​

通过 AlipayServices::miniOrderModify() 同步订单信息：

php
// 订单信息同步
$alipayServices = app()->make(AlipayServices::class);
$result = $alipayServices->miniOrderModify($orderId, $params);

代码来源：app/services/alipay/AlipayServices.php:2125

履约状态同步 ​

通过 AlipayServices::miniOrderDeliveryModify() 同步履约状态：

php
// 履约状态同步
$result = $alipayServices->miniOrderDeliveryModify($orderId, $status);

代码来源：app/services/alipay/AlipayServices.php:2221

支付宝交易组件验收专线 ​

本小节记录一次性验收能力的实现，与常规交易组件（租赁/直付通）链路隔离。归档变更：openspec/changes/archive/2026-08-11-alipay-trade-component-acceptance/。

背景与边界 ​

项值
支付宝 AppID2021006149634147（正式，体验版）
验收账号平台 UID 4（唯一白名单，需已绑定支付宝）
验收商品独立新建的普通数字零售商品（lease_type=2），单 SKU，单价 1 元 × 数量 2 = 总额 2 元，运费/优惠 0
订单识别eb_store_order.flag = 'alipay_trade_acceptance'
业务类型KX_SHOPPING

明确隔离：不使用 TradeComponentServices::orderCreate（旧租赁兼容），不调用/修改 CommerceRentServices（租赁行业交易），不把体验版状态当作支付宝验收工具通过。

目标数据流 ​

text
后台人工开启（enabled + expires_at）
  -> uniapp trial 专用入口
  -> 服务端校验 UID=4、支付宝绑定、时间、固定商品/SKU
  -> my.checkBeforeAddOrder
       requireOrder=1：创建 KX_SHOPPING 组件业务订单
       requireOrder=0：不进入组件订单流程
  -> QuickOrderServices::createMiniSaleOrder 验收分支
       忽略客户端 uid/quantity/orderPrice
       服务端固定 SKU、单价1、数量2、总额2、运费/优惠0
  -> 1 分钟内单独一次 alipay.trade.create
       out_trade_no=out_order_id
       extend_params.trade_component_order_id=order_id
       product_code=JSAPI_PAY
  -> 支付通知/查询推进状态
  -> miniOrderDeliverySend -> miniOrderDeliveryReceive
  -> alipay.trade.refund 全额退款 -> queryRefund 确认

验收资格判定式 ​

新建验收单必须同时满足：

text
enabled
AND now < expires_at
AND token.request.uid == 4
AND account has verified Alipay binding
AND server product_id == configured product_id
AND server out_item_id == eb_store_product.public_product_id
AND server out_sku_id == eb_store_product_attr_value.id
AND eb_store_product_attr_value.sale_sku_id IS NOT NULL
AND server quantity == 2
AND server unit_price == 1.00
AND server freight == 0
AND server discount == 0

2026-08 修正：eb_public_product、eb_public_product_sku_detail 等公域表已废弃。out_item_id 由 eb_store_product.public_product_id 实时推导，商家侧 out_sku_id 由 eb_store_product_attr_value.id 推导，并以 sale_sku_id 非空证明规格已提报。配置键 alipay_trade_acceptance_public_product_id / alipay_trade_acceptance_sku_id 代码已停用，生产数据保留。

配置与后台控制 ​

配置键（eb_system_config，value 为 JSON 字符串）：

text
alipay_trade_acceptance_enabled
alipay_trade_acceptance_expires_at
alipay_trade_acceptance_uid       = 4
alipay_trade_acceptance_product_id

开关直接以 SQL 维护，不开发后台页面。开启时设置 expires_at 为 24 小时后：

sql
UPDATE eb_system_config SET value = '"<timestamp>"' WHERE menu_name = 'alipay_trade_acceptance_expires_at' AND is_store = 0;
UPDATE eb_system_config SET value = '"1"'              WHERE menu_name = 'alipay_trade_acceptance_enabled' AND is_store = 0;

执行后必须清缓存：php think clear:cache。

组件订单、支付号关联与支付幂等 ​

  • 组件业务订单：alipay.open.mini.order.create，业务类型 KX_SHOPPING，本地保存支付宝 order_id。
  • 支付单：业务单成功后 1 分钟内单独调用一次 alipay.trade.create：
    • out_trade_no = out_order_id
    • extend_params.trade_component_order_id = order_id
    • product_code = JSAPI_PAY
  • 幂等：同一业务单已有支付单或已记录实际支付号 trade_no 时，重复调用 orderPay 直接返回原支付号，不创建第二个支付单。

履约与退款 ​

  • 发货：AlipayServices::miniOrderDeliverySend
  • 确认收货：AlipayServices::miniOrderDeliveryReceive
  • 退款：alipay.trade.refund 全额 2 元，锁定实际支付号，成功后用 queryRefund 确认最终状态并 dev_log 留证。

通知幂等、失败补偿和证据 ​

  • 支付通知复用既有链路：/api/pay/notify/alipay -> Pay::notify('alipay') -> AliPayService。
  • 订单中心/应用网关同步由支付宝侧自动完成，不新建消息订阅体系。
  • 缺通知时按商户单号手工查询补单；外部调用超时先查询，不盲目重试。
  • 保留：固定 SKU/金额快照、UID 判定、组件 order_id、out_trade_no、实际支付号、通知验签结果、履约结果、退款查询结果、商品映射。

失败场景与风险权衡 ​

  1. 价格真实性：相机 1 元可能被支付宝驳回，需准备真实低价配件兜底。
  2. 一单多支付：验收分支用明确支付单状态和锁禁止双支付。
  3. 旧链路误伤：用 flag='alipay_trade_acceptance' 隔离，不改租赁链路。
  4. 客户端篡改：仅信任 Token request uid 和服务端固定值。
  5. 体验版误判：体验版通过 ≠ 验收工具通过。

上线、关闭与回滚 ​

上线顺序：平台/账户预检 → 配置核对 → 代码部署 → 测试环境验证 → 人工确认生产商品/开关 → 正式体验版验收。

关闭：优先 UPDATE eb_system_config SET value = '"0"' WHERE menu_name = 'alipay_trade_acceptance_enabled'，然后清缓存。关闭/过期只禁止新建，存量订单继续履约/退款。

代码回滚范围：

  • app/services/alipay/AlipayTradeAcceptanceServices.php（新增）
  • app/controller/api/v1/alipay/TradeAcceptance.php + route/api.php 中 trade_acceptance/check
  • StoreOrder.php、OrderPayServices.php、StoreOrderRefundServices.php、Delivery.php、Take.php、QuickOrderServices.php 中的验收分支
  • view/uniapp/pages/alipay/trade_acceptance/ + pages.json + view/uniapp/pages/index/index.vue 中临时代码块
  • 相关单元测试

不回滚：租赁链路、既有订单、已完成支付/退款记录。

相关代码位置 ​

职责文件
验收资格判定与配置app/services/alipay/AlipayTradeAcceptanceServices.php
验收接口app/controller/api/v1/alipay/TradeAcceptance.php
下单分支app/services/order/StoreOrder.php、app/services/order/QuickOrderServices.php
支付分支app/services/order/OrderPayServices.php
退款/查询app/services/order/StoreOrderRefundServices.php
履约事件app/listener/order/Delivery.php、app/listener/order/Take.php
移动端入口view/uniapp/pages/alipay/trade_acceptance/index.vue

常见问题 ​

Q: 交易组件订单创建失败怎么办？ ​

A: 检查以下条件：

  1. 订单信息是否完整
  2. 商品信息是否正确
  3. 用户信息是否完整
  4. 小程序是否已授权

Q: 订单同步失败怎么办？ ​

A: 检查以下条件：

  1. 订单是否存在
  2. 同步参数是否正确
  3. 支付宝接口是否正常
  4. 小程序是否已授权

Q: 物流信息同步失败怎么办？ ​

A: 检查以下条件：

  1. 物流信息是否完整
  2. 快递公司编码是否正确
  3. 支付宝接口是否正常

承信租多门店租赁商城系统官方文档