From fde4a45c4a05c950aebb538865219a89d3c22a9b Mon Sep 17 00:00:00 2001
From: yyg-max <175597134+yyg-max@users.noreply.github.com>
Date: Wed, 15 Jul 2026 14:27:35 +0800
Subject: [PATCH 1/2] fix(payment): allow users to resume pending payments

---
 .../common/receive/ReceiveContent.tsx         |  92 ++++++++++++++-
 frontend/lib/services/payment/index.ts        |   2 +
 .../lib/services/payment/payment.service.ts   |  23 ++++
 frontend/lib/services/payment/types.ts        |   9 ++
 internal/apps/payment/err.go                  |   2 +-
 internal/apps/payment/router.go               |  38 ++++++
 internal/apps/payment/service.go              | 109 ++++++++++++++----
 internal/router/router.go                     |   1 +
 8 files changed, 249 insertions(+), 27 deletions(-)

diff --git a/frontend/components/common/receive/ReceiveContent.tsx b/frontend/components/common/receive/ReceiveContent.tsx
index 4d7edc94..389194eb 100644
--- a/frontend/components/common/receive/ReceiveContent.tsx
+++ b/frontend/components/common/receive/ReceiveContent.tsx
@@ -17,6 +17,7 @@ import {ReceiveVerify, ReceiveVerifyRef} from '@/components/common/receive/Recei
 import services from '@/lib/services';
 import {BasicUserInfo} from '@/lib/services/core';
 import {GetProjectResponseData} from '@/lib/services/project';
+import {PendingPaymentData} from '@/lib/services/payment';
 import {formatDate, formatDateTimeWithSeconds, copyToClipboard} from '@/lib/utils';
 import {motion} from 'motion/react';
 import {Separator} from '@/components/ui/separator';
@@ -46,7 +47,11 @@ interface ReceiveButtonProps {
   user: BasicUserInfo | null;
   currentTime: Date;
   isVerifying: boolean;
+  isCheckingPendingPayment: boolean;
+  isContinuingPayment: boolean;
+  pendingPayment: PendingPaymentData | null;
   onReceive: () => void;
+  onContinuePayment: () => void;
 }
 
 /**
@@ -57,11 +62,17 @@ const ReceiveButton = ({
   user,
   currentTime,
   isVerifying,
+  isCheckingPendingPayment,
+  isContinuingPayment,
+  pendingPayment,
   onReceive,
+  onContinuePayment,
 }: ReceiveButtonProps) => {
   const now = currentTime;
   const startTime = new Date(project.start_time);
   const endTime = new Date(project.end_time);
+  const priceNum = Number(project.price || '0');
+  const isPaid = priceNum > 0;
 
   if (now < startTime) {
     const timeRemaining = getTimeRemainingText(startTime, now);
@@ -82,6 +93,28 @@ const ReceiveButton = ({
     );
   }
 
+  if (isPaid && project.available_items_count <= 0 && isCheckingPendingPayment) {
+    return (
+      <Button disabled className="h-9 w-full cursor-not-allowed rounded-full bg-muted text-muted-foreground shadow-none">
+        <Loader2 className="w-4 h-4 mr-2 animate-spin" />
+        正在检查待支付订单
+      </Button>
+    );
+  }
+
+  if (pendingPayment?.has_pending && pendingPayment.pay_url) {
+    return (
+      <Button onClick={onContinuePayment} disabled={isContinuingPayment} className="h-9 w-full rounded-full shadow-none">
+        {isContinuingPayment ?
+          <Loader2 className="w-4 h-4 mr-2 animate-spin" /> :
+          <Coins className="w-4 h-4 mr-2" />}
+        {isContinuingPayment ?
+          '正在打开支付页面' :
+          `继续支付 ${pendingPayment.amount || priceNum} ${CURRENCY_LABEL}`}
+      </Button>
+    );
+  }
+
   if (project.available_items_count <= 0) {
     return (
       <Button disabled className="h-9 w-full cursor-not-allowed rounded-full bg-muted text-muted-foreground shadow-none">
@@ -109,9 +142,6 @@ const ReceiveButton = ({
     );
   }
 
-  const priceNum = Number(project.price || '0');
-  const isPaid = priceNum > 0;
-
   return (
     <Button
       onClick={onReceive}
@@ -268,6 +298,9 @@ export function ReceiveContent({data}: ReceiveContentProps) {
   const [currentProject, setCurrentProject] = useState(project);
   const [isVerifying, setIsVerifying] = useState(false);
   const [isAwaitingPayment, setIsAwaitingPayment] = useState(Boolean(incomingTradeNo) && !project.is_received);
+  const [pendingPayment, setPendingPayment] = useState<PendingPaymentData | null>(null);
+  const [isCheckingPendingPayment, setIsCheckingPendingPayment] = useState(false);
+  const [isContinuingPayment, setIsContinuingPayment] = useState(false);
   const verifyRef = useRef<ReceiveVerifyRef>(null);
 
   /**
@@ -302,6 +335,34 @@ export function ReceiveContent({data}: ReceiveContentProps) {
     verifyRef.current?.execute();
   };
 
+  /**
+   * 重新确认待支付订单仍有效，再打开 Credit 收银台。
+   */
+  const handleContinuePayment = async () => {
+    if (!projectId || isContinuingPayment) return;
+
+    setIsContinuingPayment(true);
+    try {
+      const result = await services.payment.getPendingPaymentSafe(projectId);
+      if (!result.success) {
+        toast.error(result.error || '获取待支付订单失败');
+        return;
+      }
+
+      const payment = result.data?.has_pending ? result.data : null;
+      setPendingPayment(payment);
+      if (!payment?.pay_url) {
+        toast.info('待支付订单已过期，请稍后刷新页面重试');
+        return;
+      }
+
+      toast.info('正在跳转支付页面...');
+      window.location.href = payment.pay_url;
+    } finally {
+      setIsContinuingPayment(false);
+    }
+  };
+
   /**
    * 验证成功后处理
    */
@@ -362,6 +423,27 @@ export function ReceiveContent({data}: ReceiveContentProps) {
     return () => clearInterval(timer);
   }, []);
 
+  useEffect(() => {
+    const isPaidProject = Number(project.price || '0') > 0;
+    if (!projectId || !isPaidProject || hasReceived) {
+      setPendingPayment(null);
+      setIsCheckingPendingPayment(false);
+      return;
+    }
+
+    let cancelled = false;
+    setIsCheckingPendingPayment(true);
+    services.payment.getPendingPaymentSafe(projectId).then((result) => {
+      if (cancelled) return;
+      setPendingPayment(result.success && result.data?.has_pending ? result.data : null);
+      setIsCheckingPendingPayment(false);
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [project.price, projectId, hasReceived]);
+
   // 从支付系统回跳后,轮询项目详情直到发放到账或超时
   useEffect(() => {
     if (!isAwaitingPayment || !projectId) return;
@@ -650,7 +732,11 @@ export function ReceiveContent({data}: ReceiveContentProps) {
                   user={user}
                   currentTime={currentTime}
                   isVerifying={isVerifying}
+                  isCheckingPendingPayment={isCheckingPendingPayment}
+                  isContinuingPayment={isContinuingPayment}
+                  pendingPayment={pendingPayment}
                   onReceive={handleReceive}
+                  onContinuePayment={handleContinuePayment}
                 />
               </div>
 
diff --git a/frontend/lib/services/payment/index.ts b/frontend/lib/services/payment/index.ts
index d4b6cd2f..c06a6672 100644
--- a/frontend/lib/services/payment/index.ts
+++ b/frontend/lib/services/payment/index.ts
@@ -4,4 +4,6 @@ export type {
   GetPaymentConfigResponse,
   UpsertPaymentConfigRequest,
   UpsertPaymentConfigResponse,
+  PendingPaymentData,
+  GetPendingPaymentResponse,
 } from './types';
diff --git a/frontend/lib/services/payment/payment.service.ts b/frontend/lib/services/payment/payment.service.ts
index 52548c06..ff72ddc8 100644
--- a/frontend/lib/services/payment/payment.service.ts
+++ b/frontend/lib/services/payment/payment.service.ts
@@ -4,6 +4,8 @@ import {
   PaymentConfigData,
   UpsertPaymentConfigRequest,
   UpsertPaymentConfigResponse,
+  GetPendingPaymentResponse,
+  PendingPaymentData,
 } from './types';
 
 /**
@@ -12,6 +14,27 @@ import {
 export class PaymentService {
   private static readonly base = '/api/v1/users/payment-config';
 
+  static async getPendingPayment(projectId: string): Promise<PendingPaymentData> {
+    const response = await apiClient.get<GetPendingPaymentResponse>(`/api/v1/projects/${projectId}/pending-payment`);
+    if (response.data.error_msg) {
+      throw new Error(response.data.error_msg);
+    }
+    return response.data.data;
+  }
+
+  static async getPendingPaymentSafe(projectId: string): Promise<{
+    success: boolean;
+    data?: PendingPaymentData;
+    error?: string;
+  }> {
+    try {
+      const data = await this.getPendingPayment(projectId);
+      return {success: true, data};
+    } catch (err) {
+      return {success: false, error: err instanceof Error ? err.message : '获取待支付订单失败'};
+    }
+  }
+
   static async getConfig(): Promise<PaymentConfigData> {
     const response = await apiClient.get<GetPaymentConfigResponse>(this.base);
     if (response.data.error_msg) {
diff --git a/frontend/lib/services/payment/types.ts b/frontend/lib/services/payment/types.ts
index 8ca3203d..1b84b1b5 100644
--- a/frontend/lib/services/payment/types.ts
+++ b/frontend/lib/services/payment/types.ts
@@ -29,3 +29,12 @@ export interface UpsertPaymentConfigRequest {
 }
 
 export type UpsertPaymentConfigResponse = BackendResponse<null>;
+
+/** 当前用户在指定项目下的待支付订单 */
+export interface PendingPaymentData {
+  has_pending: boolean;
+  pay_url?: string;
+  amount?: string;
+}
+
+export type GetPendingPaymentResponse = BackendResponse<PendingPaymentData>;
diff --git a/internal/apps/payment/err.go b/internal/apps/payment/err.go
index 1c871a50..22009654 100644
--- a/internal/apps/payment/err.go
+++ b/internal/apps/payment/err.go
@@ -29,7 +29,7 @@ const (
 	ErrInvalidAmount            = "金额必须大于 0 且最多 2 位小数"
 	ErrPriceRequiresOneForEach  = "仅一码一用分发支持设置金额"
 	ErrCreatorNotConfigured     = "项目创建者尚未配置支付凭据,无法发起支付"
-	ErrPendingOrderExists       = "当前项目存在进行中或已完成订单,不可重复创建"
+	ErrPendingOrderExists       = "当前项目订单已支付或正在处理,请稍后刷新"
 	ErrPaymentConfigNotFound    = "尚未配置支付凭据"
 	ErrEncryptionKeyMissing     = "服务端未配置支付密钥加密密钥"
 	ErrInvalidClientCredentials = "clientID 与 clientSecret 不能为空"
diff --git a/internal/apps/payment/router.go b/internal/apps/payment/router.go
index 662a0faf..73e824eb 100644
--- a/internal/apps/payment/router.go
+++ b/internal/apps/payment/router.go
@@ -120,6 +120,44 @@ type ReceiveResponse struct {
 	ExpireAt       string `json:"expire_at,omitempty"`
 }
 
+// PendingPaymentResponseData 当前用户在项目下的待支付订单信息。
+type PendingPaymentResponseData struct {
+	HasPending bool   `json:"has_pending"`
+	PayURL     string `json:"pay_url,omitempty"`
+	Amount     string `json:"amount,omitempty"`
+}
+
+// GetPendingPayment GET 只返回当前用户已有且未过期的待支付订单，不重新占用库存或刷新有效期。
+func GetPendingPayment(c *gin.Context) {
+	ctx := c.Request.Context()
+	currentUser, _ := oauth.GetUserFromContext(c)
+	p := &project.Project{}
+	if err := p.Exact(db.DB(ctx), c.Param("id"), true); err != nil {
+		c.JSON(http.StatusNotFound, project.ProjectResponse{ErrorMsg: err.Error()})
+		return
+	}
+
+	init, err := GetPendingPaymentInitiation(ctx, p, currentUser)
+	if err != nil {
+		if err.Error() == ErrPendingOrderExists {
+			c.JSON(http.StatusBadRequest, Response{ErrorMsg: err.Error()})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, Response{ErrorMsg: err.Error()})
+		return
+	}
+	if init == nil {
+		c.JSON(http.StatusOK, Response{Data: PendingPaymentResponseData{HasPending: false}})
+		return
+	}
+
+	c.JSON(http.StatusOK, Response{Data: PendingPaymentResponseData{
+		HasPending: true,
+		PayURL:     init.PayURL,
+		Amount:     init.Amount,
+	}})
+}
+
 // DispatchReceive POST /api/v1/projects/:id/receive
 // 运行在 project.ReceiveProjectMiddleware() 之后,已通过资格校验并在 context 注入 project。
 // 付费项目:返回 {require_payment:true, pay_url, ...};前端直接跳转 pay_url。
diff --git a/internal/apps/payment/service.go b/internal/apps/payment/service.go
index 412b21b3..6088772f 100644
--- a/internal/apps/payment/service.go
+++ b/internal/apps/payment/service.go
@@ -134,9 +134,71 @@ type PaymentInitiation struct {
 	ExpireAt   time.Time `json:"expire_at"`
 }
 
+// buildPaymentInitiation 使用本地订单信息构造易支付跳转地址。
+func buildPaymentInitiation(p *project.Project, cfg *UserPaymentConfig, secret string, order *PaymentOrder) PaymentInitiation {
+	name := truncateRuneLen("CDK-"+p.Name, 60)
+	return PaymentInitiation{
+		OutTradeNo: order.OutTradeNo,
+		PayURL: submitURL(
+			cfg.ClientID,
+			secret,
+			name,
+			moneyString(order.Amount),
+			order.OutTradeNo,
+			callbackNotifyURL(),
+			callbackReturnURL(p.ID),
+		),
+		Amount:   moneyString(order.Amount),
+		ExpireAt: order.ExpireAt,
+	}
+}
+
+// GetPendingPaymentInitiation 查询当前用户在指定项目下仍有效的待支付订单。
+func GetPendingPaymentInitiation(ctx context.Context, p *project.Project, payer *oauth.User) (*PaymentInitiation, error) {
+	if !config.Config.Payment.Enabled || !p.IsPaid() {
+		return nil, nil
+	}
+
+	var order PaymentOrder
+	err := db.DB(ctx).
+		Where(
+			"project_id = ? AND payer_id = ? AND status = ? AND expire_at > ?",
+			p.ID,
+			payer.ID,
+			OrderStatusPending,
+			time.Now(),
+		).
+		Order("id DESC").
+		First(&order).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	cfg, err := GetUserPaymentConfig(ctx, p.CreatorID)
+	if err != nil {
+		return nil, err
+	}
+	if cfg == nil {
+		return nil, errors.New(ErrCreatorNotConfigured)
+	}
+	if order.PayeeClientID != cfg.ClientID {
+		return nil, errors.New(ErrPendingOrderExists)
+	}
+	secret, err := decryptUserClientSecret(cfg)
+	if err != nil {
+		return nil, err
+	}
+
+	init := buildPaymentInitiation(p, cfg, secret, &order)
+	return &init, nil
+}
+
 // InitiatePayment 为付费项目的一次领取行为创建支付订单,并返回前端可直接跳转的支付 URL。
 // 调用方已通过 ReceiveProjectMiddleware 的前置校验。
-// 流程:载入商户凭据 → Redis LPop 预占 item → 持久化订单 PENDING → 构造 submit URL 返回。
+// 流程:载入商户凭据 → 复用已有 PENDING 订单，或 Redis LPop 预占 item 后创建新订单 → 构造 submit URL 返回。
 // 若创建订单失败或拼接失败,需立即把 itemID RPush 回 Redis 以恢复库存。
 func InitiatePayment(ctx context.Context, p *project.Project, payer *oauth.User, clientIP string) (*PaymentInitiation, error) {
 	if !config.Config.Payment.Enabled {
@@ -179,8 +241,9 @@ func InitiatePayment(ctx context.Context, p *project.Project, payer *oauth.User,
 			return err
 		}
 
-		var existedCount int64
-		if err := tx.Model(&PaymentOrder{}).
+		// 存在 COMPLETED/PAID 时阻止重复创建，否则复用最新的 PENDING。
+		var activeOrder PaymentOrder
+		queryErr := tx.Clauses(clause.Locking{Strength: "UPDATE"}).
 			Where(
 				"project_id = ? AND payer_id = ? AND status IN ?",
 				p.ID,
@@ -191,11 +254,26 @@ func InitiatePayment(ctx context.Context, p *project.Project, payer *oauth.User,
 					OrderStatusCompleted,
 				},
 			).
-			Count(&existedCount).Error; err != nil {
-			return err
+			Order("status DESC").
+			Order("id DESC").
+			First(&activeOrder).Error
+		if queryErr == nil {
+			switch activeOrder.Status {
+			case OrderStatusPaid, OrderStatusCompleted:
+				return errors.New(ErrPendingOrderExists)
+			case OrderStatusPending:
+				// 原订单属于旧的商户 ClientID 时无法安全重建签名，等待其按原流程过期释放。
+				if activeOrder.PayeeClientID != cfg.ClientID {
+					return errors.New(ErrPendingOrderExists)
+				}
+
+				init = buildPaymentInitiation(p, cfg, secret, &activeOrder)
+				logger.InfoF(ctx, "Reusing pending payment order %s for project %s and payer %d", activeOrder.OutTradeNo, p.ID, payer.ID)
+			}
+			return nil
 		}
-		if existedCount > 0 {
-			return errors.New(ErrPendingOrderExists)
+		if !errors.Is(queryErr, gorm.ErrRecordNotFound) {
+			return queryErr
 		}
 
 		// 预占 item(Redis LPOP 原子)
@@ -223,22 +301,7 @@ func InitiatePayment(ctx context.Context, p *project.Project, payer *oauth.User,
 			return err
 		}
 
-		// 构造支付跳转 URL(名称最长 64)
-		name := truncateRuneLen("CDK-"+p.Name, 60)
-		init = PaymentInitiation{
-			OutTradeNo: outTradeNo,
-			PayURL: submitURL(
-				cfg.ClientID,
-				secret,
-				name,
-				moneyString(p.Price),
-				outTradeNo,
-				callbackNotifyURL(),
-				callbackReturnURL(p.ID),
-			),
-			Amount:   moneyString(p.Price),
-			ExpireAt: expireAt,
-		}
+		init = buildPaymentInitiation(p, cfg, secret, &order)
 		return nil
 	})
 	if err != nil {
diff --git a/internal/router/router.go b/internal/router/router.go
index c2797488..2c896a90 100644
--- a/internal/router/router.go
+++ b/internal/router/router.go
@@ -116,6 +116,7 @@ func Serve() {
 				projectRouter.PUT("/:id", project.ProjectCreatorPermMiddleware(), project.UpdateProject)
 				projectRouter.DELETE("/:id", project.ProjectCreatorPermMiddleware(), project.DeleteProject)
 				projectRouter.GET("/:id/receivers", project.ProjectCreatorPermMiddleware(), project.ListProjectReceivers)
+				projectRouter.GET("/:id/pending-payment", payment.GetPendingPayment)
 				projectRouter.POST("/:id/receive", project.ReceiveProjectMiddleware(), payment.DispatchReceive)
 				projectRouter.POST("/:id/report", project.ReportProject)
 				projectRouter.GET("/received/chart", project.ListReceiveHistoryChart)

From b196ef6da6ffa0e7eff26888be88a2ee8ef93959 Mon Sep 17 00:00:00 2001
From: yyg-max <175597134+yyg-max@users.noreply.github.com>
Date: Wed, 15 Jul 2026 14:41:29 +0800
Subject: [PATCH 2/2] docs(payment): document pending payment endpoint

---
 docs/docs.go                    | 82 +++++++++++++++++++++++++++++++++
 docs/swagger.json               | 82 +++++++++++++++++++++++++++++++++
 docs/swagger.yaml               | 51 ++++++++++++++++++++
 internal/apps/payment/router.go | 12 ++++-
 4 files changed, 226 insertions(+), 1 deletion(-)

diff --git a/docs/docs.go b/docs/docs.go
index 7a46e285..91af347b 100644
--- a/docs/docs.go
+++ b/docs/docs.go
@@ -589,6 +589,65 @@ const docTemplate = `{
                 }
             }
         },
+        "/api/v1/projects/{id}/pending-payment": {
+            "get": {
+                "description": "只返回指定项目下当前用户已有且未过期的待支付订单，不重新占用库存或刷新有效期",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "payment"
+                ],
+                "summary": "获取当前用户的待支付订单",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "项目ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/payment.Response"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/payment.PendingPaymentResponseData"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/payment.Response"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/project.ProjectResponse"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/payment.Response"
+                        }
+                    }
+                }
+            }
+        },
         "/api/v1/projects/{id}/receivers": {
             "get": {
                 "consumes": [
@@ -977,6 +1036,29 @@ const docTemplate = `{
                 }
             }
         },
+        "payment.PendingPaymentResponseData": {
+            "type": "object",
+            "properties": {
+                "amount": {
+                    "type": "string"
+                },
+                "has_pending": {
+                    "type": "boolean"
+                },
+                "pay_url": {
+                    "type": "string"
+                }
+            }
+        },
+        "payment.Response": {
+            "type": "object",
+            "properties": {
+                "data": {},
+                "error_msg": {
+                    "type": "string"
+                }
+            }
+        },
         "project.CreateProjectRequestBody": {
             "type": "object",
             "required": [
diff --git a/docs/swagger.json b/docs/swagger.json
index 04f9deae..8ff4ed27 100644
--- a/docs/swagger.json
+++ b/docs/swagger.json
@@ -580,6 +580,65 @@
                 }
             }
         },
+        "/api/v1/projects/{id}/pending-payment": {
+            "get": {
+                "description": "只返回指定项目下当前用户已有且未过期的待支付订单，不重新占用库存或刷新有效期",
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "payment"
+                ],
+                "summary": "获取当前用户的待支付订单",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "项目ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "allOf": [
+                                {
+                                    "$ref": "#/definitions/payment.Response"
+                                },
+                                {
+                                    "type": "object",
+                                    "properties": {
+                                        "data": {
+                                            "$ref": "#/definitions/payment.PendingPaymentResponseData"
+                                        }
+                                    }
+                                }
+                            ]
+                        }
+                    },
+                    "400": {
+                        "description": "Bad Request",
+                        "schema": {
+                            "$ref": "#/definitions/payment.Response"
+                        }
+                    },
+                    "404": {
+                        "description": "Not Found",
+                        "schema": {
+                            "$ref": "#/definitions/project.ProjectResponse"
+                        }
+                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "schema": {
+                            "$ref": "#/definitions/payment.Response"
+                        }
+                    }
+                }
+            }
+        },
         "/api/v1/projects/{id}/receivers": {
             "get": {
                 "consumes": [
@@ -968,6 +1027,29 @@
                 }
             }
         },
+        "payment.PendingPaymentResponseData": {
+            "type": "object",
+            "properties": {
+                "amount": {
+                    "type": "string"
+                },
+                "has_pending": {
+                    "type": "boolean"
+                },
+                "pay_url": {
+                    "type": "string"
+                }
+            }
+        },
+        "payment.Response": {
+            "type": "object",
+            "properties": {
+                "data": {},
+                "error_msg": {
+                    "type": "string"
+                }
+            }
+        },
         "project.CreateProjectRequestBody": {
             "type": "object",
             "required": [
diff --git a/docs/swagger.yaml b/docs/swagger.yaml
index 8461a3c5..e31a2652 100644
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -170,6 +170,21 @@ definitions:
       error_msg:
         type: string
     type: object
+  payment.PendingPaymentResponseData:
+    properties:
+      amount:
+        type: string
+      has_pending:
+        type: boolean
+      pay_url:
+        type: string
+    type: object
+  payment.Response:
+    properties:
+      data: {}
+      error_msg:
+        type: string
+    type: object
   project.CreateProjectRequestBody:
     properties:
       allow_same_ip:
@@ -772,6 +787,42 @@ paths:
             $ref: '#/definitions/project.ProjectResponse'
       tags:
       - project
+  /api/v1/projects/{id}/pending-payment:
+    get:
+      description: 只返回指定项目下当前用户已有且未过期的待支付订单，不重新占用库存或刷新有效期
+      parameters:
+      - description: 项目ID
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            allOf:
+            - $ref: '#/definitions/payment.Response'
+            - properties:
+                data:
+                  $ref: '#/definitions/payment.PendingPaymentResponseData'
+              type: object
+        "400":
+          description: Bad Request
+          schema:
+            $ref: '#/definitions/payment.Response'
+        "404":
+          description: Not Found
+          schema:
+            $ref: '#/definitions/project.ProjectResponse'
+        "500":
+          description: Internal Server Error
+          schema:
+            $ref: '#/definitions/payment.Response'
+      summary: 获取当前用户的待支付订单
+      tags:
+      - payment
   /api/v1/projects/{id}/receivers:
     get:
       consumes:
diff --git a/internal/apps/payment/router.go b/internal/apps/payment/router.go
index 73e824eb..26793561 100644
--- a/internal/apps/payment/router.go
+++ b/internal/apps/payment/router.go
@@ -127,7 +127,17 @@ type PendingPaymentResponseData struct {
 	Amount     string `json:"amount,omitempty"`
 }
 
-// GetPendingPayment GET 只返回当前用户已有且未过期的待支付订单，不重新占用库存或刷新有效期。
+// GetPendingPayment
+// @Tags payment
+// @Summary 获取当前用户的待支付订单
+// @Description 只返回指定项目下当前用户已有且未过期的待支付订单，不重新占用库存或刷新有效期
+// @Produce json
+// @Param id path string true "项目ID"
+// @Success 200 {object} Response{data=PendingPaymentResponseData}
+// @Failure 400 {object} Response
+// @Failure 404 {object} project.ProjectResponse
+// @Failure 500 {object} Response
+// @Router /api/v1/projects/{id}/pending-payment [get]
 func GetPendingPayment(c *gin.Context) {
 	ctx := c.Request.Context()
 	currentUser, _ := oauth.GetUserFromContext(c)