feat: 添加租户成员充值功能及相关文档

backend/app/http/tenant/dto/topup_admin.go

@@ -0,0 +1,11 @@
+package dto
+
+// AdminTopupForm defines payload for tenant-admin to topup a tenant member balance.
+type AdminTopupForm struct {
+	// Amount is the topup amount in cents (CNY 分); must be > 0.
+	Amount int64 `json:"amount,omitempty"`
+	// Reason is the human-readable topup reason used for audit.
+	Reason string `json:"reason,omitempty"`
+	// IdempotencyKey ensures the topup request is processed at most once.
+	IdempotencyKey string `json:"idempotency_key,omitempty"`
+}

backend/app/http/tenant/order_admin.go

@@ -32,7 +32,12 @@ type orderAdmin struct{}
 //	@Bind		tenant local key(tenant)
 //	@Bind		tenantUser local key(tenant_user)
 //	@Bind		filter query
-func (*orderAdmin) adminOrderList(ctx fiber.Ctx, tenant *models.Tenant, tenantUser *models.TenantUser, filter *dto.AdminOrderListFilter) (*requests.Pager, error) {
+func (*orderAdmin) adminOrderList(
+	ctx fiber.Ctx,
+	tenant *models.Tenant,
+	tenantUser *models.TenantUser,
+	filter *dto.AdminOrderListFilter,
+) (*requests.Pager, error) {
 	if err := requireTenantAdmin(tenantUser); err != nil {
 		return nil, err
 	}
@@ -59,7 +64,12 @@ func (*orderAdmin) adminOrderList(ctx fiber.Ctx, tenant *models.Tenant, tenantUs
 //	@Bind		tenant local key(tenant)
 //	@Bind		tenantUser local key(tenant_user)
 //	@Bind		orderID path
-func (*orderAdmin) adminOrderDetail(ctx fiber.Ctx, tenant *models.Tenant, tenantUser *models.TenantUser, orderID int64) (*dto.AdminOrderDetail, error) {
+func (*orderAdmin) adminOrderDetail(
+	ctx fiber.Ctx,
+	tenant *models.Tenant,
+	tenantUser *models.TenantUser,
+	orderID int64,
+) (*dto.AdminOrderDetail, error) {
 	if err := requireTenantAdmin(tenantUser); err != nil {
 		return nil, err
 	}
@@ -93,7 +103,13 @@ func (*orderAdmin) adminOrderDetail(ctx fiber.Ctx, tenant *models.Tenant, tenant
 //	@Bind		tenantUser local key(tenant_user)
 //	@Bind		orderID path
 //	@Bind		form body
-func (*orderAdmin) adminRefund(ctx fiber.Ctx, tenant *models.Tenant, tenantUser *models.TenantUser, orderID int64, form *dto.AdminOrderRefundForm) (*models.Order, error) {
+func (*orderAdmin) adminRefund(
+	ctx fiber.Ctx,
+	tenant *models.Tenant,
+	tenantUser *models.TenantUser,
+	orderID int64,
+	form *dto.AdminOrderRefundForm,
+) (*models.Order, error) {
 	if err := requireTenantAdmin(tenantUser); err != nil {
 		return nil, err
 	}
@@ -109,5 +125,64 @@ func (*orderAdmin) adminRefund(ctx fiber.Ctx, tenant *models.Tenant, tenantUser
 		"idempotency_key": form.IdempotencyKey,
 	}).Info("tenant.admin.orders.refund")
 
-	return services.Order.AdminRefundOrder(ctx, tenant.ID, tenantUser.UserID, orderID, form.Force, form.Reason, form.IdempotencyKey, time.Now())
+	return services.Order.AdminRefundOrder(
+		ctx,
+		tenant.ID,
+		tenantUser.UserID,
+		orderID,
+		form.Force,
+		form.Reason,
+		form.IdempotencyKey,
+		time.Now(),
+	)
+}
+
+// adminTopupUser
+//
+//	@Summary	为租户成员充值（租户管理）
+//	@Tags		Tenant
+//	@Accept		json
+//	@Produce	json
+//	@Param		tenantCode	path		string				true	"Tenant Code"
+//	@Param		userID		path		int64				true	"UserID"
+//	@Param		form		body		dto.AdminTopupForm	true	"Form"
+//	@Success	200			{object}	models.Order
+//
+//	@Router		/t/:tenantCode/v1/admin/users/:userID/topup [post]
+//	@Bind		tenant local key(tenant)
+//	@Bind		tenantUser local key(tenant_user)
+//	@Bind		userID path
+//	@Bind		form body
+func (*orderAdmin) adminTopupUser(
+	ctx fiber.Ctx,
+	tenant *models.Tenant,
+	tenantUser *models.TenantUser,
+	userID int64,
+	form *dto.AdminTopupForm,
+) (*models.Order, error) {
+	if err := requireTenantAdmin(tenantUser); err != nil {
+		return nil, err
+	}
+	if form == nil {
+		return nil, errorx.ErrInvalidParameter
+	}
+
+	log.WithFields(log.Fields{
+		"tenant_id":       tenant.ID,
+		"operator_user":   tenantUser.UserID,
+		"target_user":     userID,
+		"amount":          form.Amount,
+		"idempotency_key": form.IdempotencyKey,
+	}).Info("tenant.admin.users.topup")
+
+	return services.Order.AdminTopupUser(
+		ctx,
+		tenant.ID,
+		tenantUser.UserID,
+		userID,
+		form.Amount,
+		form.IdempotencyKey,
+		form.Reason,
+		time.Now(),
+	)
 }

backend/app/http/tenant/routes.gen.go

@@ -148,6 +148,14 @@ func (r *Routes) Register(router fiber.Router) {
 		PathParam[int64]("orderID"),
 		Body[dto.AdminOrderRefundForm]("form"),
 	))
+	r.log.Debugf("Registering route: Post /t/:tenantCode/v1/admin/users/:userID/topup -> orderAdmin.adminTopupUser")
+	router.Post("/t/:tenantCode/v1/admin/users/:userID/topup"[len(r.Path()):], DataFunc4(
+		r.orderAdmin.adminTopupUser,
+		Local[*models.Tenant]("tenant"),
+		Local[*models.TenantUser]("tenant_user"),
+		PathParam[int64]("userID"),
+		Body[dto.AdminTopupForm]("form"),
+	))
 	// Register routes for controller: orderMe
 	r.log.Debugf("Registering route: Get /t/:tenantCode/v1/orders -> orderMe.myOrders")
 	router.Get("/t/:tenantCode/v1/orders"[len(r.Path()):], DataFunc3(

backend/app/services/ledger.go

@@ -60,6 +60,11 @@ func (s *ledger) CreditRefundTx(ctx context.Context, tx *gorm.DB, tenantID, user
 	return s.apply(ctx, tx, tenantID, userID, orderID, consts.TenantLedgerTypeCreditRefund, amount, amount, 0, idempotencyKey, remark, now)
 }
 
+// CreditTopupTx credits funds to available balance and records a ledger entry.
+func (s *ledger) CreditTopupTx(ctx context.Context, tx *gorm.DB, tenantID, userID, orderID, amount int64, idempotencyKey, remark string, now time.Time) (*LedgerApplyResult, error) {
+	return s.apply(ctx, tx, tenantID, userID, orderID, consts.TenantLedgerTypeCreditTopup, amount, amount, 0, idempotencyKey, remark, now)
+}
+
 func (s *ledger) apply(
 	ctx context.Context,
 	tx *gorm.DB,

backend/app/services/order.go

@@ -56,6 +56,107 @@ type order struct {
 	ledger *ledger
 }
 
+// AdminTopupUser credits tenant balance to a tenant member (tenant-admin action).
+func (s *order) AdminTopupUser(ctx context.Context, tenantID, operatorUserID, targetUserID, amount int64, idempotencyKey, reason string, now time.Time) (*models.Order, error) {
+	if tenantID <= 0 || operatorUserID <= 0 || targetUserID <= 0 {
+		return nil, errorx.ErrInvalidParameter.WithMsg("tenant_id/operator_user_id/target_user_id must be > 0")
+	}
+	if amount <= 0 {
+		return nil, errorx.ErrInvalidParameter.WithMsg("amount must be > 0")
+	}
+	if now.IsZero() {
+		now = time.Now()
+	}
+
+	logrus.WithFields(logrus.Fields{
+		"tenant_id":       tenantID,
+		"operator_user":   operatorUserID,
+		"target_user":     targetUserID,
+		"amount":          amount,
+		"idempotency_key": idempotencyKey,
+	}).Info("services.order.admin.topup_user")
+
+	var out models.Order
+
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// Ensure target user is a tenant member.
+		var tu models.TenantUser
+		if err := tx.
+			Clauses(clause.Locking{Strength: "UPDATE"}).
+			Where("tenant_id = ? AND user_id = ?", tenantID, targetUserID).
+			First(&tu).Error; err != nil {
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				return errorx.ErrPreconditionFailed.WithMsg("目标用户不属于该租户")
+			}
+			return err
+		}
+
+		// Idempotent by (tenant_id, user_id, idempotency_key) on orders.
+		if idempotencyKey != "" {
+			var existing models.Order
+			if err := tx.Where(
+				"tenant_id = ? AND user_id = ? AND idempotency_key = ?",
+				tenantID, targetUserID, idempotencyKey,
+			).First(&existing).Error; err == nil {
+				out = existing
+				return nil
+			} else if !errors.Is(err, gorm.ErrRecordNotFound) {
+				return err
+			}
+		}
+
+		orderModel := models.Order{
+			TenantID:       tenantID,
+			UserID:         targetUserID,
+			Type:           consts.OrderTypeTopup,
+			Status:         consts.OrderStatusPaid,
+			Currency:       consts.CurrencyCNY,
+			AmountOriginal: amount,
+			AmountDiscount: 0,
+			AmountPaid:     amount,
+			Snapshot:       types.JSON([]byte("{}")),
+			IdempotencyKey: idempotencyKey,
+			PaidAt:         now,
+			CreatedAt:      now,
+			UpdatedAt:      now,
+		}
+		if err := tx.Create(&orderModel).Error; err != nil {
+			return err
+		}
+
+		ledgerKey := fmt.Sprintf("topup:%d", orderModel.ID)
+		remark := reason
+		if remark == "" {
+			remark = fmt.Sprintf("topup by tenant_admin:%d", operatorUserID)
+		}
+		if _, err := s.ledger.CreditTopupTx(ctx, tx, tenantID, targetUserID, orderModel.ID, amount, ledgerKey, remark, now); err != nil {
+			return err
+		}
+
+		out = orderModel
+		return nil
+	})
+	if err != nil {
+		logrus.WithFields(logrus.Fields{
+			"tenant_id":       tenantID,
+			"operator_user":   operatorUserID,
+			"target_user":     targetUserID,
+			"amount":          amount,
+			"idempotency_key": idempotencyKey,
+		}).WithError(err).Warn("services.order.admin.topup_user.failed")
+		return nil, err
+	}
+
+	logrus.WithFields(logrus.Fields{
+		"tenant_id":   tenantID,
+		"target_user": targetUserID,
+		"order_id":    out.ID,
+		"amount":      amount,
+	}).Info("services.order.admin.topup_user.ok")
+
+	return &out, nil
+}
+
 // MyOrderPage lists orders for current user within a tenant.
 func (s *order) MyOrderPage(ctx context.Context, tenantID, userID int64, filter *dto.MyOrderListFilter) (*requests.Pager, error) {
 	if tenantID <= 0 || userID <= 0 {

backend/docs/docs.go

@@ -773,6 +773,54 @@ const docTemplate = `{
                 }
             }
         },
+        "/t/{tenantCode}/v1/admin/users/{userID}/topup": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Tenant"
+                ],
+                "summary": "为租户成员充值（租户管理）",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Tenant Code",
+                        "name": "tenantCode",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "integer",
+                        "format": "int64",
+                        "description": "UserID",
+                        "name": "userID",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Form",
+                        "name": "form",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/dto.AdminTopupForm"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.Order"
+                        }
+                    }
+                }
+            }
+        },
         "/t/{tenantCode}/v1/contents": {
             "get": {
                 "consumes": [
@@ -1364,6 +1412,23 @@ const docTemplate = `{
                 }
             }
         },
+        "dto.AdminTopupForm": {
+            "type": "object",
+            "properties": {
+                "amount": {
+                    "description": "Amount is the topup amount in cents (CNY 分); must be \u003e 0.",
+                    "type": "integer"
+                },
+                "idempotency_key": {
+                    "description": "IdempotencyKey ensures the topup request is processed at most once.",
+                    "type": "string"
+                },
+                "reason": {
+                    "description": "Reason is the human-readable topup reason used for audit.",
+                    "type": "string"
+                }
+            }
+        },
         "dto.ContentAssetAttachForm": {
             "type": "object",
             "properties": {

backend/docs/swagger.json

@@ -767,6 +767,54 @@
                 }
             }
         },
+        "/t/{tenantCode}/v1/admin/users/{userID}/topup": {
+            "post": {
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "Tenant"
+                ],
+                "summary": "为租户成员充值（租户管理）",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "Tenant Code",
+                        "name": "tenantCode",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "integer",
+                        "format": "int64",
+                        "description": "UserID",
+                        "name": "userID",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "description": "Form",
+                        "name": "form",
+                        "in": "body",
+                        "required": true,
+                        "schema": {
+                            "$ref": "#/definitions/dto.AdminTopupForm"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "OK",
+                        "schema": {
+                            "$ref": "#/definitions/models.Order"
+                        }
+                    }
+                }
+            }
+        },
         "/t/{tenantCode}/v1/contents": {
             "get": {
                 "consumes": [
@@ -1358,6 +1406,23 @@
                 }
             }
         },
+        "dto.AdminTopupForm": {
+            "type": "object",
+            "properties": {
+                "amount": {
+                    "description": "Amount is the topup amount in cents (CNY 分); must be \u003e 0.",
+                    "type": "integer"
+                },
+                "idempotency_key": {
+                    "description": "IdempotencyKey ensures the topup request is processed at most once.",
+                    "type": "string"
+                },
+                "reason": {
+                    "description": "Reason is the human-readable topup reason used for audit.",
+                    "type": "string"
+                }
+            }
+        },
         "dto.ContentAssetAttachForm": {
             "type": "object",
             "properties": {

backend/docs/swagger.yaml

@@ -169,6 +169,19 @@ definitions:
           退款原因：建议必填（由业务侧校验）；用于审计与追责。
         type: string
     type: object
+  dto.AdminTopupForm:
+    properties:
+      amount:
+        description: Amount is the topup amount in cents (CNY 分); must be > 0.
+        type: integer
+      idempotency_key:
+        description: IdempotencyKey ensures the topup request is processed at most
+          once.
+        type: string
+      reason:
+        description: Reason is the human-readable topup reason used for audit.
+        type: string
+    type: object
   dto.ContentAssetAttachForm:
     properties:
       asset_id:
@@ -1387,6 +1400,38 @@ paths:
       summary: 订单退款（租户管理）
       tags:
       - Tenant
+  /t/{tenantCode}/v1/admin/users/{userID}/topup:
+    post:
+      consumes:
+      - application/json
+      parameters:
+      - description: Tenant Code
+        in: path
+        name: tenantCode
+        required: true
+        type: string
+      - description: UserID
+        format: int64
+        in: path
+        name: userID
+        required: true
+        type: integer
+      - description: Form
+        in: body
+        name: form
+        required: true
+        schema:
+          $ref: '#/definitions/dto.AdminTopupForm'
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: OK
+          schema:
+            $ref: '#/definitions/models.Order'
+      summary: 为租户成员充值（租户管理）
+      tags:
+      - Tenant
   /t/{tenantCode}/v1/contents:
     get:
       consumes:

backend/tests/tenant.http

@@ -119,3 +119,15 @@ Authorization: Bearer {{ token }}
   "reason": "联调退款",
   "idempotency_key": "refund-{{ orderID }}-001"
 }
+
+### Tenant Admin - Topup a tenant member
+@topupUserID = 2
+POST {{ host }}/t/{{ tenantCode }}/v1/admin/users/{{ topupUserID }}/topup
+Content-Type: application/json
+Authorization: Bearer {{ token }}
+
+{
+  "amount": 1000,
+  "reason": "联调充值",
+  "idempotency_key": "topup-{{ topupUserID }}-001"
+}