feat: 更新服务层文档，增加中文注释以提升可读性

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,7 +56,7 @@ type order struct {
 	ledger *ledger
 }
 
-// AdminTopupUser credits tenant balance to a tenant member (tenant-admin action).
+// AdminTopupUser 租户管理员给租户成员充值（增加该租户下的可用余额）。
 func (s *order) AdminTopupUser(
 	ctx context.Context,
 	tenantID, operatorUserID, targetUserID, amount int64,
@@ -84,7 +84,7 @@ func (s *order) AdminTopupUser(
 	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"}).
@@ -96,7 +96,7 @@ func (s *order) AdminTopupUser(
 			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(
@@ -110,6 +110,7 @@ func (s *order) AdminTopupUser(
 			}
 		}
 
+		// 先落订单（paid），再写入账本（credit_topup），确保“订单可追溯 + 账本可对账”。
 		orderModel := models.Order{
 			TenantID:       tenantID,
 			UserID:         targetUserID,
@@ -129,6 +130,7 @@ func (s *order) AdminTopupUser(
 			return err
 		}
 
+		// 账本幂等键固定使用 topup:<orderID>，保证同一订单不会重复入账。
 		ledgerKey := fmt.Sprintf("topup:%d", orderModel.ID)
 		remark := reason
 		if remark == "" {
@@ -162,7 +164,7 @@ func (s *order) AdminTopupUser(
 	return &out, nil
 }
 
-// MyOrderPage lists orders for current user within a tenant.
+// MyOrderPage 分页查询当前用户在租户内的订单。
 func (s *order) MyOrderPage(
 	ctx context.Context,
 	tenantID, userID int64,
@@ -206,7 +208,7 @@ func (s *order) MyOrderPage(
 	}, 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")
@@ -230,7 +232,7 @@ func (s *order) MyOrderDetail(ctx context.Context, tenantID, userID, orderID int
 	return m, nil
 }
 
-// AdminOrderPage lists orders within a tenant for tenant-admin.
+// AdminOrderPage 租户管理员分页查询租户内订单。
 func (s *order) AdminOrderPage(
 	ctx context.Context,
 	tenantID int64,
@@ -274,7 +276,7 @@ func (s *order) AdminOrderPage(
 	}, 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")
@@ -293,7 +295,7 @@ 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.
+// AdminRefundOrder 退款已支付订单（支持强制退款），并立即回收已授予的内容权益。
 func (s *order) AdminRefundOrder(
 	ctx context.Context,
 	tenantID, operatorUserID, orderID int64,
@@ -319,6 +321,7 @@ func (s *order) AdminRefundOrder(
 	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"}).
@@ -328,6 +331,7 @@ func (s *order) AdminRefundOrder(
 			return err
 		}
 
+		// 状态机：已退款直接幂等返回；仅允许已支付订单退款。
 		if orderModel.Status == consts.OrderStatusRefunded {
 			out = &orderModel
 			return nil
@@ -339,6 +343,7 @@ func (s *order) AdminRefundOrder(
 			return errorx.ErrPreconditionFailed.WithMsg("订单缺少 paid_at，无法退款")
 		}
 
+		// 时间窗：默认 paid_at + 24h；force=true 可绕过。
 		if !force {
 			deadline := orderModel.PaidAt.Add(consts.DefaultOrderRefundWindow)
 			if now.After(deadline) {
@@ -349,13 +354,14 @@ func (s *order) AdminRefundOrder(
 		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
@@ -371,6 +377,7 @@ func (s *order) AdminRefundOrder(
 			}
 		}
 
+		// 最后更新订单退款字段，保证退款后的最终状态一致。
 		if err := tx.Table(models.TableNameOrder).
 			Where("id = ?", orderModel.ID).
 			Updates(map[string]any{
@@ -438,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(
@@ -479,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(
@@ -495,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)
@@ -513,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 {
@@ -552,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{
@@ -605,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
@@ -613,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,
@@ -672,7 +679,7 @@ 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,
@@ -708,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.
@@ -881,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
 	}
@@ -927,6 +935,7 @@ func (s *order) grantAccess(
 	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,