rogee/quyun-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Rogee
2025-12-18 14:09:08 +08:00
parent 1da84f2af3
commit a232e73358
9 changed files with 391 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
backend/app/http/tenant/dto/topup_admin.go Normal file
View File

@@ -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"`
}

83
backend/app/http/tenant/order_admin.go
View File

@@ -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(),
)
}

8
backend/app/http/tenant/routes.gen.go
View File

@@ -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(

5
backend/app/services/ledger.go
View File

@@ -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,

101
backend/app/services/order.go
View File

@@ -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 {

65
backend/docs/docs.go
View File

@@ -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": {

65
backend/docs/swagger.json
View File

@@ -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": {

45
backend/docs/swagger.yaml
View File

@@ -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:

12
backend/tests/tenant.http
View File

@@ -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"
}