优化小程序登录流程，增加用户协议和隐私政策的勾选机制，确保用户主动同意后方可登录，符合审核要求。同时，增强错误处理逻辑，提升用户体验和系统稳定性。新增用户协议和隐私政策页面，更新相关样式以改善界面交互。

2026-02-10 15:03:31 +08:00
parent 3ca7d38318
commit 90a77da2da
35 changed files with 697 additions and 108 deletions
--- a/soul-api/internal/auth/adminjwt.go
+++ b/soul-api/internal/auth/adminjwt.go
@@ -0,0 +1,68 @@
+// Package auth 管理端 JWT：签发与校验，使用 Authorization: Bearer <token>
+package auth
+
+import (
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+const adminJWTExpire = 7 * 24 * time.Hour // 7 天
+
+// AdminClaims 管理端 JWT 载荷
+type AdminClaims struct {
+	jwt.RegisteredClaims
+	Username string `json:"username"`
+	Role     string `json:"role"`
+}
+
+// IssueAdminJWT 签发管理端 JWT，使用 ADMIN_SESSION_SECRET 签名
+func IssueAdminJWT(secret, username string) (string, error) {
+	now := time.Now()
+	claims := AdminClaims{
+		RegisteredClaims: jwt.RegisteredClaims{
+			ExpiresAt: jwt.NewNumericDate(now.Add(adminJWTExpire)),
+			IssuedAt:  jwt.NewNumericDate(now),
+			Subject:   "admin",
+		},
+		Username: username,
+		Role:     "admin",
+	}
+	tok := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+	return tok.SignedString([]byte(secret))
+}
+
+// ParseAdminJWT 校验并解析 JWT，返回 claims；无效或过期返回 nil, false
+func ParseAdminJWT(tokenString, secret string) (*AdminClaims, bool) {
+	if tokenString == "" || secret == "" {
+		return nil, false
+	}
+	tok, err := jwt.ParseWithClaims(tokenString, &AdminClaims{}, func(t *jwt.Token) (interface{}, error) {
+		return []byte(secret), nil
+	}, jwt.WithValidMethods([]string{"HS256"}))
+	if err != nil || !tok.Valid {
+		return nil, false
+	}
+	claims, ok := tok.Claims.(*AdminClaims)
+	if !ok || claims.Username == "" {
+		return nil, false
+	}
+	return claims, true
+}
+
+// GetAdminJWTFromRequest 从请求中读取 JWT：优先 Authorization: Bearer <token>，其次 Cookie admin_session（兼容旧端）
+func GetAdminJWTFromRequest(r *http.Request) string {
+	// 1. Authorization: Bearer <token>
+	ah := r.Header.Get("Authorization")
+	if strings.HasPrefix(ah, "Bearer ") {
+		return strings.TrimSpace(ah[7:])
+	}
+	// 2. Cookie（兼容：若值为 JWT 格式则可用）
+	c, err := r.Cookie(adminCookieName)
+	if err != nil || c == nil {
+		return ""
+	}
+	return strings.TrimSpace(c.Value)
+}
--- a/soul-api/internal/auth/adminsession.go
+++ b/soul-api/internal/auth/adminsession.go
@@ -53,6 +53,14 @@ func AdminCookieName() string { return adminCookieName }
 // MaxAgeSec 返回 session 有效秒数
 func MaxAgeSec() int { return maxAgeSec }

+// SetCookieHeaderValue 返回完整的 Set-Cookie 头内容（含 SameSite=None; Secure，供跨站时携带 Cookie）
+func SetCookieHeaderValue(token string, maxAge int) string {
+	if maxAge <= 0 {
+		return adminCookieName + "=; Path=/; Max-Age=0; HttpOnly; SameSite=None; Secure"
+	}
+	return adminCookieName + "=" + token + "; Path=/; Max-Age=" + strconv.Itoa(maxAge) + "; HttpOnly; SameSite=None; Secure"
+}
+
 // GetAdminTokenFromRequest 从请求 Cookie 中读取 admin_session
 func GetAdminTokenFromRequest(r *http.Request) string {
 	c, err := r.Cookie(adminCookieName)
--- a/soul-api/internal/handler/admin.go
+++ b/soul-api/internal/handler/admin.go
@@ -9,19 +9,18 @@ import (
 	"github.com/gin-gonic/gin"
 )

-// AdminCheck GET /api/admin 鉴权检查（与 next-project 一致：校验 admin_session cookie，已登录返回 success 或概览占位）
+// AdminCheck GET /api/admin 鉴权检查（JWT：Authorization Bearer 或 Cookie），已登录返回 success 或概览占位
 func AdminCheck(c *gin.Context) {
 	cfg := config.Get()
 	if cfg == nil {
 		c.JSON(http.StatusOK, gin.H{"success": true})
 		return
 	}
-	token := auth.GetAdminTokenFromRequest(c.Request)
-	if !auth.VerifyAdminToken(token, cfg.AdminSessionSecret) {
+	token := auth.GetAdminJWTFromRequest(c.Request)
+	if _, ok := auth.ParseAdminJWT(token, cfg.AdminSessionSecret); !ok {
 		c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"success": false, "error": "未授权访问，请先登录"})
 		return
 	}
-	// 与 next 一致：返回 success，可选带概览占位供前端扩展
 	c.JSON(http.StatusOK, gin.H{
 		"success": true,
 		"content": gin.H{
@@ -40,7 +39,7 @@ func AdminCheck(c *gin.Context) {
 	})
 }

-// AdminLogin POST /api/admin 登录（与 next-project 一致：校验 ADMIN_USERNAME/PASSWORD，写 admin_session cookie）
+// AdminLogin POST /api/admin 登录（校验 ADMIN_USERNAME/PASSWORD，返回 JWT，前端存 token 并带 Authorization: Bearer）
 func AdminLogin(c *gin.Context) {
 	cfg := config.Get()
 	if cfg == nil {
@@ -61,19 +60,22 @@ func AdminLogin(c *gin.Context) {
 		c.JSON(http.StatusUnauthorized, gin.H{"success": false, "error": "用户名或密码错误"})
 		return
 	}
-	token := auth.CreateAdminToken(cfg.AdminSessionSecret)
-	c.SetCookie(auth.AdminCookieName(), token, auth.MaxAgeSec(), "/", "", false, true)
+	token, err := auth.IssueAdminJWT(cfg.AdminSessionSecret, username)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"success": false, "error": "签发失败"})
+		return
+	}
 	c.JSON(http.StatusOK, gin.H{
 		"success": true,
+		"token":   token,
 		"user": gin.H{
 			"id": "admin", "username": cfg.AdminUsername, "role": "admin", "name": "卡若",
 		},
 	})
 }

-// AdminLogout POST /api/admin/logout 清除 admin_session cookie
+// AdminLogout POST /api/admin/logout 服务端无状态，仅返回成功；前端需清除本地 token
 func AdminLogout(c *gin.Context) {
-	c.SetCookie(auth.AdminCookieName(), "", -1, "/", "", false, true)
 	c.JSON(http.StatusOK, gin.H{"success": true})
 }

--- a/soul-api/internal/handler/admin_withdrawals.go
+++ b/soul-api/internal/handler/admin_withdrawals.go
@@ -149,9 +149,7 @@ func AdminWithdrawalsAction(c *gin.Context) {
 			return
 		}

-		// 调用微信转账接口；未初始化时仅标记为已打款（线下打款）
-		outBatchNo := wechat.GenerateTransferBatchNo()
-		outDetailNo := wechat.GenerateTransferDetailNo()
+		// 调用微信转账接口（FundApp 单笔发起转账，与 商家转账.md 示例一致）
 		remark := "提现"
 		if w.Remark != nil && *w.Remark != "" {
 			remark = *w.Remark
@@ -161,26 +159,21 @@ func AdminWithdrawalsAction(c *gin.Context) {
 			c.JSON(http.StatusOK, gin.H{"success": false, "error": "提现金额异常"})
 			return
 		}
-		// 微信批次备注最多 32 字符，用简短文案避免超长
-		batchRemark := fmt.Sprintf("提现 %.2f 元", w.Amount)
-		if len([]rune(batchRemark)) > 32 {
-			batchRemark = "用户提现"
-		}
-		params := wechat.TransferParams{
-			OutBatchNo:  outBatchNo,
-			OutDetailNo: outDetailNo,
-			OpenID:      openID,
-			Amount:      amountFen,
-			Remark:      remark,
-			BatchName:   "用户提现",
-			BatchRemark: batchRemark,
+		outBillNo := w.ID // 商户单号，回调时 out_bill_no 即此值，用于更新该条提现
+		params := wechat.FundAppTransferParams{
+			OutBillNo:       outBillNo,
+			OpenID:          openID,
+			Amount:          amountFen,
+			Remark:          remark,
+			NotifyURL:       "", // 由 wechat 包从配置读取 WechatTransferURL
+			TransferSceneId: "1005",
 		}

-		result, err := wechat.InitiateTransfer(params)
+		result, err := wechat.InitiateTransferByFundApp(params)
 		if err != nil {
 			errMsg := err.Error()
-			fmt.Printf("[AdminWithdrawals] 发起转账失败 id=%s: %s（微信侧不会产生批次记录）\n", body.ID, errMsg)
-			// 未初始化或未配置转账：仅标记为已打款并提示线下处理（与 transfer 包返回文案一致）
+			fmt.Printf("[AdminWithdrawals] 发起转账失败 id=%s: %s\n", body.ID, errMsg)
+			// 未初始化或未配置转账：仅标记为已打款并提示线下处理
 			if errMsg == "支付/转账未初始化，请先调用 wechat.Init" || errMsg == "转账客户端未初始化" {
 				_ = db.Model(&w).Updates(map[string]interface{}{
 					"status":       "success",
@@ -192,7 +185,7 @@ func AdminWithdrawalsAction(c *gin.Context) {
 				})
 				return
 			}
-			// 其他打款失败（含调用腾讯接口失败）：记失败原因
+			// 微信接口报错或其它失败：把微信/具体原因返回给管理端展示，不返回「微信处理中」
 			failMsg := errMsg
 			_ = db.Model(&w).Updates(map[string]interface{}{
 				"status":        "failed",
@@ -200,6 +193,23 @@ func AdminWithdrawalsAction(c *gin.Context) {
 				"error_message": failMsg,
 				"processed_at":  now,
 			}).Error
+			c.JSON(http.StatusOK, gin.H{
+				"success": false,
+				"error":   "发起打款失败",
+				"message": failMsg, // 管理端直接展示微信报错信息（如 IP 白名单、参数错误等）
+			})
+			return
+		}
+
+		// 防护：微信未返回商户单号时也按失败返回，避免管理端显示「已发起打款」却无单号
+		if result.OutBillNo == "" {
+			failMsg := "微信未返回商户单号，请检查商户平台（如 IP 白名单）或查看服务端日志"
+			_ = db.Model(&w).Updates(map[string]interface{}{
+				"status":        "failed",
+				"fail_reason":   failMsg,
+				"error_message": failMsg,
+				"processed_at":  now,
+			}).Error
 			c.JSON(http.StatusOK, gin.H{
 				"success": false,
 				"error":   "发起打款失败",
@@ -208,28 +218,26 @@ func AdminWithdrawalsAction(c *gin.Context) {
 			return
 		}

-		// 打款已受理，更新为处理中并保存商家批次/明细单号及微信批次号
-		fmt.Printf("[AdminWithdrawals] 微信已受理 id=%s out_batch_no=%s batch_id=%s（商户后台「商家转账到零钱」可凭商家批次单号查询）\n", body.ID, result.OutBatchNo, result.BatchID)
+		// 打款已受理（FundApp 单笔），更新为处理中并保存商户单号、微信转账单号
+		fmt.Printf("[AdminWithdrawals] 微信已受理 id=%s out_bill_no=%s transfer_bill_no=%s\n", body.ID, result.OutBillNo, result.TransferBillNo)
 		processingStatus := "processing"
-		batchID := result.BatchID
 		if err := db.Model(&w).Updates(map[string]interface{}{
 			"status":       processingStatus,
-			"batch_no":     outBatchNo,
-			"detail_no":    outDetailNo,
-			"batch_id":     batchID,
+			"detail_no":    result.OutBillNo, // 回调用 out_bill_no 匹配此字段
+			"batch_no":     result.OutBillNo, // 单笔无批次，存同一单号便于查询
+			"batch_id":     result.TransferBillNo,
 			"processed_at": now,
 		}).Error; err != nil {
 			fmt.Printf("[AdminWithdrawals] 更新提现状态失败 id=%s: %v\n", body.ID, err)
 			c.JSON(http.StatusOK, gin.H{"success": false, "error": "更新状态失败: " + err.Error()})
 			return
 		}
-		// 始终返回 out_batch_no 便于追踪；batch_id 为微信返回，可能为空
 		c.JSON(http.StatusOK, gin.H{
 			"success": true,
 			"message": "已发起打款，微信处理中",
 			"data": gin.H{
-				"batch_id":     batchID,
-				"out_batch_no": outBatchNo,
+				"out_bill_no":      result.OutBillNo,
+				"transfer_bill_no": result.TransferBillNo,
 			},
 		})
 		return
@@ -275,20 +283,29 @@ func AdminWithdrawalsSync(c *gin.Context) {
 		if w.DetailNo != nil {
 			detailNo = *w.DetailNo
 		}
-		if batchNo == "" || detailNo == "" {
+		if detailNo == "" {
 			continue
 		}
-		res, err := wechat.QueryTransfer(batchNo, detailNo)
-		if err != nil {
-			continue
-		}
-		status := ""
-		if s, ok := res["detail_status"].(string); ok {
-			status = s
-		}
-		failReason := ""
-		if s, ok := res["fail_reason"].(string); ok {
-			failReason = s
+		var status, failReason string
+		// FundApp 单笔：batch_no == detail_no 时用商户单号查询
+		if batchNo == detailNo {
+			state, _, fail, err := wechat.QueryTransferByOutBill(detailNo)
+			if err != nil {
+				continue
+			}
+			status = state
+			failReason = fail
+		} else {
+			res, err := wechat.QueryTransfer(batchNo, detailNo)
+			if err != nil {
+				continue
+			}
+			if s, ok := res["detail_status"].(string); ok {
+				status = s
+			}
+			if s, ok := res["fail_reason"].(string); ok {
+				failReason = s
+			}
 		}
 		up := map[string]interface{}{"processed_at": now}
 		switch status {
--- a/soul-api/internal/middleware/admin_auth.go
+++ b/soul-api/internal/middleware/admin_auth.go
@@ -9,7 +9,7 @@ import (
 	"github.com/gin-gonic/gin"
 )

-// AdminAuth 管理端鉴权：校验 admin_session cookie 签名与过期（与 next-project 一致），未登录返回 401
+// AdminAuth 管理端鉴权：校验 JWT（Authorization: Bearer 或 Cookie admin_session），未登录返回 401
 func AdminAuth() gin.HandlerFunc {
 	return func(c *gin.Context) {
 		cfg := config.Get()
@@ -17,8 +17,8 @@ func AdminAuth() gin.HandlerFunc {
 			c.Next()
 			return
 		}
-		token := auth.GetAdminTokenFromRequest(c.Request)
-		if !auth.VerifyAdminToken(token, cfg.AdminSessionSecret) {
+		token := auth.GetAdminJWTFromRequest(c.Request)
+		if _, ok := auth.ParseAdminJWT(token, cfg.AdminSessionSecret); !ok {
 			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"success": false, "error": "未授权访问，请先登录"})
 			return
 		}
--- a/soul-api/internal/wechat/transfer.go
+++ b/soul-api/internal/wechat/transfer.go
@@ -8,6 +8,7 @@ import (
 	"soul-api/internal/config"

 	"github.com/ArtisanCloud/PowerLibs/v3/object"
+	fundAppRequest "github.com/ArtisanCloud/PowerWeChat/v3/src/payment/fundApp/request"
 	"github.com/ArtisanCloud/PowerWeChat/v3/src/payment/transfer/request"
 )

@@ -136,3 +137,83 @@ func GenerateTransferDetailNo() string {
 	random := now.UnixNano() % 1000000
 	return fmt.Sprintf("WDD%s%06d", timestamp, random)
 }
+
+// FundAppTransferParams 单笔转账（FundApp 发起转账）参数
+type FundAppTransferParams struct {
+	OutBillNo   string // 商户单号（唯一，回调时 out_bill_no 即此值，建议存到 withdrawal.detail_no）
+	OpenID      string
+	UserName    string // 可选
+	Amount      int    // 分
+	Remark      string
+	NotifyURL   string
+	TransferSceneId string // 可选，如 "1005"
+}
+
+// FundAppTransferResult 单笔转账结果
+type FundAppTransferResult struct {
+	OutBillNo      string
+	TransferBillNo string
+	State          string
+}
+
+// InitiateTransferByFundApp 发起商家转账到零钱（PowerWeChat FundApp.TransferBills 单笔接口）
+// 与 TransferBatch 不同，此为 /v3/fund-app/mch-transfer/transfer-bills 单笔发起，回调仍为 MCHTRANSFER.BILL.FINISHED，解密后 out_bill_no 即本接口传入的 OutBillNo
+func InitiateTransferByFundApp(params FundAppTransferParams) (*FundAppTransferResult, error) {
+	if paymentApp == nil || paymentApp.FundApp == nil {
+		return nil, fmt.Errorf("支付/转账未初始化，请先调用 wechat.Init")
+	}
+	req := &fundAppRequest.RequestTransferBills{
+		Appid:          cfg.WechatAppID,
+		OutBillNo:      params.OutBillNo,
+		TransferSceneId: params.TransferSceneId,
+		Openid:         params.OpenID,
+		UserName:       params.UserName,
+		TransferAmount: params.Amount,
+		TransferRemark: params.Remark,
+		NotifyUrl:      params.NotifyURL,
+	}
+	if req.NotifyUrl == "" && cfg.WechatTransferURL != "" {
+		req.NotifyUrl = cfg.WechatTransferURL
+	}
+	ctx := context.Background()
+	resp, err := paymentApp.FundApp.TransferBills(ctx, req)
+	if err != nil {
+		return nil, fmt.Errorf("发起转账失败: %w", err)
+	}
+	if resp == nil {
+		return nil, fmt.Errorf("转账返回为空")
+	}
+	// 微信返回 4xx 时 body 可能被解析到 resp，需根据 code 或 out_bill_no 判断是否成功
+	if resp.Code != "" {
+		msg := resp.Message
+		if msg == "" {
+			msg = resp.Code
+		}
+		return nil, fmt.Errorf("微信接口报错: %s", msg)
+	}
+	if resp.OutBillNo == "" {
+		return nil, fmt.Errorf("微信未返回商户单号，可能请求被拒绝（如IP未加入白名单）")
+	}
+	result := &FundAppTransferResult{
+		OutBillNo:      resp.OutBillNo,
+		TransferBillNo: resp.TransferBillNo,
+		State:          resp.State,
+	}
+	return result, nil
+}
+
+// QueryTransferByOutBill 按商户单号查询单笔转账结果（FundApp 接口，用于 sync）
+func QueryTransferByOutBill(outBillNo string) (state, transferBillNo, failReason string, err error) {
+	if paymentApp == nil || paymentApp.FundApp == nil {
+		return "", "", "", fmt.Errorf("支付/转账未初始化")
+	}
+	ctx := context.Background()
+	resp, err := paymentApp.FundApp.QueryOutBill(ctx, outBillNo)
+	if err != nil {
+		return "", "", "", err
+	}
+	if resp == nil {
+		return "", "", "", nil
+	}
+	return resp.State, resp.TransferBillNo, resp.FailReason, nil
+}