garrison 0.7.2

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
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
//! Copyright (c) 2026 Kirky.X. All rights reserved.
//! See LICENSE for full license text.

//! 封禁库 trait 与持久化数据模型定义。
//! 本模块定义接口契约(`DisableEntry` struct + `DisableRepository` trait)
//! 与默认实现 `DefaultDisableRepository`(持有 `Arc<dyn GarrisonDao>` 委托持久化)。

use crate::dao::GarrisonDao;
use crate::error::{GarrisonError, GarrisonResult};
use async_trait::async_trait;
use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use std::sync::Arc;

/// 封禁条目,记录单个 login_id 在指定 service 上的封禁状态。
///
/// 持久化为 JSON 存储在 DAO 中,key 格式 `disable:{service}:{login_id}`。
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct DisableEntry {
    /// 被封禁的登录主体标识。
    pub login_id: String,
    /// 封禁服务名称(如 "default"、"payment"),支持多服务独立封禁。
    pub service: String,
    /// 封禁到期时间;`None` 表示永久封禁。
    pub until: Option<DateTime<Utc>>,
    /// 封禁级别(0=普通封禁,1+=阶梯封禁,业务方可据此分级阻断)。
    pub level: u32,
    /// 封禁创建时间。
    pub created_at: DateTime<Utc>,
}

/// 封禁库 trait,提供账号封禁/解封/查询能力。
///
/// 独立于 [`GarrisonDao`] trait,通过持有 `Arc<dyn GarrisonDao>` 委托实现。
/// key 格式:`disable:{service}:{login_id}`,value 为 [`DisableEntry`] 的 JSON 序列化。
#[async_trait]
pub trait DisableRepository: Send + Sync {
    /// 封禁指定 login_id 的指定 service。
    ///
    /// # 参数
    /// - `login_id`: 被封禁的登录主体标识。
    /// - `service`: 封禁服务名称。
    /// - `until`: 封禁到期时间;`None` 表示永久封禁。
    /// - `level`: 封禁级别(0=普通,1+=阶梯)。
    /// - `duration_secs`: DAO 存储 TTL(秒);0 表示永久驻留(不自动过期)。
    async fn disable(
        &self,
        login_id: &str,
        service: &str,
        until: Option<DateTime<Utc>>,
        level: u32,
        duration_secs: u64,
    ) -> GarrisonResult<()>;

    /// 解封指定 login_id 的指定 service。
    ///
    /// # 参数
    /// - `login_id`: 被解封的登录主体标识。
    /// - `service`: 封禁服务名称。
    async fn untie_disable(&self, login_id: &str, service: &str) -> GarrisonResult<()>;

    /// 查询指定 login_id 的指定 service 是否被封禁。
    ///
    /// # 参数
    /// - `login_id`: 登录主体标识。
    /// - `service`: 封禁服务名称。
    ///
    /// # 返回
    /// - `Ok(true)`: 已封禁。
    /// - `Ok(false)`: 未封禁。
    async fn is_disable(&self, login_id: &str, service: &str) -> GarrisonResult<bool>;

    /// 获取封禁到期时间。
    ///
    /// # 参数
    /// - `login_id`: 登录主体标识。
    /// - `service`: 封禁服务名称。
    ///
    /// # 返回
    /// - `Ok(Some(time))`: 定时解封时间。
    /// - `Ok(None)`: 永久封禁或未封禁。
    async fn get_disable_time(
        &self,
        login_id: &str,
        service: &str,
    ) -> GarrisonResult<Option<DateTime<Utc>>>;

    /// 获取封禁级别。
    ///
    /// # 参数
    /// - `login_id`: 登录主体标识。
    /// - `service`: 封禁服务名称。
    ///
    /// # 返回
    /// - `Ok(Some(level))`: 已封禁,level 为封禁级别(0=普通,1+=阶梯)。
    /// - `Ok(None)`: 未封禁。
    async fn get_disable_level(&self, login_id: &str, service: &str)
        -> GarrisonResult<Option<u32>>;
}

// ============================================================================
// DefaultDisableRepository:基于 GarrisonDao 的默认实现
// ============================================================================

/// 默认封禁库实现,持有 `Arc<dyn GarrisonDao>` 委托持久化。
///
/// key 格式:`disable:{service}:{login_id}`(service 在前,便于按 service 前缀扫描)。
/// value 为 [`DisableEntry`] 的 JSON 序列化。
///
/// # 错误处理
///
/// - 序列化 `DisableEntry` 失败 → `GarrisonError::Internal`
/// - 反序列化 `DisableEntry` 失败 → `GarrisonError::Dao`
/// - DAO 读写失败 → 透传底层 `GarrisonError::Dao`
pub struct DefaultDisableRepository {
    /// DAO 实例,委托持久化封禁条目。
    dao: Arc<dyn GarrisonDao>,
}

impl DefaultDisableRepository {
    /// 创建新的 `DefaultDisableRepository` 实例。
    ///
    /// # 参数
    /// - `dao`: DAO 实例(`Arc<dyn GarrisonDao>`),用于读写封禁条目。
    pub fn new(dao: Arc<dyn GarrisonDao>) -> Self {
        Self { dao }
    }

    /// 构造封禁 key:`disable:{service}:{login_id}`。
    ///
    /// service 在前以便按 service 前缀扫描(如 `keys("disable:default:*")`)。
    ///
    /// # 错误
    /// - `service` 或 `login_id` 含 `:` 时返回 `GarrisonError::Config`,避免 key 解析歧义。
    fn disable_key(service: &str, login_id: &str) -> GarrisonResult<String> {
        if service.contains(':') {
            return Err(GarrisonError::Config(format!(
                "service 不能包含冒号(避免 key 注入): {}",
                service
            )));
        }
        if login_id.contains(':') {
            return Err(GarrisonError::Config(format!(
                "login_id 不能包含冒号(避免 key 注入): {}",
                login_id
            )));
        }
        Ok(format!("disable:{}:{}", service, login_id))
    }
}

#[async_trait]
impl DisableRepository for DefaultDisableRepository {
    async fn disable(
        &self,
        login_id: &str,
        service: &str,
        until: Option<DateTime<Utc>>,
        level: u32,
        duration_secs: u64,
    ) -> GarrisonResult<()> {
        let entry = DisableEntry {
            login_id: login_id.to_string(),
            service: service.to_string(),
            until,
            level,
            created_at: Utc::now(),
        };
        let json = serde_json::to_string(&entry)
            .map_err(|e| GarrisonError::Internal(format!("account-disable-serialize::{}", e)))?;
        let key = Self::disable_key(service, login_id)?;
        if duration_secs == 0 {
            self.dao.set_permanent(&key, &json).await
        } else {
            self.dao.set(&key, &json, duration_secs).await
        }
    }

    async fn untie_disable(&self, login_id: &str, service: &str) -> GarrisonResult<()> {
        let key = Self::disable_key(service, login_id)?;
        self.dao.delete(&key).await
    }

    async fn is_disable(&self, login_id: &str, service: &str) -> GarrisonResult<bool> {
        let key = Self::disable_key(service, login_id)?;
        match self.dao.get(&key).await? {
            Some(_) => Ok(true),
            None => Ok(false),
        }
    }

    async fn get_disable_time(
        &self,
        login_id: &str,
        service: &str,
    ) -> GarrisonResult<Option<DateTime<Utc>>> {
        let key = Self::disable_key(service, login_id)?;
        match self.dao.get(&key).await? {
            Some(json) => {
                let entry: DisableEntry = serde_json::from_str(&json).map_err(|e| {
                    GarrisonError::Dao(format!("account-disable-deserialize::{}", e))
                })?;
                Ok(entry.until)
            },
            None => Ok(None),
        }
    }

    async fn get_disable_level(
        &self,
        login_id: &str,
        service: &str,
    ) -> GarrisonResult<Option<u32>> {
        let key = Self::disable_key(service, login_id)?;
        match self.dao.get(&key).await? {
            Some(json) => {
                let entry: DisableEntry = serde_json::from_str(&json).map_err(|e| {
                    GarrisonError::Dao(format!("account-disable-deserialize::{}", e))
                })?;
                Ok(Some(entry.level))
            },
            None => Ok(None),
        }
    }
}

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

    // ========================================================================
    // T016: disable / untie_disable 方法测试
    // ========================================================================

    /// disable 写入:调用 disable 后 DAO 中存在对应 key,value 为合法 DisableEntry JSON。
    #[tokio::test]
    async fn t016_disable_writes_entry_to_dao() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        let until = Utc::now() + chrono::Duration::seconds(3600);
        repo.disable("user-1001", "default", Some(until), 0, 3600)
            .await
            .unwrap();
        let key = "disable:default:user-1001";
        let stored = dao.get(key).await.unwrap();
        assert!(stored.is_some(), "disable 后 DAO 中应存在对应 key");
        let entry: DisableEntry = serde_json::from_str(&stored.unwrap()).unwrap();
        assert_eq!(entry.login_id, "user-1001");
        assert_eq!(entry.service, "default");
        assert_eq!(entry.until, Some(until));
        assert_eq!(entry.level, 0);
    }

    /// untie_disable 删除:disable 后调用 untie_disable,DAO 中 key 不存在。
    #[tokio::test]
    async fn t016_untie_disable_removes_entry_from_dao() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        repo.disable("user-1002", "default", None, 0, 0)
            .await
            .unwrap();
        let key = "disable:default:user-1002";
        assert!(dao.get(key).await.unwrap().is_some());
        repo.untie_disable("user-1002", "default").await.unwrap();
        assert!(
            dao.get(key).await.unwrap().is_none(),
            "untie_disable 后 DAO 中 key 应不存在"
        );
    }

    /// key 格式验证:disable 后 DAO 中 key 为 `disable:{service}:{login_id}`,
    /// service 在前 login_id 在后(便于按 service 前缀扫描)。
    #[tokio::test]
    async fn t016_disable_key_format_is_service_then_login_id() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        repo.disable("user-1003", "payment", None, 0, 0)
            .await
            .unwrap();
        // 验证 key 顺序:service 在前,login_id 在后
        let expected_key = "disable:payment:user-1003";
        assert!(
            dao.get(expected_key).await.unwrap().is_some(),
            "key 应为 disable:payment:user-1003(service 在前)"
        );
        // 验证反序 key 不存在
        let wrong_key = "disable:user-1003:payment";
        assert!(
            dao.get(wrong_key).await.unwrap().is_none(),
            "反序 key 不应存在"
        );
    }

    /// 永久封禁 duration_secs=0:disable 传入 duration_secs=0 时,DAO 中 key 永久驻留(无 TTL)。
    #[tokio::test]
    async fn t016_disable_with_zero_duration_is_permanent() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        repo.disable("user-1004", "default", None, 0, 0)
            .await
            .unwrap();
        let key = "disable:default:user-1004";
        // get_timeout 返回 None 表示永久驻留(无 TTL)
        let timeout = dao.get_timeout(key).await.unwrap();
        assert!(
            timeout.is_none(),
            "duration_secs=0 应为永久驻留,get_timeout 应返回 None"
        );
    }

    /// level 传递:disable 传入 level=2 时,序列化的 JSON 中 level 字段为 2。
    #[tokio::test]
    async fn t016_disable_passes_level_to_entry() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        repo.disable("user-1005", "default", None, 2, 3600)
            .await
            .unwrap();
        let key = "disable:default:user-1005";
        let stored = dao.get(key).await.unwrap().unwrap();
        let entry: DisableEntry = serde_json::from_str(&stored).unwrap();
        assert_eq!(entry.level, 2, "disable 传入 level=2 应写入 entry.level=2");
    }

    /// 多次 disable 覆盖:对同一 login_id+service 多次 disable,DAO 中只保留最后一次。
    #[tokio::test]
    async fn t016_multiple_disable_overwrites_previous() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        // 第一次 disable(level=1)
        repo.disable("user-1006", "default", None, 1, 0)
            .await
            .unwrap();
        let key = "disable:default:user-1006";
        let entry1: DisableEntry =
            serde_json::from_str(&dao.get(key).await.unwrap().unwrap()).unwrap();
        assert_eq!(entry1.level, 1);
        // 第二次 disable(level=3)
        repo.disable("user-1006", "default", None, 3, 0)
            .await
            .unwrap();
        let entry2: DisableEntry =
            serde_json::from_str(&dao.get(key).await.unwrap().unwrap()).unwrap();
        assert_eq!(entry2.level, 3, "第二次 disable 应覆盖第一次,level 应为 3");
    }

    /// disable 后 is_disable 间接验证:disable 后 is_disable 返回 Ok(true)。
    #[tokio::test]
    async fn t016_disable_then_is_disable_returns_true() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        // 未封禁时 is_disable 返回 false
        assert!(
            !repo.is_disable("user-1007", "default").await.unwrap(),
            "未封禁时 is_disable 应返回 false"
        );
        // disable 后 is_disable 返回 true
        repo.disable("user-1007", "default", None, 0, 0)
            .await
            .unwrap();
        assert!(
            repo.is_disable("user-1007", "default").await.unwrap(),
            "disable 后 is_disable 应返回 true"
        );
    }

    /// untie_disable 不存在不报错:对未封禁的 login_id 调用 untie_disable 返回 Ok(())。
    #[tokio::test]
    async fn t016_untie_disable_missing_key_returns_ok() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        // 对未封禁的 login_id 调用 untie_disable
        let result = repo.untie_disable("never_disabled", "default").await;
        assert!(
            result.is_ok(),
            "untie_disable 对不存在的 key 应返回 Ok,实际: {:?}",
            result
        );
    }

    // ========================================================================
    // T017: 查询方法 is_disable / get_disable_time / get_disable_level 测试
    // ========================================================================

    /// 未封禁 is_disable=false(service 隔离):同一 login_id 在 "default" service 被封禁,
    /// 但在 "payment" service 上 is_disable 应返回 false(多 service 独立封禁)。
    #[tokio::test]
    async fn t017_is_disable_returns_false_for_unbanned_service() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        // 在 "default" service 上封禁
        repo.disable("user-2001", "default", None, 0, 0)
            .await
            .unwrap();
        // 同一 login_id 在 "payment" service 上应未封禁
        assert!(
            !repo.is_disable("user-2001", "payment").await.unwrap(),
            "同一 login_id 在未封禁的 service 上 is_disable 应返回 false"
        );
    }

    /// 已封禁 is_disable=true(定时封禁):disable 传入 until=Some(future) 后
    /// is_disable 返回 Ok(true)。
    #[tokio::test]
    async fn t017_is_disable_returns_true_for_timed_ban() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        let until = Utc::now() + chrono::Duration::seconds(3600);
        repo.disable("user-2002", "default", Some(until), 0, 3600)
            .await
            .unwrap();
        assert!(
            repo.is_disable("user-2002", "default").await.unwrap(),
            "定时封禁后 is_disable 应返回 true"
        );
    }

    /// get_disable_time 永久封禁返回 None:disable(until=None) 后
    /// get_disable_time 返回 Ok(None)(永久封禁无到期时间)。
    #[tokio::test]
    async fn t017_get_disable_time_returns_none_for_permanent_ban() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        repo.disable("user-2003", "default", None, 0, 0)
            .await
            .unwrap();
        assert_eq!(
            repo.get_disable_time("user-2003", "default").await.unwrap(),
            None,
            "永久封禁 get_disable_time 应返回 Ok(None)"
        );
    }

    /// get_disable_time 定时封禁返回 Some:disable(until=Some(time)) 后
    /// get_disable_time 返回 Ok(Some(time)),且时间值精确匹配。
    #[tokio::test]
    async fn t017_get_disable_time_returns_some_for_timed_ban() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        let until = Utc::now() + chrono::Duration::seconds(7200);
        repo.disable("user-2004", "default", Some(until), 0, 7200)
            .await
            .unwrap();
        let result = repo.get_disable_time("user-2004", "default").await.unwrap();
        assert_eq!(
            result,
            Some(until),
            "定时封禁 get_disable_time 应返回 Ok(Some(until)),时间值精确匹配"
        );
    }

    /// get_disable_level 正确值:disable(level=2) 后 get_disable_level 返回 Ok(Some(2))。
    #[tokio::test]
    async fn t017_get_disable_level_returns_correct_value() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        repo.disable("user-2005", "default", None, 2, 0)
            .await
            .unwrap();
        assert_eq!(
            repo.get_disable_level("user-2005", "default")
                .await
                .unwrap(),
            Some(2),
            "disable(level=2) 后 get_disable_level 应返回 Ok(Some(2))"
        );
    }

    /// get_disable_level 未封禁返回 None:未 disable 时 get_disable_level 返回 Ok(None)。
    #[tokio::test]
    async fn t017_get_disable_level_returns_none_when_not_banned() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        assert_eq!(
            repo.get_disable_level("never_banned", "default")
                .await
                .unwrap(),
            None,
            "未封禁时 get_disable_level 应返回 Ok(None)"
        );
    }

    /// 反序列化失败返回 Err:手动向 DAO 写入损坏 JSON,get_disable_time 返回 Err(Dao)。
    ///
    /// 覆盖 `serde_json::from_str` 失败路径,验证错误被包装为 `GarrisonError::Dao`。
    #[tokio::test]
    async fn t017_get_disable_time_returns_err_on_deserialize_failure() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        // 手动写入损坏 JSON 到 disable key
        let key = "disable:default:user-2006";
        dao.set(key, "{invalid json}", 0).await.unwrap();
        let result = repo.get_disable_time("user-2006", "default").await;
        assert!(
            matches!(result, Err(GarrisonError::Dao(ref msg)) if msg.contains("account-disable-deserialize")),
            "损坏 JSON 应返回 Err(GarrisonError::Dao) 含 '反序列化 DisableEntry 失败',实际: {:?}",
            result
        );
    }

    /// untie_disable 后 is_disable=false:disable 后 untie_disable,is_disable 返回 Ok(false)。
    #[tokio::test]
    async fn t017_is_disable_returns_false_after_untie_disable() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        repo.disable("user-2007", "default", None, 0, 0)
            .await
            .unwrap();
        // 封禁后 is_disable 应为 true
        assert!(
            repo.is_disable("user-2007", "default").await.unwrap(),
            "disable 后 is_disable 应为 true"
        );
        // untie_disable 后 is_disable 应为 false
        repo.untie_disable("user-2007", "default").await.unwrap();
        assert!(
            !repo.is_disable("user-2007", "default").await.unwrap(),
            "untie_disable 后 is_disable 应返回 false"
        );
    }

    /// get_disable_time 未封禁返回 None:未 disable 时 get_disable_time 返回 Ok(None)。
    #[tokio::test]
    async fn t017_get_disable_time_returns_none_when_not_banned() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        assert_eq!(
            repo.get_disable_time("never_banned", "default")
                .await
                .unwrap(),
            None,
            "未封禁时 get_disable_time 应返回 Ok(None)"
        );
    }

    // ========================================================================
    // T018: 阶梯封禁 level 支持测试
    // ========================================================================

    /// level=0 普通封禁:disable(level=0) 后 get_disable_level 返回 Ok(Some(0))。
    ///
    /// 验证默认封禁级别 0(普通封禁)可正确存储与读取。
    #[tokio::test]
    async fn t018_level_zero_normal_ban() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        repo.disable("user-3001", "default", None, 0, 0)
            .await
            .unwrap();
        assert_eq!(
            repo.get_disable_level("user-3001", "default")
                .await
                .unwrap(),
            Some(0),
            "level=0 普通封禁,get_disable_level 应返回 Ok(Some(0))"
        );
    }

    /// level=1 一级封禁:disable(level=1) 后 get_disable_level 返回 Ok(Some(1))。
    ///
    /// 验证一级阶梯封禁(如限制部分功能)可正确存储与读取。
    #[tokio::test]
    async fn t018_level_one_first_escalation() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        repo.disable("user-3002", "default", None, 1, 0)
            .await
            .unwrap();
        assert_eq!(
            repo.get_disable_level("user-3002", "default")
                .await
                .unwrap(),
            Some(1),
            "level=1 一级封禁,get_disable_level 应返回 Ok(Some(1))"
        );
    }

    /// level=3 三级封禁:disable(level=3) 后 get_disable_level 返回 Ok(Some(3))。
    ///
    /// 验证三级阶梯封禁(如完全封禁)可正确存储与读取。
    #[tokio::test]
    async fn t018_level_three_full_ban() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        repo.disable("user-3003", "default", None, 3, 0)
            .await
            .unwrap();
        assert_eq!(
            repo.get_disable_level("user-3003", "default")
                .await
                .unwrap(),
            Some(3),
            "level=3 三级封禁,get_disable_level 应返回 Ok(Some(3))"
        );
    }

    /// get_disable_level 返回正确值(高 level + JSON 持久化验证):
    /// disable(level=10) 后 get_disable_level 返回 Ok(Some(10)),
    /// 且 DAO 中的 JSON 反序列化后 level 字段也为 10。
    ///
    /// 验证高 level 值无截断/溢出,且 level 字段在 JSON 持久化层正确传递。
    #[tokio::test]
    async fn t018_get_disable_level_returns_correct_high_value() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao.clone());
        repo.disable("user-3004", "default", None, 10, 0)
            .await
            .unwrap();
        // 通过 API 验证
        assert_eq!(
            repo.get_disable_level("user-3004", "default")
                .await
                .unwrap(),
            Some(10),
            "level=10 高级封禁,get_disable_level 应返回 Ok(Some(10)) 无截断"
        );
        // 通过直接反序列化 DAO 中的 JSON 验证持久化层正确传递 level 字段
        let key = "disable:default:user-3004";
        let stored = dao.get(key).await.unwrap().unwrap();
        let entry: DisableEntry = serde_json::from_str(&stored).unwrap();
        assert_eq!(
            entry.level, 10,
            "DAO 中的 JSON 反序列化后 level 字段应为 10"
        );
    }

    // ========================================================================
    // H-1 修复:key 注入防护测试
    // ========================================================================

    /// service 含 `:` 时 disable 返回 Err,阻止 key 注入。
    #[tokio::test]
    async fn h001_disable_rejects_colon_in_service() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao);
        let result = repo.disable("1001", "evil:service", None, 0, 0).await;
        assert!(result.is_err(), "service 含冒号应被拒绝(避免 key 注入)");
    }

    /// login_id 含 `:` 时 disable 返回 Err,阻止 key 注入。
    #[tokio::test]
    async fn h001_disable_rejects_colon_in_login_id() {
        let dao = Arc::new(MockDao::new());
        let repo = DefaultDisableRepository::new(dao);
        let result = repo.disable("evil:login", "default", None, 0, 0).await;
        assert!(result.is_err(), "login_id 含冒号应被拒绝(避免 key 注入)");
    }
}