feat: 通用授权后台、离线证、Waffo 支付页与仪表盘加强

支持多产品计划展示、LICOFF 离线签发、支付独立配置与调试，以及分析看板；同步更新 README 与集成文档。

Co-authored-by: Cursor <cursoragent@cursor.com>

backend/internal/controller/analytics/analytics_controller.go

@@ -90,3 +90,33 @@ func (ctrl *AnalyticsController) GetProductDistribution(c *gin.Context) {
 	}
 	c.JSON(http.StatusOK, gin.H{"code": 0, "data": stats})
 }
+
+// GetGeoDistribution 地理分布 // Logan.Li
+func (ctrl *AnalyticsController) GetGeoDistribution(c *gin.Context) {
+	stats, err := ctrl.svc.GetGeoDistribution()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"code": 0, "data": stats})
+}
+
+// GetPlatformDistribution 客户端形态分布 // Logan.Li
+func (ctrl *AnalyticsController) GetPlatformDistribution(c *gin.Context) {
+	stats, err := ctrl.svc.GetPlatformDistribution()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"code": 0, "data": stats})
+}
+
+// GetLicenseGrowthDetail 增长明细（累计+新增） // Logan.Li
+func (ctrl *AnalyticsController) GetLicenseGrowthDetail(c *gin.Context) {
+	stats, err := ctrl.svc.GetLicenseGrowthDetail()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"code": 500, "message": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"code": 0, "data": stats})
+}

backend/internal/controller/license/license_controller.go

@@ -1,6 +1,8 @@
 package license
 
 import (
+	"backend/config"
+	"backend/internal/dto"
 	licenseservice "backend/internal/service/license"
 	"backend/utils"
 	"net/http"
@@ -12,13 +14,18 @@ import (
 
 // LicenseController License 控制器 // Logan.Li
 type LicenseController struct {
-	svc *licenseservice.LicenseService
-	db  *gorm.DB
+	svc     *licenseservice.LicenseService
+	offline *licenseservice.OfflineIssuer
+	db      *gorm.DB
 }
 
 // NewLicenseController 创建控制器实例 // Logan.Li
-func NewLicenseController(db *gorm.DB) *LicenseController {
-	return &LicenseController{svc: licenseservice.NewLicenseService(db), db: db}
+func NewLicenseController(db *gorm.DB, cfg *config.Config) *LicenseController {
+	return &LicenseController{
+		svc:     licenseservice.NewLicenseService(db),
+		offline: licenseservice.NewOfflineIssuer(db, cfg),
+		db:      db,
+	}
 }
 
 // parseListQuery 从请求解析筛选参数 // Logan.Li
@@ -26,6 +33,7 @@ func parseListQuery(c *gin.Context) licenseservice.ListQuery {
 	q := licenseservice.ListQuery{
 		Keyword: c.Query("keyword"),
 		Status:  c.Query("status"),
+		Channel: c.Query("channel"),
 	}
 	if v, err := strconv.ParseUint(c.Query("customer_id"), 10, 32); err == nil {
 		q.CustomerID = uint(v)
@@ -65,16 +73,7 @@ func (ctrl *LicenseController) Get(c *gin.Context) {
 
 // Create 创建 License // Logan.Li
 func (ctrl *LicenseController) Create(c *gin.Context) {
-	var req struct {
-		CustomerID     uint   `json:"customer_id" binding:"required"`
-		ProductID      uint   `json:"product_id" binding:"required"`
-		Duration       int    `json:"duration" binding:"required"`
-		MaxActivations int    `json:"max_activations"`
-		IsTrial        bool   `json:"is_trial"`
-		TrialDays      int    `json:"trial_days"`
-		Notes          string `json:"notes"`
-		Count          int    `json:"count"`
-	}
+	var req dto.LicenseCreate
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "参数错误: " + err.Error()})
 		return
@@ -89,6 +88,36 @@ func (ctrl *LicenseController) Create(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"code": 0, "message": "创建成功", "data": licenses})
 }
 
+// IssueOffline 签发离线许可证序列号（最长 365 天，绑定 device_id） // Logan.Li
+func (ctrl *LicenseController) IssueOffline(c *gin.Context) {
+	var req dto.OfflineLicenseCreate
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "参数错误: " + err.Error()})
+		return
+	}
+	result, err := ctrl.offline.Issue(req)
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{"code": 1, "message": err.Error()})
+		return
+	}
+	utils.LogAction(ctrl.db, c, "create_offline", "license", result.LicenseID, result.Serial, "", "",
+		"签发离线证 device="+result.DeviceID)
+	c.JSON(http.StatusOK, gin.H{"code": 0, "message": "离线许可证已生成", "data": result})
+}
+
+// OfflinePublicKey 返回当前离线验签公钥（供运维核对桌面嵌入值） // Logan.Li
+func (ctrl *LicenseController) OfflinePublicKey(c *gin.Context) {
+	pub := ""
+	if ctrl.offline != nil {
+		pub = ctrl.offline.PublicKeyHex()
+	}
+	if pub == "" {
+		c.JSON(http.StatusOK, gin.H{"code": 1, "message": "未配置 OFFLINE_LICENSE_SEED"})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"code": 0, "data": gin.H{"public_key_hex": pub}})
+}
+
 // Update 更新 License // Logan.Li
 func (ctrl *LicenseController) Update(c *gin.Context) {
 	id, _ := strconv.ParseUint(c.Param("id"), 10, 32)

backend/internal/controller/order/order_controller.go

@@ -310,15 +310,16 @@ func renderSimplePage(title, headline, body, extraHTML, deepLink string) string
 </html>`
 }
 
-// WaffoWebhook accepts loosely-shaped Waffo payment events and maps to PaymentWebhook. // Logan.Li
+// WaffoWebhook maps official Waffo Raw JSON webhooks (order.completed etc.) to PaymentWebhook.
+// Prefer data.orderMerchantExternalId (= our ORD-*) for matching; also accept legacy shapes. // Logan.Li
 func (ctrl *OrderController) WaffoWebhook(c *gin.Context) {
 	body, err := io.ReadAll(c.Request.Body)
 	if err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "无法读取请求体"})
 		return
 	}
-	// Optional: accept X-Waffo-Signature if present (no strict verification yet). // Logan.Li
-	_ = c.GetHeader("X-Waffo-Signature")
+	sigHeader := c.GetHeader("X-Waffo-Signature")
+	_ = sigHeader // optional RSA verify when WAFFO_WEBHOOK_PUBLIC_KEY is set later // Logan.Li
 
 	var payload map[string]interface{}
 	if len(body) > 0 {
@@ -330,79 +331,93 @@ func (ctrl *OrderController) WaffoWebhook(c *gin.Context) {
 		payload = map[string]interface{}{}
 	}
 
-	orderNo := firstNonEmpty(
+	data, _ := payload["data"].(map[string]interface{})
+	metaTop, _ := payload["metadata"].(map[string]interface{})
+	metaOrder, _ := data["orderMetadata"].(map[string]interface{})
+	metaLegacy, _ := data["metadata"].(map[string]interface{})
+
+	// Official: orderMerchantExternalId is our ORD-*; orderId is Waffo ORD_*. // Logan.Li
+	merchantExternalID := firstNonEmpty(
+		asString(data["orderMerchantExternalId"]),
+		asString(payload["orderMerchantExternalId"]),
+		asString(metaOrder["orderNo"]),
+		asString(metaOrder["order_no"]),
+		asString(metaLegacy["orderNo"]),
+		asString(metaLegacy["order_no"]),
+		asString(metaTop["orderNo"]),
+		asString(metaTop["order_no"]),
 		asString(payload["order_no"]),
 		asString(payload["orderNo"]),
-		asString(payload["order_id"]),
 		c.Query("order_no"),
 		c.Query("orderNo"),
 	)
-	if orderNo == "" {
-		if meta, ok := payload["metadata"].(map[string]interface{}); ok {
-			orderNo = firstNonEmpty(asString(meta["orderNo"]), asString(meta["order_no"]))
-		}
-	}
-	if orderNo == "" {
-		if data, ok := payload["data"].(map[string]interface{}); ok {
-			orderNo = firstNonEmpty(asString(data["order_no"]), asString(data["orderNo"]))
-			if orderNo == "" {
-				if meta, ok := data["metadata"].(map[string]interface{}); ok {
-					orderNo = firstNonEmpty(asString(meta["orderNo"]), asString(meta["order_no"]))
-				}
-			}
-		}
-	}
-	if orderNo == "" {
-		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "missing order_no"})
-		return
-	}
+	gatewayOrderNo := firstNonEmpty(
+		asString(data["orderId"]),
+		asString(payload["orderId"]),
+		asString(payload["gateway_order_no"]),
+		asString(payload["gatewayOrderNo"]),
+		asString(payload["id"]),
+	)
+	paymentID := firstNonEmpty(asString(data["paymentId"]), asString(payload["paymentId"]))
+	buyerEmail := firstNonEmpty(asString(data["buyerEmail"]), asString(payload["buyerEmail"]), asString(payload["customer_email"]))
 
 	eventType := firstNonEmpty(
-		asString(payload["event_type"]),
+		c.GetHeader("X-Waffo-Event"),
 		asString(payload["eventType"]),
+		asString(payload["event_type"]),
 		asString(payload["type"]),
 		asString(payload["event"]),
 		"payment",
 	)
 	statusRaw := strings.ToLower(firstNonEmpty(
+		asString(data["orderStatus"]),
+		asString(data["paymentStatus"]),
 		asString(payload["status"]),
 		asString(payload["payment_status"]),
 		asString(payload["paymentStatus"]),
 	))
-	gatewayOrderNo := firstNonEmpty(
-		asString(payload["gateway_order_no"]),
-		asString(payload["gatewayOrderNo"]),
-		asString(payload["transaction_id"]),
-		asString(payload["transactionId"]),
-		asString(payload["id"]),
-	)
 
 	mappedStatus := "paid"
 	switch {
-	case strings.Contains(statusRaw, "fail"), strings.Contains(statusRaw, "cancel"),
-		strings.Contains(eventType, "fail"), strings.Contains(eventType, "cancel"):
-		mappedStatus = "failed"
-	case strings.Contains(statusRaw, "refund"), strings.Contains(eventType, "refund"):
+	case strings.Contains(strings.ToLower(eventType), "refund"), strings.Contains(statusRaw, "refund"):
 		mappedStatus = "refunded"
-	case statusRaw == "" || strings.Contains(statusRaw, "paid") || strings.Contains(statusRaw, "complete") ||
-		strings.Contains(statusRaw, "success") || strings.Contains(eventType, "complete") ||
-		strings.Contains(eventType, "paid") || strings.Contains(eventType, "success"):
+	case strings.Contains(strings.ToLower(eventType), "fail"), strings.Contains(strings.ToLower(eventType), "cancel"),
+		strings.Contains(statusRaw, "fail"), strings.Contains(statusRaw, "cancel"):
+		mappedStatus = "failed"
+	case strings.Contains(strings.ToLower(eventType), "order.completed"),
+		strings.Contains(strings.ToLower(eventType), "payment.succeeded"),
+		statusRaw == "" || strings.Contains(statusRaw, "paid") || strings.Contains(statusRaw, "complete") ||
+			strings.Contains(statusRaw, "success") || strings.Contains(statusRaw, "succeed"):
 		mappedStatus = "paid"
 	default:
-		// Treat unknown completed-like events as paid for now. // Logan.Li
 		mappedStatus = "paid"
 	}
 
+	// Ignore non-terminal noise if event is clearly not a completion (e.g. order.created). // Logan.Li
+	et := strings.ToLower(eventType)
+	if strings.Contains(et, "order.created") || strings.Contains(et, "order.pending") ||
+		strings.Contains(et, "payment.pending") || strings.Contains(et, "checkout.session") {
+		c.JSON(http.StatusOK, gin.H{"code": 0, "message": "ignored event"})
+		return
+	}
+
+	if merchantExternalID == "" && gatewayOrderNo == "" && buyerEmail == "" {
+		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "missing orderMerchantExternalId / orderId"})
+		return
+	}
+
 	req := dto.PaymentWebhookRequest{
 		EventType:      eventType,
-		OrderNo:        orderNo,
-		GatewayOrderNo: gatewayOrderNo,
+		OrderNo:        merchantExternalID,
+		GatewayOrderNo: firstNonEmpty(gatewayOrderNo, paymentID),
 		Status:         mappedStatus,
+		CustomerEmail:  buyerEmail,
 		Gateway:        "waffo",
 		Payload:        string(body),
-		Signature:      c.GetHeader("X-Waffo-Signature"),
+		Signature:      sigHeader,
 	}
 	if err := ctrl.svc.PaymentWebhook(req, utils.GetClientIP(c)); err != nil {
+		// Still 200 so Waffo does not retry forever on business errors; log via message. // Logan.Li
 		c.JSON(http.StatusOK, gin.H{"code": 1, "message": err.Error()})
 		return
 	}

backend/internal/controller/setting/setting_controller.go

@@ -1,6 +1,7 @@
 package setting
 
 import (
+	"backend/internal/dto"
 	"backend/internal/model"
 	settingservice "backend/internal/service/setting"
 	"net/http"
@@ -32,14 +33,7 @@ func (ctrl *SettingController) Get(c *gin.Context) {
 
 // Update 更新系统设置 // Logan.Li
 func (ctrl *SettingController) Update(c *gin.Context) {
-	var req struct {
-		SystemName            *string `json:"system_name"`
-		DefaultDuration       *int    `json:"default_duration"`
-		DefaultMaxActivations *int    `json:"default_max_activations"`
-		ExpireReminderDays    *int    `json:"expire_reminder_days"`
-		APIRateLimit          *int    `json:"api_rate_limit"`
-		LogRetentionDays      *int    `json:"log_retention_days"`
-	}
+	var req dto.SettingUpdate
 	if err := c.ShouldBindJSON(&req); err != nil {
 		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "参数错误"})
 		return
@@ -52,6 +46,53 @@ func (ctrl *SettingController) Update(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"code": 0, "message": "更新成功", "data": setting})
 }
 
+// GetWaffo 获取 Waffo 支付集成配置 // Logan.Li
+func (ctrl *SettingController) GetWaffo(c *gin.Context) {
+	data, err := ctrl.svc.GetWaffo()
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{"code": 1, "message": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"code": 0, "data": data})
+}
+
+// UpdateWaffo 更新 Waffo 支付集成配置 // Logan.Li
+func (ctrl *SettingController) UpdateWaffo(c *gin.Context) {
+	var req dto.WaffoSettingsUpdate
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"code": 400, "message": "参数错误"})
+		return
+	}
+	data, err := ctrl.svc.UpdateWaffo(req)
+	if err != nil {
+		c.JSON(http.StatusOK, gin.H{"code": 1, "message": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"code": 0, "message": "Waffo 配置已保存", "data": data})
+}
+
+// DebugWaffo 用当前配置探测 Waffo create-session（不回显私钥） // Logan.Li
+func (ctrl *SettingController) DebugWaffo(c *gin.Context) {
+	var req dto.WaffoDebugRequest
+	_ = c.ShouldBindJSON(&req)
+	data := ctrl.svc.DebugWaffo(req)
+	msg := "调试完成"
+	code := 0
+	if data == nil {
+		c.JSON(http.StatusOK, gin.H{"code": 1, "message": "调试失败"})
+		return
+	}
+	if !data.OK {
+		code = 1
+		if data.ErrorSummary != "" {
+			msg = data.ErrorSummary
+		} else {
+			msg = "调试失败"
+		}
+	}
+	c.JSON(http.StatusOK, gin.H{"code": code, "message": msg, "data": data})
+}
+
 // ListAuditLogs 审计日志列表 // Logan.Li
 func (ctrl *SettingController) ListAuditLogs(c *gin.Context) {
 	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))