Refactor user tests and add content and order tests

- Updated user_test.go to remove FocusConvey and clean up commented-out code.
- Introduced content_test.go with comprehensive tests for content creation, updating, pricing, asset attachment, and access checks.
- Added order_test.go to implement tests for order management, including admin top-ups, order details, refunds, and content purchases with various scenarios.

backend/app/services/content.go

@@ -18,18 +18,18 @@ import (
 	"gorm.io/gorm"
 )
 
-// content implements content-related domain operations.
+// content 实现内容域相关的业务能力（创建/更新/定价/授权等）。
 //
 // @provider
 type content struct{}
 
-// ContentDetailResult is the internal detail result used by controllers.
+// ContentDetailResult 为内容详情的内部结果（供 controller 组合返回）。
 type ContentDetailResult struct {
-	// Content is the content entity.
+	// Content 内容实体。
 	Content *models.Content
-	// Price is the price settings (may be nil).
+	// Price 定价信息（可能为 nil，表示未设置价格）。
 	Price *models.ContentPrice
-	// HasAccess indicates whether the user can access main assets.
+	// HasAccess 当前用户是否拥有主资源访问权限。
 	HasAccess bool
 }
 
@@ -39,11 +39,13 @@ func (s *content) Create(ctx context.Context, tenantID, userID int64, form *dto.
 		"user_id":   userID,
 	}).Info("services.content.create")
 
+	// 关键默认值：未传可见性时默认“租户内可见”。
 	visibility := form.Visibility
 	if visibility == "" {
 		visibility = consts.ContentVisibilityTenantOnly
 	}
 
+	// 试看策略：默认固定时长；并强制不允许下载。
 	previewSeconds := consts.DefaultContentPreviewSeconds
 	if form.PreviewSeconds != nil && *form.PreviewSeconds > 0 {
 		previewSeconds = *form.PreviewSeconds
@@ -96,6 +98,7 @@ func (s *content) Update(ctx context.Context, tenantID, userID, contentID int64,
 	}
 	if form.Status != nil {
 		m.Status = *form.Status
+		// 发布动作：首次发布时补齐发布时间，便于后续排序/检索与审计。
 		if m.Status == consts.ContentStatusPublished && m.PublishedAt.IsZero() {
 			m.PublishedAt = time.Now()
 		}

backend/app/services/content_test.go

@@ -0,0 +1,244 @@
+package services
+
+import (
+	"database/sql"
+	"testing"
+	"time"
+
+	"quyun/v2/app/commands/testx"
+	"quyun/v2/app/http/tenant/dto"
+	"quyun/v2/database"
+	"quyun/v2/database/models"
+	"quyun/v2/pkg/consts"
+
+	. "github.com/smartystreets/goconvey/convey"
+	"github.com/stretchr/testify/suite"
+
+	_ "go.ipao.vip/atom"
+	"go.ipao.vip/atom/contracts"
+	"go.ipao.vip/gen/types"
+	"go.uber.org/dig"
+)
+
+type ContentTestSuiteInjectParams struct {
+	dig.In
+
+	DB       *sql.DB
+	Initials []contracts.Initial `group:"initials"` // nolint:structcheck
+}
+
+type ContentTestSuite struct {
+	suite.Suite
+	ContentTestSuiteInjectParams
+}
+
+func Test_Content(t *testing.T) {
+	providers := testx.Default().With(Provide)
+
+	testx.Serve(providers, t, func(p ContentTestSuiteInjectParams) {
+		suite.Run(t, &ContentTestSuite{ContentTestSuiteInjectParams: p})
+	})
+}
+
+func (s *ContentTestSuite) Test_Create() {
+	Convey("Content.Create", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+		userID := int64(2)
+
+		database.Truncate(ctx, s.DB, models.TableNameContent)
+
+		Convey("成功创建草稿内容并应用默认策略", func() {
+			form := &dto.ContentCreateForm{
+				Title:       "标题",
+				Description: "描述",
+			}
+			m, err := Content.Create(ctx, tenantID, userID, form)
+			So(err, ShouldBeNil)
+			So(m, ShouldNotBeNil)
+			So(m.TenantID, ShouldEqual, tenantID)
+			So(m.UserID, ShouldEqual, userID)
+			So(m.Status, ShouldEqual, consts.ContentStatusDraft)
+			So(m.Visibility, ShouldEqual, consts.ContentVisibilityTenantOnly)
+			So(m.PreviewSeconds, ShouldEqual, consts.DefaultContentPreviewSeconds)
+			So(m.PreviewDownloadable, ShouldBeFalse)
+		})
+	})
+}
+
+func (s *ContentTestSuite) Test_Update() {
+	Convey("Content.Update", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+		userID := int64(2)
+
+		database.Truncate(ctx, s.DB, models.TableNameContent)
+
+		m := &models.Content{
+			TenantID:            tenantID,
+			UserID:              userID,
+			Title:               "标题",
+			Description:         "描述",
+			Status:              consts.ContentStatusDraft,
+			Visibility:          consts.ContentVisibilityTenantOnly,
+			PreviewSeconds:      consts.DefaultContentPreviewSeconds,
+			PreviewDownloadable: false,
+		}
+		So(m.Create(ctx), ShouldBeNil)
+
+		Convey("发布内容应写入 published_at", func() {
+			status := consts.ContentStatusPublished
+			form := &dto.ContentUpdateForm{Status: &status}
+
+			updated, err := Content.Update(ctx, tenantID, userID, m.ID, form)
+			So(err, ShouldBeNil)
+			So(updated, ShouldNotBeNil)
+			So(updated.Status, ShouldEqual, consts.ContentStatusPublished)
+			So(updated.PublishedAt.IsZero(), ShouldBeFalse)
+		})
+	})
+}
+
+func (s *ContentTestSuite) Test_UpsertPrice() {
+	Convey("Content.UpsertPrice", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+		userID := int64(2)
+
+		database.Truncate(ctx, s.DB, models.TableNameContentPrice, models.TableNameContent)
+
+		content := &models.Content{
+			TenantID:            tenantID,
+			UserID:              userID,
+			Title:               "标题",
+			Description:         "描述",
+			Status:              consts.ContentStatusDraft,
+			Visibility:          consts.ContentVisibilityTenantOnly,
+			PreviewSeconds:      consts.DefaultContentPreviewSeconds,
+			PreviewDownloadable: false,
+		}
+		So(content.Create(ctx), ShouldBeNil)
+
+		Convey("首次 upsert 应创建价格记录", func() {
+			form := &dto.ContentPriceUpsertForm{
+				PriceAmount: 100,
+			}
+			price, err := Content.UpsertPrice(ctx, tenantID, userID, content.ID, form)
+			So(err, ShouldBeNil)
+			So(price, ShouldNotBeNil)
+			So(price.PriceAmount, ShouldEqual, 100)
+			So(price.Currency, ShouldEqual, consts.CurrencyCNY)
+			So(price.DiscountType, ShouldEqual, consts.DiscountTypeNone)
+		})
+
+		Convey("再次 upsert 应更新价格记录", func() {
+			form1 := &dto.ContentPriceUpsertForm{PriceAmount: 100}
+			_, err := Content.UpsertPrice(ctx, tenantID, userID, content.ID, form1)
+			So(err, ShouldBeNil)
+
+			form2 := &dto.ContentPriceUpsertForm{
+				PriceAmount:   200,
+				DiscountType:  consts.DiscountTypePercent,
+				DiscountValue: 10,
+			}
+			price2, err := Content.UpsertPrice(ctx, tenantID, userID, content.ID, form2)
+			So(err, ShouldBeNil)
+			So(price2.PriceAmount, ShouldEqual, 200)
+			So(price2.DiscountType, ShouldEqual, consts.DiscountTypePercent)
+			So(price2.DiscountValue, ShouldEqual, 10)
+		})
+	})
+}
+
+func (s *ContentTestSuite) Test_AttachAsset() {
+	Convey("Content.AttachAsset", s.T(), func() {
+		ctx := s.T().Context()
+		now := time.Now().UTC()
+		tenantID := int64(1)
+		userID := int64(2)
+
+		database.Truncate(ctx, s.DB, models.TableNameContentAsset, models.TableNameMediaAsset, models.TableNameContent)
+
+		content := &models.Content{
+			TenantID:            tenantID,
+			UserID:              userID,
+			Title:               "标题",
+			Description:         "描述",
+			Status:              consts.ContentStatusDraft,
+			Visibility:          consts.ContentVisibilityTenantOnly,
+			PreviewSeconds:      consts.DefaultContentPreviewSeconds,
+			PreviewDownloadable: false,
+		}
+		So(content.Create(ctx), ShouldBeNil)
+
+		asset := &models.MediaAsset{
+			TenantID:  tenantID,
+			UserID:    userID,
+			Type:      consts.MediaAssetTypeVideo,
+			Status:    consts.MediaAssetStatusReady,
+			Provider:  "test",
+			Bucket:    "bucket",
+			ObjectKey: "obj",
+			Meta:      types.JSON([]byte("{}")),
+		}
+		So(asset.Create(ctx), ShouldBeNil)
+
+		Convey("成功绑定资源到内容", func() {
+			m, err := Content.AttachAsset(ctx, tenantID, userID, content.ID, asset.ID, consts.ContentAssetRoleMain, 1, now)
+			So(err, ShouldBeNil)
+			So(m, ShouldNotBeNil)
+			So(m.ContentID, ShouldEqual, content.ID)
+			So(m.AssetID, ShouldEqual, asset.ID)
+			So(m.Role, ShouldEqual, consts.ContentAssetRoleMain)
+		})
+	})
+}
+
+func (s *ContentTestSuite) Test_HasAccess() {
+	Convey("Content.HasAccess", s.T(), func() {
+		ctx := s.T().Context()
+		now := time.Now().UTC()
+		tenantID := int64(1)
+		userID := int64(2)
+
+		database.Truncate(ctx, s.DB, models.TableNameContentAccess, models.TableNameContent)
+
+		content := &models.Content{
+			TenantID:            tenantID,
+			UserID:              userID,
+			Title:               "标题",
+			Description:         "描述",
+			Status:              consts.ContentStatusPublished,
+			Visibility:          consts.ContentVisibilityTenantOnly,
+			PreviewSeconds:      consts.DefaultContentPreviewSeconds,
+			PreviewDownloadable: false,
+			PublishedAt:         now,
+		}
+		So(content.Create(ctx), ShouldBeNil)
+
+		Convey("未授予权益应返回 false", func() {
+			ok, err := Content.HasAccess(ctx, tenantID, userID, content.ID)
+			So(err, ShouldBeNil)
+			So(ok, ShouldBeFalse)
+		})
+
+		Convey("权益 active 应返回 true", func() {
+			access := &models.ContentAccess{
+				TenantID:   tenantID,
+				UserID:     userID,
+				ContentID:  content.ID,
+				OrderID:    0,
+				Status:     consts.ContentAccessStatusActive,
+				RevokedAt:  time.Time{},
+				CreatedAt:  now,
+				UpdatedAt:  now,
+			}
+			So(access.Create(ctx), ShouldBeNil)
+
+			ok, err := Content.HasAccess(ctx, tenantID, userID, content.ID)
+			So(err, ShouldBeNil)
+			So(ok, ShouldBeTrue)
+		})
+	})
+}
+

backend/app/services/ledger.go

@@ -14,53 +14,52 @@ import (
 	"gorm.io/gorm/clause"
 )
 
-// LedgerApplyResult is the result of a single ledger application, including the created ledger record
-// and the updated tenant user balance snapshot.
+// LedgerApplyResult 表示一次账本写入（含幂等命中）的结果，包含账本记录与租户用户余额快照。
 type LedgerApplyResult struct {
-	// Ledger is the created ledger record (or existing one if idempotent hit).
+	// Ledger 为本次创建的账本记录（若幂等命中则返回已有记录）。
 	Ledger *models.TenantLedger
-	// TenantUser is the updated tenant user record reflecting the post-apply balances.
+	// TenantUser 为写入后余额状态（若幂等命中则返回当前快照）。
 	TenantUser *models.TenantUser
 }
 
-// ledger provides tenant balance ledger operations (freeze/unfreeze/etc.) with idempotency and row-locking.
+// ledger 提供租户余额账本能力（冻结/解冻/扣减/退款/充值），支持幂等与行锁保证一致性。
 //
 //	@provider
 type ledger struct {
 	db *gorm.DB
 }
 
-// Freeze moves funds from available balance to frozen balance and records a tenant ledger entry.
+// Freeze 将可用余额转入冻结余额，并写入账本记录。
 func (s *ledger) Freeze(ctx context.Context, tenantID, userID, orderID, amount int64, idempotencyKey, remark string, now time.Time) (*LedgerApplyResult, error) {
 	return s.apply(ctx, s.db, tenantID, userID, orderID, consts.TenantLedgerTypeFreeze, amount, -amount, amount, idempotencyKey, remark, now)
 }
 
-// Unfreeze moves funds from frozen balance back to available balance and records a tenant ledger entry.
+// Unfreeze 将冻结余额转回可用余额，并写入账本记录。
 func (s *ledger) Unfreeze(ctx context.Context, tenantID, userID, orderID, amount int64, idempotencyKey, remark string, now time.Time) (*LedgerApplyResult, error) {
 	return s.apply(ctx, s.db, tenantID, userID, orderID, consts.TenantLedgerTypeUnfreeze, amount, amount, -amount, idempotencyKey, remark, now)
 }
 
-// FreezeTx is the transaction-scoped variant of Freeze.
+// FreezeTx 为 Freeze 的事务版本（由外层事务控制提交/回滚）。
 func (s *ledger) FreezeTx(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.TenantLedgerTypeFreeze, amount, -amount, amount, idempotencyKey, remark, now)
 }
 
-// UnfreezeTx is the transaction-scoped variant of Unfreeze.
+// UnfreezeTx 为 Unfreeze 的事务版本（由外层事务控制提交/回滚）。
 func (s *ledger) UnfreezeTx(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.TenantLedgerTypeUnfreeze, amount, amount, -amount, idempotencyKey, remark, now)
 }
 
-// DebitPurchaseTx turns frozen funds into a finalized debit (reduces frozen balance) and records a ledger entry.
+// DebitPurchaseTx 将冻结资金转为实际扣款（减少冻结余额），并写入账本记录。
 func (s *ledger) DebitPurchaseTx(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.TenantLedgerTypeDebitPurchase, amount, 0, -amount, idempotencyKey, remark, now)
 }
 
-// CreditRefundTx credits funds back to available balance and records a ledger entry.
+// CreditRefundTx 将退款金额退回到可用余额，并写入账本记录。
 func (s *ledger) CreditRefundTx(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.TenantLedgerTypeCreditRefund, amount, amount, 0, idempotencyKey, remark, now)
 }
 
-// CreditTopupTx credits funds to available balance and records a ledger entry.
+// CreditTopupTx 将充值金额记入可用余额，并写入账本记录。
 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)
 }
@@ -74,6 +73,7 @@ func (s *ledger) apply(
 	idempotencyKey, remark string,
 	now time.Time,
 ) (*LedgerApplyResult, error) {
+	// 关键前置校验：金额必须为正；时间允许由调用方注入，便于测试与一致性落库。
 	if amount <= 0 {
 		return nil, errorx.ErrInvalidParameter.WithMsg("amount must be > 0")
 	}
@@ -96,6 +96,7 @@ func (s *ledger) apply(
 	var out LedgerApplyResult
 
 	err := tx.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// 幂等快速路径：在进入行锁之前先查一次，减少锁竞争（命中则直接返回）。
 		if idempotencyKey != "" {
 			var existing models.TenantLedger
 			if err := tx.
@@ -113,6 +114,7 @@ func (s *ledger) apply(
 			}
 		}
 
+		// 使用行锁锁住 tenant_users，确保同一租户下同一用户余额更新的串行一致性。
 		var tu models.TenantUser
 		if err := tx.
 			Clauses(clause.Locking{Strength: "UPDATE"}).
@@ -124,6 +126,7 @@ func (s *ledger) apply(
 			return err
 		}
 
+		// 二次幂等校验：防止并发下在获取锁前后插入账本导致的重复写入。
 		if idempotencyKey != "" {
 			var existing models.TenantLedger
 			if err := tx.
@@ -142,6 +145,7 @@ func (s *ledger) apply(
 		balanceAfter := balanceBefore + deltaBalance
 		frozenAfter := frozenBefore + deltaFrozen
 
+		// 关键不变量：余额/冻结余额不能为负，避免透支或超额解冻。
 		if balanceAfter < 0 {
 			return errorx.ErrPreconditionFailed.WithMsg("余额不足")
 		}
@@ -149,6 +153,7 @@ func (s *ledger) apply(
 			return errorx.ErrPreconditionFailed.WithMsg("冻结余额不足")
 		}
 
+		// 先更新余额，再写账本：任何一步失败都回滚，保证“余额变更”和“账本记录”一致。
 		if err := tx.Model(&models.TenantUser{}).
 			Where("id = ?", tu.ID).
 			Updates(map[string]any{
@@ -159,6 +164,7 @@ func (s *ledger) apply(
 			return err
 		}
 
+		// 写入账本：记录变更前后快照，便于对账与审计；幂等键用于去重。
 		ledger := &models.TenantLedger{
 			TenantID:       tenantID,
 			UserID:         userID,
@@ -175,6 +181,7 @@ func (s *ledger) apply(
 			UpdatedAt:      now,
 		}
 		if err := tx.Create(ledger).Error; err != nil {
+			// 并发下可能出现“先写成功后再重试”的情况：尝试按幂等键回读，保持接口幂等。
 			if idempotencyKey != "" {
 				var existing models.TenantLedger
 				if e2 := tx.

backend/app/services/ledger_test.go

@@ -0,0 +1,304 @@
+package services
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"testing"
+	"time"
+
+	"quyun/v2/app/commands/testx"
+	"quyun/v2/app/errorx"
+	"quyun/v2/database"
+	"quyun/v2/database/models"
+	"quyun/v2/pkg/consts"
+
+	. "github.com/smartystreets/goconvey/convey"
+	"github.com/stretchr/testify/suite"
+
+	_ "go.ipao.vip/atom"
+	"go.ipao.vip/atom/contracts"
+	"go.ipao.vip/gen/types"
+	"go.uber.org/dig"
+)
+
+type LedgerTestSuiteInjectParams struct {
+	dig.In
+
+	DB       *sql.DB
+	Initials []contracts.Initial `group:"initials"` // nolint:structcheck
+}
+
+type LedgerTestSuite struct {
+	suite.Suite
+
+	LedgerTestSuiteInjectParams
+}
+
+func Test_Ledger(t *testing.T) {
+	providers := testx.Default().With(Provide)
+
+	testx.Serve(providers, t, func(p LedgerTestSuiteInjectParams) {
+		suite.Run(t, &LedgerTestSuite{LedgerTestSuiteInjectParams: p})
+	})
+}
+
+func (s *LedgerTestSuite) seedTenantUser(ctx context.Context, tenantID, userID, balance, frozen int64) {
+	database.Truncate(ctx, s.DB, models.TableNameTenantLedger, models.TableNameTenantUser)
+
+	tu := &models.TenantUser{
+		TenantID:      tenantID,
+		UserID:        userID,
+		Role:          types.NewArray([]consts.TenantUserRole{consts.TenantUserRoleMember}),
+		Balance:       balance,
+		BalanceFrozen: frozen,
+		Status:        consts.UserStatusVerified,
+	}
+	So(tu.Create(ctx), ShouldBeNil)
+}
+
+func (s *LedgerTestSuite) Test_Freeze() {
+	Convey("Ledger.Freeze", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+		userID := int64(2)
+		now := time.Now().UTC()
+
+		s.seedTenantUser(ctx, tenantID, userID, 1000, 0)
+
+		Convey("金额非法应返回参数错误", func() {
+			_, err := Ledger.Freeze(ctx, tenantID, userID, 0, 0, "k_freeze_invalid_amount", "freeze", now)
+			So(err, ShouldNotBeNil)
+
+			var appErr *errorx.AppError
+			So(errors.As(err, &appErr), ShouldBeTrue)
+			So(appErr.Code, ShouldEqual, errorx.CodeInvalidParameter)
+		})
+
+		Convey("成功冻结", func() {
+			res, err := Ledger.Freeze(ctx, tenantID, userID, 0, 300, "k_freeze_1", "freeze", now)
+			So(err, ShouldBeNil)
+			So(res, ShouldNotBeNil)
+			So(res.Ledger, ShouldNotBeNil)
+			So(res.TenantUser, ShouldNotBeNil)
+			So(res.Ledger.Type, ShouldEqual, consts.TenantLedgerTypeFreeze)
+			So(res.Ledger.Amount, ShouldEqual, 300)
+			So(res.Ledger.BalanceBefore, ShouldEqual, 1000)
+			So(res.Ledger.BalanceAfter, ShouldEqual, 700)
+			So(res.Ledger.FrozenBefore, ShouldEqual, 0)
+			So(res.Ledger.FrozenAfter, ShouldEqual, 300)
+			So(res.TenantUser.Balance, ShouldEqual, 700)
+			So(res.TenantUser.BalanceFrozen, ShouldEqual, 300)
+		})
+
+		Convey("幂等键重复调用不应重复扣减", func() {
+			_, err := Ledger.Freeze(ctx, tenantID, userID, 0, 300, "k_freeze_idem", "freeze", now)
+			So(err, ShouldBeNil)
+
+			res2, err := Ledger.Freeze(ctx, tenantID, userID, 0, 300, "k_freeze_idem", "freeze", now.Add(time.Second))
+			So(err, ShouldBeNil)
+			So(res2, ShouldNotBeNil)
+			So(res2.Ledger, ShouldNotBeNil)
+			So(res2.Ledger.IdempotencyKey, ShouldEqual, "k_freeze_idem")
+
+			var tu2 models.TenantUser
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ?", tenantID, userID).First(&tu2).Error, ShouldBeNil)
+			So(tu2.Balance, ShouldEqual, 700)
+			So(tu2.BalanceFrozen, ShouldEqual, 300)
+		})
+
+		Convey("余额不足应返回前置条件失败", func() {
+			_, err := Ledger.Freeze(ctx, tenantID, userID, 0, 999999, "k_over", "freeze", now)
+			So(err, ShouldNotBeNil)
+
+			var appErr *errorx.AppError
+			So(errors.As(err, &appErr), ShouldBeTrue)
+			So(appErr.Code, ShouldEqual, errorx.CodePreconditionFailed)
+		})
+	})
+}
+
+func (s *LedgerTestSuite) Test_Unfreeze() {
+	Convey("Ledger.Unfreeze", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+		userID := int64(2)
+		now := time.Now().UTC()
+
+		s.seedTenantUser(ctx, tenantID, userID, 1000, 0)
+
+		Convey("金额非法应返回参数错误", func() {
+			_, err := Ledger.Unfreeze(ctx, tenantID, userID, 0, 0, "k_unfreeze_invalid_amount", "unfreeze", now)
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("冻结余额不足应返回前置条件失败", func() {
+			_, err := Ledger.Unfreeze(ctx, tenantID, userID, 0, 999999, "k_unfreeze_over", "unfreeze", now)
+			So(err, ShouldNotBeNil)
+
+			var appErr *errorx.AppError
+			So(errors.As(err, &appErr), ShouldBeTrue)
+			So(appErr.Code, ShouldEqual, errorx.CodePreconditionFailed)
+		})
+
+		Convey("成功解冻", func() {
+			_, err := Ledger.Freeze(ctx, tenantID, userID, 0, 300, "k_freeze_for_unfreeze", "freeze", now)
+			So(err, ShouldBeNil)
+
+			res, err := Ledger.Unfreeze(ctx, tenantID, userID, 0, 300, "k_unfreeze_ok", "unfreeze", now)
+			So(err, ShouldBeNil)
+			So(res, ShouldNotBeNil)
+			So(res.Ledger.Type, ShouldEqual, consts.TenantLedgerTypeUnfreeze)
+			So(res.TenantUser.Balance, ShouldEqual, 1000)
+			So(res.TenantUser.BalanceFrozen, ShouldEqual, 0)
+		})
+
+		Convey("幂等键重复调用不应重复入账", func() {
+			_, err := Ledger.Freeze(ctx, tenantID, userID, 0, 300, "k_freeze_for_unfreeze_idem", "freeze", now)
+			So(err, ShouldBeNil)
+
+			_, err = Ledger.Unfreeze(ctx, tenantID, userID, 0, 300, "k_unfreeze_idem", "unfreeze", now)
+			So(err, ShouldBeNil)
+
+			res2, err := Ledger.Unfreeze(ctx, tenantID, userID, 0, 300, "k_unfreeze_idem", "unfreeze", now.Add(time.Second))
+			So(err, ShouldBeNil)
+			So(res2, ShouldNotBeNil)
+
+			var tu2 models.TenantUser
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ?", tenantID, userID).First(&tu2).Error, ShouldBeNil)
+			So(tu2.Balance, ShouldEqual, 1000)
+			So(tu2.BalanceFrozen, ShouldEqual, 0)
+		})
+	})
+}
+
+func (s *LedgerTestSuite) Test_DebitPurchaseTx() {
+	Convey("Ledger.DebitPurchaseTx", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+		userID := int64(2)
+		now := time.Now().UTC()
+
+		s.seedTenantUser(ctx, tenantID, userID, 1000, 0)
+
+		Convey("金额非法应返回参数错误", func() {
+			_, err := Ledger.DebitPurchaseTx(ctx, _db, tenantID, userID, 123, 0, "k_debit_invalid_amount", "debit", now)
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("冻结余额不足应返回前置条件失败", func() {
+			_, err := Ledger.DebitPurchaseTx(ctx, _db, tenantID, userID, 123, 300, "k_debit_no_frozen", "debit", now)
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("成功扣款应减少冻结余额并保持可用余额不变", func() {
+			_, err := Ledger.Freeze(ctx, tenantID, userID, 0, 300, "k_freeze_for_debit", "freeze", now)
+			So(err, ShouldBeNil)
+
+			res, err := Ledger.DebitPurchaseTx(ctx, _db, tenantID, userID, 123, 300, "k_debit_1", "debit", now)
+			So(err, ShouldBeNil)
+			So(res, ShouldNotBeNil)
+			So(res.Ledger.Type, ShouldEqual, consts.TenantLedgerTypeDebitPurchase)
+			So(res.TenantUser.Balance, ShouldEqual, 700)
+			So(res.TenantUser.BalanceFrozen, ShouldEqual, 0)
+		})
+
+		Convey("幂等键重复调用不应重复扣减冻结余额", func() {
+			_, err := Ledger.Freeze(ctx, tenantID, userID, 0, 300, "k_freeze_for_debit_idem", "freeze", now)
+			So(err, ShouldBeNil)
+
+			_, err = Ledger.DebitPurchaseTx(ctx, _db, tenantID, userID, 123, 300, "k_debit_idem", "debit", now)
+			So(err, ShouldBeNil)
+
+			_, err = Ledger.DebitPurchaseTx(ctx, _db, tenantID, userID, 123, 300, "k_debit_idem", "debit", now.Add(time.Second))
+			So(err, ShouldBeNil)
+
+			var tu2 models.TenantUser
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ?", tenantID, userID).First(&tu2).Error, ShouldBeNil)
+			So(tu2.Balance, ShouldEqual, 700)
+			So(tu2.BalanceFrozen, ShouldEqual, 0)
+		})
+	})
+}
+
+func (s *LedgerTestSuite) Test_CreditRefundTx() {
+	Convey("Ledger.CreditRefundTx", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+		userID := int64(2)
+		now := time.Now().UTC()
+
+		s.seedTenantUser(ctx, tenantID, userID, 1000, 0)
+
+		Convey("金额非法应返回参数错误", func() {
+			_, err := Ledger.CreditRefundTx(ctx, _db, tenantID, userID, 123, 0, "k_refund_invalid_amount", "refund", now)
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("成功退款应增加可用余额", func() {
+			_, err := Ledger.Freeze(ctx, tenantID, userID, 0, 300, "k_freeze_for_refund", "freeze", now)
+			So(err, ShouldBeNil)
+			_, err = Ledger.DebitPurchaseTx(ctx, _db, tenantID, userID, 123, 300, "k_debit_for_refund", "debit", now)
+			So(err, ShouldBeNil)
+
+			res, err := Ledger.CreditRefundTx(ctx, _db, tenantID, userID, 123, 300, "k_refund_1", "refund", now)
+			So(err, ShouldBeNil)
+			So(res, ShouldNotBeNil)
+			So(res.Ledger.Type, ShouldEqual, consts.TenantLedgerTypeCreditRefund)
+			So(res.TenantUser.Balance, ShouldEqual, 1000)
+			So(res.TenantUser.BalanceFrozen, ShouldEqual, 0)
+		})
+
+		Convey("幂等键重复调用不应重复退款入账", func() {
+			_, err := Ledger.Freeze(ctx, tenantID, userID, 0, 300, "k_freeze_for_refund_idem", "freeze", now)
+			So(err, ShouldBeNil)
+			_, err = Ledger.DebitPurchaseTx(ctx, _db, tenantID, userID, 123, 300, "k_debit_for_refund_idem", "debit", now)
+			So(err, ShouldBeNil)
+
+			_, err = Ledger.CreditRefundTx(ctx, _db, tenantID, userID, 123, 300, "k_refund_idem", "refund", now)
+			So(err, ShouldBeNil)
+			_, err = Ledger.CreditRefundTx(ctx, _db, tenantID, userID, 123, 300, "k_refund_idem", "refund", now.Add(time.Second))
+			So(err, ShouldBeNil)
+
+			var tu2 models.TenantUser
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ?", tenantID, userID).First(&tu2).Error, ShouldBeNil)
+			So(tu2.Balance, ShouldEqual, 1000)
+		})
+	})
+}
+
+func (s *LedgerTestSuite) Test_CreditTopupTx() {
+	Convey("Ledger.CreditTopupTx", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+		userID := int64(2)
+		now := time.Now().UTC()
+
+		s.seedTenantUser(ctx, tenantID, userID, 1000, 0)
+
+		Convey("金额非法应返回参数错误", func() {
+			_, err := Ledger.CreditTopupTx(ctx, _db, tenantID, userID, 456, 0, "k_topup_invalid_amount", "topup", now)
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("成功充值应增加可用余额并写入账本", func() {
+			res, err := Ledger.CreditTopupTx(ctx, _db, tenantID, userID, 456, 200, "k_topup_1", "topup", now)
+			So(err, ShouldBeNil)
+			So(res, ShouldNotBeNil)
+			So(res.Ledger.Type, ShouldEqual, consts.TenantLedgerTypeCreditTopup)
+			So(res.TenantUser.Balance, ShouldEqual, 1200)
+			So(res.TenantUser.BalanceFrozen, ShouldEqual, 0)
+		})
+
+		Convey("幂等键重复调用不应重复充值入账", func() {
+			_, err := Ledger.CreditTopupTx(ctx, _db, tenantID, userID, 456, 200, "k_topup_idem", "topup", now)
+			So(err, ShouldBeNil)
+			_, err = Ledger.CreditTopupTx(ctx, _db, tenantID, userID, 456, 200, "k_topup_idem", "topup", now.Add(time.Second))
+			So(err, ShouldBeNil)
+
+			var tu2 models.TenantUser
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ?", tenantID, userID).First(&tu2).Error, ShouldBeNil)
+			So(tu2.Balance, ShouldEqual, 1200)
+		})
+	})
+}

backend/app/services/order.go

@@ -22,33 +22,33 @@ import (
 	"go.ipao.vip/gen/types"
 )
 
-// PurchaseContentParams defines parameters for purchasing a content within a tenant using tenant balance.
+// PurchaseContentParams 定义“租户内使用余额购买内容”的入参。
 type PurchaseContentParams struct {
-	// TenantID is the tenant scope.
+	// TenantID 租户 ID（多租户隔离范围）。
 	TenantID int64
-	// UserID is the buyer user id.
+	// UserID 购买者用户 ID。
 	UserID int64
-	// ContentID is the target content id.
+	// ContentID 内容 ID。
 	ContentID int64
-	// IdempotencyKey is used to ensure a purchase request is processed at most once.
+	// IdempotencyKey 幂等键：用于确保同一购买请求“至多处理一次”。
 	IdempotencyKey string
-	// Now is the logical time used for created_at/paid_at and ledger snapshots (optional).
+	// Now 逻辑时间：用于 created_at/paid_at 与账本快照（可选，便于测试/一致性）。
 	Now time.Time
 }
 
-// PurchaseContentResult is returned after purchase attempt (idempotent hit returns existing order/access state).
+// PurchaseContentResult 为购买结果（幂等命中时返回已存在的订单/权益状态）。
 type PurchaseContentResult struct {
-	// Order is the created or existing order record (may be nil when already purchased without order context).
+	// Order 订单记录（可能为 nil：例如“已购买且无订单上下文”的快捷路径）。
 	Order *models.Order
-	// OrderItem is the related order item record (single-item purchase).
+	// OrderItem 订单明细（本业务为单内容购买，通常只有 1 条）。
 	OrderItem *models.OrderItem
-	// Access is the content access record after purchase grant.
+	// Access 内容权益（购买完成后应为 active）。
 	Access *models.ContentAccess
-	// AmountPaid is the final paid amount in cents (CNY 分).
+	// AmountPaid 实付金额（单位：分，CNY）。
 	AmountPaid int64
 }
 
-// order provides order domain operations.
+// order 提供订单域能力（购买、充值、退款、查询等）。
 //
 //	@provider
 type order struct {
@@ -56,8 +56,13 @@ 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) {
+// AdminTopupUser 租户管理员给租户成员充值（增加该租户下的可用余额）。
+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")
 	}
@@ -79,7 +84,7 @@ func (s *order) AdminTopupUser(ctx context.Context, tenantID, operatorUserID, ta
 	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"}).
@@ -91,7 +96,7 @@ func (s *order) AdminTopupUser(ctx context.Context, tenantID, operatorUserID, ta
 			return err
 		}
 
-		// Idempotent by (tenant_id, user_id, idempotency_key) on orders.
+		// 充值幂等：按 orders(tenant_id,user_id,idempotency_key) 去重，避免重复入账。
 		if idempotencyKey != "" {
 			var existing models.Order
 			if err := tx.Where(
@@ -105,6 +110,7 @@ func (s *order) AdminTopupUser(ctx context.Context, tenantID, operatorUserID, ta
 			}
 		}
 
+		// 先落订单（paid），再写入账本（credit_topup），确保“订单可追溯 + 账本可对账”。
 		orderModel := models.Order{
 			TenantID:       tenantID,
 			UserID:         targetUserID,
@@ -124,6 +130,7 @@ func (s *order) AdminTopupUser(ctx context.Context, tenantID, operatorUserID, ta
 			return err
 		}
 
+		// 账本幂等键固定使用 topup:<orderID>，保证同一订单不会重复入账。
 		ledgerKey := fmt.Sprintf("topup:%d", orderModel.ID)
 		remark := reason
 		if remark == "" {
@@ -157,8 +164,12 @@ func (s *order) AdminTopupUser(ctx context.Context, tenantID, operatorUserID, ta
 	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) {
+// MyOrderPage 分页查询当前用户在租户内的订单。
+func (s *order) MyOrderPage(
+	ctx context.Context,
+	tenantID, userID int64,
+	filter *dto.MyOrderListFilter,
+) (*requests.Pager, error) {
 	if tenantID <= 0 || userID <= 0 {
 		return nil, errorx.ErrInvalidParameter.WithMsg("tenant_id/user_id must be > 0")
 	}
@@ -197,7 +208,7 @@ func (s *order) MyOrderPage(ctx context.Context, tenantID, userID int64, filter
 	}, nil
 }
 
-// MyOrderDetail returns order detail for current user within a tenant.
+// MyOrderDetail 查询当前用户在租户内的订单详情。
 func (s *order) MyOrderDetail(ctx context.Context, tenantID, userID, orderID int64) (*models.Order, error) {
 	if tenantID <= 0 || userID <= 0 || orderID <= 0 {
 		return nil, errorx.ErrInvalidParameter.WithMsg("tenant_id/user_id/order_id must be > 0")
@@ -221,8 +232,12 @@ func (s *order) MyOrderDetail(ctx context.Context, tenantID, userID, orderID int
 	return m, nil
 }
 
-// AdminOrderPage lists orders within a tenant for tenant-admin.
-func (s *order) AdminOrderPage(ctx context.Context, tenantID int64, filter *dto.AdminOrderListFilter) (*requests.Pager, error) {
+// AdminOrderPage 租户管理员分页查询租户内订单。
+func (s *order) AdminOrderPage(
+	ctx context.Context,
+	tenantID int64,
+	filter *dto.AdminOrderListFilter,
+) (*requests.Pager, error) {
 	if tenantID <= 0 {
 		return nil, errorx.ErrInvalidParameter.WithMsg("tenant_id must be > 0")
 	}
@@ -261,7 +276,7 @@ func (s *order) AdminOrderPage(ctx context.Context, tenantID int64, filter *dto.
 	}, nil
 }
 
-// AdminOrderDetail returns an order detail within a tenant for tenant-admin.
+// AdminOrderDetail 租户管理员查询租户内订单详情。
 func (s *order) AdminOrderDetail(ctx context.Context, tenantID, orderID int64) (*models.Order, error) {
 	if tenantID <= 0 || orderID <= 0 {
 		return nil, errorx.ErrInvalidParameter.WithMsg("tenant_id/order_id must be > 0")
@@ -280,8 +295,14 @@ func (s *order) AdminOrderDetail(ctx context.Context, tenantID, orderID int64) (
 	return m, nil
 }
 
-// AdminRefundOrder refunds a paid order (supports forced refund) and revokes granted content access.
-func (s *order) AdminRefundOrder(ctx context.Context, tenantID, operatorUserID, orderID int64, force bool, reason, idempotencyKey string, now time.Time) (*models.Order, error) {
+// AdminRefundOrder 退款已支付订单（支持强制退款），并立即回收已授予的内容权益。
+func (s *order) AdminRefundOrder(
+	ctx context.Context,
+	tenantID, operatorUserID, orderID int64,
+	force bool,
+	reason, idempotencyKey string,
+	now time.Time,
+) (*models.Order, error) {
 	if tenantID <= 0 || operatorUserID <= 0 || orderID <= 0 {
 		return nil, errorx.ErrInvalidParameter.WithMsg("tenant_id/operator_user_id/order_id must be > 0")
 	}
@@ -300,6 +321,7 @@ func (s *order) AdminRefundOrder(ctx context.Context, tenantID, operatorUserID,
 	var out *models.Order
 
 	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// 行锁锁住订单，避免并发退款/重复退款导致状态错乱。
 		var orderModel models.Order
 		if err := tx.
 			Clauses(clause.Locking{Strength: "UPDATE"}).
@@ -309,6 +331,7 @@ func (s *order) AdminRefundOrder(ctx context.Context, tenantID, operatorUserID,
 			return err
 		}
 
+		// 状态机：已退款直接幂等返回；仅允许已支付订单退款。
 		if orderModel.Status == consts.OrderStatusRefunded {
 			out = &orderModel
 			return nil
@@ -320,6 +343,7 @@ func (s *order) AdminRefundOrder(ctx context.Context, tenantID, operatorUserID,
 			return errorx.ErrPreconditionFailed.WithMsg("订单缺少 paid_at，无法退款")
 		}
 
+		// 时间窗：默认 paid_at + 24h；force=true 可绕过。
 		if !force {
 			deadline := orderModel.PaidAt.Add(consts.DefaultOrderRefundWindow)
 			if now.After(deadline) {
@@ -330,13 +354,14 @@ func (s *order) AdminRefundOrder(ctx context.Context, tenantID, operatorUserID,
 		amount := orderModel.AmountPaid
 		refundKey := fmt.Sprintf("refund:%d", orderModel.ID)
 
+		// 先退余额（账本入账），后更新订单状态与权益，确保退款可对账且可追溯。
 		if amount > 0 {
 			if _, err := s.ledger.CreditRefundTx(ctx, tx, tenantID, orderModel.UserID, orderModel.ID, amount, refundKey, reason, now); err != nil {
 				return err
 			}
 		}
 
-		// revoke content access immediately
+		// 退款对权益：立即回收 content_access（revoked）。
 		for _, item := range orderModel.Items {
 			if item == nil {
 				continue
@@ -352,6 +377,7 @@ func (s *order) AdminRefundOrder(ctx context.Context, tenantID, operatorUserID,
 			}
 		}
 
+		// 最后更新订单退款字段，保证退款后的最终状态一致。
 		if err := tx.Table(models.TableNameOrder).
 			Where("id = ?", orderModel.ID).
 			Updates(map[string]any{
@@ -419,16 +445,16 @@ func (s *order) PurchaseContent(ctx context.Context, params *PurchaseContentPara
 
 	var out PurchaseContentResult
 
-	// If idempotency key is present, use a 3-step flow to ensure:
-	// - freeze is committed first (reserve funds),
-	// - order+debit are committed together,
-	// - on debit failure, we unfreeze and persist a rollback marker so retries return "failed+rolled back".
+	// 幂等购买采用“三段式”流程，保证一致性：
+	// 1) 先独立事务冻结余额（预留资金）；
+	// 2) 再用单事务写订单+扣款+授予权益；
+	// 3) 若第 2 步失败，则解冻并写入回滚标记，保证重试稳定返回“失败+已回滚”。
 	if params.IdempotencyKey != "" {
 		freezeKey := fmt.Sprintf("%s:freeze", params.IdempotencyKey)
 		debitKey := fmt.Sprintf("%s:debit", params.IdempotencyKey)
 		rollbackKey := fmt.Sprintf("%s:rollback", params.IdempotencyKey)
 
-		// 1) If we already have an order for this idempotency key, return it.
+		// 1) 若该幂等键已生成订单，则直接返回订单与权益（幂等命中）。
 		{
 			tbl, query := models.OrderQuery.QueryContext(ctx)
 			existing, err := query.Preload(tbl.Items).Where(
@@ -460,7 +486,7 @@ func (s *order) PurchaseContent(ctx context.Context, params *PurchaseContentPara
 			}
 		}
 
-		// 2) If we previously rolled back this purchase, return stable failure.
+		// 2) 若历史已回滚过该幂等请求，则稳定返回“失败+已回滚”（避免重复冻结/重复扣款）。
 		{
 			tbl, query := models.TenantLedgerQuery.QueryContext(ctx)
 			_, err := query.Where(
@@ -476,7 +502,7 @@ func (s *order) PurchaseContent(ctx context.Context, params *PurchaseContentPara
 			}
 		}
 
-		// Load content + price outside tx for simplicity.
+		// 查询内容与价格：放在事务外简化逻辑；后续以订单事务为准。
 		var content models.Content
 		{
 			tbl, query := models.ContentQuery.QueryContext(ctx)
@@ -494,7 +520,7 @@ func (s *order) PurchaseContent(ctx context.Context, params *PurchaseContentPara
 			return nil, errorx.ErrPreconditionFailed.WithMsg("content not published")
 		}
 
-		// owner shortcut
+		// 作者自购：直接授予权益（不走余额冻结/扣款）。
 		if content.UserID == params.UserID {
 			err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 				if err := s.grantAccess(ctx, tx, params.TenantID, params.UserID, params.ContentID, 0, now); err != nil {
@@ -533,7 +559,7 @@ func (s *order) PurchaseContent(ctx context.Context, params *PurchaseContentPara
 		amountPaid := s.computeFinalPrice(priceAmount, &price, now)
 		out.AmountPaid = amountPaid
 
-		// free path: no freeze needed; keep single tx.
+		// 免费内容：无需冻结，保持单事务写订单+权益。
 		if amountPaid == 0 {
 			err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 				orderModel := &models.Order{
@@ -586,7 +612,7 @@ func (s *order) PurchaseContent(ctx context.Context, params *PurchaseContentPara
 			return &out, nil
 		}
 
-		// 3) Freeze in its own transaction so we can compensate later.
+		// 3) 独立事务冻结余额：便于后续在订单事务失败时做补偿解冻。
 		if err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 			_, err := s.ledger.FreezeTx(ctx, tx, params.TenantID, params.UserID, 0, amountPaid, freezeKey, "purchase freeze", now)
 			return err
@@ -594,7 +620,7 @@ func (s *order) PurchaseContent(ctx context.Context, params *PurchaseContentPara
 			return nil, pkgerrors.Wrap(err, "purchase freeze failed")
 		}
 
-		// 4) Create order + debit + access in a single transaction.
+		// 4) 单事务完成：落订单 → 账本扣款（消耗冻结）→ 更新订单 paid → 授予权益。
 		if err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 			orderModel := &models.Order{
 				TenantID:       params.TenantID,
@@ -653,9 +679,19 @@ func (s *order) PurchaseContent(ctx context.Context, params *PurchaseContentPara
 			out.Access = &access
 			return nil
 		}); err != nil {
-			// 5) Compensate: unfreeze and persist rollback marker.
+			// 5) 补偿：订单事务失败时，必须解冻，并写入回滚标记，保证后续幂等重试稳定返回失败。
 			_ = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-				_, e1 := s.ledger.UnfreezeTx(ctx, tx, params.TenantID, params.UserID, 0, amountPaid, rollbackKey, "purchase rollback", now)
+				_, e1 := s.ledger.UnfreezeTx(
+					ctx,
+					tx,
+					params.TenantID,
+					params.UserID,
+					0,
+					amountPaid,
+					rollbackKey,
+					"purchase rollback",
+					now,
+				)
 				return e1
 			})
 			logrus.WithFields(logrus.Fields{
@@ -679,7 +715,7 @@ func (s *order) PurchaseContent(ctx context.Context, params *PurchaseContentPara
 		return &out, nil
 	}
 
-	// Legacy atomic transaction path for requests without idempotency key.
+	// 非幂等请求走“单事务”旧流程：冻结 + 落单 + 扣款 + 授权全部在一个事务内完成（失败整体回滚）。
 	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 		var content models.Content
 		if err := tx.
@@ -852,6 +888,7 @@ func (s *order) PurchaseContent(ctx context.Context, params *PurchaseContentPara
 }
 
 func (s *order) computeFinalPrice(priceAmount int64, price *models.ContentPrice, now time.Time) int64 {
+	// 价格计算：按折扣策略与生效时间窗口计算最终实付金额（单位：分）。
 	if priceAmount <= 0 || price == nil {
 		return 0
 	}
@@ -892,7 +929,13 @@ func (s *order) computeFinalPrice(priceAmount int64, price *models.ContentPrice,
 	}
 }
 
-func (s *order) grantAccess(ctx context.Context, tx *gorm.DB, tenantID, userID, contentID, orderID int64, now time.Time) error {
+func (s *order) grantAccess(
+	ctx context.Context,
+	tx *gorm.DB,
+	tenantID, userID, contentID, orderID int64,
+	now time.Time,
+) error {
+	// 权益写入策略：按 (tenant_id,user_id,content_id) upsert，确保重复购买/重试时权益最终为 active。
 	insert := map[string]any{
 		"tenant_id":  tenantID,
 		"user_id":    userID,

backend/app/services/order_test.go

@@ -0,0 +1,586 @@
+package services
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"testing"
+	"time"
+
+	"quyun/v2/app/commands/testx"
+	"quyun/v2/app/errorx"
+	"quyun/v2/app/http/tenant/dto"
+	"quyun/v2/database"
+	"quyun/v2/database/models"
+	"quyun/v2/pkg/consts"
+
+	. "github.com/smartystreets/goconvey/convey"
+	"github.com/stretchr/testify/suite"
+
+	_ "go.ipao.vip/atom"
+	"go.ipao.vip/atom/contracts"
+	"go.ipao.vip/gen/types"
+	"go.uber.org/dig"
+)
+
+type OrderTestSuiteInjectParams struct {
+	dig.In
+
+	DB       *sql.DB
+	Initials []contracts.Initial `group:"initials"` // nolint:structcheck
+}
+
+type OrderTestSuite struct {
+	suite.Suite
+	OrderTestSuiteInjectParams
+}
+
+func Test_Order(t *testing.T) {
+	providers := testx.Default().With(Provide)
+
+	testx.Serve(providers, t, func(p OrderTestSuiteInjectParams) {
+		suite.Run(t, &OrderTestSuite{OrderTestSuiteInjectParams: p})
+	})
+}
+
+func (s *OrderTestSuite) truncate(ctx context.Context, tableNames ...string) {
+	database.Truncate(ctx, s.DB, tableNames...)
+}
+
+func (s *OrderTestSuite) seedTenantUser(ctx context.Context, tenantID, userID, balance, frozen int64) {
+	tu := &models.TenantUser{
+		TenantID:      tenantID,
+		UserID:        userID,
+		Role:          types.NewArray([]consts.TenantUserRole{consts.TenantUserRoleMember}),
+		Balance:       balance,
+		BalanceFrozen: frozen,
+		Status:        consts.UserStatusVerified,
+	}
+	So(tu.Create(ctx), ShouldBeNil)
+}
+
+func (s *OrderTestSuite) seedPublishedContent(ctx context.Context, tenantID, ownerUserID int64) *models.Content {
+	m := &models.Content{
+		TenantID:            tenantID,
+		UserID:              ownerUserID,
+		Title:               "标题",
+		Description:         "描述",
+		Status:              consts.ContentStatusPublished,
+		Visibility:          consts.ContentVisibilityTenantOnly,
+		PreviewSeconds:      consts.DefaultContentPreviewSeconds,
+		PreviewDownloadable: false,
+		PublishedAt:         time.Now().UTC(),
+	}
+	So(m.Create(ctx), ShouldBeNil)
+	return m
+}
+
+func (s *OrderTestSuite) seedContentPrice(ctx context.Context, tenantID, contentID, priceAmount int64) {
+	p := &models.ContentPrice{
+		TenantID:       tenantID,
+		UserID:         1,
+		ContentID:      contentID,
+		Currency:       consts.CurrencyCNY,
+		PriceAmount:    priceAmount,
+		DiscountType:   consts.DiscountTypeNone,
+		DiscountValue:  0,
+		DiscountStartAt: time.Time{},
+		DiscountEndAt:   time.Time{},
+	}
+	So(p.Create(ctx), ShouldBeNil)
+}
+
+func (s *OrderTestSuite) Test_AdminTopupUser() {
+	Convey("Order.AdminTopupUser", s.T(), func() {
+		ctx := s.T().Context()
+		now := time.Now().UTC()
+		tenantID := int64(1)
+		operatorUserID := int64(10)
+		targetUserID := int64(20)
+
+		s.truncate(
+			ctx,
+			models.TableNameTenantLedger,
+			models.TableNameOrderItem,
+			models.TableNameOrder,
+			models.TableNameTenantUser,
+		)
+
+		Convey("参数非法应返回错误", func() {
+			_, err := Order.AdminTopupUser(ctx, 0, operatorUserID, targetUserID, 100, "", "", now)
+			So(err, ShouldNotBeNil)
+
+			_, err = Order.AdminTopupUser(ctx, tenantID, 0, targetUserID, 100, "", "", now)
+			So(err, ShouldNotBeNil)
+
+			_, err = Order.AdminTopupUser(ctx, tenantID, operatorUserID, 0, 100, "", "", now)
+			So(err, ShouldNotBeNil)
+
+			_, err = Order.AdminTopupUser(ctx, tenantID, operatorUserID, targetUserID, 0, "", "", now)
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("目标用户不属于该租户应返回前置条件失败", func() {
+			_, err := Order.AdminTopupUser(ctx, tenantID, operatorUserID, targetUserID, 100, "idem_not_member", "", now)
+			So(err, ShouldNotBeNil)
+
+			var appErr *errorx.AppError
+			So(errors.As(err, &appErr), ShouldBeTrue)
+			So(appErr.Code, ShouldEqual, errorx.CodePreconditionFailed)
+		})
+
+		Convey("成功充值并写入账本", func() {
+			s.seedTenantUser(ctx, tenantID, targetUserID, 0, 0)
+
+			orderModel, err := Order.AdminTopupUser(ctx, tenantID, operatorUserID, targetUserID, 300, "idem_topup_1", "充值原因", now)
+			So(err, ShouldBeNil)
+			So(orderModel, ShouldNotBeNil)
+			So(orderModel.ID, ShouldBeGreaterThan, 0)
+			So(orderModel.Type, ShouldEqual, consts.OrderTypeTopup)
+			So(orderModel.Status, ShouldEqual, consts.OrderStatusPaid)
+			So(orderModel.AmountPaid, ShouldEqual, 300)
+
+			var tu models.TenantUser
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ?", tenantID, targetUserID).First(&tu).Error, ShouldBeNil)
+			So(tu.Balance, ShouldEqual, 300)
+
+			var ledgers []*models.TenantLedger
+			So(_db.WithContext(ctx).
+				Where("tenant_id = ? AND user_id = ? AND type = ?", tenantID, targetUserID, consts.TenantLedgerTypeCreditTopup).
+				Order("id ASC").
+				Find(&ledgers).Error, ShouldBeNil)
+			So(len(ledgers), ShouldEqual, 1)
+			So(ledgers[0].OrderID, ShouldEqual, orderModel.ID)
+			So(ledgers[0].Amount, ShouldEqual, 300)
+		})
+
+		Convey("幂等键重复调用不应重复入账", func() {
+			s.seedTenantUser(ctx, tenantID, targetUserID, 0, 0)
+
+			o1, err := Order.AdminTopupUser(ctx, tenantID, operatorUserID, targetUserID, 300, "idem_topup_2", "充值原因", now)
+			So(err, ShouldBeNil)
+			So(o1, ShouldNotBeNil)
+
+			o2, err := Order.AdminTopupUser(ctx, tenantID, operatorUserID, targetUserID, 999, "idem_topup_2", "不同金额也不应重复处理", now.Add(time.Second))
+			So(err, ShouldBeNil)
+			So(o2, ShouldNotBeNil)
+			So(o2.ID, ShouldEqual, o1.ID)
+
+			var tu models.TenantUser
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ?", tenantID, targetUserID).First(&tu).Error, ShouldBeNil)
+			So(tu.Balance, ShouldEqual, 300)
+		})
+	})
+}
+
+func (s *OrderTestSuite) Test_MyOrderPage() {
+	Convey("Order.MyOrderPage", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+		userID := int64(2)
+
+		s.truncate(ctx, models.TableNameOrder, models.TableNameOrderItem)
+
+		Convey("参数非法应返回错误", func() {
+			_, err := Order.MyOrderPage(ctx, 0, userID, &dto.MyOrderListFilter{})
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("空数据应返回 total=0", func() {
+			pager, err := Order.MyOrderPage(ctx, tenantID, userID, &dto.MyOrderListFilter{})
+			So(err, ShouldBeNil)
+			So(pager.Total, ShouldEqual, 0)
+		})
+	})
+}
+
+func (s *OrderTestSuite) Test_MyOrderDetail() {
+	Convey("Order.MyOrderDetail", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+		userID := int64(2)
+
+		s.truncate(ctx, models.TableNameOrder, models.TableNameOrderItem)
+
+		Convey("参数非法应返回错误", func() {
+			_, err := Order.MyOrderDetail(ctx, 0, userID, 1)
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("订单不存在应返回错误", func() {
+			_, err := Order.MyOrderDetail(ctx, tenantID, userID, 999)
+			So(err, ShouldNotBeNil)
+		})
+	})
+}
+
+func (s *OrderTestSuite) Test_AdminOrderPage() {
+	Convey("Order.AdminOrderPage", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+
+		s.truncate(ctx, models.TableNameOrder, models.TableNameOrderItem)
+
+		Convey("参数非法应返回错误", func() {
+			_, err := Order.AdminOrderPage(ctx, 0, &dto.AdminOrderListFilter{})
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("空数据应返回 total=0", func() {
+			pager, err := Order.AdminOrderPage(ctx, tenantID, &dto.AdminOrderListFilter{})
+			So(err, ShouldBeNil)
+			So(pager.Total, ShouldEqual, 0)
+		})
+	})
+}
+
+func (s *OrderTestSuite) Test_AdminOrderDetail() {
+	Convey("Order.AdminOrderDetail", s.T(), func() {
+		ctx := s.T().Context()
+		tenantID := int64(1)
+
+		s.truncate(ctx, models.TableNameOrder, models.TableNameOrderItem)
+
+		Convey("参数非法应返回错误", func() {
+			_, err := Order.AdminOrderDetail(ctx, 0, 1)
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("订单不存在应返回错误", func() {
+			_, err := Order.AdminOrderDetail(ctx, tenantID, 999)
+			So(err, ShouldNotBeNil)
+		})
+	})
+}
+
+func (s *OrderTestSuite) Test_AdminRefundOrder() {
+	Convey("Order.AdminRefundOrder", s.T(), func() {
+		ctx := s.T().Context()
+		now := time.Now().UTC()
+		tenantID := int64(1)
+		operatorUserID := int64(10)
+		buyerUserID := int64(20)
+
+		s.truncate(
+			ctx,
+			models.TableNameTenantLedger,
+			models.TableNameContentAccess,
+			models.TableNameOrderItem,
+			models.TableNameOrder,
+			models.TableNameTenantUser,
+		)
+
+		Convey("参数非法应返回错误", func() {
+			_, err := Order.AdminRefundOrder(ctx, 0, operatorUserID, 1, false, "", "", now)
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("订单非已支付状态应返回状态冲突", func() {
+			s.seedTenantUser(ctx, tenantID, buyerUserID, 0, 0)
+
+			orderModel := &models.Order{
+				TenantID:       tenantID,
+				UserID:         buyerUserID,
+				Type:           consts.OrderTypeContentPurchase,
+				Status:         consts.OrderStatusCreated,
+				Currency:       consts.CurrencyCNY,
+				AmountOriginal: 100,
+				AmountDiscount: 0,
+				AmountPaid:     100,
+				Snapshot:       types.JSON([]byte("{}")),
+				PaidAt:         now,
+				CreatedAt:      now,
+				UpdatedAt:      now,
+			}
+			So(orderModel.Create(ctx), ShouldBeNil)
+
+			_, err := Order.AdminRefundOrder(ctx, tenantID, operatorUserID, orderModel.ID, false, "原因", "", now)
+			So(err, ShouldNotBeNil)
+
+			var appErr *errorx.AppError
+			So(errors.As(err, &appErr), ShouldBeTrue)
+			So(appErr.Code, ShouldEqual, errorx.CodeStatusConflict)
+		})
+
+		Convey("已超过默认退款时间窗且非强制应失败", func() {
+			s.seedTenantUser(ctx, tenantID, buyerUserID, 0, 0)
+
+			orderModel := &models.Order{
+				TenantID:       tenantID,
+				UserID:         buyerUserID,
+				Type:           consts.OrderTypeContentPurchase,
+				Status:         consts.OrderStatusPaid,
+				Currency:       consts.CurrencyCNY,
+				AmountOriginal: 100,
+				AmountDiscount: 0,
+				AmountPaid:     100,
+				Snapshot:       types.JSON([]byte("{}")),
+				PaidAt:         now.Add(-consts.DefaultOrderRefundWindow).Add(-time.Second),
+				CreatedAt:      now,
+				UpdatedAt:      now,
+			}
+			So(orderModel.Create(ctx), ShouldBeNil)
+
+			_, err := Order.AdminRefundOrder(ctx, tenantID, operatorUserID, orderModel.ID, false, "原因", "", now)
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("成功退款应回收权益并入账", func() {
+			s.seedTenantUser(ctx, tenantID, buyerUserID, 0, 0)
+
+			contentID := int64(123)
+			orderModel := &models.Order{
+				TenantID:       tenantID,
+				UserID:         buyerUserID,
+				Type:           consts.OrderTypeContentPurchase,
+				Status:         consts.OrderStatusPaid,
+				Currency:       consts.CurrencyCNY,
+				AmountOriginal: 300,
+				AmountDiscount: 0,
+				AmountPaid:     300,
+				Snapshot:       types.JSON([]byte("{}")),
+				PaidAt:         now,
+				CreatedAt:      now,
+				UpdatedAt:      now,
+			}
+			So(orderModel.Create(ctx), ShouldBeNil)
+
+			item := &models.OrderItem{
+				TenantID:      tenantID,
+				UserID:        buyerUserID,
+				OrderID:       orderModel.ID,
+				ContentID:     contentID,
+				ContentUserID: 999,
+				AmountPaid:    300,
+				Snapshot:      types.JSON([]byte("{}")),
+				CreatedAt:     now,
+				UpdatedAt:     now,
+			}
+			So(item.Create(ctx), ShouldBeNil)
+
+			access := &models.ContentAccess{
+				TenantID:   tenantID,
+				UserID:     buyerUserID,
+				ContentID:  contentID,
+				OrderID:    orderModel.ID,
+				Status:     consts.ContentAccessStatusActive,
+				CreatedAt:  now,
+				UpdatedAt:  now,
+				RevokedAt:  time.Time{},
+			}
+			So(access.Create(ctx), ShouldBeNil)
+
+			refunded, err := Order.AdminRefundOrder(ctx, tenantID, operatorUserID, orderModel.ID, false, "原因", "", now.Add(time.Minute))
+			So(err, ShouldBeNil)
+			So(refunded, ShouldNotBeNil)
+			So(refunded.Status, ShouldEqual, consts.OrderStatusRefunded)
+
+			var tu models.TenantUser
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ?", tenantID, buyerUserID).First(&tu).Error, ShouldBeNil)
+			So(tu.Balance, ShouldEqual, 300)
+
+			var access2 models.ContentAccess
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ? AND content_id = ?", tenantID, buyerUserID, contentID).First(&access2).Error, ShouldBeNil)
+			So(access2.Status, ShouldEqual, consts.ContentAccessStatusRevoked)
+			So(access2.RevokedAt.IsZero(), ShouldBeFalse)
+
+			refunded2, err := Order.AdminRefundOrder(ctx, tenantID, operatorUserID, orderModel.ID, false, "原因2", "", now.Add(2*time.Minute))
+			So(err, ShouldBeNil)
+			So(refunded2.Status, ShouldEqual, consts.OrderStatusRefunded)
+
+			var tu2 models.TenantUser
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ?", tenantID, buyerUserID).First(&tu2).Error, ShouldBeNil)
+			So(tu2.Balance, ShouldEqual, 300)
+
+			var ledgers []*models.TenantLedger
+			So(_db.WithContext(ctx).
+				Where("tenant_id = ? AND user_id = ? AND idempotency_key = ?", tenantID, buyerUserID, fmt.Sprintf("refund:%d", orderModel.ID)).
+				Find(&ledgers).Error, ShouldBeNil)
+			So(len(ledgers), ShouldEqual, 1)
+		})
+	})
+}
+
+func (s *OrderTestSuite) Test_PurchaseContent() {
+	Convey("Order.PurchaseContent", s.T(), func() {
+		ctx := s.T().Context()
+		now := time.Now().UTC()
+		tenantID := int64(1)
+		ownerUserID := int64(100)
+		buyerUserID := int64(200)
+
+		s.truncate(
+			ctx,
+			models.TableNameTenantLedger,
+			models.TableNameContentAccess,
+			models.TableNameOrderItem,
+			models.TableNameOrder,
+			models.TableNameContentPrice,
+			models.TableNameContent,
+			models.TableNameTenantUser,
+		)
+
+		Convey("参数非法应返回错误", func() {
+			_, err := Order.PurchaseContent(ctx, nil)
+			So(err, ShouldNotBeNil)
+
+			_, err = Order.PurchaseContent(ctx, &PurchaseContentParams{TenantID: 0, UserID: 1, ContentID: 1})
+			So(err, ShouldNotBeNil)
+		})
+
+		Convey("内容未发布应返回前置条件失败", func() {
+			s.seedTenantUser(ctx, tenantID, buyerUserID, 1000, 0)
+
+			content := &models.Content{
+				TenantID:            tenantID,
+				UserID:              ownerUserID,
+				Title:               "标题",
+				Description:         "描述",
+				Status:              consts.ContentStatusDraft,
+				Visibility:          consts.ContentVisibilityTenantOnly,
+				PreviewSeconds:      consts.DefaultContentPreviewSeconds,
+				PreviewDownloadable: false,
+			}
+			So(content.Create(ctx), ShouldBeNil)
+
+			_, err := Order.PurchaseContent(ctx, &PurchaseContentParams{
+				TenantID:       tenantID,
+				UserID:         buyerUserID,
+				ContentID:      content.ID,
+				IdempotencyKey: "idem_not_published",
+				Now:            now,
+			})
+			So(err, ShouldNotBeNil)
+
+			var appErr *errorx.AppError
+			So(errors.As(err, &appErr), ShouldBeTrue)
+			So(appErr.Code, ShouldEqual, errorx.CodePreconditionFailed)
+		})
+
+		Convey("免费内容购买应创建订单并授予权益（幂等）", func() {
+			s.seedTenantUser(ctx, tenantID, buyerUserID, 1000, 0)
+			content := s.seedPublishedContent(ctx, tenantID, ownerUserID)
+
+			res1, err := Order.PurchaseContent(ctx, &PurchaseContentParams{
+				TenantID:       tenantID,
+				UserID:         buyerUserID,
+				ContentID:      content.ID,
+				IdempotencyKey: "idem_free_1",
+				Now:            now,
+			})
+			So(err, ShouldBeNil)
+			So(res1, ShouldNotBeNil)
+			So(res1.AmountPaid, ShouldEqual, 0)
+			So(res1.Order, ShouldNotBeNil)
+			So(res1.Order.Status, ShouldEqual, consts.OrderStatusPaid)
+			So(res1.Access, ShouldNotBeNil)
+			So(res1.Access.Status, ShouldEqual, consts.ContentAccessStatusActive)
+
+			res2, err := Order.PurchaseContent(ctx, &PurchaseContentParams{
+				TenantID:       tenantID,
+				UserID:         buyerUserID,
+				ContentID:      content.ID,
+				IdempotencyKey: "idem_free_1",
+				Now:            now.Add(time.Second),
+			})
+			So(err, ShouldBeNil)
+			So(res2.Order.ID, ShouldEqual, res1.Order.ID)
+		})
+
+		Convey("付费内容购买应冻结+扣款并授予权益（幂等）", func() {
+			s.truncate(
+				ctx,
+				models.TableNameTenantLedger,
+				models.TableNameContentAccess,
+				models.TableNameOrderItem,
+				models.TableNameOrder,
+				models.TableNameContentPrice,
+				models.TableNameContent,
+				models.TableNameTenantUser,
+			)
+			s.seedTenantUser(ctx, tenantID, buyerUserID, 1000, 0)
+			content := s.seedPublishedContent(ctx, tenantID, ownerUserID)
+			s.seedContentPrice(ctx, tenantID, content.ID, 300)
+
+			res1, err := Order.PurchaseContent(ctx, &PurchaseContentParams{
+				TenantID:       tenantID,
+				UserID:         buyerUserID,
+				ContentID:      content.ID,
+				IdempotencyKey: "idem_paid_1",
+				Now:            now,
+			})
+			So(err, ShouldBeNil)
+			So(res1, ShouldNotBeNil)
+			So(res1.AmountPaid, ShouldEqual, 300)
+			So(res1.Order, ShouldNotBeNil)
+			So(res1.Order.Status, ShouldEqual, consts.OrderStatusPaid)
+			So(res1.Access, ShouldNotBeNil)
+			So(res1.Access.Status, ShouldEqual, consts.ContentAccessStatusActive)
+
+			var tu models.TenantUser
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ?", tenantID, buyerUserID).First(&tu).Error, ShouldBeNil)
+			So(tu.Balance, ShouldEqual, 700)
+			So(tu.BalanceFrozen, ShouldEqual, 0)
+
+			res2, err := Order.PurchaseContent(ctx, &PurchaseContentParams{
+				TenantID:       tenantID,
+				UserID:         buyerUserID,
+				ContentID:      content.ID,
+				IdempotencyKey: "idem_paid_1",
+				Now:            now.Add(2 * time.Second),
+			})
+			So(err, ShouldBeNil)
+			So(res2.Order.ID, ShouldEqual, res1.Order.ID)
+
+			var tu2 models.TenantUser
+			So(_db.WithContext(ctx).Where("tenant_id = ? AND user_id = ?", tenantID, buyerUserID).First(&tu2).Error, ShouldBeNil)
+			So(tu2.Balance, ShouldEqual, 700)
+			So(tu2.BalanceFrozen, ShouldEqual, 0)
+		})
+
+		Convey("存在回滚标记时应稳定返回“失败+已回滚”", func() {
+			s.truncate(
+				ctx,
+				models.TableNameTenantLedger,
+				models.TableNameContentAccess,
+				models.TableNameOrderItem,
+				models.TableNameOrder,
+				models.TableNameContentPrice,
+				models.TableNameContent,
+				models.TableNameTenantUser,
+			)
+			s.seedTenantUser(ctx, tenantID, buyerUserID, 1000, 0)
+			content := s.seedPublishedContent(ctx, tenantID, ownerUserID)
+			s.seedContentPrice(ctx, tenantID, content.ID, 300)
+
+			rollbackKey := "idem_rollback_1:rollback"
+			ledger := &models.TenantLedger{
+				TenantID:       tenantID,
+				UserID:         buyerUserID,
+				OrderID:        0,
+				Type:           consts.TenantLedgerTypeUnfreeze,
+				Amount:         1,
+				BalanceBefore:  0,
+				BalanceAfter:   0,
+				FrozenBefore:   0,
+				FrozenAfter:    0,
+				IdempotencyKey: rollbackKey,
+				Remark:         "rollback marker",
+				CreatedAt:      now,
+				UpdatedAt:      now,
+			}
+			So(ledger.Create(ctx), ShouldBeNil)
+
+			_, err := Order.PurchaseContent(ctx, &PurchaseContentParams{
+				TenantID:       tenantID,
+				UserID:         buyerUserID,
+				ContentID:      content.ID,
+				IdempotencyKey: "idem_rollback_1",
+				Now:            now.Add(time.Second),
+			})
+			So(err, ShouldNotBeNil)
+			So(err.Error(), ShouldContainSubstring, "失败+已回滚")
+		})
+	})
+}

backend/app/services/user.go

@@ -44,7 +44,7 @@ func (t *user) Create(ctx context.Context, user *models.User) (*models.User, err
 	return user, nil
 }
 
-// SetStatus
+// SetStatus 设置用户状态（超级管理员侧）。
 func (t *user) SetStatus(ctx context.Context, userID int64, status consts.UserStatus) error {
 	m, err := t.FindByID(ctx, userID)
 	if err != nil {
@@ -55,7 +55,7 @@ func (t *user) SetStatus(ctx context.Context, userID int64, status consts.UserSt
 	return m.Save(ctx)
 }
 
-// Page
+// Page 用户分页查询（超级管理员侧）。
 func (t *user) Page(ctx context.Context, filter *dto.UserPageFilter) (*requests.Pager, error) {
 	tbl, query := models.UserQuery.QueryContext(ctx)
 
@@ -94,7 +94,7 @@ func (t *user) Page(ctx context.Context, filter *dto.UserPageFilter) (*requests.
 	}, nil
 }
 
-// UpdateStatus
+// UpdateStatus 更新用户状态（超级管理员侧）。
 func (t *user) UpdateStatus(ctx context.Context, userID int64, status consts.UserStatus) error {
 	logrus.WithField("user_id", userID).WithField("status", status).Info("update user status")
 
@@ -112,7 +112,7 @@ func (t *user) UpdateStatus(ctx context.Context, userID int64, status consts.Use
 	return nil
 }
 
-// Statistics
+// Statistics 按状态统计用户数量（超级管理员侧）。
 func (t *user) Statistics(ctx context.Context) ([]*dto.UserStatistics, error) {
 	tbl, query := models.UserQuery.QueryContext(ctx)
 

backend/app/services/user_test.go

@@ -101,7 +101,7 @@ func (t *UserTestSuite) Test_FindByUsername() {
 
 // Test_Page
 func (t *UserTestSuite) Test_Page() {
-	FocusConvey("test page", t.T(), func() {
+	Convey("test page", t.T(), func() {
 		Convey("filter username", func() {
 			database.Truncate(t.T().Context(), t.DB, models.TableNameUser)
 
@@ -124,7 +124,7 @@ func (t *UserTestSuite) Test_Page() {
 			So(pager.Total, ShouldEqual, 1)
 		})
 
-		FocusConvey("filter tenant users", func() {
+		Convey("filter tenant users", func() {
 			database.Truncate(
 				t.T().Context(),
 				t.DB,
@@ -205,53 +205,6 @@ func (t *UserTestSuite) Test_Page() {
 
 func (t *UserTestSuite) Test_Relations() {
 	Convey("test page", t.T(), func() {
-		// database.Truncate(
-		// 	t.T().Context(),
-		// 	t.DB,
-		// 	models.TableNameUser,
-		// 	models.TableNameTenant,
-		// 	models.TableNameTenantUser,
-		// )
-
-		// username := "test-user"
-		// mUser01 := &models.User{
-		// 	Username: username,
-		// 	Password: "test-password",
-		// 	Roles:    types.NewArray([]consts.Role{consts.RoleUser}),
-		// 	Status:   consts.UserStatusPendingVerify,
-		// }
-
-		// err := mUser01.Create(t.T().Context())
-		// So(err, ShouldBeNil)
-
-		// tenantModel := &models.Tenant{
-		// 	UserID: 1,
-		// 	Code:   "abc",
-		// 	UUID:   types.NewUUIDv4(),
-		// 	Name:   "T01",
-		// 	Status: consts.TenantStatusVerified,
-		// }
-
-		// err = tenantModel.Create(t.T().Context())
-		// So(err, ShouldBeNil)
-
-		// count := 10
-		// for i := 0; i < count; i++ {
-		// 	mUser := &models.User{
-		// 		Username: fmt.Sprintf("user_%d", i),
-		// 		Password: "test-password",
-		// 		Roles:    types.NewArray([]consts.Role{consts.RoleUser}),
-		// 		Status:   consts.UserStatusPendingVerify,
-		// 	}
-
-		// 	err = mUser.Create(t.T().Context())
-		// 	So(err, ShouldBeNil)
-
-		// 	// create tenant user
-		// 	err = Tenant.AddUser(t.T().Context(), 1, mUser.ID)
-		// 	So(err, ShouldBeNil)
-		// }
-
 		Convey("filter tenant users", func() {
 			m, err := User.FindByID(t.T().Context(), 1)
 			So(err, ShouldBeNil)

backend/llm.txt

@@ -21,6 +21,8 @@ This file condenses `backend/docs/dev/http_api.md` + `backend/docs/dev/model.md`
 - DO keep Swagger annotations consistent with actual Fiber route paths (including `:param`).
 - MUST: route path parameter placeholders MUST be `camelCase` (e.g. `:tenantCode`), never `snake_case` (e.g. `:tenant_code`).
 - MUST: when creating/generating Go `struct` definitions (DTOs/requests/responses/etc.), add detailed per-field comments describing meaning, usage scenario, and validation/usage rules (do not rely on “self-explanatory” names).
+- MUST: business code comments MUST be written in Chinese (中文注释), to keep review/maintenance consistent across the team.
+- MUST: in `backend/app/services`, add Chinese comments at key steps to explain business intent and invariants (e.g., 事务边界、幂等语义、余额冻结/扣减/回滚、权限/前置条件校验点), avoid “what the code does” boilerplate.
 
 ---
 
@@ -230,3 +232,99 @@ Generator will convert snake_case columns to Go struct field names (e.g. `class_
 - `atomctl migrate create ...` / `atomctl migrate up`
 - `atomctl gen model` / `atomctl gen enum` / `atomctl gen service`
 - `make init` (full refresh)
+
+---
+
+## 5) Service Layer Unit Testing Guidelines (Generic)
+
+This section is framework-agnostic and applies to any Go service layer (regardless of DI container, ORM, or web framework).
+
+### 5.1 Decide what you are testing
+
+- **Pure unit tests**: no DB/network/filesystem; dependencies are mocked/faked; tests are fast and deterministic.
+- **DB-backed tests (recommended whenever the feature touches the database)**: exercise a real database to validate SQL, constraints, transactions, and ORM behavior.
+- Always state which tier the test belongs to and keep the scope consistent.
+
+### 5.2 Design the service for testability
+
+- Inject dependencies via constructor or fields; depend on **interfaces**, not concrete DB clients.
+- Keep domain logic **pure** where possible: parse/validate/compute should be testable without IO.
+- Make time/UUID/randomness deterministic by injecting `Clock`/`IDGenerator` when needed.
+- If the feature requires database access, **do not mock the database**; test with an **actual database** (ideally same engine/version as production) to ensure data accuracy. Use mocks/fakes only for non-DB external dependencies when appropriate (e.g., HTTP, SMS, third-party APIs).
+
+### 5.3 Test structure and conventions
+
+- Prefer `*_test.go` with table-driven tests and subtests: `t.Run("case", func(t *testing.T) { ... })`.
+- Prefer testing the public API from an external package (`package xxx_test`) unless you must access unexported helpers.
+- Avoid “focused” tests in committed code (e.g. `FocusConvey`, `FIt`, `fit`, `it.only`, or equivalent), because they silently skip other tests.
+- MUST: in service layer tests, **one test method should focus on one service method** only (e.g. `Test_Freeze` covers `Ledger.Freeze`, `Test_Unfreeze` covers `Ledger.Unfreeze`); do not bundle multiple service methods into a single `Test_*` method.
+- MUST: within that single `Test_<Method>` function, cover the method’s key behavior contracts and boundary conditions via subcases (`Convey` blocks or `t.Run`) so the method’s behavior can be reviewed in one place (do NOT claim to cover “all edge cases”, but cover the important ones).
+- MUST (minimum set): for each service method test, cover at least: happy path; invalid params / precondition failures; insufficient resources / permission denied (if applicable); idempotency/duplicate call behavior (if applicable); and at least one typical persistence/transaction failure branch (if it is hard to simulate reliably, move that branch coverage to a DB-backed integration/e2e test).
+
+### 5.4 Isolation rules
+
+- Each test must be independent and order-agnostic.
+- For integration tests:
+  - Use transaction rollback per test when possible; otherwise use truncate + deterministic fixtures.
+  - Never depend on developer-local state; prefer ephemeral DB (container) or a dedicated test database/schema.
+
+### 5.5 Assertions and error checks
+
+- Always assert both **result** and **error** (and error types via `errors.Is` / `errors.As` when wrapping is used).
+- Keep assertions minimal but complete: verify behavior, not implementation details.
+- Use the standard library (`testing`) or a single assertion library consistently across the repo.
+
+### 5.6 Minimal test file template (DI-bootstrapped, DB-backed)
+
+This template matches a common pattern where tests boot a DI container and run against a real database. Replace the bootstrap (`testx.Default/Serve`, `Provide`) and cleanup (`database.Truncate`) with your project's equivalents.
+
+```go
+package services
+
+import (
+	"database/sql"
+	"testing"
+
+	"quyun/v2/app/commands/testx"
+	"quyun/v2/database"
+	"quyun/v2/database/models"
+
+	. "github.com/smartystreets/goconvey/convey"
+	"github.com/stretchr/testify/suite"
+
+	"go.ipao.vip/atom/contracts"
+	"go.uber.org/dig"
+)
+
+type XxxTestSuiteInjectParams struct {
+	dig.In
+
+	DB       *sql.DB
+	Initials []contracts.Initial `group:"initials"`
+}
+
+type XxxTestSuite struct {
+	suite.Suite
+	XxxTestSuiteInjectParams
+}
+
+func Test_Xxx(t *testing.T) {
+	providers := testx.Default().With(Provide)
+
+	testx.Serve(providers, t, func(p XxxTestSuiteInjectParams) {
+		suite.Run(t, &XxxTestSuite{XxxTestSuiteInjectParams: p})
+	})
+}
+
+func (s *XxxTestSuite) Test_Method() {
+	Convey("describe behavior here", s.T(), func() {
+		ctx := s.T().Context()
+
+		database.Truncate(ctx, s.DB, models.TableNameUser)
+
+		got, err := User.FindByUsername(ctx, "alice")
+		So(err, ShouldNotBeNil)
+		So(got, ShouldBeNil)
+	})
+}
+```