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(