nadis 2.0.0

Redis 基础层:业务键有序分区消费、Stream/Proxy 生命周期、有界微批、幂等管线、锁与 RedisJob
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
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
// RediSearch 文档元数据、键派生与类型化查询。
//
// RedisDocument 提供静态元数据和 HASH 编解码;DocMeta 在绑定时校验配置。
// 查询 AST 在 I/O 之前校验字段类型并转义 Tag。索引策略显式区分校验、缺失时创建和重建,
// 不自动删除已有索引;缺少 FT 或 JSON 模块时返回明确错误。
//
// Hash、Json 使用直接键读取与 FT.SEARCH;JsonArray、JsonArrayBucket 使用 JSONPath 与 Lua。
// prefix 占位符按出现顺序替换,动态段禁止 :{} 以防键碰撞。分桶按 UTF-16 String.hashCode
// 与 floorMod 派生,属于持久化协议。过程宏生成的代码使用本模块公开 API。

/// RediSearch 索引生命周期、文档读写、查询和聚合执行器。
pub mod actuator;
/// RedisJSON 数组与分桶数组的原子 Lua 操作。
pub mod array;
/// 类型化 RediSearch 查询 AST 及安全渲染器。
pub mod query;

use std::collections::HashMap;

use crate::error::{NasaRedisError, Result};
use crate::partition::compat_string_hash;

/// 业务作用:把文档序列化为 JSON,并递归移除对象中值为 null 的成员。
/// 数组中的对象同样处理,数组自身的 null 元素保持原位置;该策略不依赖字段上的
/// skip_serializing_if 标记。共享 Redis key 的生产者必须采用相同字段省略规则。
/// 返回:JSON 文本;序列化失败时返回 Codec 错误。
///
/// # 参数
/// - `doc`: 当前处理的配置文档。
pub fn to_json_omit_null<T: serde::Serialize>(doc: &T) -> Result<String> {
    let mut v = serde_json::to_value(doc).map_err(|e| NasaRedisError::Codec(e.to_string()))?;
    strip_nulls(&mut v);
    serde_json::to_string(&v).map_err(|e| NasaRedisError::Codec(e.to_string()))
}

/// 业务作用:递归剔除 JSON 对象中值为 null 的成员(对象/数组深度遍历)。
///
/// # 参数
/// - `v`: 待转换的值。
fn strip_nulls(v: &mut serde_json::Value) {
    match v {
        serde_json::Value::Object(map) => {
            map.retain(|_, val| !val.is_null());
            for val in map.values_mut() {
                strip_nulls(val);
            }
        }
        serde_json::Value::Array(arr) => {
            for val in arr.iter_mut() {
                strip_nulls(val);
            }
        }
        _ => {}
    }
}

/// 存储形态。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DataType {
    /// 扁平 HASH:field=列名;FT.CREATE ON HASH。
    Hash,
    /// RedisJSON 单文档:FT.CREATE ON JSON,字段经 `$.path AS alias` 映射。
    Json,
    /// JSON 数组:1 个 ARRAY key 装多个子文档(key = prefix + @JsonArrayKey 值拼接)。
    /// 不建 FT 索引,查询走 JSONPath filter(JsonArrayOps,见 array.rs)。
    JsonArray,
    /// JSON 数组分桶:同一组 array key 散到 N 个桶 key,
    /// 桶 key 共享 `{body}` hash tag 锁同 slot,跨桶操作用 Lua 一次 RTT 扫全桶。
    JsonArrayBucket,
}

impl DataType {
    /// 业务作用:是否 ARRAY 系(JsonArrayOps 专属;SearchActuator 拒绝)。
    pub fn is_array(&self) -> bool {
        matches!(self, DataType::JsonArray | DataType::JsonArrayBucket)
    }
}

/// 字段索引类型。
#[derive(Debug, Clone, PartialEq)]
pub enum FieldType {
    /// 精确匹配(离散值:ID/状态/枚举);FT 语法 `@f:{v}`。
    /// `separator` 是多值分隔符(默认 `,`,None 表示使用 RediSearch 默认值),`case_sensitive`
    /// 控制 CASESENSITIVE(默认不区分大小写);配置必须与实际索引一致,否则匹配语义不同。
    Tag {
        /// 是否允许 RediSearch 对该字段排序。
        sortable: bool,
        /// 多值 Tag 分隔符;`None` 表示使用 RediSearch 默认值。
        separator: Option<char>,
        /// 是否启用大小写敏感匹配。
        case_sensitive: bool,
        /// WITHSUFFIXTRIE 会建立后缀树,启用 `*foo`(后缀)和 `*foo*`(包含)查询。
        with_suffix_trie: bool,
    },
    /// 全文搜索;FT 语法 `@f:(词)`。
    /// `no_stem`(NOSTEM 关闭词干还原)、`phonetic`(例如 `dm:en`)和 `no_index`
    /// (NOINDEX 只存不建倒排,仅 SORTABLE/投影用)。
    Text {
        /// 是否允许 RediSearch 对该字段排序。
        sortable: bool,
        /// 全文字段在相关性评分中的权重。
        weight: f64,
        /// 是否关闭词干还原。
        no_stem: bool,
        /// 可选的 RediSearch phonetic matcher 名称。
        phonetic: Option<String>,
        /// 是否只存储字段而不建立倒排索引。
        no_index: bool,
        /// WITHSUFFIXTRIE 会建立后缀树,启用 `*foo`(后缀)和 `*foo*`(包含)查询。
        with_suffix_trie: bool,
    },
    /// 数值范围字段,FT 语法为 `@f:[min max]`。
    /// no_index 启用 NOINDEX,只保存值而不建立数值索引,适用于 SORTABLE 或投影。
    Numeric {
        /// 是否允许 RediSearch 对该字段排序。
        sortable: bool,
        /// 是否只存储字段而不建立数值索引。
        no_index: bool,
    },
    /// 地理坐标;存储为 `"lon,lat"`,FT 语法为 `@f:[lon lat radius unit]`。
    Geo,
}

/// 一个被索引字段的元数据。
#[derive(Debug, Clone)]
pub struct FieldMeta {
    /// 业务字段名(HASH 的 field 名;JSON 模式下若未给 json_path 则默认 `$.{name}`)。
    pub name: String,
    /// RediSearch 别名(查询里 `@alias:`;空 = 用 name)。
    pub alias: String,
    /// JSON 模式的显式 JSONPath(None = `$.{name}`;HASH 模式忽略)。
    pub json_path: Option<String>,
    /// 字段的索引类型与 RediSearch 修饰参数。
    pub ftype: FieldType,
}

impl FieldMeta {
    /// 业务作用:优先返回字段别名,未配置别名时返回原字段名。
    pub fn alias_or_name(&self) -> &str {
        if self.alias.is_empty() {
            &self.name
        } else {
            &self.alias
        }
    }
}

/// prefix 的字面段或占位符字段引用。
/// DocMeta 可由手写或 derive 构造,在键派生时按需解析,不持有额外的全局解析缓存。
#[derive(Debug, Clone, PartialEq)]
pub enum KeySeg {
    /// 字面段:原样拼接。
    Lit(String),
    /// 占位符段:`{name}` —— name 仅作文档与 derive 编译期匹配用,
    /// 运行时值由调用方按占位符出现顺序提供(key_of_parts / placeholder_parts)。
    Field(String),
}

/// 文档元数据。
#[derive(Debug, Clone)]
pub struct DocMeta {
    /// RediSearch 索引名(如 "idx:order")。ARRAY 系不建索引,仍要求非空(诊断用)。
    pub index: String,
    /// Redis key 前缀。三种形态:
    ///   · 纯字面量:完整 key = prefix + id;
    ///   · 含 `{field}` 占位符:如 `"order:SMO:{sym}:{d}:"`,动态段运行时填充;
    ///   · ARRAY 系:完整 key = prefix + @JsonArrayKey 值拼接(占位符在 ARRAY 系禁用)。
    pub prefix: String,
    /// 文档在 Redis 中的存储与索引形态。
    pub data_type: DataType,
    /// 参与索引、查询和编解码的字段元数据。
    pub fields: Vec<FieldMeta>,
    /// @RsId 字段的存储名(JSONPath idFilter `@.{id_name}==…` 与 HASH 回填用)。
    pub id_name: String,
    /// id 在 JSON 文档中是否渲染为数字(serde 数值类型)。
    /// 决定 idFilter 字面量形态:数字不加引号、字符串加引号转义——
    /// 标记必须与实际存储类型一致,否则 JSONPath 等值条件无法命中。
    pub id_numeric: bool,
    /// ARRAY 系:@JsonArrayKey 字段名列表,**按 order 升序**(决定 key 拼接顺序,
    /// 是持久化协议——改顺序等于改 key,老数据查不到)。非 ARRAY 系为空。
    pub array_keys: Vec<String>,
    /// 仅 JsonArrayBucket 使用的桶数,必须大于 1;其它模式为 0。
    /// 桶数决定持久化键布局,不能热修改;变更时必须迁移已存储数据。
    pub bucket_count: u32,
}

impl DocMeta {
    /// 业务作用:构建期校验(字段在 metadata 期校验,不等到发命令才失败)。
    pub fn validate(&self) -> Result<()> {
        if self.index.is_empty() || self.prefix.is_empty() {
            return Err(NasaRedisError::Config(
                "DocMeta: index/prefix 不能为空".into(),
            ));
        }
        if self.id_name.is_empty() {
            return Err(NasaRedisError::Config("DocMeta: id_name 不能为空".into()));
        }
        let mut seen = std::collections::HashSet::new();
        for f in &self.fields {
            if f.name.is_empty() {
                return Err(NasaRedisError::Config("DocMeta: 字段 name 为空".into()));
            }
            if !seen.insert(f.alias_or_name().to_string()) {
                return Err(NasaRedisError::Config(format!(
                    "DocMeta: 别名重复 \"{}\"",
                    f.alias_or_name()
                )));
            }
        }
        // 占位符语法校验(括号配对/非空/不嵌套)——解析即校验
        let segs = self.segments()?;
        // ARRAY 系约束
        match self.data_type {
            DataType::JsonArray | DataType::JsonArrayBucket => {
                if self.array_keys.is_empty() {
                    return Err(NasaRedisError::Config(
                        "DocMeta: ARRAY 模式必须声明至少一个 array_keys(@JsonArrayKey)".into(),
                    ));
                }
                if segs.is_some() {
                    // ARRAY key = prefix + parts,动态性由 @JsonArrayKey 承担;
                    // 占位符与数组键派生叠加会造成键形态歧义,因此在发送命令前拒绝
                    return Err(NasaRedisError::Config(
                        "DocMeta: ARRAY 模式 prefix 不支持 {field} 占位符".into(),
                    ));
                }
                if self.data_type == DataType::JsonArrayBucket && self.bucket_count <= 1 {
                    return Err(NasaRedisError::Config(format!(
                        "DocMeta: JsonArrayBucket 要求 bucket_count > 1,得到 {}",
                        self.bucket_count
                    )));
                }
                if self.data_type == DataType::JsonArray && self.bucket_count != 0 {
                    return Err(NasaRedisError::Config(
                        "DocMeta: JsonArray(非 BUCKET)bucket_count 必须为 0".into(),
                    ));
                }
            }
            _ => {
                if !self.array_keys.is_empty() || self.bucket_count != 0 {
                    return Err(NasaRedisError::Config(
                        "DocMeta: array_keys/bucket_count 仅 ARRAY 模式可用".into(),
                    ));
                }
            }
        }
        Ok(())
    }

    /// 业务作用:按别名查字段(查询 renderer 用)。
    ///
    /// # 参数
    /// - `alias`: 调用方在查询、排序或聚合中使用的字段别名;空别名字段会回退匹配字段名。
    pub fn field(&self, alias: &str) -> Option<&FieldMeta> {
        self.fields.iter().find(|f| f.alias_or_name() == alias)
    }

    // ───────────────── prefix {field} 占位符─────────────────

    /// 业务作用:解析 prefix 为编译段。返回 None = 无占位符(fast path:prefix + id)。
    /// 语法:`{name}`,不嵌套;`{`/`}` 必须配对;name 非空。
    pub fn segments(&self) -> Result<Option<Vec<KeySeg>>> {
        if !self.prefix.contains('{') {
            // 孤立的 '}'(无 '{')也算语法错——它会破坏 Cluster hash tag 解析
            if self.prefix.contains('}') {
                return Err(NasaRedisError::Config(format!(
                    "DocMeta: prefix \"{}\" 含未配对的 '}}'",
                    self.prefix
                )));
            }
            return Ok(None);
        }
        let mut segs = Vec::new();
        let mut lit = String::new();
        let mut rest = self.prefix.as_str();
        while let Some(open) = rest.find('{') {
            //`{` 之前的 literal 片段含孤立 '}' = 未配对(会破坏 Cluster hash tag 解析);
            if rest[..open].contains('}') {
                return Err(NasaRedisError::Config(format!(
                    "DocMeta: prefix \"{}\" 含未配对的 '}}'",
                    self.prefix
                )));
            }
            lit.push_str(&rest[..open]);
            let after = &rest[open + 1..];
            let close = after.find('}').ok_or_else(|| {
                NasaRedisError::Config(format!("DocMeta: prefix \"{}\" 占位符未闭合", self.prefix))
            })?;
            let name = &after[..close];
            if name.is_empty() || name.contains('{') {
                return Err(NasaRedisError::Config(format!(
                    "DocMeta: prefix \"{}\" 占位符名非法(空或嵌套)",
                    self.prefix
                )));
            }
            if !lit.is_empty() {
                segs.push(KeySeg::Lit(std::mem::take(&mut lit)));
            }
            segs.push(KeySeg::Field(name.to_string()));
            rest = &after[close + 1..];
        }
        if rest.contains('}') {
            return Err(NasaRedisError::Config(format!(
                "DocMeta: prefix \"{}\" 含未配对的 '}}'",
                self.prefix
            )));
        }
        if !rest.is_empty() {
            segs.push(KeySeg::Lit(rest.to_string()));
        }
        Ok(Some(segs))
    }

    /// 业务作用:是否含占位符(业务侧据此决定走单 id API 还是 parts API)。
    pub fn has_placeholder(&self) -> bool {
        self.prefix.contains('{')
    }

    /// 业务作用:占位符段数(key_of_parts 入参校验用)。
    pub fn placeholder_count(&self) -> usize {
        self.prefix.matches('{').count()
    }

    /// 业务作用:取得 FT.CREATE PREFIX 使用的字面前缀,覆盖该文档的全部键变体。
    /// 参数说明:无。
    /// 返回:首个占位符之前的字面部分;无占位符时返回完整 prefix。
    pub fn literal_prefix(&self) -> &str {
        match self.prefix.find('{') {
            Some(i) => &self.prefix[..i],
            None => &self.prefix,
        }
    }

    /// 业务作用:在无占位符模式下把 prefix 与 id 拼成完整 Redis key。
    /// 返回:完整 key;存在占位符时返回错误,调用方须使用 key_of_parts。
    ///
    /// # 参数
    /// - `id`: 文档业务 ID,会直接拼到无占位符 prefix 之后形成 Redis key。
    pub fn key_of(&self, id: &str) -> Result<String> {
        if self.has_placeholder() {
            return Err(NasaRedisError::Config(format!(
                "prefix \"{}\" 含占位符,必须用 key_of_parts(parts, id)",
                self.prefix
            )));
        }
        Ok(format!("{}{}", self.prefix, id))
    }

    /// 业务作用:占位符模式拼 key:parts 按占位符出现顺序,id 拼末尾。
    /// 动态段(占位符值 + id)一律 check_part 禁 `:`/`{`/`}` ——
    /// 不同输入拼出相同 key = 数据互相覆盖,必须写入前拒绝。
    /// 无占位符模式要求 parts 为空,直接拼接 prefix 与 id,不对 id 做动态段校验。
    ///
    /// # 参数
    /// - `parts`: prefix 中 `{field}` 占位符对应的业务分片值,顺序必须与占位符出现顺序一致。
    /// - `id`: 文档业务 ID,作为 key 的最后一个动态段并参与防碰撞校验。
    pub fn key_of_parts(&self, parts: &[&str], id: &str) -> Result<String> {
        let Some(segs) = self.segments()? else {
            if !parts.is_empty() {
                return Err(NasaRedisError::Config(format!(
                    "prefix \"{}\" 无占位符,parts 必须为空(得到 {} 个)",
                    self.prefix,
                    parts.len()
                )));
            }
            return Ok(format!("{}{}", self.prefix, id));
        };
        let expected = self.placeholder_count();
        if parts.len() != expected {
            return Err(NasaRedisError::Config(format!(
                "prefix \"{}\" 有 {expected} 个占位符,得到 {} 个 parts",
                self.prefix,
                parts.len()
            )));
        }
        let mut out = String::with_capacity(self.prefix.len() + id.len() + 16);
        let mut idx = 0usize;
        for seg in &segs {
            match seg {
                KeySeg::Lit(s) => out.push_str(s),
                KeySeg::Field(name) => {
                    let v = parts[idx];
                    idx += 1;
                    check_part(v, &format!("占位符 {{{name}}}"))?;
                    out.push_str(v);
                }
            }
        }
        // 占位模式 id 同样校验分隔符防撞 key
        check_part(id, "@RsId")?;
        out.push_str(id);
        Ok(out)
    }

    // ───────────────── ARRAY key 派生─────────────────

    /// 业务作用:ARRAY key 主体:parts 按 array_keys 顺序以 `:` 拼接(逐段 check_part)。
    ///
    /// # 参数
    /// - `parts`: 路径、占位符或 SQL 片段拆分后的部分。
    fn array_body(&self, parts: &[&str]) -> Result<String> {
        if parts.len() != self.array_keys.len() {
            return Err(NasaRedisError::Config(format!(
                "array key 需要 {} 个 parts(@JsonArrayKey 字段数),得到 {}",
                self.array_keys.len(),
                parts.len()
            )));
        }
        let mut body = String::with_capacity(32);
        for (i, p) in parts.iter().enumerate() {
            check_part(p, &format!("@JsonArrayKey \"{}\"", self.array_keys[i]))?;
            if i > 0 {
                body.push(':');
            }
            body.push_str(p);
        }
        Ok(body)
    }

    /// 业务作用:按 array_keys 顺序构造数组键的主体。
    /// 返回:ARRAY 的完整键;BUCKET 返回尚未追加桶号的主体,继续由 bucket_key 派生。
    ///
    /// # 参数
    /// - `parts`: `array_keys` 顺序对应的业务 key 段,每段都会做分隔符和 hash tag 字符校验。
    pub fn array_key_of(&self, parts: &[&str]) -> Result<String> {
        if !self.data_type.is_array() {
            return Err(NasaRedisError::Config(format!(
                "array_key_of 仅 ARRAY 模式可用(当前 {:?})",
                self.data_type
            )));
        }
        Ok(format!("{}{}", self.prefix, self.array_body(parts)?))
    }

    /// 业务作用:按 UTF-16 String.hashCode 与 floorMod 计算子文档的稳定桶号。
    /// 该算法属于持久化协议,改变散列或 ID 文本会改变数据位置;floorMod 避免最小有符号
    /// 整数在 abs 运算中溢出。调用前元数据必须已通过 validate。
    /// 返回:小于 bucket_count 的桶号;非 JsonArrayBucket 模式返回错误。
    ///
    /// # 参数
    /// - `sub_id`: 数组子文档 ID 的最终字符串形态,用于稳定散列到 bucket。
    pub fn bucket_index_of(&self, sub_id: &str) -> Result<u32> {
        if self.data_type != DataType::JsonArrayBucket {
            return Err(NasaRedisError::Config(
                "bucket_index_of 仅 JsonArrayBucket 模式可用".into(),
            ));
        }
        let h = compat_string_hash(sub_id) as i64;
        let n = self.bucket_count as i64;
        Ok(((h % n + n) % n) as u32)
    }

    /// 业务作用:BUCKET 模式:给定 parts + subId 定位单桶 key:
    /// `prefix + "{" + body + "}" + ":bucket:" + idx`(`{body}` = Cluster hash tag,
    /// 同组所有桶必落同 slot,跨桶 Lua 不触发 CROSSSLOT)。
    ///
    /// # 参数
    /// - `parts`: `array_keys` 顺序对应的业务 key 段,决定同组数组的 hash tag 主体。
    /// - `sub_id`: 数组子文档 ID,用于选择具体 bucket 号。
    pub fn bucket_key(&self, parts: &[&str], sub_id: &str) -> Result<String> {
        let idx = self.bucket_index_of(sub_id)?;
        Ok(format!(
            "{}{{{}}}:bucket:{}",
            self.prefix,
            self.array_body(parts)?,
            idx
        ))
    }

    /// 业务作用:BUCKET 模式:全部 N 个桶 key(桶号 0..N-1 顺序;跨桶 Lua 的 KEYS 入参)。
    ///
    /// # 参数
    /// - `parts`: `array_keys` 顺序对应的业务 key 段,用于生成同组全部 bucket key。
    pub fn all_bucket_keys(&self, parts: &[&str]) -> Result<Vec<String>> {
        if self.data_type != DataType::JsonArrayBucket {
            return Err(NasaRedisError::Config(
                "all_bucket_keys 仅 JsonArrayBucket 模式可用".into(),
            ));
        }
        let tag = format!("{}{{{}}}:bucket:", self.prefix, self.array_body(parts)?);
        Ok((0..self.bucket_count)
            .map(|i| format!("{tag}{i}"))
            .collect())
    }

    /// 业务作用:`array_key_of` / `bucket_key` 的**逆向解析**:
    /// 从一个完整 key 还原出 array_key parts(scan 后按业务键归组时用)。
    /// 段数必须等于 array_keys 数,否则视为非本 entity 的 key → Err。
    /// 因 `check_part` 禁止 parts 含 `:`/`{`/`}`,对 body 直接 `split(':')` 无损还原:
    ///   · JsonArray:`prefix + "a:b"` → ["a","b"];
    ///   · JsonArrayBucket:`prefix + "{a:b}:bucket:N"` → 取 `{}` 内主体再 split。
    ///
    /// # 参数
    /// - `key`: 扫描或事件中拿到的完整 Redis key,必须属于当前 `DocMeta` 的 ARRAY key 空间。
    pub fn parse_array_key(&self, key: &str) -> Result<Vec<String>> {
        if !self.data_type.is_array() {
            return Err(NasaRedisError::Config(format!(
                "parse_array_key 仅 ARRAY 模式可用(当前 {:?})",
                self.data_type
            )));
        }
        let rest = key.strip_prefix(self.prefix.as_str()).ok_or_else(|| {
            NasaRedisError::Config(format!(
                "key \"{key}\" 不以 prefix \"{}\" 开头",
                self.prefix
            ))
        })?;
        let body = if matches!(self.data_type, DataType::JsonArrayBucket) {
            // 形如 {body}:bucket:N —— 取首个 `{` 与 `}:bucket:` 之间的主体
            rest.strip_prefix('{')
                .and_then(|s| s.split_once("}:bucket:"))
                .map(|(b, _)| b)
                .ok_or_else(|| {
                    NasaRedisError::Config(format!(
                        "bucket key \"{key}\" 形态不符 {{body}}:bucket:N"
                    ))
                })?
        } else {
            rest
        };
        let parts: Vec<String> = body.split(':').map(|s| s.to_string()).collect();
        if parts.len() != self.array_keys.len() {
            return Err(NasaRedisError::Config(format!(
                "key \"{key}\" 解析出 {} 段,期望 {}(@JsonArrayKey 字段数)",
                parts.len(),
                self.array_keys.len()
            )));
        }
        Ok(parts)
    }

    /// 业务作用:实体路径的 ARRAY key(save 用):ARRAY = 单 key;BUCKET = 按 subId 定位单桶。
    ///
    /// # 参数
    /// - `parts`: `array_keys` 顺序对应的业务 key 段。
    /// - `sub_id`: 数组子文档 ID,BUCKET 模式下用于确定写入桶。
    pub fn array_key_for(&self, parts: &[&str], sub_id: &str) -> Result<String> {
        match self.data_type {
            DataType::JsonArray => self.array_key_of(parts),
            DataType::JsonArrayBucket => self.bucket_key(parts, sub_id),
            other => Err(NasaRedisError::Config(format!(
                "array_key_for 仅 ARRAY 模式可用(当前 {other:?})"
            ))),
        }
    }

    /// 业务作用:生成 FT.CREATE 的 SCHEMA 参数序列(actuator 建索引 + 归一化比较共用同一来源,
    /// 保证"期望 schema"只有一处定义)。
    pub fn schema_args(&self) -> Vec<String> {
        let mut out = Vec::new();
        for f in &self.fields {
            match self.data_type {
                DataType::Json => {
                    // JSON 模式:identifier = JSONPath,AS alias
                    out.push(
                        f.json_path
                            .clone()
                            .unwrap_or_else(|| format!("$.{}", f.name)),
                    );
                    out.push("AS".into());
                    out.push(f.alias_or_name().to_string());
                }
                // HASH 形态(ARRAY 系不建索引,不会走到这;归 HASH 分支保持穷尽)
                _ => out.push(f.name.clone()),
            }
            // HASH 模式且 alias ≠ name:同样需要 AS
            if matches!(self.data_type, DataType::Hash) && !f.alias.is_empty() && f.alias != f.name
            {
                out.push("AS".into());
                out.push(f.alias.clone());
            }
            match &f.ftype {
                FieldType::Tag {
                    sortable,
                    separator,
                    case_sensitive,
                    with_suffix_trie,
                } => {
                    // FT.CREATE TAG 顺序:[SEPARATOR x] [CASESENSITIVE] [WITHSUFFIXTRIE] [SORTABLE]
                    out.push("TAG".into());
                    if let Some(sep) = separator {
                        out.push("SEPARATOR".into());
                        out.push(sep.to_string());
                    }
                    if *case_sensitive {
                        out.push("CASESENSITIVE".into());
                    }
                    if *with_suffix_trie {
                        out.push("WITHSUFFIXTRIE".into());
                    }
                    if *sortable {
                        out.push("SORTABLE".into());
                    }
                }
                FieldType::Text {
                    sortable,
                    weight,
                    no_stem,
                    phonetic,
                    no_index,
                    with_suffix_trie,
                } => {
                    // FT.CREATE TEXT 顺序:[NOSTEM] [WEIGHT w] [PHONETIC m] [WITHSUFFIXTRIE] [SORTABLE] [NOINDEX]
                    out.push("TEXT".into());
                    if *no_stem {
                        out.push("NOSTEM".into());
                    }
                    if (*weight - 1.0).abs() > f64::EPSILON {
                        out.push("WEIGHT".into());
                        out.push(weight.to_string());
                    }
                    if let Some(matcher) = phonetic {
                        out.push("PHONETIC".into());
                        out.push(matcher.clone());
                    }
                    if *with_suffix_trie {
                        out.push("WITHSUFFIXTRIE".into());
                    }
                    if *sortable {
                        out.push("SORTABLE".into());
                    }
                    if *no_index {
                        out.push("NOINDEX".into());
                    }
                }
                FieldType::Numeric { sortable, no_index } => {
                    // FT.CREATE NUMERIC 顺序:[SORTABLE] [NOINDEX]
                    out.push("NUMERIC".into());
                    if *sortable {
                        out.push("SORTABLE".into());
                    }
                    if *no_index {
                        out.push("NOINDEX".into());
                    }
                }
                FieldType::Geo => out.push("GEO".into()),
            }
        }
        out
    }
}

/// 业务作用:动态 key 段校验:禁 `:`(key 分隔符)与
/// `{`/`}`(Cluster hash tag 字符)——含它们的不同输入会拼出相同 key(数据互相
/// 覆盖)或破坏 slot 归属,写入前 fail-fast。
///
/// # 参数
/// - `s`: 待写入 Redis key 动态段的业务值。
/// - `desc`: 出错时展示的字段说明,用于定位是哪个占位符、ID 或 array key 字段非法。
pub fn check_part(s: &str, desc: &str) -> Result<()> {
    if s.contains(':') || s.contains('{') || s.contains('}') {
        return Err(NasaRedisError::Config(format!(
            "{desc} 值 \"{s}\" 不得含 ':'/'{{'/'}}'(':' 是 key 分隔符;'{{}}' 破坏 hash tag)"
        )));
    }
    Ok(())
}

/// 文档 trait(;手写 impl 与 #[derive(RedisDocument)] 共用同一形态——
/// 宏只是生成下面这些方法,语义零差异)。
/// HASH 编解码内聚于 trait;
/// JSON 模式经 serde(actuator 对 T: Serialize+DeserializeOwned 额外约束)。
pub trait RedisDocument: Sized + Send + Sync {
    /// 业务作用:静态元数据(进程内单例;`OnceLock` 惯用)。
    fn meta() -> &'static DocMeta;

    /// 业务作用:提供文档业务 ID,供元数据派生 Redis key 或 JSONPath 匹配条件。
    fn id(&self) -> String;

    /// 业务作用:HASH 编码:全部字段 →(field, value)字符串对(含 id 字段本身)。
    /// 占位符模式注意:占位符字段也必须在内——值只存在 key 里且 key 不可逆推,
    /// 不写 HASH 则 find(query) 读回为 null。
    fn to_fields(&self) -> Vec<(String, String)>;

    /// 业务作用:HASH 解码:从 field→value 表重建(缺字段按业务默认/报错,impl 决定)。
    ///
    /// # 参数
    /// - `fields`: Redis HASH 读取出的字段名到字符串值映射,由具体实体负责转成业务类型。
    fn from_fields(fields: &HashMap<String, String>) -> Result<Self>;

    /// 业务作用:占位符模式:按 prefix 占位符出现顺序返回渲染后的字段值
    /// 。
    fn placeholder_parts(&self) -> Vec<String> {
        Vec::new()
    }

    /// 业务作用:ARRAY 模式:按 meta().array_keys 顺序返回渲染后的 @JsonArrayKey 字段值
    /// 。
    fn array_key_parts(&self) -> Vec<String> {
        Vec::new()
    }
}