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        self.query = self.query.where_and(conditions.to_vec())?;
92        Ok(self)
93    }
94
95    /// 在定义允许搜索的文本字段上应用关键词。
96    pub fn search(mut self, keyword: Option<&str>) -> Result<Self, BaseError> {
97        self.query = self.query.search(keyword)?;
98        Ok(self)
99    }
100
101    /// 应用受权限保护的排序。
102    pub fn order(mut self, field: &str, order: SortOrder) -> Result<Self, BaseError> {
103        self.query = self.query.order_by(field, order)?;
104        Ok(self)
105    }
106
107    /// 应用分页。
108    pub fn page(mut self, page: usize, limit: usize) -> Result<Self, BaseError> {
109        self.query = self.query.page(page, limit)?;
110        Ok(self)
111    }
112
113    /// 一次性应用标准 QueryParams。
114    pub fn params(mut self, params: QueryParams) -> Result<Self, BaseError> {
115        self.query = self.query.apply_params(params)?;
116        Ok(self)
117    }
118
119    /// 返回标准列表参数默认值。
120    pub fn params_table() -> QueryParams {
121        QueryParams::new().with_pagination(1, DEFAULT_QUERY_PAGE_SIZE)
122    }
123
124    /// 执行标准分页列表。
125    #[cfg(feature = "mysql")]
126    pub async fn table_list(self) -> Result<PaginatedResult<Record>, BaseError> {
127        self.query.paginate_records().await
128    }
129
130    /// 执行选择器数据查询。
131    ///
132    /// 底层 `all()` 一次性读取全部匹配行,**不受** TableQuery 最大分页限制保护;
133    /// 调用方必须先通过 where/search 条件把结果规模约束在内存可承载范围内。
134    #[cfg(feature = "mysql")]
135    pub async fn table_select(self) -> Result<Vec<Record>, BaseError> {
136        self.query.all().await
137    }
138
139    /// 查询全量选择结果并按默认 `id` / `parent_id` 组装树。
140    ///
141    /// 节点数受 [`DEFAULT_TREE_MAX_NODES`] 限制,超出即报错;需要自定义上限的
142    /// 树 View 应使用 [`Tables::table_tree_view`] 并在 `TreeViewSpec` 中配置。
143    #[cfg(feature = "mysql")]
144    pub async fn table_tree(self) -> Result<Vec<TableTreeNode>, BaseError> {
145        let read_limit = DEFAULT_TREE_MAX_NODES
146            .checked_add(1)
147            .ok_or_else(|| BaseError::ConfigError("默认树节点上限无法计算截断探针".to_string()))?;
148        let rows = self.query.prefetch_limit(read_limit)?.all().await?;
149        ensure_tree_node_cap(rows.len(), DEFAULT_TREE_MAX_NODES)?;
150        Self::build_tree(rows, "id", "parent_id")
151    }
152
153    /// 按启动期已校验的 View 树拓扑查询并组装节点。
154    ///
155    /// 节点数上限取 `TreeViewSpec::max_nodes`(缺省 [`DEFAULT_TREE_MAX_NODES`]),
156    /// 超出即报错,避免全表无界读入内存。
157    #[cfg(feature = "mysql")]
158    pub async fn table_tree_view(
159        self,
160        view: &CompiledTableView,
161    ) -> Result<Vec<TableTreeNode>, BaseError> {
162        let tree = view
163            .tree()
164            .ok_or_else(|| BaseError::ConfigError(format!("View {} 未声明树拓扑", view.name())))?;
165        let max_nodes = tree.max_nodes();
166        let read_limit = max_nodes.checked_add(1).ok_or_else(|| {
167            BaseError::ConfigError(format!("View {} 的树节点上限过大", view.name()))
168        })?;
169        let rows = self
170            .view(view)?
171            .query
172            .prefetch_limit(read_limit)?
173            .all()
174            .await?;
175        ensure_tree_node_cap(rows.len(), max_nodes)?;
176        Self::build_tree(rows, tree.id_field_name(), tree.parent_field_name())
177    }
178
179    /// 将已查询记录组装为树;关系键只用于内存索引,不进入 SQL。
180    pub fn build_tree(
181        rows: Vec<Record>,
182        id_field: &str,
183        parent_field: &str,
184    ) -> Result<Vec<TableTreeNode>, BaseError> {
185        let mut ids = HashMap::with_capacity(rows.len());
186        for (index, row) in rows.iter().enumerate() {
187            let id = row.get(id_field).ok_or_else(|| {
188                BaseError::ParamInvalid(id_field.to_string(), "树节点缺少主键".to_string())
189            })?;
190            if id.is_null() {
191                return Err(BaseError::ParamInvalid(
192                    id_field.to_string(),
193                    "树节点主键不能为 null".to_string(),
194                ));
195            }
196            if ids.insert(value_key(id), index).is_some() {
197                return Err(BaseError::ConfigError(format!(
198                    "树节点主键重复: {id_field}={id}"
199                )));
200            }
201        }
202
203        let mut children = vec![Vec::new(); rows.len()];
204        let mut roots = Vec::new();
205        for (index, row) in rows.iter().enumerate() {
206            let parent = row.get(parent_field).unwrap_or(&Value::Null);
207            if parent.is_null() {
208                roots.push(index);
209            } else if let Some(parent_index) = ids.get(&value_key(parent)).copied() {
210                children[parent_index].push(index);
211            } else {
212                roots.push(index);
213            }
214        }
215
216        let mut rows = rows.into_iter().map(Some).collect::<Vec<_>>();
217        let mut visiting = HashSet::new();
218        let nodes = roots
219            .into_iter()
220            .map(|index| build_node(index, &mut rows, &children, &mut visiting))
221            .collect::<Result<Vec<_>, _>>()?;
222        if rows.iter().any(Option::is_some) {
223            return Err(BaseError::ConfigError("树关系包含循环".to_string()));
224        }
225        Ok(nodes)
226    }
227
228    /// 执行分页列表并按关系种类批量加载展示数据。
229    #[cfg(feature = "mysql")]
230    pub async fn table_list_with_relations<E>(
231        self,
232        executor: &E,
233    ) -> Result<TableListResult, BaseError>
234    where
235        E: RelationBatchExecutor,
236    {
237        let page = self.query.paginate_records().await?;
238        let relations = self.relation_loader.load(&page.data, executor).await?;
239        Ok(TableListResult { page, relations })
240    }
241}
242
243fn value_key(value: &Value) -> String {
244    serde_json::to_string(value).unwrap_or_else(|_| "null".to_string())
245}
246
247fn build_node(
248    index: usize,
249    rows: &mut [Option<Record>],
250    children: &[Vec<usize>],
251    visiting: &mut HashSet<usize>,
252) -> Result<TableTreeNode, BaseError> {
253    if !visiting.insert(index) {
254        return Err(BaseError::ConfigError("树关系包含循环".to_string()));
255    }
256    let record = rows[index]
257        .take()
258        .ok_or_else(|| BaseError::ConfigError("树节点被重复引用".to_string()))?;
259    let nodes = children[index]
260        .iter()
261        .copied()
262        .map(|child| build_node(child, rows, children, visiting))
263        .collect::<Result<Vec<_>, _>>()?;
264    visiting.remove(&index);
265    Ok(TableTreeNode {
266        record,
267        children: nodes,
268    })
269}
270
271#[cfg(test)]
272mod tests {
273    use super::*;
274
275    #[test]
276    fn tree_node_cap_rejects_overflow() {
277        // 边界:恰好等于上限放行。
278        ensure_tree_node_cap(DEFAULT_TREE_MAX_NODES, DEFAULT_TREE_MAX_NODES)
279            .expect("节点数等于上限应放行");
280        ensure_tree_node_cap(3, 10).expect("节点数低于上限应放行");
281
282        let error = ensure_tree_node_cap(DEFAULT_TREE_MAX_NODES + 1, DEFAULT_TREE_MAX_NODES)
283            .expect_err("节点数超过上限必须报错");
284        assert!(
285            matches!(error, BaseError::ParamInvalid(_, _)),
286            "树节点超限应返回 ParamInvalid: {error:?}"
287        );
288
289        // 显式配置的小上限同样生效。
290        let error = ensure_tree_node_cap(11, 10).expect_err("自定义上限超限必须报错");
291        assert!(matches!(error, BaseError::ParamInvalid(_, _)));
292    }
293
294    #[test]
295    fn tree_builder_keeps_order_and_nests_children() {
296        let rows = vec![
297            Record::new().set("id", 1).set("parent_id", Value::Null),
298            Record::new().set("id", 2).set("parent_id", 1),
299        ];
300        let tree = Tables::build_tree(rows, "id", "parent_id").expect("树关系应有效");
301        assert_eq!(tree.len(), 1);
302        assert_eq!(tree[0].children.len(), 1);
303        assert_eq!(
304            tree[0].children[0].record.get("id"),
305            Some(&serde_json::json!(2))
306        );
307    }
308
309    #[test]
310    fn tree_builder_rejects_null_and_duplicate_ids() {
311        let null_id = Tables::build_tree(
312            vec![Record::new()
313                .set("id", Value::Null)
314                .set("parent_id", Value::Null)],
315            "id",
316            "parent_id",
317        )
318        .expect_err("null 主键必须失败");
319        assert!(matches!(null_id, BaseError::ParamInvalid(_, _)));
320
321        let duplicate = Tables::build_tree(
322            vec![
323                Record::new().set("id", 1).set("parent_id", Value::Null),
324                Record::new().set("id", 1).set("parent_id", Value::Null),
325            ],
326            "id",
327            "parent_id",
328        )
329        .expect_err("重复主键必须失败");
330        assert!(matches!(duplicate, BaseError::ConfigError(_)));
331    }
332
333    #[test]
334    fn tree_builder_rejects_cycles_without_roots() {
335        let cycle = Tables::build_tree(
336            vec![
337                Record::new().set("id", 1).set("parent_id", 2),
338                Record::new().set("id", 2).set("parent_id", 1),
339            ],
340            "id",
341            "parent_id",
342        )
343        .expect_err("无根循环必须失败");
344        assert!(matches!(cycle, BaseError::ConfigError(_)));
345    }
346}