Skip to main content

yang_base/definition/ui/
table.rs

1//! 通用 TableView/Form/Tree 的请求级契约与关系 options、排序、校验提示。
2
3use super::hints::{SortDirection, WidgetHint};
4use crate::definition::FieldRef;
5use schemars::JsonSchema;
6use serde::Serialize;
7
8/// 关系字段的稳定 options 与展示契约。
9#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
10pub struct RelationOptionsSchema {
11    /// 返回 [`RelationOptionsResponse`](crate::table::RelationOptionsResponse) 的 Action。
12    pub operation_id: String,
13    /// 关系值对应的限定目标字段。
14    pub value_field: String,
15    /// 用于解释已选值的限定展示字段。
16    pub label_fields: Vec<String>,
17}
18
19/// View 构建期声明的默认排序。
20#[derive(Debug, Clone, PartialEq, Eq)]
21pub struct TableSortSpec {
22    /// 必须属于当前 View 且允许排序的字段。
23    pub field: FieldRef,
24    /// 默认排序方向。
25    pub direction: SortDirection,
26}
27
28impl TableSortSpec {
29    /// 创建默认排序声明。
30    pub fn new(field: FieldRef, direction: SortDirection) -> Self {
31        Self { field, direction }
32    }
33}
34
35/// 请求级默认排序。
36#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
37pub struct TableSortSchema {
38    /// 行数据中的本地字段名。
39    pub field: String,
40    /// 默认排序方向。
41    pub direction: SortDirection,
42}
43
44/// 通用 TableView 的查询能力与服务端分页边界。
45#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
46pub struct TableQuerySchema {
47    /// 当前用户可见且允许关键词搜索的字段。
48    pub search_fields: Vec<String>,
49    /// 当前用户可见且允许结构化条件筛选的字段。
50    pub filter_fields: Vec<String>,
51    /// 按声明顺序排列的默认排序;不可读字段会从请求级投影中移除。
52    pub default_sort: Vec<TableSortSchema>,
53    /// 默认分页大小。
54    pub default_page_size: usize,
55    /// 服务端强制执行的最大分页大小。
56    pub max_page_size: usize,
57}
58
59/// 通用表格页的单列展示契约。
60#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
61pub struct TableColumnSchema {
62    /// 行数据中的字段名。
63    pub field: String,
64    /// 用户可见标题。
65    pub title: String,
66    /// 字段帮助说明。
67    pub description: String,
68    /// 建议控件;未知值由消费者降级为 JSON/text。
69    pub widget: WidgetHint,
70    /// 输入时是否必填。
71    pub required: bool,
72    /// 是否允许关键词搜索。
73    pub searchable: bool,
74    /// 是否允许作为结构化筛选字段。
75    pub filterable: bool,
76    /// 是否允许排序。
77    pub sortable: bool,
78    /// 当前请求有权调用的关系 options 契约。
79    #[serde(skip_serializing_if = "Option::is_none")]
80    pub relation: Option<RelationOptionsSchema>,
81}
82
83/// 通用表单字段的输入校验提示。
84///
85/// 与存储类型解耦,仅作为前端预校验提示;服务端 Handler 仍必须独立执行权威校验。
86/// 未声明的约束一律省略,不占用线上字节。
87#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
88pub struct FormFieldValidationSchema {
89    /// 字符最小长度。
90    #[serde(skip_serializing_if = "Option::is_none")]
91    pub min_length: Option<usize>,
92    /// 字符最大长度。
93    #[serde(skip_serializing_if = "Option::is_none")]
94    pub max_length: Option<usize>,
95    /// 数值下限,十进制文本,避免浮点漂移。
96    #[serde(skip_serializing_if = "Option::is_none")]
97    pub minimum: Option<String>,
98    /// 数值上限,十进制文本,避免浮点漂移。
99    #[serde(skip_serializing_if = "Option::is_none")]
100    pub maximum: Option<String>,
101    /// 可选正则表达式。
102    #[serde(skip_serializing_if = "Option::is_none")]
103    pub pattern: Option<String>,
104}
105
106impl FormFieldValidationSchema {
107    /// 从字段定义投影校验提示;字段未声明任何约束时返回 `None`。
108    pub(crate) fn from_spec(spec: &crate::definition::ValidationSpec) -> Option<Self> {
109        if spec.min_length.is_none()
110            && spec.max_length.is_none()
111            && spec.minimum.is_none()
112            && spec.maximum.is_none()
113            && spec.pattern.is_none()
114        {
115            return None;
116        }
117        Some(Self {
118            min_length: spec.min_length,
119            max_length: spec.max_length,
120            minimum: spec.minimum.clone(),
121            maximum: spec.maximum.clone(),
122            pattern: spec.pattern.clone(),
123        })
124    }
125}
126
127/// 通用表单的单字段契约。
128#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
129pub struct FormFieldSchema {
130    /// 提交数据中的字段名。
131    pub field: String,
132    /// 用户可见标题。
133    pub title: String,
134    /// 字段帮助说明。
135    pub description: String,
136    /// 建议输入控件。
137    pub widget: WidgetHint,
138    /// 当前表单中是否必填。
139    pub required: bool,
140    /// 当前用户只能查看,不能提交修改。
141    pub read_only: bool,
142    /// 字段只允许提交,前端不得从详情数据预填。
143    pub write_only: bool,
144    /// 当前请求有权调用的关系 options 契约。
145    #[serde(skip_serializing_if = "Option::is_none")]
146    pub relation: Option<RelationOptionsSchema>,
147    /// 服务端声明的输入校验提示;随字段权限一并过滤,未声明约束时省略。
148    #[serde(skip_serializing_if = "Option::is_none")]
149    pub validation: Option<FormFieldValidationSchema>,
150}
151
152/// 请求级通用表单契约。
153#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
154pub struct FormSchema {
155    /// 按 View 定义顺序排列的字段。
156    pub fields: Vec<FormFieldSchema>,
157}
158
159/// 请求级通用树 View 拓扑契约。
160#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
161pub struct TreeViewSchema {
162    /// 节点唯一标识字段。
163    pub id_field: String,
164    /// 父节点标识字段;根节点应返回 null。
165    pub parent_field: String,
166    /// 节点用户可见标签字段。
167    pub label_field: String,
168    /// 服务端强制执行的单次树查询节点上限。
169    pub max_nodes: usize,
170}
171
172/// 请求级通用表格 View 契约。
173#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
174pub struct TableViewSchema {
175    /// 稳定 View ID,不与前端文件路径绑定。
176    pub view_id: String,
177    /// 用户可见标题。
178    pub title: String,
179    /// 表所属逻辑数据源;与 `table` 一起唯一标识物理表。
180    pub datasource: String,
181    /// 服务端表定义名。
182    pub table: String,
183    /// 返回标准分页行数据的 Action operation ID。
184    pub data_action: String,
185    /// 当前用户可读的有序列。
186    pub columns: Vec<TableColumnSchema>,
187    /// 当前用户可读或可写的通用表单字段。
188    pub form: FormSchema,
189    /// 可选树拓扑;所需字段不可读时省略并安全降级为普通表格。
190    #[serde(skip_serializing_if = "Option::is_none")]
191    pub tree: Option<TreeViewSchema>,
192    /// 搜索、筛选、默认排序和分页能力。
193    pub query: TableQuerySchema,
194    /// 当前用户可调用的有序 Action operation IDs。
195    pub actions: Vec<String>,
196    /// 当前用户可调用 Action 的声明式展示语义。
197    pub action_presentations: Vec<super::action::ActionPresentationSchema>,
198}