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

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

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)