Version: 0.6.7.dev.260317

✨ feat(agent): 新增 Token 配额门禁中间件（Redis 快照 + 封禁键 + 7 天懒重置）

- 🚪 在 `POST /api/v1/agent/chat` 挂载 `TokenQuotaGuard`，在请求进入业务逻辑前完成额度校验
- ⚡ 新增 Redis 配额快照与封禁键机制：超额用户命中封禁键后可快速拦截，降低重复查库带来的开销
- 🗃️ 新增用户配额 DAO 能力：按需读取 `token_limit`、`token_usage`、`last_reset_at`，并支持基于“到期条件更新”的懒重置
- 🔄 实现 7 天懒重置策略：用户访问时若检测到配额周期已到期，则重置 `token_usage` 并清理封禁状态
- 🚫 新增超额响应码 `40051`，用于标识 `token usage exceeds limit`

backend/dao/cache.go

@@ -15,6 +15,17 @@ type CacheDAO struct {
 	client *redis.Client
 }
 
+// UserTokenQuotaSnapshot 是“用户额度判断”的 Redis 快照结构。
+//
+// 设计说明：
+// 1. 只保留额度判断必要字段，避免把 users 全字段塞进缓存；
+// 2. 该结构仅用于“快速门禁判断”，权威账本仍以 MySQL 为准。
+type UserTokenQuotaSnapshot struct {
+	TokenLimit  int       `json:"token_limit"`
+	TokenUsage  int       `json:"token_usage"`
+	LastResetAt time.Time `json:"last_reset_at"`
+}
+
 func NewCacheDAO(client *redis.Client) *CacheDAO {
 	return &CacheDAO{client: client}
 }
@@ -266,3 +277,79 @@ func (d *CacheDAO) DeleteUserOngoingScheduleFromCache(ctx context.Context, userI
 	key := fmt.Sprintf("smartflow:ongoing_schedule:%d", userID)
 	return d.client.Del(ctx, key).Err()
 }
+
+func userTokenQuotaSnapshotKey(userID int) string {
+	return fmt.Sprintf("smartflow:user_token_quota_snapshot:%d", userID)
+}
+
+func userTokenBlockedKey(userID int) string {
+	return fmt.Sprintf("smartflow:user_token_blocked:%d", userID)
+}
+
+// GetUserTokenQuotaSnapshot 读取用户 token 配额快照。
+//
+// 输入输出语义：
+// 1. 命中返回 (*UserTokenQuotaSnapshot, true, nil)；
+// 2. 未命中返回 (nil, false, nil)；
+// 3. Redis/反序列化错误返回 (nil, false, err)。
+func (d *CacheDAO) GetUserTokenQuotaSnapshot(ctx context.Context, userID int) (*UserTokenQuotaSnapshot, bool, error) {
+	key := userTokenQuotaSnapshotKey(userID)
+	val, err := d.client.Get(ctx, key).Result()
+	if errors.Is(err, redis.Nil) {
+		return nil, false, nil
+	}
+	if err != nil {
+		return nil, false, err
+	}
+
+	var snapshot UserTokenQuotaSnapshot
+	if err = json.Unmarshal([]byte(val), &snapshot); err != nil {
+		return nil, false, err
+	}
+	return &snapshot, true, nil
+}
+
+// SetUserTokenQuotaSnapshot 写入用户 token 配额快照。
+//
+// 职责边界：
+// 1. 只做缓存写入，不做额度判断；
+// 2. ttl 由上层策略控制，便于按场景调优“性能 vs 一致性”。
+func (d *CacheDAO) SetUserTokenQuotaSnapshot(ctx context.Context, userID int, snapshot UserTokenQuotaSnapshot, ttl time.Duration) error {
+	key := userTokenQuotaSnapshotKey(userID)
+	data, err := json.Marshal(snapshot)
+	if err != nil {
+		return err
+	}
+	return d.client.Set(ctx, key, data, ttl).Err()
+}
+
+// DeleteUserTokenQuotaSnapshot 删除用户 token 快照缓存。
+func (d *CacheDAO) DeleteUserTokenQuotaSnapshot(ctx context.Context, userID int) error {
+	return d.client.Del(ctx, userTokenQuotaSnapshotKey(userID)).Err()
+}
+
+// IsUserTokenBlocked 检查用户是否被“额度封禁键”命中。
+func (d *CacheDAO) IsUserTokenBlocked(ctx context.Context, userID int) (bool, error) {
+	result, err := d.client.Get(ctx, userTokenBlockedKey(userID)).Result()
+	if errors.Is(err, redis.Nil) {
+		return false, nil
+	}
+	if err != nil {
+		return false, err
+	}
+	return result == "1", nil
+}
+
+// SetUserTokenBlocked 设置用户“额度封禁键”。
+//
+// 说明：
+// 1. 该键是快速拦截层，不是权威账本；
+// 2. ttl 建议设置到“下一次重置时间”，到期自动解封。
+func (d *CacheDAO) SetUserTokenBlocked(ctx context.Context, userID int, ttl time.Duration) error {
+	return d.client.Set(ctx, userTokenBlockedKey(userID), "1", ttl).Err()
+}
+
+// DeleteUserTokenBlocked 清理用户“额度封禁键”。
+func (d *CacheDAO) DeleteUserTokenBlocked(ctx context.Context, userID int) error {
+	return d.client.Del(ctx, userTokenBlockedKey(userID)).Err()
+}

backend/dao/user.go

@@ -1,6 +1,7 @@
 package dao
 
 import (
+	"context"
 	"errors"
 	"time"
 
@@ -85,3 +86,47 @@ func (r *UserDAO) GetUserByID(id int) (*model.User, error) {
 	}
 	return &user, nil
 }
+
+// GetUserTokenQuotaByID 查询用户 token 配额快照（仅查询配额相关字段）。
+//
+// 职责边界：
+// 1. 只返回 token_limit / token_usage / last_reset_at 等“额度判断必需字段”；
+// 2. 不负责做超额判断与重置判断（由中间件统一决策）；
+// 3. 不返回密码等敏感字段，避免把无关信息带入鉴权链路。
+func (r *UserDAO) GetUserTokenQuotaByID(ctx context.Context, id int) (*model.User, error) {
+	var user model.User
+	err := r.db.WithContext(ctx).
+		Select("id", "token_limit", "token_usage", "last_reset_at").
+		Where("id = ?", id).
+		First(&user).Error
+	if err != nil {
+		return nil, err
+	}
+	return &user, nil
+}
+
+// ResetUserTokenUsageIfDue 在“已到重置窗口”时执行懒重置。
+//
+// 输入输出语义：
+// 1. dueBefore：判定“到期可重置”的截止时间（通常是 now-7d）；
+// 2. resetAt：本次重置写入的时间戳；
+// 3. 返回值 bool：
+//   - true  表示本次调用实际执行了重置；
+//   - false 表示条件未命中（尚未到期或记录不存在）。
+//
+// 并发与幂等说明：
+// 1. 使用条件更新（WHERE last_reset_at <= dueBefore）保证并发下最多一次成功重置；
+// 2. 重复调用是安全的，未命中条件时不会破坏现有统计。
+func (r *UserDAO) ResetUserTokenUsageIfDue(ctx context.Context, id int, dueBefore time.Time, resetAt time.Time) (bool, error) {
+	result := r.db.WithContext(ctx).
+		Model(&model.User{}).
+		Where("id = ? AND (last_reset_at IS NULL OR last_reset_at <= ?)", id, dueBefore).
+		Updates(map[string]interface{}{
+			"token_usage":   0,
+			"last_reset_at": resetAt,
+		})
+	if result.Error != nil {
+		return false, result.Error
+	}
+	return result.RowsAffected > 0, nil
+}