Skip to main content

yang_base/table/
table_query.rs

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