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()
+}