Skip to main content

yang_base/table/
tables.rs

1//! BR 心智连续的 Tables 深模块。
2
3#[cfg(feature = "mysql")]
4use super::RelationBatchExecutor;
5use super::{
6    PaginatedResult, QueryParams, Record, RelationData, RelationLoader, SortOrder, TableQuery,
7    WhereCondition, DEFAULT_QUERY_PAGE_SIZE,
8};
9use crate::definition::CompiledTableView;
10use crate::error::BaseError;
11use serde_json::Value;
12use std::collections::{HashMap, HashSet};
13
14/// 树查询的默认节点上限(I-7)。
15///
16/// 树查询需要把全部匹配行读入内存组装,无分页保护;该常量限制单次树查询
17/// 可处理的节点数,超出即报错。`TreeViewSpec::max_nodes` 可按 View 覆盖。
18pub const DEFAULT_TREE_MAX_NODES: usize = 10_000;
19
20/// 校验树查询节点数未超过上限;超限返回 `ParamInvalid`,提示调用方先收窄筛选。
21#[cfg(any(feature = "mysql", test))]
22fn ensure_tree_node_cap(count: usize, max_nodes: usize) -> Result<(), BaseError> {
23    if count > max_nodes {
24        return Err(BaseError::ParamInvalid(
25            "tree".to_string(),
26            format!("树节点数 {count} 超过上限 {max_nodes},请先收窄查询范围"),
27        ));
28    }
29    Ok(())
30}
31
32/// 带批量关系数据的稳定列表响应。
33#[derive(Debug, Clone, serde::Serialize)]
34pub struct TableListResult {
35    /// 分页主数据。
36    pub page: PaginatedResult<Record>,
37    /// 按源字段分组的批量关系记录。
38    pub relations: RelationData,
39}
40
41/// `table_tree` 的稳定树节点响应。
42#[derive(Debug, Clone, serde::Serialize)]
43pub struct TableTreeNode {
44    /// 当前节点原始列。
45    #[serde(flatten)]
46    pub record: Record,
47    /// 子节点,保持数据库结果中的相对顺序。
48    pub children: Vec<TableTreeNode>,
49}
50
51/// 统一封装列表参数、View 字段、分页与关系批量加载。
52#[derive(Debug, Clone)]
53pub struct Tables {
54    query: TableQuery,
55    relation_loader: RelationLoader,
56}
57
58impl Tables {
59    /// 从已经绑定权限和租户范围的 TableQuery 创建。
60    pub fn new(query: TableQuery) -> Self {
61        Self {
62            query,
63            relation_loader: RelationLoader::default(),
64        }
65    }
66
67    /// 应用启动期预编译的 View 字段。
68    pub fn view(mut self, view: &CompiledTableView) -> Result<Self, BaseError> {
69        let fields = view
70            .fields()
71            .iter()
72            .map(|field| {
73                field
74                    .as_str()
75                    .rsplit_once('.')
76                    .map_or(field.as_str(), |(_, name)| name)
77            })
78            .collect::<Vec<_>>();
79        self.query = self.query.select_fields(&fields)?;
80        Ok(self)
81    }
82
83    /// 配置启动期预编译的关系批量加载器。
84    pub fn relations(mut self, loader: RelationLoader) -> Self {
85        self.relation_loader = loader;
86        self
87    }
88
89    /// 应用通用筛选条件;空集合是恒真条件,不改变现有查询范围。
90    pub fn where_from(mut self, conditions: &[WhereCondition]) -> Result<Self, BaseError> {
91        if conditions.is_empty() {
92            return Ok(self);
93        }
94        self.query = self.query.where_and(conditions.to_vec())?;
95        Ok(self)
96    }
97
98    /// 在定义允许搜索的文本字段上应用关键词。
99    pub fn search(mut self, keyword: Option<&str>) -> Result<Self, BaseError> {
100        self.query = self.query.search(keyword)?;
101        Ok(self)
102    }
103
104    /// 应用受权限保护的排序。
105    pub fn order(mut self, field: &str, order: SortOrder) -> Result<Self, BaseError> {
106        self.query = self.query.order_by(field, order)?;
107        Ok(self)
108    }
109
110    /// 应用分页。
111    pub fn page(mut self, page: usize, limit: usize) -> Result<Self, BaseError> {
112        self.query = self.query.page(page, limit)?;
113        Ok(self)
114    }
115
116    /// 一次性应用标准 QueryParams。
117    pub fn params(mut self, params: QueryParams) -> Result<Self, BaseError> {
118        self.query = self.query.apply_params(params)?;
119        Ok(self)
120    }
121
122    /// 返回标准列表参数默认值。
123    pub fn params_table() -> QueryParams {
124        QueryParams::new().with_pagination(1, DEFAULT_QUERY_PAGE_SIZE)
125    }
126
127    /// 执行标准分页列表。
128    #[cfg(feature = "mysql")]
129    pub async fn table_list(self) -> Result<PaginatedResult<Record>, BaseError> {
130        self.query.paginate_records().await
131    }
132
133    /// 执行选择器数据查询。
134    ///
135    /// 底层 `all()` 一次性读取全部匹配行,**不受** TableQuery 最大分页限制保护;
136    /// 调用方必须先通过 where/search 条件把结果规模约束在内存可承载范围内。
137    #[cfg(feature = "mysql")]
138    pub async fn table_select(self) -> Result<Vec<Record>, BaseError> {
139        self.query.all().await
140    }
141
142    /// 查询全量选择结果并按默认 `id` / `parent_id` 组装树。
143    ///
144    /// 节点数受 [`DEFAULT_TREE_MAX_NODES`] 限制,超出即报错;需要自定义上限的
145    /// 树 View 应使用 [`Tables::table_tree_view`] 并在 `TreeViewSpec` 中配置。
146    #[cfg(feature = "mysql")]
147    pub async fn table_tree(self) -> Result<Vec<TableTreeNode>, BaseError> {
148        let read_limit = DEFAULT_TREE_MAX_NODES
149            .checked_add(1)
150            .ok_or_else(|| BaseError::ConfigError("默认树节点上限无法计算截断探针".to_string()))?;
151        let rows = self.query.prefetch_limit(read_limit)?.all().await?;
152        ensure_tree_node_cap(rows.len(), DEFAULT_TREE_MAX_NODES)?;
153        Self::build_tree(rows, "id", "parent_id")
154    }
155
156    /// 按启动期已校验的 View 树拓扑查询并组装节点。
157    ///
158    /// 节点数上限取 `TreeViewSpec::max_nodes`(缺省 [`DEFAULT_TREE_MAX_NODES`]),
159    /// 超出即报错,避免全表无界读入内存。
160    #[cfg(feature = "mysql")]
161    pub async fn table_tree_view(
162        self,
163        view: &CompiledTableView,
164    ) -> Result<Vec<TableTreeNode>, BaseError> {
165        let tree = view
166            .tree()
167            .ok_or_else(|| BaseError::ConfigError(format!("View {} 未声明树拓扑", view.name())))?;
168        let max_nodes = tree.max_nodes();
169        let read_limit = max_nodes.checked_add(1).ok_or_else(|| {
170            BaseError::ConfigError(format!("View {} 的树节点上限过大", view.name()))
171        })?;
172        let rows = self
173            .view(view)?
174            .query
175            .prefetch_limit(read_limit)?
176            .all()
177            .await?;
178        ensure_tree_node_cap(rows.len(), max_nodes)?;
179        Self::build_tree(rows, tree.id_field_name(), tree.parent_field_name())
180    }
181
182    /// 将已查询记录组装为树;关系键只用于内存索引,不进入 SQL。
183    pub fn build_tree(
184        rows: Vec<Record>,
185        id_field: &str,
186        parent_field: &str,
187    ) -> Result<Vec<TableTreeNode>, BaseError> {
188        let mut ids = HashMap::with_capacity(rows.len());
189        for (index, row) in rows.iter().enumerate() {
190            let id = row.get(id_field).ok_or_else(|| {
191                BaseError::ParamInvalid(id_field.to_string(), "树节点缺少主键".to_string())
192            })?;
193            if id.is_null() {
194                return Err(BaseError::ParamInvalid(
195                    id_field.to_string(),
196                    "树节点主键不能为 null".to_string(),
197                ));
198            }
199            if ids.insert(value_key(id), index).is_some() {
200                return Err(BaseError::ConfigError(format!(
201                    "树节点主键重复: {id_field}={id}"
202                )));
203            }
204        }
205
206        let mut children = vec![Vec::new(); rows.len()];
207        let mut roots = Vec::new();
208        for (index, row) in rows.iter().enumerate() {
209            let parent = row.get(parent_field).unwrap_or(&Value::Null);
210            if parent.is_null() {
211                roots.push(index);
212            } else if let Some(parent_index) = ids.get(&value_key(parent)).copied() {
213                children[parent_index].push(index);
214            } else {
215                roots.push(index);
216            }
217        }
218
219        let mut rows = rows.into_iter().map(Some).collect::<Vec<_>>();
220        let mut visiting = HashSet::new();
221        let nodes = roots
222            .into_iter()
223            .map(|index| build_node(index, &mut rows, &children, &mut visiting))
224            .collect::<Result<Vec<_>, _>>()?;
225        if rows.iter().any(Option::is_some) {
226            return Err(BaseError::ConfigError("树关系包含循环".to_string()));
227        }
228        Ok(nodes)
229    }
230
231    /// 执行分页列表并按关系种类批量加载展示数据。
232    #[cfg(feature = "mysql")]
233    pub async fn table_list_with_relations<E>(
234        self,
235        executor: &E,
236    ) -> Result<TableListResult, BaseError>
237    where
238        E: RelationBatchExecutor,
239    {
240        let page = self.query.paginate_records().await?;
241        let relations = self.relation_loader.load(&page.data, executor).await?;
242        Ok(TableListResult { page, relations })
243    }
244}
245
246fn value_key(value: &Value) -> String {
247    serde_json::to_string(value).unwrap_or_else(|_| "null".to_string())
248}
249
250fn build_node(
251    index: usize,
252    rows: &mut [Option<Record>],
253    children: &[Vec<usize>],
254    visiting: &mut HashSet<usize>,
255) -> Result<TableTreeNode, BaseError> {
256    if !visiting.insert(index) {
257        return Err(BaseError::ConfigError("树关系包含循环".to_string()));
258    }
259    let record = rows[index]
260        .take()
261        .ok_or_else(|| BaseError::ConfigError("树节点被重复引用".to_string()))?;
262    let nodes = children[index]
263        .iter()
264        .copied()
265        .map(|child| build_node(child, rows, children, visiting))
266        .collect::<Result<Vec<_>, _>>()?;
267    visiting.remove(&index);
268    Ok(TableTreeNode {
269        record,
270        children: nodes,
271    })
272}
273
274#[cfg(test)]
275mod tests {
276    use super::*;
277
278    #[test]
279    fn tree_node_cap_rejects_overflow() {
280        // 边界:恰好等于上限放行。
281        ensure_tree_node_cap(DEFAULT_TREE_MAX_NODES, DEFAULT_TREE_MAX_NODES)
282            .expect("节点数等于上限应放行");
283        ensure_tree_node_cap(3, 10).expect("节点数低于上限应放行");
284
285        let error = ensure_tree_node_cap(DEFAULT_TREE_MAX_NODES + 1, DEFAULT_TREE_MAX_NODES)
286            .expect_err("节点数超过上限必须报错");
287        assert!(
288            matches!(error, BaseError::ParamInvalid(_, _)),
289            "树节点超限应返回 ParamInvalid: {error:?}"
290        );
291
292        // 显式配置的小上限同样生效。
293        let error = ensure_tree_node_cap(11, 10).expect_err("自定义上限超限必须报错");
294        assert!(matches!(error, BaseError::ParamInvalid(_, _)));
295    }
296
297    #[test]
298    fn tree_builder_keeps_order_and_nests_children() {
299        let rows = vec![
300            Record::new().set("id", 1).set("parent_id", Value::Null),
301            Record::new().set("id", 2).set("parent_id", 1),
302        ];
303        let tree = Tables::build_tree(rows, "id", "parent_id").expect("树关系应有效");
304        assert_eq!(tree.len(), 1);
305        assert_eq!(tree[0].children.len(), 1);
306        assert_eq!(
307            tree[0].children[0].record.get("id"),
308            Some(&serde_json::json!(2))
309        );
310    }
311
312    #[test]
313    fn tree_builder_rejects_null_and_duplicate_ids() {
314        let null_id = Tables::build_tree(
315            vec![Record::new()
316                .set("id", Value::Null)
317                .set("parent_id", Value::Null)],
318            "id",
319            "parent_id",
320        )
321        .expect_err("null 主键必须失败");
322        assert!(matches!(null_id, BaseError::ParamInvalid(_, _)));
323
324        let duplicate = Tables::build_tree(
325            vec![
326                Record::new().set("id", 1).set("parent_id", Value::Null),
327                Record::new().set("id", 1).set("parent_id", Value::Null),
328            ],
329            "id",
330            "parent_id",
331        )
332        .expect_err("重复主键必须失败");
333        assert!(matches!(duplicate, BaseError::ConfigError(_)));
334    }
335
336    #[test]
337    fn tree_builder_rejects_cycles_without_roots() {
338        let cycle = Tables::build_tree(
339            vec![
340                Record::new().set("id", 1).set("parent_id", 2),
341                Record::new().set("id", 2).set("parent_id", 1),
342            ],
343            "id",
344            "parent_id",
345        )
346        .expect_err("无根循环必须失败");
347        assert!(matches!(cycle, BaseError::ConfigError(_)));
348    }
349}