富友支付支持

openspec/specs/external-integration/spec.md

@@ -66,6 +66,41 @@
 - **WHEN** 渠道再次发送相同业务事实
 - **THEN** 系统返回渠道可接受响应且不重复推进卡状态
 
+### Requirement: 富友主扫统一下单与订单查询
+
+系统 SHALL 通过富友主扫统一下单创建微信二维码支付并返回 `qr_code` 二维码链接；系统 SHALL 通过富友订单查询按 `trans_stat` 将状态映射为已支付、已关闭、待支付或未知，未知状态 MUST 保持待恢复。下单与查询失败 MUST 映射为项目稳定错误，已接入外部交互日志的调用保留脱敏结果。
+
+#### Scenario: 主扫下单成功返回二维码链接
+
+- **GIVEN** 富友支付配置完整
+- **WHEN** 系统发起主扫统一下单且渠道返回成功
+- **THEN** 系统返回 `qr_code` 作为支付链接，业务以该链接生成二维码
+
+#### Scenario: 查询映射支付成功
+
+- **WHEN** 富友订单查询返回 `trans_stat=SUCCESS`
+- **THEN** 系统将状态映射为已支付并取得渠道交易号、金额与支付时间
+
+#### Scenario: 查询映射已关闭
+
+- **WHEN** 富友订单查询返回 `trans_stat` 为 `PAYERROR`、`CLOSED` 或 `REVOKED`
+- **THEN** 系统将状态映射为已关闭
+
+#### Scenario: 查询映射待支付
+
+- **WHEN** 富友订单查询返回 `trans_stat` 为 `USERPAYING` 或 `NOTPAY`
+- **THEN** 系统将状态映射为待支付
+
+#### Scenario: 查询状态未知保持待恢复
+
+- **WHEN** 富友订单查询返回系统错误、找不到交易或无法识别的 `trans_stat`
+- **THEN** 系统将状态映射为未知并保持本地支付单待恢复，不得据此确认收款或关闭订单
+
+#### Scenario: 下单失败返回稳定错误
+
+- **WHEN** 富友主扫统一下单返回失败或请求结果未知
+- **THEN** 系统返回项目稳定错误且已接入外部交互日志的调用记录脱敏结果
+
 ## 可达操作索引
 
 本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。