Skip to main content

yang_base/table/
table_query.rs

1//! 表查询构建器
2//!
3//! 提供基于 TableConfig 的类型安全查询构建器,支持字段权限验证和 CRUD 操作。
4//!
5//! # 主要组件
6//!
7//! - `TableQuery`:查询构建器,支持链式调用
8//!
9//! # 示例
10//!
11//! ```rust,ignore
12//! use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
13//! use std::sync::Arc;
14//!
15//! // 创建表配置
16//! let table_config = Arc::new(
17//!     TableConfig::new("users")
18//!         .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
19//!         .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
20//!         .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
21//! );
22//!
23//! // 创建查询构建器
24//! let query = TableQuery::new(
25//!     table_config,
26//!     vec!["user".to_string()],
27//!     pool,
28//! );
29//!
30//! // 链式调用构建查询
31//! let result = query
32//!     .select_fields(&["id", "name", "email"])?
33//!     .where_eq("status", json!("active"))?
34//!     .order_by("created_at", SortOrder::Desc)?
35//!     .page(1, 20)?
36//!     .execute()
37//!     .await?;
38//! ```
39
40use crate::error::BaseError;
41use crate::table::{QueryParams, SortOrder, TableConfig, WhereCondition};
42#[cfg(feature = "mysql")]
43use serde::Serialize;
44use serde_json::Value;
45use std::collections::HashSet;
46use std::sync::Arc;
47
48/// 受保护表查询允许的最大单页大小。
49///
50/// 该上限必须在 `TableQuery` 底层执行,而不能只放在上层 action。自定义 action 或库调用方
51/// 可直接调用 `ctx.table_query()?.page(...)`,底层没有上限会绕过内置 `SelectAction` 的保护,
52/// 导致超大查询拖垮数据库或应用内存。
53pub const MAX_TABLE_QUERY_PAGE_SIZE: usize = super::query_params::MAX_QUERY_PAGE_SIZE;
54
55/// 表查询构建器
56///
57/// 基于 TableConfig 创建类型安全的查询构建器,支持:
58/// - 字段选择和权限验证
59/// - WHERE 条件构建
60/// - 排序规则
61/// - 分页查询
62///
63/// # 字段
64///
65/// - `table_config`:表配置引用,包含字段定义和权限配置
66/// - `user_roles`:用户角色列表,用于权限检查
67/// - `query_params`:查询参数,包含字段选择、WHERE 条件、排序规则和分页参数
68/// - `pool`:数据库连接池引用(预留,暂未使用)
69///
70/// # 示例
71///
72/// ```rust,ignore
73/// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
74/// use std::sync::Arc;
75/// use serde_json::json;
76///
77/// let table_config = Arc::new(
78///     TableConfig::new("users")
79///         .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
80///         .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
81/// );
82///
83/// let query = TableQuery::new(
84///     table_config,
85///     vec!["admin".to_string()],
86///     pool,
87/// );
88///
89/// // 选择字段
90/// let query = query.select_fields(&["id", "name"])?;
91///
92/// // 添加 WHERE 条件
93/// let query = query.where_eq("status", json!(1))?;
94///
95/// // 添加排序
96/// let query = query.order_by("created_at", SortOrder::Desc)?;
97///
98/// // 设置分页
99/// let query = query.page(1, 20)?;
100/// ```
101#[derive(Debug, Clone)]
102pub struct TableQuery {
103    /// 表配置引用
104    ///
105    /// 包含表结构、字段定义和权限配置
106    table_config: Arc<TableConfig>,
107
108    /// 用户角色列表
109    ///
110    /// 使用 Arc<[String]> 共享所有权,避免不必要的克隆
111    user_roles: Arc<[String]>,
112    /// 用户角色 HashSet 缓存(O(1) 查找,避免每次 can_read/can_write 时转换)
113    user_roles_set: HashSet<String>,
114
115    /// 查询参数
116    ///
117    /// 包含字段选择、WHERE 条件、排序规则和分页参数
118    query_params: QueryParams,
119
120    /// 是否在读取路径包含软删除记录
121    ///
122    /// 默认 `false`:配置了 `soft_delete_field` 的表,软删行不出现在
123    /// select/count/paginate 结果中。置为 `true`(经 [`TableQuery::with_trashed`])
124    /// 时读取全量(含已软删行)。
125    include_trashed: bool,
126
127    /// 是否允许无 WHERE 的全表 UPDATE/DELETE
128    ///
129    /// 默认 `false`:无 WHERE 的更新/删除会返回 [`BaseError::MissingWhereClause`],
130    /// 与 yang-db 的安全网对齐。置为 `true`(经 [`TableQuery::allow_full_table`])
131    /// 时显式放行全表操作。
132    allow_full_table: bool,
133
134    /// 数据库连接池引用(预留)
135    ///
136    /// 暂未使用,预留用于后续实现 CRUD 操作
137    #[cfg(feature = "mysql")]
138    #[allow(dead_code)]
139    pool: Option<Arc<sqlx::MySqlPool>>,
140
141    /// 慢查询阈值(可观测性 C4)
142    ///
143    /// `Some(d)` 时,单次执行耗时超过 `d` 会 `tracing::warn!`;`None`(默认)
144    /// 整个计时分支短路,热路径仅一次 `Instant::now()`,无分配。
145    /// 由 [`ActionContext::table_query`](crate::action::ActionContext) 从
146    /// [`ObservabilityConfig`](crate::observability::ObservabilityConfig) 注入。
147    slow_threshold: Option<std::time::Duration>,
148
149    /// 本次派发的运行期标识(用于慢查询日志串联),由 ActionContext 注入。
150    request_id: Option<crate::action::RequestId>,
151}
152
153/// 检查字符串是否为合法的 SQL 标识符
154///
155/// 合法标识符规则:
156/// - 首字符必须是 ASCII 字母或下划线
157/// - 后续字符必须是 ASCII 字母、数字或下划线
158/// - 不能为空
159/// - 不能包含分号、`--`、空白字符
160#[cfg(feature = "mysql")]
161fn is_valid_identifier(s: &str) -> bool {
162    if s.is_empty() {
163        return false;
164    }
165    let mut chars = s.chars();
166    match chars.next() {
167        Some(c) if c.is_ascii_alphabetic() || c == '_' => {}
168        _ => return false,
169    }
170    chars.all(|c| c.is_ascii_alphanumeric() || c == '_')
171}
172
173impl TableQuery {
174    /// 对字段名进行反引号转义
175    ///
176    /// 对合法标识符添加反引号,内部反引号转义为双反引号。
177    /// 非法字段名返回 `BaseError::FieldNotFound`。
178    ///
179    /// # 参数
180    ///
181    /// - `field`: 字段名
182    ///
183    /// # 返回
184    ///
185    /// - `Ok(String)`: 转义后的字段名,如 `` `field_name` ``
186    /// - `Err(BaseError)`: 字段名非法
187    #[cfg(feature = "mysql")]
188    fn quote_identifier(&self, field: &str) -> Result<String, BaseError> {
189        if !is_valid_identifier(field) {
190            return Err(BaseError::FieldNotFound(
191                self.table_config.table_name.clone(),
192                field.to_string(),
193            ));
194        }
195        // 反引号转义:内部反引号变双反引号
196        Ok(format!("`{}`", field.replace('`', "``")))
197    }
198
199    /// 对表名进行反引号转义(与字段名走同一条校验/转义路径)
200    ///
201    /// 防止非法表名破坏引号边界。表名虽来自开发者配置而非终端用户输入,
202    /// 但统一转义可消除字段名与表名处理的不一致(防御纵深)。
203    ///
204    /// # 返回
205    ///
206    /// - `Ok(String)`: 转义后的表名,如 `` `users` ``
207    /// - `Err(BaseError)`: 表名非法
208    #[cfg(feature = "mysql")]
209    fn quoted_table_name(&self) -> Result<String, BaseError> {
210        let name = &self.table_config.table_name;
211        if !is_valid_identifier(name) {
212            return Err(BaseError::FieldNotFound(
213                name.clone(),
214                "非法表名".to_string(),
215            ));
216        }
217        Ok(format!("`{}`", name.replace('`', "``")))
218    }
219
220    /// 创建新的查询构建器
221    ///
222    /// # 参数
223    ///
224    /// - `table_config`:表配置引用
225    /// - `user_roles`:用户角色列表(`Arc<[String]>` 共享所有权)
226    /// - `pool`:数据库连接池引用(可选)
227    ///
228    /// # 返回值
229    ///
230    /// 返回新的 TableQuery 实例
231    #[cfg(feature = "mysql")]
232    pub fn new(
233        table_config: Arc<TableConfig>,
234        user_roles: Arc<[String]>,
235        pool: Option<Arc<sqlx::MySqlPool>>,
236    ) -> Self {
237        let user_roles_set: HashSet<String> = user_roles.iter().cloned().collect();
238        Self {
239            table_config,
240            user_roles,
241            user_roles_set,
242            query_params: QueryParams::new(),
243            include_trashed: false,
244            allow_full_table: false,
245            pool,
246            slow_threshold: None,
247            request_id: None,
248        }
249    }
250
251    /// 创建新的查询构建器(无数据库连接池)
252    ///
253    /// 当未启用 `mysql` feature 时使用此方法。
254    #[cfg(not(feature = "mysql"))]
255    pub fn new(
256        table_config: Arc<TableConfig>,
257        user_roles: Arc<[String]>,
258        _pool: Option<()>,
259    ) -> Self {
260        let user_roles_set: HashSet<String> = user_roles.iter().cloned().collect();
261        Self {
262            table_config,
263            user_roles,
264            user_roles_set,
265            query_params: QueryParams::new(),
266            include_trashed: false,
267            allow_full_table: false,
268            slow_threshold: None,
269            request_id: None,
270        }
271    }
272
273    /// 设置慢查询阈值(链式)。超过该耗时的单次执行会 `tracing::warn!`。
274    ///
275    /// 通常由 `ActionContext::table_query()` 从全局 `ObservabilityConfig` 注入;
276    /// 也可手动覆盖。`None`/不调用时不启用慢查询日志。
277    pub fn with_slow_threshold(mut self, threshold: Option<std::time::Duration>) -> Self {
278        self.slow_threshold = threshold;
279        self
280    }
281
282    /// 设置本次查询关联的 request_id(链式),用于慢查询日志串联。
283    pub fn with_request_id(mut self, request_id: crate::action::RequestId) -> Self {
284        self.request_id = Some(request_id);
285        self
286    }
287
288    /// 选择查询字段
289    ///
290    /// 设置要查询的字段列表,并验证:
291    /// 1. 字段是否存在于表配置中
292    /// 2. 用户是否有字段的读取权限
293    ///
294    /// # 参数
295    ///
296    /// - `fields`:字段名列表
297    ///
298    /// # 返回值
299    ///
300    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
301    /// - `Err(BaseError)`:验证失败,返回错误
302    ///
303    /// # 错误
304    ///
305    /// - `BaseError::FieldNotFound`:字段不存在
306    /// - `BaseError::FieldPermissionDenied`:用户无读取权限
307    ///
308    /// # 示例
309    ///
310    /// ```rust
311    /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
312    /// use std::sync::Arc;
313    ///
314    /// // 创建表配置
315    /// let table_config = Arc::new(
316    ///     TableConfig::new("users")
317    ///         .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
318    ///         .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
319    ///         .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
320    /// );
321    ///
322    /// // 创建查询构建器(不需要数据库连接)
323    /// let query = TableQuery::new(
324    ///     table_config,
325    ///     Arc::from(vec!["admin".to_string()]),
326    ///     None,
327    /// );
328    ///
329    /// // 选择存在的字段,应成功
330    /// let result = query.select_fields(&["id", "name", "email"]);
331    /// assert!(result.is_ok());
332    ///
333    /// // 选择不存在的字段,应返回错误
334    /// let table_config2 = Arc::new(
335    ///     TableConfig::new("users")
336    ///         .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
337    /// );
338    /// let query2 = TableQuery::new(
339    ///     table_config2,
340    ///     Arc::from(vec!["admin".to_string()]),
341    ///     None,
342    /// );
343    /// let result2 = query2.select_fields(&["nonexistent_field"]);
344    /// assert!(result2.is_err());
345    /// ```
346    fn validate_read_field(&self, field_name: &str) -> Result<(), BaseError> {
347        let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
348            BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.to_string())
349        })?;
350
351        if !field_config.permissions.can_read(&self.user_roles_set) {
352            return Err(BaseError::FieldPermissionDenied(
353                self.table_config.table_name.clone(),
354                field_name.to_string(),
355                "用户无读取权限".to_string(),
356            ));
357        }
358
359        Ok(())
360    }
361
362    fn validate_all_fields_readable_for_roles(
363        &self,
364        roles: &HashSet<String>,
365    ) -> Result<(), BaseError> {
366        if let Some(field_name) = self
367            .table_config
368            .fields
369            .iter()
370            .filter_map(|(field_name, field_config)| {
371                (!field_config.permissions.can_read(roles)).then_some(field_name)
372            })
373            .min()
374        {
375            return Err(BaseError::FieldPermissionDenied(
376                self.table_config.table_name.clone(),
377                field_name.clone(),
378                "用户无读取权限".to_string(),
379            ));
380        }
381        Ok(())
382    }
383
384    #[cfg(feature = "mysql")]
385    fn validate_all_fields_readable(&self) -> Result<(), BaseError> {
386        self.validate_all_fields_readable_for_roles(&self.user_roles_set)
387    }
388
389    /// 选择要查询的字段。
390    ///
391    /// 会校验字段存在,并校验当前用户角色具备这些字段的读取权限。
392    pub fn select_fields(mut self, fields: &[&str]) -> Result<Self, BaseError> {
393        if fields.is_empty() {
394            return Err(BaseError::ParamInvalid(
395                "fields".to_string(),
396                "查询字段列表不能为空".to_string(),
397            ));
398        }
399
400        // 验证每个字段
401        for field_name in fields {
402            self.validate_read_field(field_name)?;
403        }
404
405        // 设置字段列表
406        self.query_params.fields = Some(fields.iter().map(|s| s.to_string()).collect());
407
408        Ok(self)
409    }
410
411    /// 强制校验当前用户对表内所有字段的读权限
412    ///
413    /// 内置 Get/Select Action 读取整实体(`SELECT *`)时,在执行查询前调用本方法,
414    /// 确保不会把用户无权读取的字段一并返回。遍历表配置中的每个字段,对
415    /// `readable_roles` 非空且用户不具备任一可读角色的字段返回
416    /// [`BaseError::FieldPermissionDenied`]。与 [`TableQuery::select_fields`] 的
417    /// `can_read` 判定机制保持一致。
418    ///
419    /// # 参数
420    ///
421    /// - `user`:当前用户(其 `roles` 用于权限判定)
422    ///
423    /// # 返回值
424    ///
425    /// - `Ok(())`:用户对全部字段可读
426    /// - `Err(BaseError::FieldPermissionDenied)`:存在不可读字段
427    pub fn ensure_fields_readable(&self, user: &crate::action::User) -> Result<(), BaseError> {
428        self.validate_all_fields_readable_for_roles(&user.roles)
429    }
430
431    /// 添加等于条件 (WHERE field = value)
432    ///
433    /// 添加 WHERE 等于条件,并验证:
434    /// 1. 字段是否存在于表配置中
435    /// 2. 用户是否有字段的筛选权限
436    ///
437    /// # 参数
438    ///
439    /// - `field`:字段名
440    /// - `value`:比较值
441    ///
442    /// # 返回值
443    ///
444    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
445    /// - `Err(BaseError)`:验证失败,返回错误
446    ///
447    /// # 错误
448    ///
449    /// - `BaseError::FieldNotFound`:字段不存在
450    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
451    ///
452    /// # 示例
453    ///
454    /// ```rust,ignore
455    /// use serde_json::json;
456    ///
457    /// let query = query.where_eq("status", json!("active"))?;
458    /// ```
459    pub fn where_eq(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
460        // 验证字段和权限
461        self.validate_filter_field(field)?;
462
463        // 添加 WHERE 条件
464        self.query_params.where_conditions.push(WhereCondition::Eq {
465            field: field.to_string(),
466            value,
467        });
468
469        Ok(self)
470    }
471
472    /// 添加包含条件 (WHERE field IN (values))
473    ///
474    /// 添加 WHERE IN 条件,并验证:
475    /// 1. 字段是否存在于表配置中
476    /// 2. 用户是否有字段的筛选权限
477    ///
478    /// # 参数
479    ///
480    /// - `field`:字段名
481    /// - `values`:值列表
482    ///
483    /// # 返回值
484    ///
485    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
486    /// - `Err(BaseError)`:验证失败,返回错误
487    ///
488    /// # 错误
489    ///
490    /// - `BaseError::FieldNotFound`:字段不存在
491    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
492    ///
493    /// # 示例
494    ///
495    /// ```rust,ignore
496    /// use serde_json::json;
497    ///
498    /// let query = query.where_in("status", vec![json!(1), json!(2), json!(3)])?;
499    /// ```
500    pub fn where_in(mut self, field: &str, values: Vec<Value>) -> Result<Self, BaseError> {
501        if values.is_empty() {
502            return Err(BaseError::ParamInvalid(
503                "values".to_string(),
504                "IN 列表不能为空".to_string(),
505            ));
506        }
507
508        // QRY-2: IN 列表元素数上限
509        if values.len() > Self::MAX_IN_LIST_SIZE {
510            return Err(BaseError::ParamInvalid(
511                "values".to_string(),
512                format!(
513                    "IN 列表元素数 {} 超过上限 {}",
514                    values.len(),
515                    Self::MAX_IN_LIST_SIZE
516                ),
517            ));
518        }
519
520        // 验证字段和权限
521        self.validate_filter_field(field)?;
522
523        // 添加 WHERE 条件
524        self.query_params.where_conditions.push(WhereCondition::In {
525            field: field.to_string(),
526            values,
527        });
528
529        Ok(self)
530    }
531
532    /// 添加模糊匹配条件 (WHERE field LIKE pattern)
533    ///
534    /// 添加 WHERE LIKE 条件,并验证:
535    /// 1. 字段是否存在于表配置中
536    /// 2. 用户是否有字段的筛选权限
537    ///
538    /// # 参数
539    ///
540    /// - `field`:字段名
541    /// - `pattern`:匹配模式,支持 % 和 _ 通配符
542    ///
543    /// # 返回值
544    ///
545    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
546    /// - `Err(BaseError)`:验证失败,返回错误
547    ///
548    /// # 错误
549    ///
550    /// - `BaseError::FieldNotFound`:字段不存在
551    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
552    ///
553    /// # 示例
554    ///
555    /// ```rust,ignore
556    /// let query = query.where_like("name", "%alice%")?;
557    /// ```
558    pub fn where_like(mut self, field: &str, pattern: String) -> Result<Self, BaseError> {
559        // QRY-1: LIKE pattern 长度上限
560        if pattern.len() > Self::MAX_LIKE_PATTERN_LEN {
561            return Err(BaseError::ParamInvalid(
562                "pattern".to_string(),
563                format!(
564                    "LIKE pattern 长度 {} 超过上限 {}",
565                    pattern.len(),
566                    Self::MAX_LIKE_PATTERN_LEN
567                ),
568            ));
569        }
570
571        // 验证字段和权限
572        self.validate_filter_field(field)?;
573
574        // 添加 WHERE 条件
575        self.query_params
576            .where_conditions
577            .push(WhereCondition::Like {
578                field: field.to_string(),
579                pattern,
580            });
581
582        Ok(self)
583    }
584
585    /// 添加模糊匹配条件 (WHERE field LIKE '%keyword%')
586    ///
587    /// 便捷方法:自动将 `keyword` 用 `%` 包裹,并转义其中的 `%` 和 `_` 通配符,
588    /// 避免用户输入中的通配符被解释为 SQL LIKE 语法。
589    ///
590    /// # 参数
591    ///
592    /// - `field`:字段名
593    /// - `keyword`:搜索关键词(无需手动加 `%`)
594    ///
595    /// # 返回值
596    ///
597    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
598    /// - `Err(BaseError)`:验证失败(字段不存在 / 无权限 / 转义后超长)
599    ///
600    /// # 示例
601    ///
602    /// ```rust,ignore
603    /// // WHERE name LIKE '%alice%',且 "%" / "_" 被转义
604    /// let query = query.where_contains("name", "alice")?;
605    /// ```
606    pub fn where_contains(mut self, field: &str, keyword: &str) -> Result<Self, BaseError> {
607        if keyword.trim().is_empty() {
608            return Err(BaseError::ParamInvalid(
609                "keyword".to_string(),
610                "搜索关键词不能为空".to_string(),
611            ));
612        }
613
614        // 转义 LIKE 通配符:% → \%,_ → \_
615        let escaped = keyword
616            .replace('\\', "\\\\")
617            .replace('%', "\\%")
618            .replace('_', "\\_");
619        let pattern = format!("%{}%", escaped);
620
621        // 复用 where_like 的校验(含 pattern 长度上限 + 字段权限)
622        self = self.where_like(field, pattern)?;
623        Ok(self)
624    }
625
626    /// 添加不等于条件 (WHERE field <> value)
627    ///
628    /// 添加 WHERE 不等于条件,并验证:
629    /// 1. 字段是否存在于表配置中
630    /// 2. 用户是否有字段的筛选权限
631    ///
632    /// # 参数
633    ///
634    /// - `field`:字段名
635    /// - `value`:比较值
636    ///
637    /// # 返回值
638    ///
639    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
640    /// - `Err(BaseError)`:验证失败,返回错误
641    ///
642    /// # 错误
643    ///
644    /// - `BaseError::FieldNotFound`:字段不存在
645    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
646    pub fn where_ne(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
647        self.validate_filter_field(field)?;
648        self.query_params.where_conditions.push(WhereCondition::Ne {
649            field: field.to_string(),
650            value,
651        });
652        Ok(self)
653    }
654
655    /// 添加小于条件 (WHERE field < value)
656    ///
657    /// 添加 WHERE 小于条件,并验证:
658    /// 1. 字段是否存在于表配置中
659    /// 2. 用户是否有字段的筛选权限
660    ///
661    /// # 参数
662    ///
663    /// - `field`:字段名
664    /// - `value`:比较值
665    ///
666    /// # 返回值
667    ///
668    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
669    /// - `Err(BaseError)`:验证失败,返回错误
670    ///
671    /// # 错误
672    ///
673    /// - `BaseError::FieldNotFound`:字段不存在
674    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
675    pub fn where_lt(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
676        self.validate_filter_field(field)?;
677        self.query_params.where_conditions.push(WhereCondition::Lt {
678            field: field.to_string(),
679            value,
680        });
681        Ok(self)
682    }
683
684    /// 添加小于等于条件 (WHERE field <= value)
685    ///
686    /// 添加 WHERE 小于等于条件,并验证:
687    /// 1. 字段是否存在于表配置中
688    /// 2. 用户是否有字段的筛选权限
689    ///
690    /// # 参数
691    ///
692    /// - `field`:字段名
693    /// - `value`:比较值
694    ///
695    /// # 返回值
696    ///
697    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
698    /// - `Err(BaseError)`:验证失败,返回错误
699    ///
700    /// # 错误
701    ///
702    /// - `BaseError::FieldNotFound`:字段不存在
703    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
704    pub fn where_lte(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
705        self.validate_filter_field(field)?;
706        self.query_params
707            .where_conditions
708            .push(WhereCondition::Lte {
709                field: field.to_string(),
710                value,
711            });
712        Ok(self)
713    }
714
715    /// 添加大于条件 (WHERE field > value)
716    ///
717    /// 添加 WHERE 大于条件,并验证:
718    /// 1. 字段是否存在于表配置中
719    /// 2. 用户是否有字段的筛选权限
720    ///
721    /// # 参数
722    ///
723    /// - `field`:字段名
724    /// - `value`:比较值
725    ///
726    /// # 返回值
727    ///
728    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
729    /// - `Err(BaseError)`:验证失败,返回错误
730    ///
731    /// # 错误
732    ///
733    /// - `BaseError::FieldNotFound`:字段不存在
734    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
735    pub fn where_gt(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
736        self.validate_filter_field(field)?;
737        self.query_params.where_conditions.push(WhereCondition::Gt {
738            field: field.to_string(),
739            value,
740        });
741        Ok(self)
742    }
743
744    /// 添加大于等于条件 (WHERE field >= value)
745    ///
746    /// 添加 WHERE 大于等于条件,并验证:
747    /// 1. 字段是否存在于表配置中
748    /// 2. 用户是否有字段的筛选权限
749    ///
750    /// # 参数
751    ///
752    /// - `field`:字段名
753    /// - `value`:比较值
754    ///
755    /// # 返回值
756    ///
757    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
758    /// - `Err(BaseError)`:验证失败,返回错误
759    ///
760    /// # 错误
761    ///
762    /// - `BaseError::FieldNotFound`:字段不存在
763    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
764    pub fn where_gte(mut self, field: &str, value: Value) -> Result<Self, BaseError> {
765        self.validate_filter_field(field)?;
766        self.query_params
767            .where_conditions
768            .push(WhereCondition::Gte {
769                field: field.to_string(),
770                value,
771            });
772        Ok(self)
773    }
774
775    /// 添加区间条件 (WHERE field BETWEEN lo AND hi)
776    ///
777    /// 添加 WHERE BETWEEN 条件,并验证:
778    /// 1. 字段是否存在于表配置中
779    /// 2. 用户是否有字段的筛选权限
780    ///
781    /// 当 `lo > hi` 时 BETWEEN 返回空集(MySQL 标准行为,框架不做特殊处理)。
782    ///
783    /// # 参数
784    ///
785    /// - `field`:字段名
786    /// - `lo`:区间下界(包含)
787    /// - `hi`:区间上界(包含)
788    ///
789    /// # 返回值
790    ///
791    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
792    /// - `Err(BaseError)`:验证失败,返回错误
793    ///
794    /// # 错误
795    ///
796    /// - `BaseError::FieldNotFound`:字段不存在
797    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
798    pub fn where_between(mut self, field: &str, lo: Value, hi: Value) -> Result<Self, BaseError> {
799        self.validate_filter_field(field)?;
800        self.query_params
801            .where_conditions
802            .push(WhereCondition::Between {
803                field: field.to_string(),
804                lo,
805                hi,
806            });
807        Ok(self)
808    }
809
810    /// 添加空值判断 (WHERE field IS NULL)
811    ///
812    /// 添加 WHERE IS NULL 条件,并验证:
813    /// 1. 字段是否存在于表配置中
814    /// 2. 用户是否有字段的筛选权限
815    ///
816    /// # 参数
817    ///
818    /// - `field`:字段名
819    ///
820    /// # 返回值
821    ///
822    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
823    /// - `Err(BaseError)`:验证失败,返回错误
824    ///
825    /// # 错误
826    ///
827    /// - `BaseError::FieldNotFound`:字段不存在
828    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
829    pub fn where_null(mut self, field: &str) -> Result<Self, BaseError> {
830        self.validate_filter_field(field)?;
831        self.query_params
832            .where_conditions
833            .push(WhereCondition::IsNull {
834                field: field.to_string(),
835            });
836        Ok(self)
837    }
838
839    /// 添加非空值判断 (WHERE field IS NOT NULL)
840    ///
841    /// 添加 WHERE IS NOT NULL 条件,并验证:
842    /// 1. 字段是否存在于表配置中
843    /// 2. 用户是否有字段的筛选权限
844    ///
845    /// # 参数
846    ///
847    /// - `field`:字段名
848    ///
849    /// # 返回值
850    ///
851    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
852    /// - `Err(BaseError)`:验证失败,返回错误
853    ///
854    /// # 错误
855    ///
856    /// - `BaseError::FieldNotFound`:字段不存在
857    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
858    pub fn where_not_null(mut self, field: &str) -> Result<Self, BaseError> {
859        self.validate_filter_field(field)?;
860        self.query_params
861            .where_conditions
862            .push(WhereCondition::IsNotNull {
863                field: field.to_string(),
864            });
865        Ok(self)
866    }
867
868    /// 添加不在列表条件 (WHERE field NOT IN (values))
869    ///
870    /// 添加 WHERE NOT IN 条件,并验证:
871    /// 1. 字段是否存在于表配置中
872    /// 2. 用户是否有字段的筛选权限
873    ///
874    /// # 参数
875    ///
876    /// - `field`:字段名
877    /// - `values`:排除值列表
878    ///
879    /// # 返回值
880    ///
881    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
882    /// - `Err(BaseError)`:验证失败,返回错误
883    ///
884    /// # 错误
885    ///
886    /// - `BaseError::FieldNotFound`:字段不存在
887    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
888    pub fn where_not_in(mut self, field: &str, values: Vec<Value>) -> Result<Self, BaseError> {
889        if values.is_empty() {
890            return Err(BaseError::ParamInvalid(
891                "values".to_string(),
892                "NOT IN 列表不能为空".to_string(),
893            ));
894        }
895
896        // QRY-2: NOT IN 列表元素数上限
897        if values.len() > Self::MAX_IN_LIST_SIZE {
898            return Err(BaseError::ParamInvalid(
899                "values".to_string(),
900                format!(
901                    "NOT IN 列表元素数 {} 超过上限 {}",
902                    values.len(),
903                    Self::MAX_IN_LIST_SIZE
904                ),
905            ));
906        }
907
908        self.validate_filter_field(field)?;
909        self.query_params
910            .where_conditions
911            .push(WhereCondition::NotIn {
912                field: field.to_string(),
913                values,
914            });
915        Ok(self)
916    }
917
918    /// 添加排序规则 (ORDER BY field direction)
919    ///
920    /// 添加排序规则,并验证:
921    /// 1. 字段是否存在于表配置中
922    /// 2. 用户是否有字段的排序权限
923    ///
924    /// # 参数
925    ///
926    /// - `field`:字段名
927    /// - `order`:排序方向 (Asc 或 Desc)
928    ///
929    /// # 返回值
930    ///
931    /// - `Ok(Self)`:验证通过,返回 self 支持链式调用
932    /// - `Err(BaseError)`:验证失败,返回错误
933    ///
934    /// # 错误
935    ///
936    /// - `BaseError::FieldNotFound`:字段不存在
937    /// - `BaseError::FieldPermissionDenied`:用户无排序权限
938    ///
939    /// # 示例
940    ///
941    /// ```rust,ignore
942    /// use yang_base::table::SortOrder;
943    ///
944    /// let query = query.order_by("created_at", SortOrder::Desc)?;
945    /// ```
946    fn validate_order_field(&self, field: &str) -> Result<(), BaseError> {
947        // 1. 检查字段是否存在
948        let field_config = self.table_config.get_field(field).ok_or_else(|| {
949            BaseError::FieldNotFound(self.table_config.table_name.clone(), field.to_string())
950        })?;
951
952        // 2. 字段级排序开关:标记为不可排序的字段直接拒绝(先于角色权限,
953        //    确保 `.sortable(false)` 是硬约束而非可被空角色列表绕过的软提示)
954        if !field_config.sortable {
955            return Err(BaseError::FieldPermissionDenied(
956                self.table_config.table_name.clone(),
957                field.to_string(),
958                "字段不允许排序".to_string(),
959            ));
960        }
961
962        // 3. 检查用户是否有排序权限
963        if !field_config.permissions.can_sort(&self.user_roles_set) {
964            return Err(BaseError::FieldPermissionDenied(
965                self.table_config.table_name.clone(),
966                field.to_string(),
967                "用户无排序权限".to_string(),
968            ));
969        }
970
971        Ok(())
972    }
973
974    /// 添加排序规则。
975    ///
976    /// 会校验字段存在、字段允许排序,以及当前用户角色具备排序权限。
977    pub fn order_by(mut self, field: &str, order: SortOrder) -> Result<Self, BaseError> {
978        self.validate_order_field(field)?;
979
980        // 添加排序规则
981        self.query_params.order_by.push((field.to_string(), order));
982
983        Ok(self)
984    }
985
986    /// 设置分页参数 (LIMIT and OFFSET)
987    ///
988    /// 设置查询的分页参数
989    ///
990    /// # 参数
991    ///
992    /// - `page`:当前页码,从 1 开始
993    /// - `page_size`:每页大小
994    ///
995    /// # 返回值
996    ///
997    /// 返回 self 支持链式调用
998    ///
999    /// # 示例
1000    ///
1001    /// ```rust,ignore
1002    /// let query = query.page(1, 20)?;
1003    /// ```
1004    pub fn page(mut self, page: usize, page_size: usize) -> Result<Self, BaseError> {
1005        if page == 0 || page_size == 0 {
1006            return Err(BaseError::ParamInvalid(
1007                "page".to_string(),
1008                "页码与每页大小必须从 1 开始且大于 0".to_string(),
1009            ));
1010        }
1011        if page_size > MAX_TABLE_QUERY_PAGE_SIZE {
1012            return Err(BaseError::ParamInvalid(
1013                "page_size".to_string(),
1014                format!("每页大小不能超过 {}", MAX_TABLE_QUERY_PAGE_SIZE),
1015            ));
1016        }
1017        self.query_params.page = Some(page);
1018        self.query_params.page_size = Some(page_size);
1019        Ok(self)
1020    }
1021
1022    /// 在读取路径包含软删除记录
1023    ///
1024    /// 默认情况下,配置了 `soft_delete_field` 的表会在 select/count/paginate
1025    /// 时自动追加 `软删字段 IS NULL` 过滤,隐藏已软删行。调用本方法后,本次查询
1026    /// 读取全量数据(含已软删行)。
1027    ///
1028    /// # 返回值
1029    ///
1030    /// 返回 self 支持链式调用
1031    pub fn with_trashed(mut self) -> Self {
1032        self.include_trashed = true;
1033        self
1034    }
1035
1036    /// 允许无 WHERE 条件的全表 UPDATE/DELETE
1037    ///
1038    /// 默认情况下,未设置任何 WHERE 条件的更新/删除会返回
1039    /// [`BaseError::MissingWhereClause`] 以防止误操作整表。调用本方法显式放行
1040    /// 全表操作(如批量初始化、清空表)。
1041    ///
1042    /// # 返回值
1043    ///
1044    /// 返回 self 支持链式调用
1045    pub fn allow_full_table(mut self) -> Self {
1046        self.allow_full_table = true;
1047        self
1048    }
1049
1050    /// 验证筛选字段的权限
1051    ///
1052    /// 内部辅助方法,用于验证字段是否存在以及用户是否有筛选权限
1053    ///
1054    /// # 参数
1055    ///
1056    /// - `field`:字段名
1057    ///
1058    /// # 返回值
1059    ///
1060    /// - `Ok(())`:验证通过
1061    /// - `Err(BaseError)`:验证失败
1062    ///
1063    /// # 错误
1064    ///
1065    /// - `BaseError::FieldNotFound`:字段不存在
1066    /// - `BaseError::FieldPermissionDenied`:用户无筛选权限
1067    fn validate_filter_field(&self, field: &str) -> Result<(), BaseError> {
1068        // 1. 检查字段是否存在
1069        let field_config = self.table_config.get_field(field).ok_or_else(|| {
1070            BaseError::FieldNotFound(self.table_config.table_name.clone(), field.to_string())
1071        })?;
1072
1073        // 2. 字段级筛选开关:标记为不可筛选的字段直接拒绝(先于角色权限,
1074        //    确保 `.filterable(false)` 是硬约束而非可被空角色列表绕过的软提示)
1075        if !field_config.filterable {
1076            return Err(BaseError::FieldPermissionDenied(
1077                self.table_config.table_name.clone(),
1078                field.to_string(),
1079                "字段不允许筛选".to_string(),
1080            ));
1081        }
1082
1083        // 3. 检查用户是否有筛选权限
1084        if !field_config.permissions.can_filter(&self.user_roles_set) {
1085            return Err(BaseError::FieldPermissionDenied(
1086                self.table_config.table_name.clone(),
1087                field.to_string(),
1088                "用户无筛选权限".to_string(),
1089            ));
1090        }
1091
1092        Ok(())
1093    }
1094
1095    /// 嵌套布尔条件的最大递归深度,防止深层嵌套(或恶意构造)爆栈。
1096    ///
1097    /// 校验期(`validate_condition_tree`)与渲染期(`render_condition`)共用同一上限。
1098    const MAX_WHERE_DEPTH: usize = 32;
1099
1100    /// LIKE pattern 最大字节长度(QRY-1 防 DoS)。
1101    ///
1102    /// 超长 pattern 会导致 MySQL 索引失效、全表扫描放大;`where_like` /
1103    /// `where_contains` / 校验期 / 渲染期统一拦截。
1104    const MAX_LIKE_PATTERN_LEN: usize = 128;
1105
1106    /// IN / NOT IN 列表最大元素数(QRY-2 防 DoS)。
1107    ///
1108    /// 过长的 IN 列表会导致 MySQL 优化器退化、解析/绑定开销放大;`where_in` /
1109    /// `where_not_in` / 校验期 / 渲染期统一拦截。
1110    const MAX_IN_LIST_SIZE: usize = 500;
1111
1112    /// 递归校验一棵 WHERE 条件树的字段与筛选权限。
1113    ///
1114    /// 叶子条件校验其字段存在且当前角色可筛选;逻辑组(`And`/`Or`)递归下钻校验
1115    /// 每个子条件。深度超过 [`Self::MAX_WHERE_DEPTH`] 返回 `ParamInvalid` 而非
1116    /// panic,与渲染期保持一致的防爆栈上限。
1117    ///
1118    /// # 错误
1119    ///
1120    /// - `BaseError::FieldNotFound`:某叶子字段不存在
1121    /// - `BaseError::FieldPermissionDenied`:某叶子字段无筛选权限
1122    /// - `BaseError::ParamInvalid`:嵌套层数超限
1123    fn validate_condition_tree(
1124        &self,
1125        condition: &WhereCondition,
1126        depth: usize,
1127    ) -> Result<(), BaseError> {
1128        if depth > Self::MAX_WHERE_DEPTH {
1129            return Err(BaseError::ParamInvalid(
1130                "where".to_string(),
1131                format!("嵌套布尔条件层数超过上限 {}", Self::MAX_WHERE_DEPTH),
1132            ));
1133        }
1134
1135        match condition {
1136            WhereCondition::And { conditions } | WhereCondition::Or { conditions } => {
1137                // 空布尔组拒绝:空 And 渲染为 `1=1`、空 Or 渲染为 `1=0`,前者会使
1138                // `where_conditions` 非空从而绕过 UPDATE/DELETE 的全表写守卫,生成
1139                // `WHERE (1=1)` 全表改写。在校验期直接拒绝空组,杜绝该绕过路径。
1140                if conditions.is_empty() {
1141                    return Err(BaseError::ParamInvalid(
1142                        "where".to_string(),
1143                        "AND/OR 布尔组不能为空".to_string(),
1144                    ));
1145                }
1146                for child in conditions {
1147                    self.validate_condition_tree(child, depth + 1)?;
1148                }
1149                Ok(())
1150            }
1151            // 叶子:必有字段,校验存在性与筛选权限;同时校验 LIKE/IN 上限(QRY-1/QRY-2)
1152            leaf => {
1153                let field = leaf.field().ok_or_else(|| {
1154                    BaseError::ParamInvalid(
1155                        "condition".to_string(),
1156                        "条件节点缺少字段名".to_string(),
1157                    )
1158                })?;
1159                self.validate_filter_field(field)?;
1160                // LIKE pattern 长度上限(QRY-1)
1161                if let WhereCondition::Like { pattern, .. } = leaf {
1162                    if pattern.len() > Self::MAX_LIKE_PATTERN_LEN {
1163                        return Err(BaseError::ParamInvalid(
1164                            "pattern".to_string(),
1165                            format!(
1166                                "LIKE pattern 长度 {} 超过上限 {}",
1167                                pattern.len(),
1168                                Self::MAX_LIKE_PATTERN_LEN
1169                            ),
1170                        ));
1171                    }
1172                }
1173                // IN / NOT IN 列表元素数上限(QRY-2)
1174                if let WhereCondition::In { values, .. } | WhereCondition::NotIn { values, .. } =
1175                    leaf
1176                {
1177                    if values.is_empty() {
1178                        return Err(BaseError::ParamInvalid(
1179                            "values".to_string(),
1180                            "IN/NOT IN 列表不能为空".to_string(),
1181                        ));
1182                    }
1183
1184                    if values.len() > Self::MAX_IN_LIST_SIZE {
1185                        return Err(BaseError::ParamInvalid(
1186                            "values".to_string(),
1187                            format!(
1188                                "IN/NOT IN 列表元素数 {} 超过上限 {}",
1189                                values.len(),
1190                                Self::MAX_IN_LIST_SIZE
1191                            ),
1192                        ));
1193                    }
1194                }
1195                Ok(())
1196            }
1197        }
1198    }
1199
1200    /// 添加一个 OR 逻辑组 (WHERE ... AND (c1 OR c2 OR ...))
1201    ///
1202    /// 组内每个子条件递归校验字段存在性与筛选权限;通过后整组以 `Or` 节点追加到
1203    /// 顶层条件列表,与既有条件以隐式 AND 连接。空组等价于恒假(`1=0`)。
1204    ///
1205    /// 子条件可由 [`WhereCondition`] 直接构造,亦可嵌套 `And`/`Or` 组(深度上限
1206    /// [`Self::MAX_WHERE_DEPTH`])。
1207    ///
1208    /// # 参数
1209    ///
1210    /// - `conditions`:OR 组的子条件列表
1211    ///
1212    /// # 返回值
1213    ///
1214    /// - `Ok(Self)`:校验通过,返回 self 支持链式调用
1215    /// - `Err(BaseError)`:字段不存在 / 无筛选权限 / 嵌套超限
1216    ///
1217    /// # 示例
1218    ///
1219    /// ```rust,ignore
1220    /// use yang_base::table::WhereCondition;
1221    /// use serde_json::json;
1222    ///
1223    /// // WHERE status = 'active' AND (age >= 18 OR vip = true)
1224    /// let query = query
1225    ///     .where_eq("status", json!("active"))?
1226    ///     .where_or(vec![
1227    ///         WhereCondition::Gte { field: "age".into(), value: json!(18) },
1228    ///         WhereCondition::Eq { field: "vip".into(), value: json!(true) },
1229    ///     ])?;
1230    /// ```
1231    pub fn where_or(mut self, conditions: Vec<WhereCondition>) -> Result<Self, BaseError> {
1232        let group = WhereCondition::Or { conditions };
1233        // 递归校验整棵子树(含嵌套组)
1234        self.validate_condition_tree(&group, 0)?;
1235        self.query_params.where_conditions.push(group);
1236        Ok(self)
1237    }
1238
1239    /// 添加一个 AND 逻辑组 (WHERE ... AND (c1 AND c2 AND ...))
1240    ///
1241    /// 语义同 [`TableQuery::where_or`],但组内子条件以 AND 连接。主要用于在 OR 组
1242    /// 内部嵌套 AND 子组;顶层多个条件本就隐式 AND,单独使用通常无必要。空组等价
1243    /// 于恒真(`1=1`)。
1244    ///
1245    /// # 参数
1246    ///
1247    /// - `conditions`:AND 组的子条件列表
1248    ///
1249    /// # 返回值
1250    ///
1251    /// - `Ok(Self)`:校验通过,返回 self 支持链式调用
1252    /// - `Err(BaseError)`:字段不存在 / 无筛选权限 / 嵌套超限
1253    pub fn where_and(mut self, conditions: Vec<WhereCondition>) -> Result<Self, BaseError> {
1254        let group = WhereCondition::And { conditions };
1255        self.validate_condition_tree(&group, 0)?;
1256        self.query_params.where_conditions.push(group);
1257        Ok(self)
1258    }
1259
1260    /// 追加一棵任意 WHERE 条件(叶子或 `And`/`Or` 组),递归校验后并入顶层条件。
1261    ///
1262    /// 这是类型化布尔树([`Filter`](crate::table::Filter))桥接到受保护层的统一入口:
1263    /// 整棵树先经 [`Self::validate_condition_tree`] 递归校验字段存在性、筛选权限与
1264    /// 嵌套深度,通过后作为单个条件追加(与既有条件隐式 AND 连接)。
1265    ///
1266    /// # 参数
1267    ///
1268    /// - `condition`:任意 `WhereCondition`(叶子或逻辑组)
1269    ///
1270    /// # 返回值
1271    ///
1272    /// - `Ok(Self)`:校验通过,返回 self 支持链式调用
1273    /// - `Err(BaseError)`:字段不存在 / 无筛选权限 / 嵌套超限
1274    pub fn where_tree(mut self, condition: WhereCondition) -> Result<Self, BaseError> {
1275        self.validate_condition_tree(&condition, 0)?;
1276        self.query_params.where_conditions.push(condition);
1277        Ok(self)
1278    }
1279
1280    /// 获取查询参数的引用
1281    ///
1282    /// 用于测试或调试,获取当前构建的查询参数
1283    ///
1284    /// # 返回值
1285    ///
1286    /// 返回查询参数的引用
1287    #[allow(dead_code)]
1288    pub fn get_query_params(&self) -> &QueryParams {
1289        &self.query_params
1290    }
1291
1292    /// 获取表配置的引用
1293    ///
1294    /// 用于测试或调试,获取表配置
1295    ///
1296    /// # 返回值
1297    ///
1298    /// 返回表配置的引用
1299    #[allow(dead_code)]
1300    pub fn get_table_config(&self) -> &Arc<TableConfig> {
1301        &self.table_config
1302    }
1303
1304    /// 获取用户角色列表的引用
1305    ///
1306    /// 用于测试或调试,获取用户角色列表
1307    ///
1308    /// # 返回值
1309    ///
1310    /// 返回用户角色列表的引用
1311    #[allow(dead_code)]
1312    pub fn get_user_roles(&self) -> &[String] {
1313        &self.user_roles
1314    }
1315
1316    /// 创建仅有表配置、无数据库连接池的查询构建器(测试用)
1317    ///
1318    /// 使用空的用户角色列表,适合访问无权限限制字段的单元测试。
1319    #[cfg(test)]
1320    pub fn new_without_pool(table_config: Arc<TableConfig>) -> Self {
1321        Self::new(table_config, Arc::from(vec![]), None)
1322    }
1323}
1324
1325/// 数据库执行方法(需要启用 `mysql` feature)
1326#[cfg(feature = "mysql")]
1327impl TableQuery {
1328    /// 执行分页查询操作
1329    ///
1330    /// 执行分页查询,包括以下步骤:
1331    /// 1. 执行 COUNT(*) 查询获取总记录数
1332    /// 2. 计算 LIMIT 和 OFFSET
1333    /// 3. 执行数据查询
1334    /// 4. 计算总页数
1335    /// 5. 构建并返回 PaginatedResult
1336    ///
1337    /// # 类型参数
1338    ///
1339    /// - `T`:结果类型,必须实现 `sqlx::FromRow` 和 `Serialize` trait
1340    ///
1341    /// # 返回值
1342    ///
1343    /// - `Ok(PaginatedResult<T>)`:查询成功,返回分页结果
1344    /// - `Err(BaseError)`:查询失败,返回错误
1345    ///
1346    /// # 错误
1347    ///
1348    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
1349    /// - `BaseError::DatabaseQueryFailed`:查询执行失败
1350    ///
1351    /// # 示例
1352    ///
1353    /// ```rust,ignore
1354    /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType, PaginatedResult};
1355    /// use std::sync::Arc;
1356    /// use serde::{Deserialize, Serialize};
1357    ///
1358    /// #[derive(Debug, Serialize, Deserialize, sqlx::FromRow)]
1359    /// struct User {
1360    ///     id: i64,
1361    ///     name: String,
1362    ///     email: String,
1363    /// }
1364    ///
1365    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
1366    /// let table_config = Arc::new(
1367    ///     TableConfig::new("users")
1368    ///         .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
1369    ///         .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
1370    ///         .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
1371    /// );
1372    ///
1373    /// let query = TableQuery::new(
1374    ///     table_config,
1375    ///     vec!["user".to_string()],
1376    ///     Some(pool),
1377    /// );
1378    ///
1379    /// // 执行分页查询
1380    /// let result: PaginatedResult<User> = query
1381    ///     .select_fields(&["id", "name", "email"])?
1382    ///     .where_eq("status", serde_json::json!("active"))?
1383    ///     .order_by("created_at", SortOrder::Desc)?
1384    ///     .page(1, 20)?
1385    ///     .paginate()
1386    ///     .await?;
1387    ///
1388    /// println!("总记录数: {}", result.total);
1389    /// println!("当前页: {}/{}", result.page, result.total_pages);
1390    /// println!("数据条数: {}", result.data.len());
1391    /// # Ok(())
1392    /// # }
1393    /// ```
1394    fn with_effective_pagination(self) -> Result<(Self, usize, usize), BaseError> {
1395        let page = self.query_params.page.unwrap_or(1);
1396        let page_size = self
1397            .query_params
1398            .page_size
1399            .unwrap_or(super::query_params::DEFAULT_QUERY_PAGE_SIZE);
1400        let query = self.page(page, page_size)?;
1401
1402        Ok((query, page, page_size))
1403    }
1404
1405    /// 执行分页查询。
1406    ///
1407    /// 未显式设置分页时会使用默认页码和默认每页大小,并确保数据查询带有 `LIMIT/OFFSET`。
1408    pub async fn paginate<T>(self) -> Result<crate::table::PaginatedResult<T>, BaseError>
1409    where
1410        T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin + Serialize,
1411    {
1412        // 1. 检查数据库连接池是否存在
1413        let _pool = self
1414            .pool
1415            .as_ref()
1416            .ok_or(BaseError::DatabaseNotInitialized)?;
1417
1418        // 2. 获取分页参数,如果未设置则使用默认值,并写回数据查询
1419        let (query, page, page_size) = self.with_effective_pagination()?;
1420
1421        // 3. 执行 COUNT(*) 查询获取总记录数
1422        let total = query.count_internal().await?;
1423
1424        // 4. 如果总记录数为 0,直接返回空结果
1425        if total == 0 {
1426            return Ok(crate::table::PaginatedResult::empty(page, page_size));
1427        }
1428
1429        // 5. 执行数据查询
1430        let data = query.select().await?;
1431
1432        // 6. 构建并返回 PaginatedResult
1433        Ok(crate::table::PaginatedResult::new(
1434            data, total, page, page_size,
1435        ))
1436    }
1437
1438    /// 执行 COUNT 查询获取总记录数(内部方法,供 paginate 使用)
1439    ///
1440    /// 构建 COUNT(*) SQL 语句,应用已配置的 WHERE 条件,执行查询并返回总记录数。
1441    /// 返回 `usize` 以与 `PaginatedResult::new` 的 `total: usize` 参数直接匹配;
1442    /// 公开接口 `count()` 通过 `as u64` 适配。
1443    ///
1444    /// # 返回值
1445    ///
1446    /// - `Ok(usize)`:查询成功,返回总记录数
1447    /// - `Err(BaseError)`:查询失败,返回错误
1448    ///
1449    /// # 错误
1450    ///
1451    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
1452    /// - `BaseError::DatabaseQueryFailed`:查询执行失败
1453    async fn count_internal(&self) -> Result<usize, BaseError> {
1454        // 1. 检查数据库连接池是否存在
1455        let pool = self
1456            .pool
1457            .as_ref()
1458            .ok_or(BaseError::DatabaseNotInitialized)?;
1459
1460        // 2. 构建 COUNT SQL 语句
1461        let (sql, params) = self.build_count_sql()?;
1462
1463        // 3. 创建查询
1464        let mut query = sqlx::query_scalar::<_, i64>(&sql);
1465
1466        // 4. 绑定参数
1467        for param in params {
1468            query = Self::bind_count_param(query, &param);
1469        }
1470
1471        // 5. 执行查询(计时观测)
1472        let count = Self::timed(
1473            self.slow_threshold,
1474            self.request_id,
1475            &self.table_config.table_name,
1476            "count",
1477            query.fetch_one(pool.as_ref()),
1478        )
1479        .await
1480        .map_err(|e| BaseError::DatabaseQueryFailed(yang_db::DbError::from(e)))?;
1481
1482        Ok(count as usize)
1483    }
1484
1485    /// 执行 COUNT 查询获取总记录数
1486    ///
1487    /// 构建 COUNT(*) SQL 语句,应用已配置的 WHERE 条件,执行查询并返回总记录数。
1488    ///
1489    /// # 返回值
1490    ///
1491    /// - `Ok(u64)`:查询成功,返回总记录数
1492    /// - `Err(BaseError)`:查询失败,返回错误
1493    ///
1494    /// # 错误
1495    ///
1496    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
1497    /// - `BaseError::DatabaseQueryFailed`:查询执行失败
1498    ///
1499    /// # 示例
1500    ///
1501    /// ```rust,ignore
1502    /// let total = query
1503    ///     .where_eq("status", serde_json::json!("active"))?
1504    ///     .count()
1505    ///     .await?;
1506    ///
1507    /// println!("总记录数: {}", total);
1508    /// ```
1509    pub async fn count(self) -> Result<u64, BaseError> {
1510        self.count_internal().await.map(|n| n as u64)
1511    }
1512
1513    /// 统一拼接 WHERE 子句到 SQL 字符串
1514    ///
1515    /// 集中处理 12 种叶子条件(Eq/Ne/In/NotIn/Like/Gt/Gte/Lt/Lte/Between/IsNull/IsNotNull)
1516    /// 与两种逻辑组(And/Or)的 SQL 拼接:顶层 `where_conditions` 列表仍以隐式 AND 连接
1517    /// (向后兼容),逻辑组递归渲染并用括号包裹。所有字段名通过 `quote_identifier`
1518    /// 反引号转义,防止 SQL 注入。
1519    ///
1520    /// # 参数
1521    ///
1522    /// - `sql`:目标 SQL 字符串(追加模式)
1523    /// - `params`:参数列表(追加模式)
1524    /// - `apply_soft_delete`:是否追加软删过滤(仅读路径)
1525    ///
1526    /// # 返回值
1527    ///
1528    /// - `Ok(())`:拼接成功
1529    /// - `Err(BaseError)`:字段名非法、参数转换失败或嵌套层数超限
1530    fn append_where_to_sql(
1531        &self,
1532        sql: &mut String,
1533        params: &mut Vec<SqlParam>,
1534        apply_soft_delete: bool,
1535    ) -> Result<(), BaseError> {
1536        // 计算是否需要追加软删过滤子句(仅读路径,且未显式 with_trashed)
1537        let has_soft_delete = apply_soft_delete
1538            && !self.include_trashed
1539            && self.table_config.soft_delete_field.is_some();
1540
1541        // 既无 WHERE 条件也无需软删过滤,直接返回
1542        if self.query_params.where_conditions.is_empty() && !has_soft_delete {
1543            return Ok(());
1544        }
1545
1546        sql.push_str(" WHERE ");
1547        let mut first = true;
1548
1549        // 顶层条件以隐式 AND 连接;每个条件递归渲染(组节点自带括号)
1550        for condition in &self.query_params.where_conditions {
1551            if !first {
1552                sql.push_str(" AND ");
1553            }
1554            first = false;
1555            self.render_condition(condition, sql, params, 0)?;
1556        }
1557
1558        // 读路径软删过滤:追加 `软删字段 IS NULL`(与已有条件用 AND 连接)
1559        if has_soft_delete {
1560            if let Some(field) = &self.table_config.soft_delete_field {
1561                let quoted = self.quote_identifier(field)?;
1562                if !first {
1563                    sql.push_str(" AND ");
1564                }
1565                sql.push_str(&format!("{} IS NULL", quoted));
1566            }
1567        }
1568
1569        Ok(())
1570    }
1571
1572    /// 递归渲染单个 WHERE 条件到 SQL(叶子直接拼接,And/Or 组括号包裹后递归)。
1573    ///
1574    /// `depth` 从 0 起递增,超过 [`Self::MAX_WHERE_DEPTH`] 返回 `ParamInvalid`
1575    /// 而非 panic,保证受保护层不因深嵌套输入崩溃。
1576    fn render_condition(
1577        &self,
1578        condition: &WhereCondition,
1579        sql: &mut String,
1580        params: &mut Vec<SqlParam>,
1581        depth: usize,
1582    ) -> Result<(), BaseError> {
1583        if depth > Self::MAX_WHERE_DEPTH {
1584            return Err(BaseError::ParamInvalid(
1585                "where".to_string(),
1586                format!("嵌套布尔条件层数超过上限 {}", Self::MAX_WHERE_DEPTH),
1587            ));
1588        }
1589
1590        match condition {
1591            WhereCondition::Eq { field, value } => {
1592                let quoted = self.quote_identifier(field)?;
1593                sql.push_str(&format!("{} = ?", quoted));
1594                params.push(SqlParam::from_json(value)?);
1595            }
1596            WhereCondition::In { field, values } => {
1597                // QRY-2 安全网:渲染期再次校验 IN 列表元素数上限
1598                if values.len() > Self::MAX_IN_LIST_SIZE {
1599                    return Err(BaseError::ParamInvalid(
1600                        "values".to_string(),
1601                        format!(
1602                            "IN 列表元素数 {} 超过上限 {}",
1603                            values.len(),
1604                            Self::MAX_IN_LIST_SIZE
1605                        ),
1606                    ));
1607                }
1608                let quoted = self.quote_identifier(field)?;
1609                if values.is_empty() {
1610                    // 空 IN 集合:等价于恒假,避免拼出非法的 `IN ()`
1611                    sql.push_str("1=0");
1612                } else {
1613                    let placeholders = vec!["?"; values.len()].join(", ");
1614                    sql.push_str(&format!("{} IN ({})", quoted, placeholders));
1615                    for value in values {
1616                        params.push(SqlParam::from_json(value)?);
1617                    }
1618                }
1619            }
1620            WhereCondition::Like { field, pattern } => {
1621                // QRY-1 安全网:渲染期再次校验 LIKE pattern 长度上限
1622                if pattern.len() > Self::MAX_LIKE_PATTERN_LEN {
1623                    return Err(BaseError::ParamInvalid(
1624                        "pattern".to_string(),
1625                        format!(
1626                            "LIKE pattern 长度 {} 超过上限 {}",
1627                            pattern.len(),
1628                            Self::MAX_LIKE_PATTERN_LEN
1629                        ),
1630                    ));
1631                }
1632                let quoted = self.quote_identifier(field)?;
1633                sql.push_str(&format!("{} LIKE ?", quoted));
1634                params.push(SqlParam::String(pattern.clone()));
1635            }
1636            WhereCondition::Gt { field, value } => {
1637                let quoted = self.quote_identifier(field)?;
1638                sql.push_str(&format!("{} > ?", quoted));
1639                params.push(SqlParam::from_json(value)?);
1640            }
1641            WhereCondition::Gte { field, value } => {
1642                let quoted = self.quote_identifier(field)?;
1643                sql.push_str(&format!("{} >= ?", quoted));
1644                params.push(SqlParam::from_json(value)?);
1645            }
1646            WhereCondition::Lt { field, value } => {
1647                let quoted = self.quote_identifier(field)?;
1648                sql.push_str(&format!("{} < ?", quoted));
1649                params.push(SqlParam::from_json(value)?);
1650            }
1651            WhereCondition::Lte { field, value } => {
1652                let quoted = self.quote_identifier(field)?;
1653                sql.push_str(&format!("{} <= ?", quoted));
1654                params.push(SqlParam::from_json(value)?);
1655            }
1656            WhereCondition::IsNull { field } => {
1657                let quoted = self.quote_identifier(field)?;
1658                sql.push_str(&format!("{} IS NULL", quoted));
1659            }
1660            WhereCondition::IsNotNull { field } => {
1661                let quoted = self.quote_identifier(field)?;
1662                sql.push_str(&format!("{} IS NOT NULL", quoted));
1663            }
1664            WhereCondition::Ne { field, value } => {
1665                let quoted = self.quote_identifier(field)?;
1666                sql.push_str(&format!("{} <> ?", quoted));
1667                params.push(SqlParam::from_json(value)?);
1668            }
1669            WhereCondition::Between { field, lo, hi } => {
1670                let quoted = self.quote_identifier(field)?;
1671                sql.push_str(&format!("{} BETWEEN ? AND ?", quoted));
1672                params.push(SqlParam::from_json(lo)?);
1673                params.push(SqlParam::from_json(hi)?);
1674            }
1675            WhereCondition::NotIn { field, values } => {
1676                // QRY-2 安全网:渲染期再次校验 NOT IN 列表元素数上限
1677                if values.len() > Self::MAX_IN_LIST_SIZE {
1678                    return Err(BaseError::ParamInvalid(
1679                        "values".to_string(),
1680                        format!(
1681                            "NOT IN 列表元素数 {} 超过上限 {}",
1682                            values.len(),
1683                            Self::MAX_IN_LIST_SIZE
1684                        ),
1685                    ));
1686                }
1687                let quoted = self.quote_identifier(field)?;
1688                if values.is_empty() {
1689                    // 空 NOT IN 集合:等价于恒真,不排除任何行
1690                    sql.push_str("1=1");
1691                } else {
1692                    let placeholders = vec!["?"; values.len()].join(", ");
1693                    sql.push_str(&format!("{} NOT IN ({})", quoted, placeholders));
1694                    for value in values {
1695                        params.push(SqlParam::from_json(value)?);
1696                    }
1697                }
1698            }
1699            // 逻辑组:括号包裹,子条件以 AND/OR 连接,递归渲染(深度 +1)
1700            WhereCondition::And { conditions } => {
1701                self.render_group(conditions, " AND ", "1=1", sql, params, depth)?;
1702            }
1703            WhereCondition::Or { conditions } => {
1704                self.render_group(conditions, " OR ", "1=0", sql, params, depth)?;
1705            }
1706        }
1707
1708        Ok(())
1709    }
1710
1711    /// 渲染逻辑组:`(c1 <sep> c2 <sep> ...)`;空组用 `empty_literal` 兜底
1712    /// (And→`1=1` 恒真,Or→`1=0` 恒假),避免拼出非法空括号。
1713    fn render_group(
1714        &self,
1715        conditions: &[WhereCondition],
1716        separator: &str,
1717        empty_literal: &str,
1718        sql: &mut String,
1719        params: &mut Vec<SqlParam>,
1720        depth: usize,
1721    ) -> Result<(), BaseError> {
1722        if conditions.is_empty() {
1723            sql.push_str(empty_literal);
1724            return Ok(());
1725        }
1726
1727        sql.push('(');
1728        let mut first = true;
1729        for cond in conditions {
1730            if !first {
1731                sql.push_str(separator);
1732            }
1733            first = false;
1734            self.render_condition(cond, sql, params, depth + 1)?;
1735        }
1736        sql.push(')');
1737        Ok(())
1738    }
1739
1740    /// 构建 COUNT SQL 语句
1741    ///
1742    /// # 返回值
1743    ///
1744    /// 返回 (SQL 语句, 参数列表) 元组
1745    ///
1746    /// # 错误
1747    ///
1748    /// - `BaseError::DatabaseQueryFailed`:SQL 构建失败
1749    fn build_count_sql(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
1750        let mut sql = format!("SELECT COUNT(*) FROM {}", self.quoted_table_name()?);
1751        let mut params = Vec::new();
1752
1753        // 通过统一方法拼接 WHERE 子句(读路径,应用软删过滤)
1754        self.append_where_to_sql(&mut sql, &mut params, true)?;
1755
1756        Ok((sql, params))
1757    }
1758
1759    /// 绑定参数到 COUNT 查询
1760    ///
1761    /// # 参数
1762    ///
1763    /// - `query`:sqlx 查询对象
1764    /// - `param`:SQL 参数值
1765    ///
1766    /// # 返回值
1767    ///
1768    /// 绑定参数后的查询对象
1769    fn bind_count_param<'q>(
1770        query: sqlx::query::QueryScalar<'q, sqlx::MySql, i64, sqlx::mysql::MySqlArguments>,
1771        param: &SqlParam,
1772    ) -> sqlx::query::QueryScalar<'q, sqlx::MySql, i64, sqlx::mysql::MySqlArguments> {
1773        match param {
1774            SqlParam::Null => query.bind(Option::<i32>::None),
1775            SqlParam::Bool(b) => query.bind(*b),
1776            SqlParam::Int(i) => query.bind(*i),
1777            SqlParam::Uint(u) => query.bind(*u),
1778            SqlParam::Float(f) => query.bind(*f),
1779            SqlParam::String(s) => query.bind(s.clone()),
1780            SqlParam::DateTime(dt) => query.bind(*dt),
1781            SqlParam::Bytes(b) => query.bind(b.clone()),
1782            SqlParam::Json(j) => query.bind(j.clone()),
1783        }
1784    }
1785
1786    /// 执行 SELECT 查询操作
1787    ///
1788    /// 使用 sqlx 构建 SELECT 语句,应用已配置的字段选择、WHERE 条件和排序规则,
1789    /// 执行查询并将结果反序列化为指定的泛型类型 T。
1790    ///
1791    /// # 类型参数
1792    ///
1793    /// - `T`:结果类型,必须实现 `sqlx::FromRow` trait
1794    ///
1795    /// # 返回值
1796    ///
1797    /// - `Ok(Vec<T>)`:查询成功,返回结果列表
1798    /// - `Err(BaseError)`:查询失败,返回错误
1799    ///
1800    /// # 错误
1801    ///
1802    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
1803    /// - `BaseError::DatabaseQueryFailed`:查询执行失败
1804    ///
1805    /// # 示例
1806    ///
1807    /// ```rust,ignore
1808    /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
1809    /// use std::sync::Arc;
1810    /// use serde::{Deserialize, Serialize};
1811    ///
1812    /// #[derive(Debug, Serialize, Deserialize, sqlx::FromRow)]
1813    /// struct User {
1814    ///     id: i64,
1815    ///     name: String,
1816    ///     email: String,
1817    /// }
1818    ///
1819    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
1820    /// let table_config = Arc::new(
1821    ///     TableConfig::new("users")
1822    ///         .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
1823    ///         .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
1824    ///         .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
1825    /// );
1826    ///
1827    /// let query = TableQuery::new(
1828    ///     table_config,
1829    ///     vec!["user".to_string()],
1830    ///     Some(pool),
1831    /// );
1832    ///
1833    /// // 执行查询
1834    /// let users: Vec<User> = query
1835    ///     .select_fields(&["id", "name", "email"])?
1836    ///     .where_eq("status", serde_json::json!("active"))?
1837    ///     .order_by("created_at", SortOrder::Desc)?
1838    ///     .select()
1839    ///     .await?;
1840    ///
1841    /// println!("找到 {} 个用户", users.len());
1842    /// # Ok(())
1843    /// # }
1844    /// ```
1845    pub async fn select<T>(self) -> Result<Vec<T>, BaseError>
1846    where
1847        T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
1848    {
1849        // 1. 检查数据库连接池是否存在
1850        let pool = self
1851            .pool
1852            .as_ref()
1853            .ok_or(BaseError::DatabaseNotInitialized)?;
1854
1855        // 2. 构建 SQL 语句
1856        let (sql, params) = self.build_select_sql(None)?;
1857
1858        // 3. 在连接池上执行查询(计时观测,慢查询超阈值 warn)
1859        Self::timed(
1860            self.slow_threshold,
1861            self.request_id,
1862            &self.table_config.table_name,
1863            "select",
1864            Self::run_fetch_all(pool.as_ref(), &sql, &params),
1865        )
1866        .await
1867    }
1868
1869    /// 在事务中执行 SELECT 查询并返回多条记录
1870    ///
1871    /// 与 [`TableQuery::select`] 完全一致的建句与权限/软删逻辑,但在调用方提供的
1872    /// `yang_db::Transaction` 内执行,使「读-改-写」场景的读取与后续写入处于同一
1873    /// 事务、看到一致快照。
1874    ///
1875    /// # 参数
1876    ///
1877    /// - `tx`:由 [`ActionContext::begin_transaction`](crate::action::ActionContext::begin_transaction)
1878    ///   或 [`GlobalDatabase::transaction`](crate::database::GlobalDatabase::transaction) 取得的活动事务
1879    ///
1880    /// # 错误
1881    ///
1882    /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚,连接不可用
1883    /// - `BaseError::DatabaseQueryFailed`:查询执行失败
1884    pub async fn select_in_tx<T>(self, tx: &mut yang_db::Transaction) -> Result<Vec<T>, BaseError>
1885    where
1886        T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
1887    {
1888        // 构建 SQL(与普通路径一致,含字段权限/软删过滤)
1889        let (sql, params) = self.build_select_sql(None)?;
1890
1891        // 借出事务底层连接执行;事务已结束则返回错误而非 panic
1892        let executor = tx.executor().ok_or_else(|| {
1893            BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
1894                "事务已提交或回滚".to_string(),
1895            ))
1896        })?;
1897
1898        Self::timed(
1899            self.slow_threshold,
1900            self.request_id,
1901            &self.table_config.table_name,
1902            "select_in_tx",
1903            Self::run_fetch_all(executor, &sql, &params),
1904        )
1905        .await
1906    }
1907
1908    /// 构建 SELECT SQL 语句
1909    ///
1910    /// # 返回值
1911    ///
1912    /// 返回 (SQL 语句, 参数列表) 元组
1913    ///
1914    /// # 错误
1915    ///
1916    /// - `BaseError::DatabaseQueryFailed`:SQL 构建失败
1917    fn build_select_sql(
1918        &self,
1919        hard_limit: Option<usize>,
1920    ) -> Result<(String, Vec<SqlParam>), BaseError> {
1921        let mut sql = String::from("SELECT ");
1922        let mut params = Vec::new();
1923
1924        // 1. 字段列表(通过 quote_identifier 转义字段名)
1925        if let Some(fields) = &self.query_params.fields {
1926            if fields.is_empty() {
1927                self.validate_all_fields_readable()?;
1928                sql.push('*');
1929            } else {
1930                // 对每个字段名进行反引号转义
1931                let quoted_fields: Result<Vec<String>, BaseError> = fields
1932                    .iter()
1933                    .map(|f| {
1934                        self.validate_read_field(f)?;
1935                        self.quote_identifier(f)
1936                    })
1937                    .collect();
1938                sql.push_str(&quoted_fields?.join(", "));
1939            }
1940        } else {
1941            self.validate_all_fields_readable()?;
1942            sql.push('*');
1943        }
1944
1945        // 2. FROM 子句(表名走统一转义路径)
1946        sql.push_str(&format!(" FROM {}", self.quoted_table_name()?));
1947
1948        // 3. 通过统一方法拼接 WHERE 子句(读路径,应用软删过滤)
1949        self.append_where_to_sql(&mut sql, &mut params, true)?;
1950
1951        // 4. ORDER BY 子句:显式 order_by 优先,否则回退到表配置的 default_order
1952        let order_source = if !self.query_params.order_by.is_empty() {
1953            Some(&self.query_params.order_by)
1954        } else if !self.table_config.default_order.is_empty() {
1955            Some(&self.table_config.default_order)
1956        } else {
1957            None
1958        };
1959        if let Some(orders) = order_source {
1960            sql.push_str(" ORDER BY ");
1961            let order_clauses: Result<Vec<String>, BaseError> = orders
1962                .iter()
1963                .map(|(field, order)| {
1964                    self.validate_order_field(field)?;
1965                    let direction = match order {
1966                        SortOrder::Asc => "ASC",
1967                        SortOrder::Desc => "DESC",
1968                    };
1969                    self.quote_identifier(field)
1970                        .map(|quoted| format!("{} {}", quoted, direction))
1971                })
1972                .collect();
1973            sql.push_str(&order_clauses?.join(", "));
1974        }
1975
1976        // 5. LIMIT 和 OFFSET 子句(分页与 hard_limit 互斥,避免拼出两段 LIMIT)
1977        if let (Some(page), Some(page_size)) = (self.query_params.page, self.query_params.page_size)
1978        {
1979            // 使用 saturating_sub 防止 page==0 时 usize 下溢(纵深防御,
1980            // 主校验在 page() 入口;直接构造 query_params 的调用方也安全)
1981            let offset = page.saturating_sub(1).saturating_mul(page_size);
1982            sql.push_str(&format!(" LIMIT {} OFFSET {}", page_size, offset));
1983        } else if let Some(limit) = hard_limit {
1984            // 无分页时应用硬上限(如 fetch_optional 仅需 1 行)
1985            sql.push_str(&format!(" LIMIT {}", limit));
1986        }
1987
1988        Ok((sql, params))
1989    }
1990
1991    /// 绑定参数到查询
1992    ///
1993    /// # 参数
1994    ///
1995    /// - `query`:sqlx 查询对象
1996    /// - `param`:SQL 参数值
1997    ///
1998    /// # 返回值
1999    ///
2000    /// 绑定参数后的查询对象
2001    fn bind_param<'q, T>(
2002        query: sqlx::query::QueryAs<'q, sqlx::MySql, T, sqlx::mysql::MySqlArguments>,
2003        param: &SqlParam,
2004    ) -> sqlx::query::QueryAs<'q, sqlx::MySql, T, sqlx::mysql::MySqlArguments>
2005    where
2006        T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
2007    {
2008        match param {
2009            SqlParam::Null => query.bind(Option::<i32>::None),
2010            SqlParam::Bool(b) => query.bind(*b),
2011            SqlParam::Int(i) => query.bind(*i),
2012            SqlParam::Uint(u) => query.bind(*u),
2013            SqlParam::Float(f) => query.bind(*f),
2014            SqlParam::String(s) => query.bind(s.clone()),
2015            SqlParam::DateTime(dt) => query.bind(*dt),
2016            SqlParam::Bytes(b) => query.bind(b.clone()),
2017            SqlParam::Json(j) => query.bind(j.clone()),
2018        }
2019    }
2020
2021    /// 执行查询并返回可选的单条记录
2022    ///
2023    /// 执行 SELECT 查询,返回第一条匹配记录,如果没有匹配记录则返回 None。
2024    /// 通常与 `where_eq` 等条件方法配合使用,用于按主键查询单条记录。
2025    ///
2026    /// # 类型参数
2027    ///
2028    /// - `T`:结果类型,必须实现 `sqlx::FromRow` trait
2029    ///
2030    /// # 返回值
2031    ///
2032    /// - `Ok(Some(T))`:找到匹配记录
2033    /// - `Ok(None)`:没有匹配记录
2034    /// - `Err(BaseError)`:查询失败
2035    ///
2036    /// # 错误
2037    ///
2038    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
2039    /// - `BaseError::DatabaseQueryFailed`:查询执行失败
2040    ///
2041    /// # 示例
2042    ///
2043    /// ```rust,ignore
2044    /// use yang_base::table::DynamicRow;
2045    ///
2046    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
2047    /// // 按主键查询单条记录
2048    /// let row: Option<DynamicRow> = query
2049    ///     .where_eq("id", serde_json::json!(1))?
2050    ///     .fetch_optional()
2051    ///     .await?;
2052    ///
2053    /// match row {
2054    ///     Some(r) => println!("找到记录: {:?}", r.columns),
2055    ///     None => println!("记录不存在"),
2056    /// }
2057    /// # Ok(())
2058    /// # }
2059    /// ```
2060    pub async fn fetch_optional<T>(self) -> Result<Option<T>, BaseError>
2061    where
2062        T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
2063    {
2064        // 1. 检查数据库连接池是否存在
2065        let pool = self
2066            .pool
2067            .as_ref()
2068            .ok_or(BaseError::DatabaseNotInitialized)?;
2069
2070        // 2. 构建 SQL 语句(限制返回 1 条记录)
2071        let (sql, params) = self.build_select_sql(Some(1))?;
2072
2073        // 3. 创建查询
2074        let mut query = sqlx::query_as::<_, T>(&sql);
2075
2076        // 4. 绑定参数
2077        for param in params {
2078            query = Self::bind_param(query, &param);
2079        }
2080
2081        // 5. 执行查询,返回可选结果(计时观测)
2082        let result = Self::timed(
2083            self.slow_threshold,
2084            self.request_id,
2085            &self.table_config.table_name,
2086            "fetch_optional",
2087            query.fetch_optional(pool.as_ref()),
2088        )
2089        .await
2090        .map_err(|e| BaseError::DatabaseQueryFailed(yang_db::DbError::from(e)))?;
2091
2092        Ok(result)
2093    }
2094
2095    /// 执行 INSERT 操作
2096    ///
2097    /// 插入数据到表中,包括以下步骤:
2098    /// 1. 验证所有字段值的合法性(使用 FieldConfig::validate)
2099    /// 2. 检查用户是否有字段的写入权限
2100    /// 3. 构建 INSERT SQL 语句
2101    /// 4. 执行插入操作
2102    /// 5. 返回影响行数
2103    ///
2104    /// # 参数
2105    ///
2106    /// - `data`:要插入的数据,格式为 HashMap<String, Value>
2107    ///
2108    /// # 返回值
2109    ///
2110    /// - `Ok(u64)`:插入成功,返回影响行数(通常为 1)
2111    /// - `Err(BaseError)`:插入失败,返回错误
2112    ///
2113    /// # 错误
2114    ///
2115    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
2116    /// - `BaseError::FieldRequired`:必填字段缺失
2117    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
2118    /// - `BaseError::ValidationFailed`:字段值验证失败
2119    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
2120    ///
2121    /// # 示例
2122    ///
2123    /// ```rust,ignore
2124    /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
2125    /// use std::sync::Arc;
2126    /// use std::collections::HashMap;
2127    /// use serde_json::json;
2128    ///
2129    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
2130    /// let table_config = Arc::new(
2131    ///     TableConfig::new("users")
2132    ///         .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
2133    ///         .field(FieldConfig::new("name", FieldType::String { max_length: 50 }).required(true)).expect("有效字段配置应注册成功")
2134    ///         .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
2135    /// );
2136    ///
2137    /// let query = TableQuery::new(
2138    ///     table_config,
2139    ///     vec!["user".to_string()],
2140    ///     Some(pool),
2141    /// );
2142    ///
2143    /// // 准备插入数据
2144    /// let mut data = HashMap::new();
2145    /// data.insert("name".to_string(), json!("张三"));
2146    /// data.insert("email".to_string(), json!("zhangsan@example.com"));
2147    ///
2148    /// // 执行插入
2149    /// let affected = query.insert(data).await?;
2150    /// println!("插入成功,影响行数: {}", affected);
2151    /// # Ok(())
2152    /// # }
2153    /// ```
2154    pub async fn insert(
2155        self,
2156        data: std::collections::HashMap<String, Value>,
2157    ) -> Result<u64, BaseError> {
2158        // 1. 检查数据库连接池是否存在
2159        let pool = self
2160            .pool
2161            .as_ref()
2162            .ok_or(BaseError::DatabaseNotInitialized)?;
2163
2164        // 2. 填充默认值/时间戳并校验(顺序:写权限→填充默认值→必填/类型校验)
2165        let data = self.prepare_and_validate_insert(data)?;
2166
2167        // 3. 构建 INSERT SQL 语句
2168        let (sql, params) = self.build_insert_sql(&data)?;
2169
2170        // 4. 在连接池上执行插入(计时观测)
2171        let result = Self::timed(
2172            self.slow_threshold,
2173            self.request_id,
2174            &self.table_config.table_name,
2175            "insert",
2176            Self::run_execute(pool.as_ref(), &sql, &params),
2177        )
2178        .await?;
2179
2180        Ok(result.rows_affected())
2181    }
2182
2183    /// 在事务中执行 INSERT 操作
2184    ///
2185    /// 与 [`TableQuery::insert`] 完全一致的写权限校验/默认值填充/时间戳/必填校验
2186    /// 流程,但在调用方提供的事务内执行,可与其它写操作原子提交。
2187    ///
2188    /// # 错误
2189    ///
2190    /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
2191    /// - 其余同 [`TableQuery::insert`]
2192    pub async fn insert_in_tx(
2193        self,
2194        tx: &mut yang_db::Transaction,
2195        data: std::collections::HashMap<String, Value>,
2196    ) -> Result<u64, BaseError> {
2197        let data = self.prepare_and_validate_insert(data)?;
2198        let (sql, params) = self.build_insert_sql(&data)?;
2199
2200        let executor = tx.executor().ok_or_else(|| {
2201            BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
2202                "事务已提交或回滚".to_string(),
2203            ))
2204        })?;
2205
2206        let result = Self::timed(
2207            self.slow_threshold,
2208            self.request_id,
2209            &self.table_config.table_name,
2210            "insert_in_tx",
2211            Self::run_execute(executor, &sql, &params),
2212        )
2213        .await?;
2214        Ok(result.rows_affected())
2215    }
2216
2217    /// 执行 INSERT 操作并返回自增主键
2218    ///
2219    /// 与 [`TableQuery::insert`] 完全一致的校验与拼 SQL 流程,但额外返回本次
2220    /// INSERT 产生的自增主键值(`last_insert_id`),便于调用方拿到新建记录 ID。
2221    ///
2222    /// # 参数
2223    ///
2224    /// - `data`:要插入的数据
2225    ///
2226    /// # 返回值
2227    ///
2228    /// - `Ok((affected, id))`:插入成功,返回 (影响行数, 自增主键值)。
2229    ///   表无自增列时 `id` 为 0。
2230    /// - `Err(BaseError)`:插入失败
2231    ///
2232    /// # 错误
2233    ///
2234    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
2235    /// - `BaseError::FieldRequired`:必填字段缺失
2236    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
2237    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
2238    pub async fn insert_returning_id(
2239        self,
2240        data: std::collections::HashMap<String, Value>,
2241    ) -> Result<(u64, u64), BaseError> {
2242        let pool = self
2243            .pool
2244            .as_ref()
2245            .ok_or(BaseError::DatabaseNotInitialized)?;
2246
2247        let data = self.prepare_and_validate_insert(data)?;
2248        let (sql, params) = self.build_insert_sql(&data)?;
2249
2250        let result = Self::timed(
2251            self.slow_threshold,
2252            self.request_id,
2253            &self.table_config.table_name,
2254            "insert_returning_id",
2255            Self::run_execute(pool.as_ref(), &sql, &params),
2256        )
2257        .await?;
2258
2259        Ok((result.rows_affected(), result.last_insert_id()))
2260    }
2261
2262    /// 在事务中执行 INSERT 并返回自增主键
2263    ///
2264    /// 与 [`TableQuery::insert_returning_id`] 一致,但在事务内执行。批量写入或
2265    /// 「插入父行→用其主键插入子行」等需要拿到新 ID 再继续的原子场景使用。
2266    pub async fn insert_returning_id_in_tx(
2267        self,
2268        tx: &mut yang_db::Transaction,
2269        data: std::collections::HashMap<String, Value>,
2270    ) -> Result<(u64, u64), BaseError> {
2271        let data = self.prepare_and_validate_insert(data)?;
2272        let (sql, params) = self.build_insert_sql(&data)?;
2273
2274        let executor = tx.executor().ok_or_else(|| {
2275            BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
2276                "事务已提交或回滚".to_string(),
2277            ))
2278        })?;
2279
2280        let result = Self::timed(
2281            self.slow_threshold,
2282            self.request_id,
2283            &self.table_config.table_name,
2284            "insert_returning_id_in_tx",
2285            Self::run_execute(executor, &sql, &params),
2286        )
2287        .await?;
2288        Ok((result.rows_affected(), result.last_insert_id()))
2289    }
2290
2291    /// 填充默认值/时间戳并验证插入数据
2292    ///
2293    /// 处理顺序(修复 required+default 字段被误报 FieldRequired 的问题):
2294    /// 1. 写权限校验:对调用方显式提供了非 null 值、但用户无写权限的字段拒绝
2295    /// 2. 填充默认值:data 中缺失或为 null 且配置了 `default_value` 的字段补默认值
2296    /// 3. 填充时间戳:`timestamp_fields` 配置且列存在、调用方未提供时,写入当前时间
2297    /// 4. 必填/类型/验证器校验:在补齐后的数据上执行
2298    ///
2299    /// # 参数
2300    ///
2301    /// - `data`:调用方提供的原始插入数据
2302    ///
2303    /// # 返回值
2304    ///
2305    /// - `Ok(HashMap)`:补齐默认值与时间戳后的最终插入数据
2306    /// - `Err(BaseError)`:权限或校验失败
2307    fn prepare_and_validate_insert(
2308        &self,
2309        data: std::collections::HashMap<String, Value>,
2310    ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
2311        let mut prepared = data;
2312
2313        // 1. 写权限校验:仅拦截"无权限却显式赋了非 null 值"的字段
2314        for (field_name, field_config) in &self.table_config.fields {
2315            if !field_config.permissions.can_write(&self.user_roles_set) {
2316                if let Some(v) = prepared.get(field_name) {
2317                    if !v.is_null() {
2318                        return Err(BaseError::FieldPermissionDenied(
2319                            self.table_config.table_name.clone(),
2320                            field_name.clone(),
2321                            "用户无写入权限".to_string(),
2322                        ));
2323                    }
2324                }
2325            }
2326        }
2327
2328        // 2. 填充默认值(缺失或为 null 且配置了 default_value)
2329        for (field_name, field_config) in &self.table_config.fields {
2330            if let Some(default) = &field_config.default_value {
2331                let missing = prepared
2332                    .get(field_name)
2333                    .map(|v| v.is_null())
2334                    .unwrap_or(true);
2335                if missing {
2336                    prepared.insert(field_name.clone(), default.clone());
2337                }
2338            }
2339        }
2340
2341        // 3. 填充创建/更新时间戳(列存在且调用方未提供时)
2342        if let Some(ts) = &self.table_config.timestamp_fields {
2343            let now = chrono::Utc::now().timestamp();
2344            for ts_field in [&ts.created_at, &ts.updated_at].into_iter().flatten() {
2345                if self.table_config.fields.contains_key(ts_field) {
2346                    let missing = prepared.get(ts_field).map(|v| v.is_null()).unwrap_or(true);
2347                    if missing {
2348                        prepared.insert(ts_field.clone(), Value::Number(now.into()));
2349                    }
2350                }
2351            }
2352        }
2353
2354        // 4. 在补齐后的数据上执行必填/类型/验证器校验
2355        for (field_name, field_config) in &self.table_config.fields {
2356            if !field_config.permissions.can_write(&self.user_roles_set) {
2357                continue;
2358            }
2359            let value = prepared.get(field_name).unwrap_or(&Value::Null);
2360            field_config.validate(value)?;
2361        }
2362
2363        Ok(prepared)
2364    }
2365
2366    /// 构建 INSERT SQL 语句
2367    ///
2368    /// # 参数
2369    ///
2370    /// - `data`:要插入的数据
2371    ///
2372    /// # 返回值
2373    ///
2374    /// 返回 (SQL 语句, 参数列表) 元组
2375    ///
2376    /// # 错误
2377    ///
2378    /// - `BaseError::DatabaseQueryFailed`:SQL 构建失败
2379    fn build_insert_sql(
2380        &self,
2381        data: &std::collections::HashMap<String, Value>,
2382    ) -> Result<(String, Vec<SqlParam>), BaseError> {
2383        let mut fields = Vec::with_capacity(data.len());
2384        let mut placeholders = Vec::with_capacity(data.len());
2385        let mut params = Vec::with_capacity(data.len());
2386
2387        // 遍历数据,构建字段列表和参数列表
2388        for (field_name, value) in data {
2389            // 检查字段是否存在于表配置中
2390            if !self.table_config.fields.contains_key(field_name) {
2391                return Err(BaseError::FieldNotFound(
2392                    self.table_config.table_name.clone(),
2393                    field_name.clone(),
2394                ));
2395            }
2396
2397            // 写入权限已在 validate_insert_data 集中校验(无权限且赋非 null 值会
2398            // 直接报错),此处不再二次跳过,保证 data 中所有字段一致入列。
2399
2400            // 对字段名进行反引号转义,防止 SQL 注入
2401            let quoted = self.quote_identifier(field_name)?;
2402            fields.push(quoted);
2403            placeholders.push("?".to_string());
2404            params.push(SqlParam::from_json(value)?);
2405        }
2406
2407        // 构建 SQL 语句(表名走统一转义路径)
2408        let sql = format!(
2409            "INSERT INTO {} ({}) VALUES ({})",
2410            self.quoted_table_name()?,
2411            fields.join(", "),
2412            placeholders.join(", ")
2413        );
2414
2415        Ok((sql, params))
2416    }
2417
2418    /// 执行 UPDATE 操作
2419    ///
2420    /// 更新表中的数据,包括以下步骤:
2421    /// 1. 验证所有字段值的合法性(使用 FieldConfig::validate)
2422    /// 2. 检查用户是否有字段的写入权限
2423    /// 3. 构建 UPDATE SQL 语句
2424    /// 4. 应用已配置的 WHERE 条件
2425    /// 5. 执行更新操作
2426    /// 6. 返回影响行数
2427    ///
2428    /// # 参数
2429    ///
2430    /// - `data`:要更新的数据,格式为 HashMap<String, Value>
2431    ///
2432    /// # 返回值
2433    ///
2434    /// - `Ok(u64)`:更新成功,返回影响行数
2435    /// - `Err(BaseError)`:更新失败,返回错误
2436    ///
2437    /// # 错误
2438    ///
2439    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
2440    /// - `BaseError::FieldNotFound`:字段不存在
2441    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
2442    /// - `BaseError::ValidationFailed`:字段值验证失败
2443    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
2444    ///
2445    /// # 示例
2446    ///
2447    /// ```rust,ignore
2448    /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
2449    /// use std::sync::Arc;
2450    /// use std::collections::HashMap;
2451    /// use serde_json::json;
2452    ///
2453    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
2454    /// let table_config = Arc::new(
2455    ///     TableConfig::new("users")
2456    ///         .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
2457    ///         .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
2458    ///         .field(FieldConfig::new("email", FieldType::String { max_length: 100 })).expect("有效字段配置应注册成功")
2459    /// );
2460    ///
2461    /// let query = TableQuery::new(
2462    ///     table_config,
2463    ///     vec!["user".to_string()],
2464    ///     Some(pool),
2465    /// );
2466    ///
2467    /// // 准备更新数据
2468    /// let mut data = HashMap::new();
2469    /// data.insert("name".to_string(), json!("李四"));
2470    /// data.insert("email".to_string(), json!("lisi@example.com"));
2471    ///
2472    /// // 执行更新(需要先设置 WHERE 条件)
2473    /// let affected = query
2474    ///     .where_eq("id", json!(1))?
2475    ///     .update(data)
2476    ///     .await?;
2477    /// println!("更新成功,影响行数: {}", affected);
2478    /// # Ok(())
2479    /// # }
2480    /// ```
2481    pub async fn update(
2482        self,
2483        data: std::collections::HashMap<String, Value>,
2484    ) -> Result<u64, BaseError> {
2485        // 1. 检查数据库连接池是否存在
2486        let pool = self
2487            .pool
2488            .as_ref()
2489            .ok_or(BaseError::DatabaseNotInitialized)?;
2490
2491        // 2. 验证所有字段值的合法性和权限
2492        self.validate_update_data(&data)?;
2493
2494        // 3. 构建 UPDATE SQL 语句
2495        let (sql, params) = self.build_update_sql(&data)?;
2496
2497        // 4. 在连接池上执行更新(计时观测)
2498        let result = Self::timed(
2499            self.slow_threshold,
2500            self.request_id,
2501            &self.table_config.table_name,
2502            "update",
2503            Self::run_execute(pool.as_ref(), &sql, &params),
2504        )
2505        .await?;
2506
2507        Ok(result.rows_affected())
2508    }
2509
2510    /// 在事务中执行 UPDATE 操作
2511    ///
2512    /// 与 [`TableQuery::update`] 一致的字段校验/权限/WHERE 守卫/自动 `updated_at`
2513    /// 逻辑,但在事务内执行。
2514    ///
2515    /// # 错误
2516    ///
2517    /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
2518    /// - 其余同 [`TableQuery::update`]
2519    pub async fn update_in_tx(
2520        self,
2521        tx: &mut yang_db::Transaction,
2522        data: std::collections::HashMap<String, Value>,
2523    ) -> Result<u64, BaseError> {
2524        self.validate_update_data(&data)?;
2525        let (sql, params) = self.build_update_sql(&data)?;
2526
2527        let executor = tx.executor().ok_or_else(|| {
2528            BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
2529                "事务已提交或回滚".to_string(),
2530            ))
2531        })?;
2532
2533        let result = Self::timed(
2534            self.slow_threshold,
2535            self.request_id,
2536            &self.table_config.table_name,
2537            "update_in_tx",
2538            Self::run_execute(executor, &sql, &params),
2539        )
2540        .await?;
2541        Ok(result.rows_affected())
2542    }
2543
2544    /// 验证更新数据
2545    ///
2546    /// 验证所有要更新的字段值的合法性和用户权限
2547    ///
2548    /// # 参数
2549    ///
2550    /// - `data`:要更新的数据
2551    ///
2552    /// # 返回值
2553    ///
2554    /// - `Ok(())`:验证通过
2555    /// - `Err(BaseError)`:验证失败
2556    ///
2557    /// # 错误
2558    ///
2559    /// - `BaseError::FieldNotFound`:字段不存在
2560    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
2561    /// - `BaseError::ValidationFailed`:字段值验证失败
2562    #[cfg(test)]
2563    pub fn validate_update_data(
2564        &self,
2565        data: &std::collections::HashMap<String, Value>,
2566    ) -> Result<(), BaseError> {
2567        self.validate_update_data_impl(data)
2568    }
2569
2570    /// 验证更新数据(内部实现)
2571    #[cfg(not(test))]
2572    fn validate_update_data(
2573        &self,
2574        data: &std::collections::HashMap<String, Value>,
2575    ) -> Result<(), BaseError> {
2576        self.validate_update_data_impl(data)
2577    }
2578
2579    /// 验证更新数据的实际实现
2580    fn validate_update_data_impl(
2581        &self,
2582        data: &std::collections::HashMap<String, Value>,
2583    ) -> Result<(), BaseError> {
2584        // 只验证提供的字段(与 INSERT 不同,UPDATE 不需要验证所有字段)
2585        for (field_name, value) in data {
2586            // 1. 检查字段是否存在于表配置中
2587            let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
2588                BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
2589            })?;
2590
2591            // 2. 检查用户是否有写入权限
2592            if !field_config.permissions.can_write(&self.user_roles_set) {
2593                return Err(BaseError::FieldPermissionDenied(
2594                    self.table_config.table_name.clone(),
2595                    field_name.clone(),
2596                    "用户无写入权限".to_string(),
2597                ));
2598            }
2599
2600            // 3. 验证字段值(包括类型检查和验证器检查)
2601            // 注意:UPDATE 操作中,字段不一定是必填的,因为我们只更新部分字段
2602            // 所以这里不检查 required 约束,只检查类型和验证器
2603            field_config.validate(value)?;
2604        }
2605
2606        Ok(())
2607    }
2608
2609    /// 构建 UPDATE SQL 语句
2610    ///
2611    /// # 参数
2612    ///
2613    /// - `data`:要更新的数据
2614    ///
2615    /// # 返回值
2616    ///
2617    /// 返回 (SQL 语句, 参数列表) 元组
2618    ///
2619    /// # 错误
2620    ///
2621    /// - `BaseError::DatabaseQueryFailed`:SQL 构建失败
2622    #[cfg(test)]
2623    #[allow(private_interfaces)]
2624    pub fn build_update_sql(
2625        &self,
2626        data: &std::collections::HashMap<String, Value>,
2627    ) -> Result<(String, Vec<SqlParam>), BaseError> {
2628        self.build_update_sql_impl(data)
2629    }
2630
2631    /// 构建 UPDATE SQL 语句(内部实现)
2632    #[cfg(not(test))]
2633    fn build_update_sql(
2634        &self,
2635        data: &std::collections::HashMap<String, Value>,
2636    ) -> Result<(String, Vec<SqlParam>), BaseError> {
2637        self.build_update_sql_impl(data)
2638    }
2639
2640    /// 构建 UPDATE SQL 语句的实际实现
2641    fn build_update_sql_impl(
2642        &self,
2643        data: &std::collections::HashMap<String, Value>,
2644    ) -> Result<(String, Vec<SqlParam>), BaseError> {
2645        // 0. 拒绝空更新:用户未提供任何可更新字段
2646        if data.is_empty() {
2647            return Err(BaseError::ParamInvalid(
2648                "data".to_string(),
2649                "无可更新字段".to_string(),
2650            ));
2651        }
2652
2653        // 1. 自动刷新 updated_at(若已配置且列存在于表),仅在需要时克隆
2654        let need_timestamp = self
2655            .table_config
2656            .timestamp_fields
2657            .as_ref()
2658            .and_then(|ts| ts.updated_at.as_ref())
2659            .is_some_and(|updated_at| self.table_config.fields.contains_key(updated_at));
2660
2661        let mut owned_data;
2662        let working: &std::collections::HashMap<String, Value> = if need_timestamp {
2663            owned_data = data.clone();
2664            // SAFETY: need_timestamp 为 true 意味着 timestamp_fields 和 updated_at 一定存在
2665            let ts = self.table_config.timestamp_fields.as_ref().unwrap();
2666            let updated_at = ts.updated_at.as_ref().unwrap();
2667            let now = chrono::Utc::now().timestamp();
2668            owned_data.insert(updated_at.clone(), Value::Number(now.into()));
2669            &owned_data
2670        } else {
2671            data
2672        };
2673
2674        let mut set_clauses = Vec::with_capacity(working.len());
2675        let mut params = Vec::with_capacity(working.len());
2676
2677        // 2. 构建 SET 子句(通过 quote_identifier 转义字段名)
2678        for (field_name, value) in working {
2679            // 检查字段是否存在于表配置中
2680            if !self.table_config.fields.contains_key(field_name) {
2681                return Err(BaseError::FieldNotFound(
2682                    self.table_config.table_name.clone(),
2683                    field_name.clone(),
2684                ));
2685            }
2686
2687            // 对字段名进行反引号转义
2688            let quoted = self.quote_identifier(field_name)?;
2689            set_clauses.push(format!("{} = ?", quoted));
2690            params.push(SqlParam::from_json(value)?);
2691        }
2692
2693        // 3. 构建基本 UPDATE 语句(表名走统一转义路径)
2694        let mut sql = format!(
2695            "UPDATE {} SET {}",
2696            self.quoted_table_name()?,
2697            set_clauses.join(", ")
2698        );
2699
2700        // 4. WHERE 守卫:无 WHERE 且未显式放行全表,拒绝全表更新
2701        if self.query_params.where_conditions.is_empty() && !self.allow_full_table {
2702            return Err(BaseError::MissingWhereClause("UPDATE".to_string()));
2703        }
2704
2705        // 5. 通过统一方法拼接 WHERE 子句(写路径,不应用软删过滤)
2706        self.append_where_to_sql(&mut sql, &mut params, false)?;
2707
2708        Ok((sql, params))
2709    }
2710
2711    /// 执行 DELETE 操作
2712    ///
2713    /// 删除表中的数据,支持软删除和物理删除两种模式:
2714    /// 1. 如果配置了软删除字段(soft_delete_field),执行 UPDATE 设置删除标记
2715    /// 2. 如果未配置软删除字段,执行物理删除
2716    /// 3. 应用已配置的 WHERE 条件
2717    /// 4. 返回影响行数
2718    ///
2719    /// # 返回值
2720    ///
2721    /// - `Ok(u64)`:删除成功,返回影响行数
2722    /// - `Err(BaseError)`:删除失败,返回错误
2723    ///
2724    /// # 错误
2725    ///
2726    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
2727    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
2728    ///
2729    /// # 示例
2730    ///
2731    /// ```rust,ignore
2732    /// use yang_base::table::{TableQuery, TableConfig, FieldConfig, FieldType};
2733    /// use std::sync::Arc;
2734    /// use serde_json::json;
2735    ///
2736    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
2737    /// // 配置了软删除字段的表
2738    /// let table_config = Arc::new(
2739    ///     TableConfig::new("users")
2740    ///         .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
2741    ///         .field(FieldConfig::new("name", FieldType::String { max_length: 50 })).expect("有效字段配置应注册成功")
2742    ///         .field(FieldConfig::new("deleted_at", FieldType::BigInt)).expect("有效字段配置应注册成功")
2743    ///         .soft_delete_field("deleted_at")  // 配置软删除字段
2744    /// );
2745    ///
2746    /// let query = TableQuery::new(
2747    ///     table_config,
2748    ///     vec!["admin".to_string()],
2749    ///     Some(pool),
2750    /// );
2751    ///
2752    /// // 执行软删除(实际上是 UPDATE deleted_at = <timestamp>)
2753    /// let affected = query
2754    ///     .where_eq("id", json!(1))?
2755    ///     .delete()
2756    ///     .await?;
2757    /// println!("删除成功,影响行数: {}", affected);
2758    ///
2759    /// // 未配置软删除字段的表将执行物理删除
2760    /// let table_config2 = Arc::new(
2761    ///     TableConfig::new("logs")
2762    ///         .field(FieldConfig::new("id", FieldType::BigInt)).expect("有效字段配置应注册成功")
2763    ///         .field(FieldConfig::new("message", FieldType::Text)).expect("有效字段配置应注册成功")
2764    ///         // 未配置 soft_delete_field
2765    /// );
2766    ///
2767    /// let query2 = TableQuery::new(
2768    ///     table_config2,
2769    ///     vec!["admin".to_string()],
2770    ///     Some(pool),
2771    /// );
2772    ///
2773    /// // 执行物理删除(实际上是 DELETE FROM logs WHERE ...)
2774    /// let affected2 = query2
2775    ///     .where_eq("id", json!(1))?
2776    ///     .delete()
2777    ///     .await?;
2778    /// println!("物理删除成功,影响行数: {}", affected2);
2779    /// # Ok(())
2780    /// # }
2781    /// ```
2782    pub async fn delete(self) -> Result<u64, BaseError> {
2783        // 1. 检查是否配置了软删除字段
2784        if let Some(soft_delete_field) = &self.table_config.soft_delete_field {
2785            // 软删除:走 build_update_sql_impl 跳过 validate_update_data_impl
2786            // 的用户写权限检查,与 updated_at 自动写入语义对称。
2787            let now = chrono::Utc::now().timestamp();
2788            let mut data = std::collections::HashMap::new();
2789            data.insert(soft_delete_field.clone(), Value::Number(now.into()));
2790            let (sql, params) = self.build_update_sql_impl(&data)?;
2791            let pool = self
2792                .pool
2793                .as_ref()
2794                .ok_or(BaseError::DatabaseNotInitialized)?;
2795            let result = Self::timed(
2796                self.slow_threshold,
2797                self.request_id,
2798                &self.table_config.table_name,
2799                "delete",
2800                Self::run_execute(pool.as_ref(), &sql, &params),
2801            )
2802            .await?;
2803            return Ok(result.rows_affected());
2804        }
2805
2806        // 2. 物理删除:检查连接池
2807        let pool = self
2808            .pool
2809            .as_ref()
2810            .ok_or(BaseError::DatabaseNotInitialized)?;
2811
2812        // 3. 物理删除:构建 DELETE SQL 语句
2813        let (sql, params) = self.build_delete_sql()?;
2814
2815        // 4. 在连接池上执行删除(计时观测)
2816        let result = Self::timed(
2817            self.slow_threshold,
2818            self.request_id,
2819            &self.table_config.table_name,
2820            "delete",
2821            Self::run_execute(pool.as_ref(), &sql, &params),
2822        )
2823        .await?;
2824
2825        Ok(result.rows_affected())
2826    }
2827
2828    /// 在事务中执行 DELETE 操作
2829    ///
2830    /// 与 [`TableQuery::delete`] 一致:配置了软删除字段时走 UPDATE 标记(同样在
2831    /// 事务内),否则物理删除;WHERE 守卫与软删语义完全复用。
2832    ///
2833    /// # 错误
2834    ///
2835    /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
2836    /// - 其余同 [`TableQuery::delete`]
2837    pub async fn delete_in_tx(self, tx: &mut yang_db::Transaction) -> Result<u64, BaseError> {
2838        // 软删除:走 build_update_sql_impl 跳过 validate_update_data_impl
2839        // 的用户写权限检查,与 updated_at 自动写入语义对称。
2840        if let Some(soft_delete_field) = &self.table_config.soft_delete_field {
2841            let now = chrono::Utc::now().timestamp();
2842            let mut data = std::collections::HashMap::new();
2843            data.insert(soft_delete_field.clone(), Value::Number(now.into()));
2844            let (sql, params) = self.build_update_sql_impl(&data)?;
2845            let executor = tx.executor().ok_or_else(|| {
2846                BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
2847                    "事务已提交或回滚".to_string(),
2848                ))
2849            })?;
2850            let result = Self::timed(
2851                self.slow_threshold,
2852                self.request_id,
2853                &self.table_config.table_name,
2854                "delete_in_tx",
2855                Self::run_execute(executor, &sql, &params),
2856            )
2857            .await?;
2858            return Ok(result.rows_affected());
2859        }
2860
2861        let (sql, params) = self.build_delete_sql()?;
2862
2863        let executor = tx.executor().ok_or_else(|| {
2864            BaseError::DatabaseTransactionFailed(yang_db::DbError::TransactionError(
2865                "事务已提交或回滚".to_string(),
2866            ))
2867        })?;
2868
2869        let result = Self::timed(
2870            self.slow_threshold,
2871            self.request_id,
2872            &self.table_config.table_name,
2873            "delete_in_tx",
2874            Self::run_execute(executor, &sql, &params),
2875        )
2876        .await?;
2877        Ok(result.rows_affected())
2878    }
2879
2880    /// 构建 DELETE SQL 语句
2881    ///
2882    /// # 返回值
2883    ///
2884    /// 返回 (SQL 语句, 参数列表) 元组
2885    ///
2886    /// # 错误
2887    ///
2888    /// - `BaseError::DatabaseQueryFailed`:SQL 构建失败
2889    #[cfg(test)]
2890    #[allow(private_interfaces)]
2891    pub fn build_delete_sql(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
2892        self.build_delete_sql_impl()
2893    }
2894
2895    /// 构建 SELECT SQL 语句(仅供测试使用)
2896    #[cfg(test)]
2897    #[allow(private_interfaces)]
2898    pub fn build_select_sql_for_test(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
2899        self.build_select_sql(None)
2900    }
2901
2902    /// 构建 INSERT SQL 语句(仅供测试使用)
2903    ///
2904    /// 先经 `prepare_and_validate_insert` 补默认值/时间戳并校验,再拼 SQL,
2905    /// 等价于 `insert`/`insert_returning_id` 的建句路径,但无需数据库连接。
2906    #[cfg(test)]
2907    #[allow(private_interfaces)]
2908    pub fn build_insert_sql_for_test(
2909        &self,
2910        data: std::collections::HashMap<String, Value>,
2911    ) -> Result<(String, Vec<SqlParam>), BaseError> {
2912        let prepared = self.prepare_and_validate_insert(data)?;
2913        self.build_insert_sql(&prepared)
2914    }
2915
2916    /// 构建 DELETE SQL 语句(内部实现)
2917    #[cfg(not(test))]
2918    fn build_delete_sql(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
2919        self.build_delete_sql_impl()
2920    }
2921
2922    /// 构建 DELETE SQL 语句的实际实现
2923    fn build_delete_sql_impl(&self) -> Result<(String, Vec<SqlParam>), BaseError> {
2924        // 表名走统一转义路径
2925        let mut sql = format!("DELETE FROM {}", self.quoted_table_name()?);
2926        let mut params = Vec::new();
2927
2928        // WHERE 守卫:无 WHERE 且未显式放行全表,拒绝全表物理删除
2929        if self.query_params.where_conditions.is_empty() && !self.allow_full_table {
2930            return Err(BaseError::MissingWhereClause("DELETE".to_string()));
2931        }
2932
2933        // 通过统一方法拼接 WHERE 子句(写路径,不应用软删过滤)
2934        self.append_where_to_sql(&mut sql, &mut params, false)?;
2935
2936        Ok((sql, params))
2937    }
2938
2939    /// 绑定参数到执行查询
2940    ///
2941    /// # 参数
2942    ///
2943    /// - `query`:sqlx 查询对象
2944    /// - `param`:SQL 参数值
2945    ///
2946    /// # 返回值
2947    ///
2948    /// 绑定参数后的查询对象
2949    fn bind_execute_param<'q>(
2950        query: sqlx::query::Query<'q, sqlx::MySql, sqlx::mysql::MySqlArguments>,
2951        param: &SqlParam,
2952    ) -> sqlx::query::Query<'q, sqlx::MySql, sqlx::mysql::MySqlArguments> {
2953        match param {
2954            SqlParam::Null => query.bind(Option::<i32>::None),
2955            SqlParam::Bool(b) => query.bind(*b),
2956            SqlParam::Int(i) => query.bind(*i),
2957            SqlParam::Uint(u) => query.bind(*u),
2958            SqlParam::Float(f) => query.bind(*f),
2959            SqlParam::String(s) => query.bind(s.clone()),
2960            SqlParam::DateTime(dt) => query.bind(*dt),
2961            SqlParam::Bytes(b) => query.bind(b.clone()),
2962            SqlParam::Json(j) => query.bind(j.clone()),
2963        }
2964    }
2965
2966    /// 执行边界计时(慢查询观测,C4)。
2967    ///
2968    /// 包裹一次数据库执行 `fut`:`threshold` 为 `None`(默认)时仅一次
2969    /// `Instant::now()`,无额外分配、无日志;为 `Some(d)` 且实际耗时超过 `d` 时
2970    /// 发一条 `tracing::warn!`(含表名、操作、耗时毫秒、request_id)。
2971    ///
2972    /// 设计为关联函数(不借用 `&self`),以便在消费 `self` 的终端方法里,与
2973    /// 借用 `self.pool`/`sql`/`params` 的执行 future 共存而不冲突借用检查。
2974    /// SQL 文本**默认不记**(防泄漏 + 防高基数)。`op` 为静态操作名。
2975    pub(crate) async fn timed<F, R>(
2976        threshold: Option<std::time::Duration>,
2977        request_id: Option<crate::action::RequestId>,
2978        table: &str,
2979        op: &'static str,
2980        fut: F,
2981    ) -> R
2982    where
2983        F: std::future::Future<Output = R>,
2984    {
2985        // 阈值未配置:直接 await,热路径仅一次分支判断,无 Instant
2986        let threshold = match threshold {
2987            Some(t) => t,
2988            None => return fut.await,
2989        };
2990        let start = std::time::Instant::now();
2991        let result = fut.await;
2992        let elapsed = start.elapsed();
2993        if elapsed >= threshold {
2994            let elapsed_ms = elapsed.as_secs_f64() * 1000.0;
2995            match request_id {
2996                Some(rid) => tracing::warn!(
2997                    table = %table,
2998                    op,
2999                    elapsed_ms,
3000                    request_id = %rid,
3001                    "慢查询",
3002                ),
3003                None => tracing::warn!(table = %table, op, elapsed_ms, "慢查询"),
3004            }
3005        }
3006        result
3007    }
3008
3009    /// 在给定执行器上绑定参数并执行写语句(INSERT/UPDATE/DELETE 共用)
3010    ///
3011    /// 执行器既可以是 `&MySqlPool`(普通路径),也可以是
3012    /// `&mut sqlx::MySqlConnection`(事务路径,经 [`yang_db::Transaction::executor`]
3013    /// 取得)。如此一来,受保护层的写操作可以直接执行,也可纳入同一事务原子提交,
3014    /// 而所有权限/校验/软删/WHERE 守卫逻辑在调用方保持不变。
3015    ///
3016    /// 返回 `MySqlQueryResult`,由调用方按需提取 `rows_affected()` /
3017    /// `last_insert_id()`。
3018    async fn run_execute<'e, E>(
3019        executor: E,
3020        sql: &str,
3021        params: &[SqlParam],
3022    ) -> Result<sqlx::mysql::MySqlQueryResult, BaseError>
3023    where
3024        E: sqlx::Executor<'e, Database = sqlx::MySql>,
3025    {
3026        let mut query = sqlx::query(sql);
3027        for param in params {
3028            query = Self::bind_execute_param(query, param);
3029        }
3030        query
3031            .execute(executor)
3032            .await
3033            .map_err(|e| BaseError::DatabaseExecuteFailed(yang_db::DbError::from(e)))
3034    }
3035
3036    /// 在给定执行器上绑定参数并执行 SELECT 查询,返回多行
3037    ///
3038    /// 与 [`TableQuery::run_execute`] 同理对执行器泛型,使 `select` 既能走连接池
3039    /// 也能在事务内执行(read-modify-write 场景)。
3040    async fn run_fetch_all<'e, E, T>(
3041        executor: E,
3042        sql: &str,
3043        params: &[SqlParam],
3044    ) -> Result<Vec<T>, BaseError>
3045    where
3046        E: sqlx::Executor<'e, Database = sqlx::MySql>,
3047        T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
3048    {
3049        let mut query = sqlx::query_as::<_, T>(sql);
3050        for param in params {
3051            query = Self::bind_param(query, param);
3052        }
3053        query
3054            .fetch_all(executor)
3055            .await
3056            .map_err(|e| BaseError::DatabaseQueryFailed(yang_db::DbError::from(e)))
3057    }
3058}
3059
3060/// SQL 参数类型
3061///
3062/// 用于表示 SQL 查询中的参数值
3063#[cfg(feature = "mysql")]
3064#[derive(Debug, Clone)]
3065#[cfg_attr(test, derive(PartialEq))]
3066#[allow(dead_code)] // DateTime/Bytes/Json 已声明,待 from_json 外部构造路径落地
3067pub(crate) enum SqlParam {
3068    /// 空值
3069    Null,
3070    /// 布尔值
3071    Bool(bool),
3072    /// 整数
3073    Int(i64),
3074    /// 无符号整数(保留超出 i64 范围的 u64 值,避免精度丢失)
3075    Uint(u64),
3076    /// 浮点数
3077    Float(f64),
3078    /// 字符串
3079    String(String),
3080    /// 日期时间(ISO 8601 字符串解析)
3081    DateTime(chrono::NaiveDateTime),
3082    /// 二进制数据
3083    Bytes(Vec<u8>),
3084    /// JSON 值
3085    Json(serde_json::Value),
3086}
3087
3088#[cfg(feature = "mysql")]
3089impl SqlParam {
3090    /// 从 JSON 值创建 SQL 参数
3091    ///
3092    /// # 参数
3093    ///
3094    /// - `value`:JSON 值
3095    ///
3096    /// # 返回值
3097    ///
3098    /// - `Ok(SqlParam)`:转换成功
3099    /// - `Err(BaseError)`:转换失败
3100    fn from_json(value: &Value) -> Result<Self, BaseError> {
3101        match value {
3102            Value::Null => Ok(SqlParam::Null),
3103            Value::Bool(b) => Ok(SqlParam::Bool(*b)),
3104            Value::Number(n) => {
3105                if let Some(i) = n.as_i64() {
3106                    Ok(SqlParam::Int(i))
3107                } else if let Some(u) = n.as_u64() {
3108                    // 超出 i64 范围的正整数,保留为 u64 避免精度丢失
3109                    Ok(SqlParam::Uint(u))
3110                } else if let Some(f) = n.as_f64() {
3111                    Ok(SqlParam::Float(f))
3112                } else {
3113                    Err(BaseError::DatabaseQueryFailed(
3114                        yang_db::DbError::QueryError(format!("不支持的数字类型: {}", n)),
3115                    ))
3116                }
3117            }
3118            Value::String(s) => {
3119                // QRY-5: 尝试解析为 DateTime(ISO 8601 格式)
3120                if let Ok(dt) = chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%dT%H:%M:%S")
3121                    .or_else(|_| chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%d %H:%M:%S"))
3122                    .or_else(|_| chrono::NaiveDateTime::parse_from_str(s, "%Y-%m-%dT%H:%M:%S%.f"))
3123                {
3124                    return Ok(SqlParam::DateTime(dt));
3125                }
3126                Ok(SqlParam::String(s.clone()))
3127            }
3128            Value::Array(_) => Ok(SqlParam::Json(value.clone())),
3129            Value::Object(_) => Ok(SqlParam::Json(value.clone())),
3130        }
3131    }
3132}
3133
3134#[cfg(all(test, feature = "mysql"))]
3135mod tests {
3136    use super::*;
3137    use std::collections::HashSet;
3138    use std::sync::Arc;
3139
3140    fn test_query() -> TableQuery {
3141        let config = Arc::new(
3142            crate::table::TableConfig::new("users")
3143                .field(crate::table::FieldConfig::new(
3144                    "id",
3145                    crate::table::FieldType::Integer,
3146                ))
3147                .expect("有效字段配置应注册成功"),
3148        );
3149        let roles: Arc<[String]> = Arc::from(Vec::<String>::new());
3150        TableQuery::new(config, roles, None)
3151    }
3152
3153    #[test]
3154    fn test_page_rejects_page_size_above_production_limit() {
3155        let err = test_query()
3156            .page(1, 101)
3157            .expect_err("page_size 超过 100 应被拒绝");
3158
3159        assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "page_size"));
3160    }
3161
3162    #[test]
3163    fn test_default_order_rejects_unsortable_field() {
3164        let config = Arc::new(
3165            crate::table::TableConfig::new("users")
3166                .field(
3167                    crate::table::FieldConfig::new("secret_rank", crate::table::FieldType::Integer)
3168                        .sortable(false),
3169                )
3170                .expect("有效字段配置应注册成功")
3171                .default_order(vec![(
3172                    "secret_rank".to_string(),
3173                    crate::table::SortOrder::Desc,
3174                )]),
3175        );
3176        let roles: Arc<[String]> = Arc::from(Vec::<String>::new());
3177        let query = TableQuery::new(config, roles, None);
3178
3179        let err = query
3180            .build_select_sql(None)
3181            .expect_err("默认排序不应绕过 sortable(false)");
3182
3183        assert!(
3184            matches!(err, BaseError::FieldPermissionDenied(table, field, _) if table == "users" && field == "secret_rank")
3185        );
3186    }
3187
3188    #[test]
3189    fn test_select_star_rejects_unreadable_field() {
3190        let protected_permissions = crate::table::FieldPermissions {
3191            readable_roles: HashSet::from(["admin".to_string()]),
3192            ..crate::table::FieldPermissions::default()
3193        };
3194        let config = Arc::new(
3195            crate::table::TableConfig::new("users")
3196                .field(crate::table::FieldConfig::new(
3197                    "id",
3198                    crate::table::FieldType::Integer,
3199                ))
3200                .expect("有效字段配置应注册成功")
3201                .field(
3202                    crate::table::FieldConfig::new(
3203                        "secret",
3204                        crate::table::FieldType::String { max_length: 64 },
3205                    )
3206                    .permissions(protected_permissions),
3207                )
3208                .expect("有效字段配置应注册成功"),
3209        );
3210        let roles: Arc<[String]> = Arc::from(Vec::<String>::new());
3211        let query = TableQuery::new(config, roles, None);
3212
3213        let err = query
3214            .build_select_sql(None)
3215            .expect_err("SELECT * 不应返回用户无权读取的字段");
3216
3217        assert!(
3218            matches!(err, BaseError::FieldPermissionDenied(table, field, _) if table == "users" && field == "secret")
3219        );
3220    }
3221
3222    #[test]
3223    fn test_select_projection_permission_matrix() {
3224        let protected = crate::table::FieldPermissions {
3225            readable_roles: HashSet::from(["admin".to_string()]),
3226            ..crate::table::FieldPermissions::default()
3227        };
3228
3229        let all_readable = Arc::new(
3230            crate::table::TableConfig::new("public_rows")
3231                .field(crate::table::FieldConfig::new(
3232                    "id",
3233                    crate::table::FieldType::Integer,
3234                ))
3235                .expect("公开字段配置应有效")
3236                .field(crate::table::FieldConfig::new(
3237                    "name",
3238                    crate::table::FieldType::String { max_length: 64 },
3239                ))
3240                .expect("公开字段配置应有效"),
3241        );
3242        let roles: Arc<[String]> = Arc::from(vec!["user".to_string()]);
3243        let (sql, _) = TableQuery::new(all_readable, Arc::clone(&roles), None)
3244            .build_select_sql(None)
3245            .expect("全部字段可读时 SELECT * 应成功");
3246        assert!(sql.starts_with("SELECT * FROM `public_rows`"));
3247
3248        let partially_readable = Arc::new(
3249            crate::table::TableConfig::new("mixed_rows")
3250                .field(crate::table::FieldConfig::new(
3251                    "id",
3252                    crate::table::FieldType::Integer,
3253                ))
3254                .expect("公开字段配置应有效")
3255                .field(
3256                    crate::table::FieldConfig::new(
3257                        "secret",
3258                        crate::table::FieldType::String { max_length: 64 },
3259                    )
3260                    .permissions(protected.clone()),
3261                )
3262                .expect("受限字段配置应有效"),
3263        );
3264        let partial_err =
3265            TableQuery::new(Arc::clone(&partially_readable), Arc::clone(&roles), None)
3266                .build_select_sql(None)
3267                .expect_err("部分字段不可读时 SELECT * 应 fail-closed");
3268        assert!(
3269            matches!(partial_err, BaseError::FieldPermissionDenied(table, field, _) if table == "mixed_rows" && field == "secret")
3270        );
3271
3272        let explicit_err = TableQuery::new(partially_readable, Arc::clone(&roles), None)
3273            .select_fields(&["id", "secret"])
3274            .expect_err("显式请求受限字段应被拒绝");
3275        assert!(
3276            matches!(explicit_err, BaseError::FieldPermissionDenied(table, field, _) if table == "mixed_rows" && field == "secret")
3277        );
3278
3279        let none_readable = Arc::new(
3280            crate::table::TableConfig::new("private_rows")
3281                .field(
3282                    crate::table::FieldConfig::new("alpha", crate::table::FieldType::Integer)
3283                        .permissions(protected.clone()),
3284                )
3285                .expect("受限字段配置应有效")
3286                .field(
3287                    crate::table::FieldConfig::new("beta", crate::table::FieldType::Integer)
3288                        .permissions(protected),
3289                )
3290                .expect("受限字段配置应有效"),
3291        );
3292        let none_err = TableQuery::new(none_readable, roles, None)
3293            .build_select_sql(None)
3294            .expect_err("零字段可读时 SELECT * 应 fail-closed");
3295        assert!(matches!(
3296            none_err,
3297            BaseError::FieldPermissionDenied(table, _, _) if table == "private_rows"
3298        ));
3299    }
3300
3301    #[test]
3302    fn test_unreadable_field_errors_are_deterministic() {
3303        let protected = crate::table::FieldPermissions {
3304            readable_roles: HashSet::from(["admin".to_string()]),
3305            ..crate::table::FieldPermissions::default()
3306        };
3307        let user = crate::action::User::new(1, "reader").with_roles(["user"]);
3308
3309        for _ in 0..64 {
3310            let config = Arc::new(
3311                crate::table::TableConfig::new("secrets")
3312                    .field(
3313                        crate::table::FieldConfig::new(
3314                            "z_secret",
3315                            crate::table::FieldType::Integer,
3316                        )
3317                        .permissions(protected.clone()),
3318                    )
3319                    .expect("受限字段配置应有效")
3320                    .field(
3321                        crate::table::FieldConfig::new(
3322                            "a_secret",
3323                            crate::table::FieldType::Integer,
3324                        )
3325                        .permissions(protected.clone()),
3326                    )
3327                    .expect("受限字段配置应有效")
3328                    .field(
3329                        crate::table::FieldConfig::new(
3330                            "m_secret",
3331                            crate::table::FieldType::Integer,
3332                        )
3333                        .permissions(protected.clone()),
3334                    )
3335                    .expect("受限字段配置应有效"),
3336            );
3337            let roles: Arc<[String]> = Arc::from(vec!["user".to_string()]);
3338            let query = TableQuery::new(config, roles, None);
3339
3340            let sql_err = query
3341                .build_select_sql(None)
3342                .expect_err("SELECT * 应拒绝受限字段");
3343            assert!(
3344                matches!(sql_err, BaseError::FieldPermissionDenied(_, field, _) if field == "a_secret")
3345            );
3346
3347            let action_err = query
3348                .ensure_fields_readable(&user)
3349                .expect_err("整实体 Action 应拒绝受限字段");
3350            assert!(
3351                matches!(action_err, BaseError::FieldPermissionDenied(_, field, _) if field == "a_secret")
3352            );
3353        }
3354    }
3355
3356    #[test]
3357    fn test_effective_pagination_applies_default_limit_to_data_query_sql() {
3358        let (query, page, page_size) = test_query()
3359            .with_effective_pagination()
3360            .expect("默认分页参数应合法");
3361
3362        assert_eq!(page, 1);
3363        assert_eq!(
3364            page_size,
3365            crate::table::query_params::DEFAULT_QUERY_PAGE_SIZE
3366        );
3367
3368        let (sql, _) = query
3369            .build_select_sql(None)
3370            .expect("默认分页后的 SELECT SQL 应可构建");
3371
3372        assert!(
3373            sql.contains(&format!(
3374                " LIMIT {} OFFSET 0",
3375                crate::table::query_params::DEFAULT_QUERY_PAGE_SIZE
3376            )),
3377            "分页数据查询必须包含默认 LIMIT,实际 SQL: {sql}"
3378        );
3379    }
3380}