garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
// Copyright (c) 2026 Kirky.X🌠
// SPDX-License-Identifier: Apache-2.0

//! Credit KV 热数据存储层。
//!
//! `CreditMeterStorage` 通过 `GarrisonDao` KV 接口管理当前周期的 credit 计数与元数据,
//! 消费/查询/重置均走 KV 缓存保证性能。
//!
//! 非原子性与性能声明:`GarrisonDao::incr` 每次仅递增 1 且无 `INCRBY` 语义,
//! [`CreditMeterStorage::incr_consumed`] 在 `credits > 1` 时循环调用 N 次 DAO——单次
//! 调用原子,但整体递增非原子(并发交错可使返回计数偏离单次 `INCRBY` 语义),且产生
//! N 次串行网络往返(大额消费延迟线性增长)。精确/高效批量递增需后端提供批量接口。

use crate::credit::cycle::CreditCycle;
use crate::credit::error::{CreditError, CreditResult};
use crate::dao::GarrisonDao;
use std::sync::Arc;

/// 配额 key 前缀。
const CREDIT_KEY_PREFIX: &str = "credit";

/// 配额计数 key:`credit:{tenant_id}:consumed`。
fn credit_consumed_key(tenant_id: i64) -> String {
    format!("{}:{}:consumed", CREDIT_KEY_PREFIX, tenant_id)
}

/// 配额元数据 key:`credit:{tenant_id}:meta`。
///
/// 格式:`consumed|limit|window_start|window_end|cycle_type|cycle_param`
fn credit_meta_key(tenant_id: i64) -> String {
    format!("{}:{}:meta", CREDIT_KEY_PREFIX, tenant_id)
}

/// 滚动窗口起始 key:`credit:{tenant_id}:window_start`(仅 Rolling 模式)。
fn credit_window_start_key(tenant_id: i64) -> String {
    format!("{}:{}:window_start", CREDIT_KEY_PREFIX, tenant_id)
}

/// Credit 周期元数据。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CreditMeta {
    /// 当前周期已消费总量。
    pub consumed: u64,
    /// 当前周期 credit 配额。
    pub limit: u64,
    /// 当前周期起始(Unix 时间戳)。
    pub window_start: i64,
    /// 当前周期结束(Unix 时间戳)。
    pub window_end: i64,
    /// 周期模式。
    pub cycle: CreditCycle,
}

/// KV 热数据存储层。
///
/// 持有 `Arc<dyn GarrisonDao>`,提供 credit 计数的读写操作。
pub struct CreditMeterStorage {
    dao: Arc<dyn GarrisonDao>,
}

impl CreditMeterStorage {
    /// 创建存储实例。
    pub fn new(dao: Arc<dyn GarrisonDao>) -> Self {
        Self { dao }
    }

    /// 获取当前周期已消费 credit 计数。
    ///
    /// 返回 `None` 表示尚无消费记录。
    pub async fn get_consumed(&self, tenant_id: i64) -> CreditResult<Option<u64>> {
        let key = credit_consumed_key(tenant_id);
        let val = self
            .dao
            .get(&key)
            .await
            .map_err(|e| CreditError::Dao(format!("credit-get-consumed::{}", e)))?;
        match val {
            Some(s) => {
                let count: u64 = s.parse().map_err(|e| {
                    CreditError::Dao(format!(
                        "credit-consumed-parse-failed::{}::{}::{}",
                        key, s, e
                    ))
                })?;
                Ok(Some(count))
            },
            None => Ok(None),
        }
    }

    /// 递增已消费 credit 计数。
    ///
    /// 循环 `dao.incr` credits 次(cost=1 时单次,进程内原子;cost>1 时整体非原子),
    /// 每个 credit 一次 DAO 往返——N 个 credit 即 N 次串行网络调用(批量递增需 DAO
    /// 提供 `INCRBY` 类接口);返回递增后的新计数。
    pub async fn incr_consumed(&self, tenant_id: i64, credits: u64, ttl: u64) -> CreditResult<u64> {
        let key = credit_consumed_key(tenant_id);
        let mut new_count = 0u64;
        for _ in 0..credits {
            new_count = self
                .dao
                .incr(&key, ttl)
                .await
                .map_err(|e| CreditError::Dao(format!("credit-incr-failed::{}", e)))?;
        }
        Ok(new_count)
    }

    /// 递减已消费 credit 计数(拒绝路径回滚已扣减量专用,best-effort)。
    ///
    /// 循环 `dao.decr` times 次,与 [`Self::incr_consumed`] 相同的非原子性;单次 `decr`
    /// 失败**不中断回滚**:以 `tracing::warn` 记录后继续(best-effort,不掩盖消费结果
    /// 中的拒绝语义),返回最后一次成功的计数值。
    pub async fn decr_consumed(&self, tenant_id: i64, times: u64) -> u64 {
        let key = credit_consumed_key(tenant_id);
        let mut count = 0u64;
        for _ in 0..times {
            match self.dao.decr(&key).await {
                Ok(v) => count = v,
                Err(e) => {
                    tracing::warn!(
                        tenant_id,
                        error = %e,
                        "{}",
                        crate::i18n::translate_detail("logs-credit-decr-rollback-failed", &[])
                    );
                },
            }
        }
        count
    }

    /// 获取当前周期元数据;`None` 表示 meta key 不存在(尚未消费或已重置),脏数据
    /// (parse 失败)返回 `Err`(fail-fast)。
    pub async fn get_meta(&self, tenant_id: i64) -> CreditResult<Option<CreditMeta>> {
        let key = credit_meta_key(tenant_id);
        let val = self
            .dao
            .get(&key)
            .await
            .map_err(|e| CreditError::Dao(format!("credit-get-meta::{}", e)))?;
        match val {
            Some(s) => {
                let parts: Vec<&str> = s.split('|').collect();
                if parts.len() != 6 {
                    return Err(CreditError::Dao(format!(
                        "credit-meta-format-error::{}::{}::expected 6 parts, got {}",
                        key,
                        s,
                        parts.len()
                    )));
                }
                let consumed: u64 = parts[0].parse().map_err(|e| {
                    CreditError::Dao(format!(
                        "credit-meta-consumed-parse-failed::{}::{}::{}",
                        key, parts[0], e
                    ))
                })?;
                let limit: u64 = parts[1].parse().map_err(|e| {
                    CreditError::Dao(format!(
                        "credit-meta-limit-parse-failed::{}::{}::{}",
                        key, parts[1], e
                    ))
                })?;
                let window_start: i64 = parts[2].parse().map_err(|e| {
                    CreditError::Dao(format!(
                        "credit-meta-window-start-parse-failed::{}::{}::{}",
                        key, parts[2], e
                    ))
                })?;
                let window_end: i64 = parts[3].parse().map_err(|e| {
                    CreditError::Dao(format!(
                        "credit-meta-window-end-parse-failed::{}::{}::{}",
                        key, parts[3], e
                    ))
                })?;
                let cycle_type = parts[4];
                let cycle_param: u32 = parts[5].parse().map_err(|e| {
                    CreditError::Dao(format!(
                        "credit-meta-cycle-param-parse-failed::{}::{}::{}",
                        key, parts[5], e
                    ))
                })?;
                let cycle = CreditCycle::from_tag(cycle_type, cycle_param).ok_or_else(|| {
                    CreditError::Dao(format!(
                        "credit-meta-unknown-cycle-type::{}::{}",
                        key, cycle_type
                    ))
                })?;
                Ok(Some(CreditMeta {
                    consumed,
                    limit,
                    window_start,
                    window_end,
                    cycle,
                }))
            },
            None => Ok(None),
        }
    }

    /// 写入当前周期元数据。
    pub async fn set_meta(&self, tenant_id: i64, meta: &CreditMeta, ttl: u64) -> CreditResult<()> {
        let key = credit_meta_key(tenant_id);
        let val = format!(
            "{}|{}|{}|{}|{}|{}",
            meta.consumed,
            meta.limit,
            meta.window_start,
            meta.window_end,
            meta.cycle.type_tag(),
            meta.cycle.param()
        );
        self.dao
            .set(&key, &val, ttl)
            .await
            .map_err(|e| CreditError::Dao(format!("credit-set-meta-failed::{}", e)))
    }

    /// 重置 credit 计数(删除 consumed + meta + window_start 三个 key)。
    ///
    /// 三个删除**无事务保证**:中途失败时已删除的 key 不恢复(部分重置语义),返回的
    /// 错误标识首个失败的 key;并发消费/查询在重置期间可能观察到中间态。TTL 兜底:
    /// 三个 key 均带周期 TTL,残留键会随周期到期自动清理。
    pub async fn reset(&self, tenant_id: i64) -> CreditResult<()> {
        let consumed_key = credit_consumed_key(tenant_id);
        let meta_key = credit_meta_key(tenant_id);
        let ws_key = credit_window_start_key(tenant_id);
        if let Err(e) = self.dao.delete(&consumed_key).await {
            tracing::warn!(
                tenant_id,
                error = %e,
                "{}",
                crate::i18n::translate_detail("logs-credit-reset-consumed-delete-failed", &[])
            );
            return Err(CreditError::Dao(format!("credit-reset-consumed::{}", e)));
        }
        if let Err(e) = self.dao.delete(&meta_key).await {
            tracing::warn!(
                tenant_id,
                error = %e,
                "{}",
                crate::i18n::translate_detail("logs-credit-reset-meta-delete-failed", &[])
            );
            return Err(CreditError::Dao(format!("credit-reset-meta::{}", e)));
        }
        self.dao
            .delete(&ws_key)
            .await
            .map_err(|e| CreditError::Dao(format!("credit-reset-window-start::{}", e)))?;
        Ok(())
    }

    /// 获取滚动窗口起始时间戳(仅 Rolling 模式使用)。
    pub async fn get_window_start(&self, tenant_id: i64) -> CreditResult<Option<i64>> {
        let key = credit_window_start_key(tenant_id);
        let val = self
            .dao
            .get(&key)
            .await
            .map_err(|e| CreditError::Dao(format!("credit-get-window-start::{}", e)))?;
        match val {
            Some(s) => {
                let ts: i64 = s.parse().map_err(|e| {
                    CreditError::Dao(format!(
                        "credit-window-start-parse-failed::{}::{}::{}",
                        key, s, e
                    ))
                })?;
                Ok(Some(ts))
            },
            None => Ok(None),
        }
    }

    /// 设置滚动窗口起始时间戳。
    pub async fn set_window_start(&self, tenant_id: i64, ts: i64, ttl: u64) -> CreditResult<()> {
        let key = credit_window_start_key(tenant_id);
        self.dao
            .set(&key, &ts.to_string(), ttl)
            .await
            .map_err(|e| CreditError::Dao(format!("credit-set-window-start::{}", e)))
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::dao::tests::MockDao;

    fn make_dao() -> Arc<dyn GarrisonDao> {
        Arc::new(MockDao::new())
    }

    /// incr_consumed 返回递增后的新计数。
    #[tokio::test]
    async fn test_incr_consumed_returns_new_count() {
        let storage = CreditMeterStorage::new(make_dao());
        let count = storage.incr_consumed(42, 3, 3600).await.unwrap();
        assert_eq!(count, 3);
        let count2 = storage.incr_consumed(42, 2, 3600).await.unwrap();
        assert_eq!(count2, 5);
    }

    /// get_meta 正确解析合法 meta 数据。
    #[tokio::test]
    async fn test_get_meta_parse_success() {
        let storage = CreditMeterStorage::new(make_dao());
        let meta = CreditMeta {
            consumed: 100,
            limit: 1000,
            window_start: 1_700_000_000,
            window_end: 1_702_592_000,
            cycle: CreditCycle::Fixed { day_of_month: 1 },
        };
        storage.set_meta(42, &meta, 86400).await.unwrap();
        let loaded = storage.get_meta(42).await.unwrap().unwrap();
        assert_eq!(loaded.consumed, 100);
        assert_eq!(loaded.limit, 1000);
        assert_eq!(loaded.cycle, CreditCycle::Fixed { day_of_month: 1 });
    }

    /// get_meta 脏数据返回 Err(fail-fast)。
    #[tokio::test]
    async fn test_get_meta_dirty_data_returns_err() {
        let storage = CreditMeterStorage::new(make_dao());
        // 写入段数不对的 meta(3 段而非 6 段)
        storage
            .dao
            .set("credit:42:meta", "100|1000|bad", 0)
            .await
            .unwrap();
        let result = storage.get_meta(42).await;
        assert!(result.is_err(), "脏 meta 应返回 Err");
    }

    /// reset 清除所有 key。
    #[tokio::test]
    async fn test_reset_clears_all_keys() {
        let storage = CreditMeterStorage::new(make_dao());
        storage.incr_consumed(42, 5, 3600).await.unwrap();
        let meta = CreditMeta {
            consumed: 5,
            limit: 100,
            window_start: 1_700_000_000,
            window_end: 1_702_592_000,
            cycle: CreditCycle::Fixed { day_of_month: 1 },
        };
        storage.set_meta(42, &meta, 3600).await.unwrap();
        storage.reset(42).await.unwrap();
        assert!(storage.get_consumed(42).await.unwrap().is_none());
        assert!(storage.get_meta(42).await.unwrap().is_none());
    }

    /// get_consumed 在 key 不存在时返回 None。
    #[tokio::test]
    async fn test_get_consumed_missing_returns_none() {
        let storage = CreditMeterStorage::new(make_dao());
        assert!(storage.get_consumed(999).await.unwrap().is_none());
    }

    /// get_consumed 脏数据(非数字)返回 Err(fail-fast)。
    #[tokio::test]
    async fn test_get_consumed_dirty_data_returns_err() {
        let storage = CreditMeterStorage::new(make_dao());
        storage
            .dao
            .set("credit:42:consumed", "not-a-number", 0)
            .await
            .unwrap();
        let result = storage.get_consumed(42).await;
        let err = result.unwrap_err();
        assert!(
            format!("{}", err).contains("consumed-parse-failed"),
            "应报 consumed 解析错误: {}",
            err
        );
    }

    /// get_consumed 负数字符串返回 Err(u64 解析失败)。
    #[tokio::test]
    async fn test_get_consumed_negative_value_returns_err() {
        let storage = CreditMeterStorage::new(make_dao());
        storage.dao.set("credit:7:consumed", "-5", 0).await.unwrap();
        assert!(storage.get_consumed(7).await.is_err());
    }

    /// get_meta 在 meta key 不存在时返回 None。
    #[tokio::test]
    async fn test_get_meta_missing_returns_none() {
        let storage = CreditMeterStorage::new(make_dao());
        assert!(storage.get_meta(12345).await.unwrap().is_none());
    }

    /// get_meta:consumed 段非数字返回 Err(逐段校验 fail-fast)。
    #[tokio::test]
    async fn test_get_meta_consumed_parse_failed() {
        let storage = CreditMeterStorage::new(make_dao());
        storage
            .dao
            .set("credit:42:meta", "abc|100|1|2|fixed|1", 0)
            .await
            .unwrap();
        let err = storage.get_meta(42).await.unwrap_err();
        assert!(
            format!("{}", err).contains("consumed-parse-failed"),
            "实际: {}",
            err
        );
    }

    /// get_meta:limit 段非数字返回 Err。
    #[tokio::test]
    async fn test_get_meta_limit_parse_failed() {
        let storage = CreditMeterStorage::new(make_dao());
        storage
            .dao
            .set("credit:42:meta", "1|abc|1|2|fixed|1", 0)
            .await
            .unwrap();
        let err = storage.get_meta(42).await.unwrap_err();
        assert!(
            format!("{}", err).contains("limit-parse-failed"),
            "实际: {}",
            err
        );
    }

    /// get_meta:window_start 段非数字返回 Err。
    #[tokio::test]
    async fn test_get_meta_window_start_parse_failed() {
        let storage = CreditMeterStorage::new(make_dao());
        storage
            .dao
            .set("credit:42:meta", "1|100|abc|2|fixed|1", 0)
            .await
            .unwrap();
        let err = storage.get_meta(42).await.unwrap_err();
        assert!(
            format!("{}", err).contains("window-start-parse-failed"),
            "实际: {}",
            err
        );
    }

    /// get_meta:window_end 段非数字返回 Err。
    #[tokio::test]
    async fn test_get_meta_window_end_parse_failed() {
        let storage = CreditMeterStorage::new(make_dao());
        storage
            .dao
            .set("credit:42:meta", "1|100|1|abc|fixed|1", 0)
            .await
            .unwrap();
        let err = storage.get_meta(42).await.unwrap_err();
        assert!(
            format!("{}", err).contains("window-end-parse-failed"),
            "实际: {}",
            err
        );
    }

    /// get_meta:cycle param 段非数字返回 Err。
    #[tokio::test]
    async fn test_get_meta_cycle_param_parse_failed() {
        let storage = CreditMeterStorage::new(make_dao());
        storage
            .dao
            .set("credit:42:meta", "1|100|1|2|fixed|abc", 0)
            .await
            .unwrap();
        let err = storage.get_meta(42).await.unwrap_err();
        assert!(
            format!("{}", err).contains("cycle-param-parse-failed"),
            "实际: {}",
            err
        );
    }

    /// get_meta:未知 cycle 类型返回 Err。
    #[tokio::test]
    async fn test_get_meta_unknown_cycle_type() {
        let storage = CreditMeterStorage::new(make_dao());
        storage
            .dao
            .set("credit:42:meta", "1|100|1|2|biweekly|14", 0)
            .await
            .unwrap();
        let err = storage.get_meta(42).await.unwrap_err();
        assert!(
            format!("{}", err).contains("unknown-cycle-type"),
            "实际: {}",
            err
        );
    }

    /// get_meta:Rolling 周期往返(type_tag = rolling)。
    #[tokio::test]
    async fn test_get_meta_rolling_roundtrip() {
        let storage = CreditMeterStorage::new(make_dao());
        let meta = CreditMeta {
            consumed: 7,
            limit: 0,
            window_start: 1_700_000_000,
            window_end: 1_702_592_000,
            cycle: CreditCycle::Rolling { days: 14 },
        };
        storage.set_meta(9, &meta, 86400).await.unwrap();
        let loaded = storage.get_meta(9).await.unwrap().unwrap();
        assert_eq!(loaded, meta);
    }

    /// get_window_start:未设置时返回 None。
    #[tokio::test]
    async fn test_get_window_start_missing_returns_none() {
        let storage = CreditMeterStorage::new(make_dao());
        assert!(storage.get_window_start(42).await.unwrap().is_none());
    }

    /// get_window_start:set 后返回写入的时间戳(往返一致)。
    #[tokio::test]
    async fn test_set_then_get_window_start_roundtrip() {
        let storage = CreditMeterStorage::new(make_dao());
        storage
            .set_window_start(42, 1_700_000_000, 3600)
            .await
            .unwrap();
        assert_eq!(
            storage.get_window_start(42).await.unwrap(),
            Some(1_700_000_000)
        );
    }

    /// get_window_start:脏数据返回 Err。
    #[tokio::test]
    async fn test_get_window_start_dirty_data_returns_err() {
        let storage = CreditMeterStorage::new(make_dao());
        storage
            .dao
            .set("credit:42:window_start", "oops", 0)
            .await
            .unwrap();
        let err = storage.get_window_start(42).await.unwrap_err();
        assert!(
            format!("{}", err).contains("window-start-parse-failed"),
            "实际: {}",
            err
        );
    }

    /// reset 清除 window_start key(Rolling 周期重置依赖此语义)。
    #[tokio::test]
    async fn test_reset_clears_window_start() {
        let storage = CreditMeterStorage::new(make_dao());
        storage
            .set_window_start(42, 1_700_000_000, 3600)
            .await
            .unwrap();
        storage.reset(42).await.unwrap();
        assert!(storage.get_window_start(42).await.unwrap().is_none());
    }

    /// incr_consumed credits=0 时不执行递增,返回 0。
    #[tokio::test]
    async fn test_incr_consumed_zero_credits() {
        let storage = CreditMeterStorage::new(make_dao());
        let count = storage.incr_consumed(42, 0, 3600).await.unwrap();
        assert_eq!(count, 0, "credits=0 应返回 0");
        assert!(storage.get_consumed(42).await.unwrap().is_none());
    }

    /// incr_consumed 多次调用累计计数正确(u32::MAX 量级不可行:循环次数超过 TTL 会使
    /// 键过期计数重置,属测试规模与 TTL 语义冲突,故以千级累计验证循环与计数正确性)。
    #[tokio::test]
    async fn test_incr_consumed_accumulates() {
        let storage = CreditMeterStorage::new(make_dao());
        storage.incr_consumed(42, 600, 3600).await.unwrap();
        let count = storage.incr_consumed(42, 400, 3600).await.unwrap();
        assert_eq!(count, 1000);
        assert_eq!(storage.get_consumed(42).await.unwrap(), Some(1000));
    }

    /// 租户隔离:不同 tenant_id 的计数互不干扰(键前缀含 tenant_id)。
    #[tokio::test]
    async fn test_tenant_isolation_between_counters() {
        let storage = CreditMeterStorage::new(make_dao());
        storage.incr_consumed(1, 5, 3600).await.unwrap();
        storage.incr_consumed(2, 10, 3600).await.unwrap();
        assert_eq!(storage.get_consumed(1).await.unwrap(), Some(5));
        assert_eq!(storage.get_consumed(2).await.unwrap(), Some(10));
        // 负数 tenant_id 同样按字符串隔离
        storage.incr_consumed(-1, 3, 3600).await.unwrap();
        assert_eq!(storage.get_consumed(-1).await.unwrap(), Some(3));
        assert_eq!(storage.get_consumed(1).await.unwrap(), Some(5));
    }

    /// KV 键格式:consumed/meta/window_start 分别落在
    /// `credit:{tenant_id}:{suffix}` 前缀下(与 reset 删除的键一致)。
    #[tokio::test]
    async fn test_key_format_uses_credit_prefix() {
        let storage = CreditMeterStorage::new(make_dao());
        storage.incr_consumed(42, 1, 3600).await.unwrap();
        let consumed = storage.dao.get("credit:42:consumed").await.unwrap();
        assert_eq!(
            consumed,
            Some("1".to_string()),
            "consumed 键应为 credit:42:consumed"
        );

        let meta = CreditMeta {
            consumed: 1,
            limit: 100,
            window_start: 1,
            window_end: 2,
            cycle: CreditCycle::Fixed { day_of_month: 1 },
        };
        storage.set_meta(42, &meta, 3600).await.unwrap();
        let raw_meta = storage.dao.get("credit:42:meta").await.unwrap().unwrap();
        assert_eq!(
            raw_meta, "1|100|1|2|fixed|1",
            "meta 序列化格式应为 6 段管道分隔"
        );

        storage.set_window_start(42, 77, 3600).await.unwrap();
        let ws = storage.dao.get("credit:42:window_start").await.unwrap();
        assert_eq!(
            ws,
            Some("77".to_string()),
            "window_start 键应为 credit:42:window_start"
        );
    }
}