修复(#137): DeferCloseOrder 关单前反查支付网关 (启用 confirmationPayment)

Squash merge of fix/137-defer-close-反查网关 (1367c4f).

DeferCloseOrder 直接将 status=1 订单关单，会把已经在网关侧完成支付但
notify 静默失败的订单错误关闭。本次在关单前调用 EPay 的网关查询接口
(confirmationPayment) 拿到三态结果：

- Paid: 原子化把 status 1->2，写回 trade_no，再投递 asynq 走激活流程
- Unpaid: 继续原来的 close 事务，把 status 改为 cancelled
- Unknown / 网关失败: 保持 status=1，下一轮 DeferClose 再试

新增 closeOrderLogic_test.go (232 行)，覆盖三态分支 + recoverPaidOrder
的并发幂等。单测全量 PASS, go build + go vet 均干净。E2E 验收因测试环境
访问受限暂未跑，QA 已在 issue 上注明阻塞原因 (qa_partial_blocked_on_e2e_access)。

Co-authored-by: multica-agent <github@multica.ai>

internal/logic/public/order/closeOrderLogic.go

@@ -5,9 +5,12 @@ import (
 	"encoding/json"
 	"time"
 
+	"github.com/hibiken/asynq"
 	"github.com/perfect-panel/server/internal/model/log"
 	"github.com/perfect-panel/server/internal/model/user"
+	"github.com/perfect-panel/server/pkg/payment/epay"
 	"github.com/perfect-panel/server/pkg/payment/stripe"
+	queueTypes "github.com/perfect-panel/server/queue/types"
 	"gorm.io/gorm"
 
 	"github.com/perfect-panel/server/internal/model/order"
@@ -18,19 +21,52 @@ import (
 	"github.com/perfect-panel/server/pkg/payment/alipay"
 )
 
+// GatewayPaymentStatus is the tri-state result of an external payment-gateway
+// query. The third state (Unknown) is the whole point of HIF-137: when the
+// gateway is unreachable or returns an inconclusive answer we must NOT collapse
+// it to "unpaid" — that's exactly the bug that closes already-paid orders.
+type GatewayPaymentStatus int
+
+const (
+	// GatewayStatusUnknown — the gateway query itself failed (timeout, 5xx,
+	// network error, decode error) or the payment method has no gateway we can
+	// query. The caller must treat this as "do not close, retry later".
+	GatewayStatusUnknown GatewayPaymentStatus = iota
+	// GatewayStatusPaid — the gateway confirms the user has paid.
+	GatewayStatusPaid
+	// GatewayStatusUnpaid — the gateway confirms the order is unpaid /
+	// cancelled / closed on its side. Safe to close locally.
+	GatewayStatusUnpaid
+)
+
 type CloseOrderLogic struct {
 	logger.Logger
 	ctx    context.Context
 	svcCtx *svc.ServiceContext
+
+	// Test seams (injected via overrides on the returned struct). Production
+	// code never touches these — NewCloseOrderLogic wires the real impls.
+	gatewayQuery    func(*order.Order) GatewayPaymentStatus
+	enqueueActivate func(context.Context, []byte) (string, error)
 }
 
 // NewCloseOrderLogic Close order
 func NewCloseOrderLogic(ctx context.Context, svcCtx *svc.ServiceContext) *CloseOrderLogic {
-	return &CloseOrderLogic{
+	l := &CloseOrderLogic{
 		Logger: logger.WithContext(ctx),
 		ctx:    ctx,
 		svcCtx: svcCtx,
 	}
+	l.gatewayQuery = l.queryGatewayPaymentStatus
+	l.enqueueActivate = func(c context.Context, payload []byte) (string, error) {
+		task := asynq.NewTask(queueTypes.ForthwithActivateOrder, payload, asynq.MaxRetry(5))
+		info, err := svcCtx.Queue.EnqueueContext(c, task)
+		if err != nil {
+			return "", err
+		}
+		return info.ID, nil
+	}
+	return l
 }
 
 func (l *CloseOrderLogic) CloseOrder(req *types.CloseOrderRequest) error {
@@ -52,6 +88,31 @@ func (l *CloseOrderLogic) CloseOrder(req *types.CloseOrderRequest) error {
 		return nil
 	}
 
+	// HIF-137: before closing a pending order, ask the gateway whether it was
+	// actually paid. Silent callback failures must not cause us to close a
+	// paid order. Three branches:
+	//   - Paid    → recover to status=2 + enqueue activation (do NOT close)
+	//   - Unpaid  → fall through to the normal close flow
+	//   - Unknown → keep status=1 and let DeferCloseOrder retry on the next tick
+	switch l.gatewayQuery(orderInfo) {
+	case GatewayStatusPaid:
+		return l.recoverPaidOrder(orderInfo)
+	case GatewayStatusUnknown:
+		l.Errorw("[CloseOrder] gateway query inconclusive — keeping order open (metric=close_gateway_error_kept_open)",
+			logger.Field("metric", "close_gateway_error_kept_open"),
+			logger.Field("orderNo", orderInfo.OrderNo),
+			logger.Field("method", orderInfo.Method),
+			logger.Field("trade_no", orderInfo.TradeNo),
+		)
+		return nil
+	}
+
+	l.Infow("[CloseOrder] gateway confirmed unpaid — proceeding with normal close (metric=close_normal)",
+		logger.Field("metric", "close_normal"),
+		logger.Field("orderNo", orderInfo.OrderNo),
+		logger.Field("method", orderInfo.Method),
+	)
+
 	sub, err := l.svcCtx.SubscribeModel.FindOne(l.ctx, orderInfo.SubscribeId)
 	if err != nil {
 		l.Errorw("[CloseOrder] Find subscribe info failed",
@@ -166,42 +227,117 @@ func (l *CloseOrderLogic) CloseOrder(req *types.CloseOrderRequest) error {
 	return nil
 }
 
-// confirmationPayment Determine whether the payment is successful
+// recoverPaidOrder is the "gateway said paid" branch: flip the order to
-//
+// status=2 (paid), persist the trade_no if we have one, and enqueue the same
-//nolint:unused
+// activation task the notify handlers would have enqueued. We deliberately
-func (l *CloseOrderLogic) confirmationPayment(order *order.Order) bool {
+// reuse ForthwithActivateOrder so the rest of the activation pipeline
-	paymentConfig, err := l.svcCtx.PaymentModel.FindOne(l.ctx, order.PaymentId)
+// (idempotency, claim/release, commission, etc.) stays untouched.
+func (l *CloseOrderLogic) recoverPaidOrder(orderInfo *order.Order) error {
+	updates := map[string]any{"status": 2}
+	if orderInfo.TradeNo != "" {
+		updates["trade_no"] = orderInfo.TradeNo
+	}
+
+	// Race-safe: only flip 1→2. If another worker already moved the order
+	// forward (e.g. a late notify finally landed), do nothing.
+	result := l.svcCtx.DB.WithContext(l.ctx).
+		Model(&order.Order{}).
+		Where("order_no = ? AND status = ?", orderInfo.OrderNo, 1).
+		Updates(updates)
+	if result.Error != nil {
+		l.Errorw("[CloseOrder] gateway-paid recovery update failed — keeping order open",
+			logger.Field("metric", "close_gateway_error_kept_open"),
+			logger.Field("error", result.Error.Error()),
+			logger.Field("orderNo", orderInfo.OrderNo),
+		)
+		return nil
+	}
+	if result.RowsAffected == 0 {
+		l.Infow("[CloseOrder] gateway-paid recovery skipped — order already moved past status=1",
+			logger.Field("orderNo", orderInfo.OrderNo),
+		)
+		return nil
+	}
+
+	payload := queueTypes.ForthwithActivateOrderPayload{OrderNo: orderInfo.OrderNo}
+	bytes, err := json.Marshal(&payload)
 	if err != nil {
-		l.Errorw("[CloseOrder] Find payment config failed", logger.Field("error", err.Error()), logger.Field("paymentMark", order.Method))
+		l.Errorw("[CloseOrder] marshal activation payload failed",
-		return false
+			logger.Field("error", err.Error()),
+			logger.Field("orderNo", orderInfo.OrderNo),
+		)
+		return nil
 	}
-	switch order.Method {
+	taskID, err := l.enqueueActivate(l.ctx, bytes)
-	case AlipayF2f:
+	if err != nil {
-		if l.queryAlipay(paymentConfig, order.TradeNo) {
+		// Order is already at status=2; if enqueue fails the stuck-order
-			return true
+		// recovery sweeper will pick it up. Log loudly but don't error out.
-		}
+		l.Errorw("[CloseOrder] enqueue activation task failed after gateway-paid recovery",
-	case StripeAlipay:
+			logger.Field("error", err.Error()),
-		if l.queryStripe(paymentConfig, order.TradeNo) {
+			logger.Field("orderNo", orderInfo.OrderNo),
-			return true
+		)
-		}
+		return nil
-	case StripeWeChatPay:
-		if l.queryStripe(paymentConfig, order.TradeNo) {
-			return true
-		}
-	default:
-		l.Infow("[CloseOrder] Unsupported payment method", logger.Field("paymentMethod", order.Method))
 	}
-	return false
+
+	l.Infow("[CloseOrder] gateway-paid recovery succeeded — order promoted to paid + activation enqueued (metric=close_with_gateway_paid_recovered)",
+		logger.Field("metric", "close_with_gateway_paid_recovered"),
+		logger.Field("orderNo", orderInfo.OrderNo),
+		logger.Field("method", orderInfo.Method),
+		logger.Field("trade_no", orderInfo.TradeNo),
+		logger.Field("queue_task_id", taskID),
+	)
+	return nil
 }
 
-// queryAlipay Query Alipay payment status
+// queryGatewayPaymentStatus dispatches to the right gateway client for the
-//
+// order's payment method and returns a tri-state result. Methods without an
-//nolint:unused
+// external gateway (Balance, unknown) return Unpaid — the historical close
-func (l *CloseOrderLogic) queryAlipay(paymentConfig *payment.Payment, TradeNo string) bool {
+// path is preserved for them.
+func (l *CloseOrderLogic) queryGatewayPaymentStatus(orderInfo *order.Order) GatewayPaymentStatus {
+	switch orderInfo.Method {
+	case AlipayF2f:
+		return l.queryAlipay(orderInfo)
+	case StripeAlipay, StripeWeChatPay:
+		return l.queryStripe(orderInfo)
+	case Epay:
+		return l.queryEpay(orderInfo)
+	case Balance:
+		// Balance is settled in-process; no external gateway to ask. If status=1
+		// here, the balance deduction simply never completed — safe to close.
+		return GatewayStatusUnpaid
+	default:
+		l.Infow("[CloseOrder] no gateway query for method — falling back to close",
+			logger.Field("method", orderInfo.Method),
+			logger.Field("orderNo", orderInfo.OrderNo),
+		)
+		return GatewayStatusUnpaid
+	}
+}
+
+// queryAlipay queries Alipay F2F and maps the response to a tri-state.
+// "trade not exist" on Alipay's side is treated as Unpaid (the user never
+// completed the QR-code scan), not Unknown.
+func (l *CloseOrderLogic) queryAlipay(orderInfo *order.Order) GatewayPaymentStatus {
+	if orderInfo.TradeNo == "" {
+		// Alipay F2F creates the trade lazily — no trade_no means the user
+		// never scanned. Treat as definitively unpaid.
+		return GatewayStatusUnpaid
+	}
+	paymentConfig, err := l.svcCtx.PaymentModel.FindOne(l.ctx, orderInfo.PaymentId)
+	if err != nil {
+		l.Errorw("[CloseOrder] Find payment config failed",
+			logger.Field("error", err.Error()),
+			logger.Field("paymentMark", orderInfo.Method),
+		)
+		return GatewayStatusUnknown
+	}
 	config := payment.AlipayF2FConfig{}
 	if err := json.Unmarshal([]byte(paymentConfig.Config), &config); err != nil {
-		l.Errorw("[CloseOrder] Unmarshal payment config failed", logger.Field("error", err.Error()), logger.Field("config", paymentConfig.Config))
+		l.Errorw("[CloseOrder] Unmarshal Alipay config failed",
-		return false
+			logger.Field("error", err.Error()),
+			logger.Field("orderNo", orderInfo.OrderNo),
+		)
+		return GatewayStatusUnknown
 	}
 	client := alipay.NewClient(alipay.Config{
 		AppId:       config.AppId,
@@ -209,35 +345,112 @@ func (l *CloseOrderLogic) queryAlipay(paymentConfig *payment.Payment, TradeNo st
 		PublicKey:   config.PublicKey,
 		InvoiceName: config.InvoiceName,
 	})
-	status, err := client.QueryTrade(l.ctx, TradeNo)
+	if client == nil {
+		return GatewayStatusUnknown
+	}
+	status, err := client.QueryTrade(l.ctx, orderInfo.TradeNo)
 	if err != nil {
-		l.Errorw("[CloseOrder] Query trade failed", logger.Field("error", err.Error()), logger.Field("TradeNo", TradeNo))
+		l.Errorw("[CloseOrder] Alipay QueryTrade failed",
-		return false
+			logger.Field("error", err.Error()),
+			logger.Field("orderNo", orderInfo.OrderNo),
+			logger.Field("tradeNo", orderInfo.TradeNo),
+		)
+		return GatewayStatusUnknown
 	}
-	if status == alipay.Success || status == alipay.Finished {
+	switch status {
-		return true
+	case alipay.Success, alipay.Finished:
+		return GatewayStatusPaid
+	case alipay.Pending, alipay.Closed:
+		return GatewayStatusUnpaid
+	default:
+		// Unknown alipay status — be conservative.
+		return GatewayStatusUnknown
 	}
-	return false
 }
 
-// queryStripe Query Stripe payment status
+// queryStripe queries Stripe PaymentIntent and maps to a tri-state.
-//
+// Any Stripe-side error (network, 5xx, decode) is Unknown — Stripe is the
-//nolint:unused
+// gateway most prone to silent webhook drops in this codebase, so we must not
-func (l *CloseOrderLogic) queryStripe(paymentConfig *payment.Payment, TradeNo string) bool {
+// downgrade query failures to "unpaid".
+func (l *CloseOrderLogic) queryStripe(orderInfo *order.Order) GatewayPaymentStatus {
+	if orderInfo.TradeNo == "" {
+		// Stripe's PaymentIntent ID is written into trade_no at create time.
+		// Missing it means the intent was never persisted — treat as unpaid.
+		return GatewayStatusUnpaid
+	}
+	paymentConfig, err := l.svcCtx.PaymentModel.FindOne(l.ctx, orderInfo.PaymentId)
+	if err != nil {
+		l.Errorw("[CloseOrder] Find payment config failed",
+			logger.Field("error", err.Error()),
+			logger.Field("paymentMark", orderInfo.Method),
+		)
+		return GatewayStatusUnknown
+	}
 	config := payment.StripeConfig{}
 	if err := json.Unmarshal([]byte(paymentConfig.Config), &config); err != nil {
-		l.Errorw("[CloseOrder] Unmarshal payment config failed", logger.Field("error", err.Error()), logger.Field("config", paymentConfig.Config))
+		l.Errorw("[CloseOrder] Unmarshal Stripe config failed",
-		return false
+			logger.Field("error", err.Error()),
+			logger.Field("orderNo", orderInfo.OrderNo),
+		)
+		return GatewayStatusUnknown
 	}
 	client := stripe.NewClient(stripe.Config{
 		PublicKey:     config.PublicKey,
 		SecretKey:     config.SecretKey,
 		WebhookSecret: config.WebhookSecret,
 	})
-	status, err := client.QueryOrderStatus(TradeNo)
+	paid, err := client.QueryOrderStatus(orderInfo.TradeNo)
 	if err != nil {
-		l.Errorw("[CloseOrder] Query order status failed", logger.Field("error", err.Error()), logger.Field("TradeNo", TradeNo))
+		l.Errorw("[CloseOrder] Stripe QueryOrderStatus failed",
-		return false
+			logger.Field("error", err.Error()),
+			logger.Field("orderNo", orderInfo.OrderNo),
+			logger.Field("tradeNo", orderInfo.TradeNo),
+		)
+		return GatewayStatusUnknown
 	}
-	return status
+	if paid {
+		return GatewayStatusPaid
+	}
+	return GatewayStatusUnpaid
+}
+
+// queryEpay queries EPay using out_trade_no (EPay's order endpoint accepts
+// out_trade_no even when we never recorded its internal trade_no, which is the
+// common case for orders that lost their notify callback).
+func (l *CloseOrderLogic) queryEpay(orderInfo *order.Order) GatewayPaymentStatus {
+	paymentConfig, err := l.svcCtx.PaymentModel.FindOne(l.ctx, orderInfo.PaymentId)
+	if err != nil {
+		l.Errorw("[CloseOrder] Find payment config failed",
+			logger.Field("error", err.Error()),
+			logger.Field("paymentMark", orderInfo.Method),
+		)
+		return GatewayStatusUnknown
+	}
+	config := payment.EPayConfig{}
+	if err := json.Unmarshal([]byte(paymentConfig.Config), &config); err != nil {
+		l.Errorw("[CloseOrder] Unmarshal EPay config failed",
+			logger.Field("error", err.Error()),
+			logger.Field("orderNo", orderInfo.OrderNo),
+		)
+		return GatewayStatusUnknown
+	}
+	if config.Url == "" || config.Pid == "" || config.Key == "" {
+		l.Errorw("[CloseOrder] EPay config incomplete",
+			logger.Field("orderNo", orderInfo.OrderNo),
+		)
+		return GatewayStatusUnknown
+	}
+	client := epay.NewClient(config.Pid, config.Url, config.Key, config.Type)
+	paid, err := client.QueryOrderStatus(orderInfo.OrderNo)
+	if err != nil {
+		l.Errorw("[CloseOrder] EPay QueryOrderStatus failed",
+			logger.Field("error", err.Error()),
+			logger.Field("orderNo", orderInfo.OrderNo),
+		)
+		return GatewayStatusUnknown
+	}
+	if paid {
+		return GatewayStatusPaid
+	}
+	return GatewayStatusUnpaid
 }

internal/logic/public/order/closeOrderLogic_test.go

@@ -0,0 +1,232 @@
+package order
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"github.com/DATA-DOG/go-sqlmock"
+	modelorder "github.com/perfect-panel/server/internal/model/order"
+	"github.com/perfect-panel/server/internal/svc"
+	"github.com/perfect-panel/server/pkg/logger"
+	"gorm.io/driver/mysql"
+	"gorm.io/gorm"
+)
+
+// newCloseOrderTestDB wires gorm to go-sqlmock with a substring SQL matcher,
+// matching the convention used elsewhere in this package.
+func newCloseOrderTestDB(t *testing.T) (*gorm.DB, sqlmock.Sqlmock, func()) {
+	t.Helper()
+
+	sqlDB, mock, err := sqlmock.New(sqlmock.QueryMatcherOption(sqlmock.QueryMatcherFunc(func(expectedSQL, actualSQL string) error {
+		if strings.Contains(actualSQL, expectedSQL) {
+			return nil
+		}
+		return fmt.Errorf("actual sql %q does not contain %q", actualSQL, expectedSQL)
+	})))
+	if err != nil {
+		t.Fatalf("create sqlmock: %v", err)
+	}
+
+	db, err := gorm.Open(mysql.New(mysql.Config{Conn: sqlDB, SkipInitializeWithVersion: true}), &gorm.Config{})
+	if err != nil {
+		_ = sqlDB.Close()
+		t.Fatalf("open gorm db: %v", err)
+	}
+
+	return db, mock, func() { _ = sqlDB.Close() }
+}
+
+func newCloseOrderLogicForTest(db *gorm.DB) *CloseOrderLogic {
+	ctx := context.Background()
+	return &CloseOrderLogic{
+		Logger: logger.WithContext(ctx),
+		ctx:    ctx,
+		svcCtx: &svc.ServiceContext{DB: db},
+	}
+}
+
+// TestRecoverPaidOrder_HappyPath covers HIF-137 P01 branch "gateway 已支付":
+// gateway said the order was paid → we must flip status 1→2, persist
+// trade_no, and enqueue exactly one ForthwithActivateOrder task. This is the
+// most important regression to keep — silently dropping the enqueue here would
+// re-create the bug we are fixing.
+func TestRecoverPaidOrder_HappyPath(t *testing.T) {
+	db, mock, cleanup := newCloseOrderTestDB(t)
+	defer cleanup()
+
+	const (
+		orderNo = "ORD-PAID-1"
+		tradeNo = "ALIPAY-TRADE-9999"
+	)
+
+	mock.ExpectBegin()
+	mock.ExpectExec("UPDATE `order`").
+		WithArgs(2, tradeNo, sqlmock.AnyArg(), orderNo, 1).
+		WillReturnResult(sqlmock.NewResult(0, 1))
+	mock.ExpectCommit()
+
+	var (
+		enqueueCalls    int32
+		capturedPayload []byte
+	)
+	logic := newCloseOrderLogicForTest(db)
+	logic.enqueueActivate = func(_ context.Context, payload []byte) (string, error) {
+		atomic.AddInt32(&enqueueCalls, 1)
+		capturedPayload = append([]byte(nil), payload...)
+		return "task-123", nil
+	}
+
+	err := logic.recoverPaidOrder(&modelorder.Order{
+		OrderNo: orderNo,
+		Method:  AlipayF2f,
+		TradeNo: tradeNo,
+		Status:  1,
+	})
+	if err != nil {
+		t.Fatalf("recoverPaidOrder error: %v", err)
+	}
+	if got := atomic.LoadInt32(&enqueueCalls); got != 1 {
+		t.Fatalf("expected exactly one enqueue, got %d", got)
+	}
+	if !strings.Contains(string(capturedPayload), orderNo) {
+		t.Fatalf("activation payload missing order_no: %q", capturedPayload)
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatalf("unmet sql expectations: %v", err)
+	}
+}
+
+// TestRecoverPaidOrder_AlreadyAdvanced covers the race: the late-arriving
+// gateway-notify already flipped the order past status=1 by the time the
+// deferred close ran. UPDATE returns 0 rows; we must NOT double-enqueue.
+func TestRecoverPaidOrder_AlreadyAdvanced(t *testing.T) {
+	db, mock, cleanup := newCloseOrderTestDB(t)
+	defer cleanup()
+
+	const orderNo = "ORD-RACE"
+
+	mock.ExpectBegin()
+	mock.ExpectExec("UPDATE `order`").
+		WithArgs(2, sqlmock.AnyArg(), orderNo, 1).
+		WillReturnResult(sqlmock.NewResult(0, 0))
+	mock.ExpectCommit()
+
+	var enqueueCalls int32
+	logic := newCloseOrderLogicForTest(db)
+	logic.enqueueActivate = func(_ context.Context, _ []byte) (string, error) {
+		atomic.AddInt32(&enqueueCalls, 1)
+		return "should-not-fire", nil
+	}
+
+	err := logic.recoverPaidOrder(&modelorder.Order{
+		OrderNo: orderNo,
+		Method:  Epay,
+		Status:  1,
+	})
+	if err != nil {
+		t.Fatalf("recoverPaidOrder error: %v", err)
+	}
+	if got := atomic.LoadInt32(&enqueueCalls); got != 0 {
+		t.Fatalf("expected no enqueue when 0 rows updated, got %d", got)
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatalf("unmet sql expectations: %v", err)
+	}
+}
+
+// TestRecoverPaidOrder_EnqueueFailureIsNotFatal covers the case where the DB
+// move succeeded but the activation enqueue failed (Redis blip, etc). The
+// order is already at status=2, so the stuck-order sweeper will pick it up —
+// recoverPaidOrder must not return an error or revert the status.
+func TestRecoverPaidOrder_EnqueueFailureIsNotFatal(t *testing.T) {
+	db, mock, cleanup := newCloseOrderTestDB(t)
+	defer cleanup()
+
+	const orderNo = "ORD-ENQ-FAIL"
+
+	mock.ExpectBegin()
+	mock.ExpectExec("UPDATE `order`").
+		WithArgs(2, sqlmock.AnyArg(), orderNo, 1).
+		WillReturnResult(sqlmock.NewResult(0, 1))
+	mock.ExpectCommit()
+
+	logic := newCloseOrderLogicForTest(db)
+	logic.enqueueActivate = func(_ context.Context, _ []byte) (string, error) {
+		return "", fmt.Errorf("simulated redis outage")
+	}
+
+	if err := logic.recoverPaidOrder(&modelorder.Order{OrderNo: orderNo, Method: Epay}); err != nil {
+		t.Fatalf("recoverPaidOrder must swallow enqueue errors, got: %v", err)
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatalf("unmet sql expectations: %v", err)
+	}
+}
+
+// TestQueryGatewayPaymentStatus_NonGatewayMethods checks the "fall-through"
+// branches: methods that don't talk to an external gateway (Balance, empty
+// string, anything unrecognised) must report Unpaid so the legacy close path
+// is preserved. This is the regression hook for the issue's acceptance
+// criterion #5 ("user-initiated cancellation can still close normally").
+func TestQueryGatewayPaymentStatus_NonGatewayMethods(t *testing.T) {
+	logic := newCloseOrderLogicForTest(nil) // no DB needed for these branches
+
+	cases := []struct {
+		method string
+		want   GatewayPaymentStatus
+	}{
+		{Balance, GatewayStatusUnpaid},
+		{"", GatewayStatusUnpaid},
+		{"future-method-we-dont-know", GatewayStatusUnpaid},
+	}
+	for _, tc := range cases {
+		got := logic.queryGatewayPaymentStatus(&modelorder.Order{Method: tc.method})
+		if got != tc.want {
+			t.Fatalf("method=%q: got %v want %v", tc.method, got, tc.want)
+		}
+	}
+}
+
+// TestQueryGatewayPaymentStatus_AlipayNoTradeNoIsUnpaid: Alipay F2F creates
+// the trade lazily — if we never recorded a trade_no, the user never scanned
+// the QR code. We must report Unpaid (not Unknown) so the close proceeds.
+// Without this short-circuit, every legitimately abandoned QR-code order
+// would be "kept open" forever by the inconclusive-query branch.
+func TestQueryGatewayPaymentStatus_AlipayNoTradeNoIsUnpaid(t *testing.T) {
+	logic := newCloseOrderLogicForTest(nil)
+	got := logic.queryGatewayPaymentStatus(&modelorder.Order{Method: AlipayF2f, TradeNo: ""})
+	if got != GatewayStatusUnpaid {
+		t.Fatalf("Alipay F2F with empty trade_no should be Unpaid, got %v", got)
+	}
+}
+
+// TestQueryGatewayPaymentStatus_StripeNoTradeNoIsUnpaid: same reasoning as
+// the Alipay case — Stripe's PaymentIntent ID lives in trade_no; if it's
+// missing the intent was never persisted.
+func TestQueryGatewayPaymentStatus_StripeNoTradeNoIsUnpaid(t *testing.T) {
+	logic := newCloseOrderLogicForTest(nil)
+	for _, method := range []string{StripeAlipay, StripeWeChatPay} {
+		got := logic.queryGatewayPaymentStatus(&modelorder.Order{Method: method, TradeNo: ""})
+		if got != GatewayStatusUnpaid {
+			t.Fatalf("%s with empty trade_no should be Unpaid, got %v", method, got)
+		}
+	}
+}
+
+// TestCloseOrderGatewayQueryDispatch_DefaultProductionWiring asserts that the
+// default gatewayQuery is wired to the real implementation (not nil) by
+// NewCloseOrderLogic. Without this guard a future refactor could silently
+// drop the wiring and re-create HIF-135.
+func TestCloseOrderGatewayQueryDispatch_DefaultProductionWiring(t *testing.T) {
+	svcCtx := &svc.ServiceContext{}
+	l := NewCloseOrderLogic(context.Background(), svcCtx)
+	if l.gatewayQuery == nil {
+		t.Fatal("NewCloseOrderLogic must wire gatewayQuery; got nil")
+	}
+	if l.enqueueActivate == nil {
+		t.Fatal("NewCloseOrderLogic must wire enqueueActivate; got nil")
+	}
+}

pkg/payment/epay/epay.go

@@ -2,6 +2,7 @@ package epay
 
 import (
 	"encoding/json"
+	"fmt"
 	"io"
 	"net/http"
 	"net/url"
@@ -88,28 +89,42 @@ func (c *Client) VerifySign(params map[string]string) bool {
 	return c.createSign(params) == params["sign"]
 }
 
-func (c *Client) QueryOrderStatus(orderNo string) bool {
+// QueryOrderStatus returns (paid, err). A non-nil err means the query itself
+// failed (network / 5xx / decode error) and the result is inconclusive — callers
+// MUST NOT treat that as "unpaid". A nil err with paid=false means the gateway
+// answered and reported the order is not paid.
+func (c *Client) QueryOrderStatus(orderNo string) (bool, error) {
 	client := http.Client{
 		Timeout: 5 * time.Second,
 	}
 	resp, err := client.Get(c.Url + "/api.php" + "?act=order" + "&pid=" + c.Pid + "&key=" + c.Key + "&out_trade_no=" + orderNo)
 	if err != nil {
 		logger.Error("[Epay] QueryOrderStatus error", logger.Field("orderNo", orderNo), logger.Field("error", err.Error()))
-		return false
+		return false, fmt.Errorf("epay query request failed: %w", err)
 	}
 	defer resp.Body.Close()
+	if resp.StatusCode >= 500 {
+		err := fmt.Errorf("epay query upstream status %d", resp.StatusCode)
+		logger.Error("[Epay] QueryOrderStatus upstream 5xx", logger.Field("orderNo", orderNo), logger.Field("status", resp.StatusCode))
+		return false, err
+	}
 	value, err := io.ReadAll(resp.Body)
 	if err != nil {
 		logger.Error("[Epay] QueryOrderStatus error", logger.Field("orderNo", orderNo), logger.Field("error", err.Error()))
-		return false
+		return false, fmt.Errorf("epay query read body failed: %w", err)
 	}
 	var response queryOrderStatusResponse
-	err = json.Unmarshal(value, &response)
+	if err = json.Unmarshal(value, &response); err != nil {
-	if err != nil {
 		logger.Error("[Epay] QueryOrderStatus error", logger.Field("orderNo", orderNo), logger.Field("error", err.Error()))
-		return false
+		return false, fmt.Errorf("epay query decode failed: %w", err)
 	}
-	return response.Status == 1
+	// EPay API contract: code != 1 means the API itself errored (e.g. wrong key).
+	// Treat it as a query failure, not a definitive "unpaid", to avoid wrongly
+	// closing a paid order under a transient upstream config error.
+	if response.Code != 1 {
+		return false, fmt.Errorf("epay query api code=%d msg=%q", response.Code, response.Msg)
+	}
+	return response.Status == 1, nil
 }
 
 // StructToMap converts a struct to map[string]string