feat(server): 免费版账户级分钟卡控 + 累加式看广告加时(#21 后端)

免费版此前形同虚设:ConnectNode 每次连接发固定 daily_minutes×1min TTL、
从不扣减已用,重连即崭新 10 分钟,日额度从未强制。改为账户级(全设备共享)
真卡控 + 累加式看广告加时:

- migration 000020: usage_daily 加 ad_bonus_minutes(sqlite+mysql)。
  当日额度 = plans.daily_minutes + ad_bonus_minutes;剩余 = 额度 − minutes_used。
- usage.store.AddAdBonusMinutes: 事务内累加封顶(替代布尔 MarkAdUnlocked),
  返回新总额+本次实际加时;GetDay/GetUsageRange 补读 ad_bonus_minutes。
- usage.service.UnlockAd: verify+nonce 后 +adBonusPerAd(10) 封顶 adDailyBonusCeiling(120),
  返回 granted+remaining;TodaySummary 加 MinutesCap/AdBonusMinutes。
- usage.ads DevVerifier: 放行式占位校验(nonce 防重放仍生效),接真 AdMob 前
  让看广告加时流程可端到端跑通;main.go 按 ADS_DEV_MODE/默认装配。
- ads/unlock: 204 → 200 返回 {granted_minutes, minutes_remaining}。
- ConnectNode 免费门: 读 AccountDayMinutes(used,bonus) → remaining≤0 拒 QUOTA_EXHAUSTED,
  否则 TTL=remaining(凭证到点硬切断兜底)。nodes.store 加 AccountDayMinutes。
- /me: 补 ad_bonus_minutes,quota_today_min 分母改 daily+bonus,加 quota_cap_min。
- quota.CheckFreeConnect 同步累加语义(免费基础 10 分钟不再需先看广告)。
- openapi + 契约/迁移版本/集成测试同步;新增 SQLite AddAdBonusMinutes 单测。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

server/internal/usage/service.go

@@ -13,6 +13,14 @@ import (
 // nowFunc is overridable in tests to pin "today".
 var nowFunc = time.Now
 
+const (
+	// adBonusPerAd is how many minutes one rewarded-ad view grants (免费版加时).
+	adBonusPerAd = 10
+	// adDailyBonusCeiling caps the total ad-granted minutes per UTC day, so the
+	// free tier can't be extended indefinitely by ad-watching.
+	adDailyBonusCeiling = 120
+)
+
 // utcToday returns the current UTC calendar date (time truncated).
 func utcToday() time.Time {
 	n := nowFunc().UTC()
@@ -159,8 +167,10 @@ func (svc *Service) DeviceUsage(ctx context.Context, userID int64, days int) ([]
 // TodaySummary is the /v1/me today_usage block.
 type TodaySummary struct {
 	MinutesUsed      int  `json:"minutes_used"`
+	MinutesCap       *int `json:"minutes_cap"`       // 当日额度 = daily + ad_bonus; nil = unlimited
 	MinutesRemaining *int `json:"minutes_remaining"` // nil = unlimited (pro/team)
-	AdUnlocked       bool `json:"ad_unlocked"`
+	AdBonusMinutes   int  `json:"ad_bonus_minutes"`  // 当日已通过看广告累加的分钟
+	AdUnlocked       bool `json:"ad_unlocked"`       // 历史字段:当日曾解锁过(bonus>0)
 }
 
 // TodaySummary returns the current user's usage summary for today (UTC),
@@ -176,34 +186,38 @@ func (svc *Service) TodaySummary(ctx context.Context, userID int64) (*TodaySumma
 	}
 
 	used := 0
-	adUnlocked := false
+	bonus := 0
 	if day != nil {
 		used = day.MinutesUsed
-		adUnlocked = day.AdUnlockedAt.Valid
+		bonus = day.AdBonusMinutes
 	}
 
-	out := &TodaySummary{MinutesUsed: used, AdUnlocked: adUnlocked}
+	out := &TodaySummary{MinutesUsed: used, AdBonusMinutes: bonus, AdUnlocked: bonus > 0}
 	if plan.DailyMinutes.Valid {
-		remaining := int(plan.DailyMinutes.Int64) - used
+		cap := int(plan.DailyMinutes.Int64) + bonus
+		remaining := cap - used
 		if remaining < 0 {
 			remaining = 0
 		}
+		out.MinutesCap = &cap
 		out.MinutesRemaining = &remaining
 	}
 	return out, nil
 }
 
-// UnlockAd verifies a rewarded-ad receipt and records the day's ad-unlock.
+// UnlockAd verifies a rewarded-ad receipt and grants additional free minutes.
 //
 // Flow: validate inputs → verify the receipt with the ad network → consume the
-// ad_token as a one-time nonce (replay-protected) → set ad_unlocked_at.  A
-// second unlock on a day already unlocked is idempotent (alreadyUnlocked=true).
-func (svc *Service) UnlockAd(ctx context.Context, userID int64, deviceID, adToken string) (alreadyUnlocked bool, apiErr *apierr.Error) {
+// ad_token as a one-time nonce (replay-protected) → add adBonusPerAd minutes to
+// the day's ad bonus (capped at adDailyBonusCeiling).  It returns the granted
+// minutes (0 when the daily ceiling was already reached) and the new remaining
+// minutes for today so the client can refresh its quota immediately.
+func (svc *Service) UnlockAd(ctx context.Context, userID int64, deviceID, adToken string) (granted, remaining int, apiErr *apierr.Error) {
 	if deviceID == "" || adToken == "" {
-		return false, apierr.ErrBadRequest
+		return 0, 0, apierr.ErrBadRequest
 	}
 	if svc.verifier == nil {
-		return false, apierr.ErrInternal
+		return 0, 0, apierr.ErrInternal
 	}
 
 	// 1. Authenticate the receipt with the ad network.
@@ -212,22 +226,32 @@ func (svc *Service) UnlockAd(ctx context.Context, userID int64, deviceID, adToke
 		DeviceID: deviceID,
 		AdToken:  adToken,
 	}); err != nil {
-		return false, apierr.ErrAdVerifyFailed
+		return 0, 0, apierr.ErrAdVerifyFailed
 	}
 
 	// 2. One-time nonce: a genuine receipt may only be redeemed once.
 	if dup, err := svc.consumeAdNonce(ctx, adToken); err != nil {
-		return false, apierr.ErrInternal
+		return 0, 0, apierr.ErrInternal
 	} else if dup {
-		return false, apierr.ErrAdReplay
+		return 0, 0, apierr.ErrAdReplay
 	}
 
-	// 3. Record the unlock (idempotent per UTC day).
-	already, err := svc.store.MarkAdUnlocked(ctx, userID, utcToday())
-	if err != nil {
-		return false, apierr.ErrInternal
+	// 3. Grant the reward: add adBonusPerAd minutes, capped at the daily ceiling.
+	_, g, addErr := svc.store.AddAdBonusMinutes(ctx, userID, utcToday(), adBonusPerAd, adDailyBonusCeiling)
+	if addErr != nil {
+		return 0, 0, apierr.ErrInternal
 	}
-	return already, nil
+	granted = g
+
+	// 4. Recompute remaining for the client to refresh its quota immediately.
+	summary, sErr := svc.TodaySummary(ctx, userID)
+	if sErr != nil {
+		return 0, 0, sErr
+	}
+	if summary.MinutesRemaining != nil {
+		remaining = *summary.MinutesRemaining
+	}
+	return granted, remaining, nil
 }
 
 // consumeAdNonce atomically records the ad_token so it cannot be reused.