Skip to main content

yang_base/table/
relation_options.rs

1//! 关系选择器的稳定请求/响应 DTO。
2
3use super::MAX_QUERY_PAGE_SIZE;
4use crate::definition::{ParamInput, Params};
5use crate::error::BaseError;
6use schemars::JsonSchema;
7use serde::{Deserialize, Serialize};
8use serde_json::Value;
9use std::collections::BTreeMap;
10
11const DEFAULT_OPTIONS_LIMIT: usize = 20;
12const MAX_SEARCH_CHARS: usize = 200;
13const MAX_SELECTED_VALUES: usize = 100;
14const MAX_FILTER_FIELDS: usize = 20;
15
16/// 关系选项请求。
17///
18/// `filter` 只表示字段到值的声明式精确筛选;执行器仍必须按目标表字段白名单、当前
19/// 用户权限和租户范围逐项校验,不能把字段名直接拼接进 SQL。
20#[derive(Debug, Clone, PartialEq, Deserialize, JsonSchema)]
21#[serde(default, deny_unknown_fields)]
22pub struct RelationOptionsRequest {
23    /// 模糊搜索文本。
24    pub search: Option<String>,
25    /// 需要回填的已选主键;即使不在当前搜索页也应返回。
26    pub selected: Vec<Value>,
27    /// 声明式精确筛选字段。
28    pub filter: BTreeMap<String, Value>,
29    /// 从 1 开始的页码。
30    pub page: usize,
31    /// 每页数量,上限与通用查询一致。
32    pub limit: usize,
33}
34
35impl Default for RelationOptionsRequest {
36    fn default() -> Self {
37        Self {
38            search: None,
39            selected: Vec::new(),
40            filter: BTreeMap::new(),
41            page: 1,
42            limit: DEFAULT_OPTIONS_LIMIT,
43        }
44    }
45}
46
47impl ParamInput for RelationOptionsRequest {
48    fn params() -> Params {
49        Params::new()
50    }
51
52    /// 反序列化后立即执行边界校验:select Action 经 `Action::Input` 解码时 fail-closed,
53    /// handler 不再依赖显式调用 [`RelationOptionsRequest::validate`] 才能守住传输边界。
54    fn decode(request: &mut crate::action::Request) -> Result<Self, BaseError> {
55        let input: Self = serde_json::from_value(std::mem::take(&mut request.body))
56            .map_err(|error| BaseError::ParamInvalid("input".into(), error.to_string()))?;
57        input.validate()?;
58        Ok(input)
59    }
60}
61
62impl RelationOptionsRequest {
63    /// 校验传输层通用边界。
64    ///
65    /// 字段存在性、可筛选权限和租户隔离属于执行器职责,不能由本 DTO 绕过。
66    pub fn validate(&self) -> Result<(), BaseError> {
67        if self.page == 0 {
68            return Err(BaseError::ParamInvalid(
69                "page".to_string(),
70                "页码必须从 1 开始".to_string(),
71            ));
72        }
73        if self.limit == 0 || self.limit > MAX_QUERY_PAGE_SIZE {
74            return Err(BaseError::ParamInvalid(
75                "limit".to_string(),
76                format!("每页数量必须在 1..={MAX_QUERY_PAGE_SIZE} 范围内"),
77            ));
78        }
79        if self
80            .search
81            .as_ref()
82            .is_some_and(|search| search.chars().count() > MAX_SEARCH_CHARS)
83        {
84            return Err(BaseError::ParamInvalid(
85                "search".to_string(),
86                format!("搜索文本不能超过 {MAX_SEARCH_CHARS} 个字符"),
87            ));
88        }
89        if self.selected.len() > MAX_SELECTED_VALUES {
90            return Err(BaseError::ParamInvalid(
91                "selected".to_string(),
92                format!("已选值不能超过 {MAX_SELECTED_VALUES} 个"),
93            ));
94        }
95        if self
96            .selected
97            .iter()
98            .any(|value| !matches!(value, Value::String(_) | Value::Number(_)))
99        {
100            return Err(BaseError::ParamInvalid(
101                "selected".to_string(),
102                "已选值只允许字符串或数字主键".to_string(),
103            ));
104        }
105        if self.filter.len() > MAX_FILTER_FIELDS {
106            return Err(BaseError::ParamInvalid(
107                "filter".to_string(),
108                format!("筛选字段不能超过 {MAX_FILTER_FIELDS} 个"),
109            ));
110        }
111        if self
112            .filter
113            .keys()
114            .any(|field| field.trim().is_empty() || field.len() > 128)
115        {
116            return Err(BaseError::ParamInvalid(
117                "filter".to_string(),
118                "筛选字段名不能为空且不能超过 128 字节".to_string(),
119            ));
120        }
121        Ok(())
122    }
123}
124
125/// 单个关系选项的稳定 `{value,label}` 形状。
126#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
127pub struct RelationOption {
128    /// 真实主键值。
129    pub value: Value,
130    /// 用户可见标签。
131    pub label: String,
132}
133
134/// 分页关系选项响应。
135#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
136pub struct RelationOptionsResponse {
137    /// 当前页选项;回填项可由执行器合并并去重。
138    pub items: Vec<RelationOption>,
139    /// 当前页码。
140    pub page: usize,
141    /// 实际每页数量。
142    pub limit: usize,
143    /// 可选总数;执行器不做 count 时为 `None`。
144    pub total: Option<u64>,
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150    use crate::action::Request;
151    use serde_json::json;
152
153    #[test]
154    fn defaults_and_wire_shape_are_stable() {
155        let request: RelationOptionsRequest =
156            serde_json::from_value(json!({})).expect("空请求应应用稳定默认值");
157        assert_eq!(request.page, 1);
158        assert_eq!(request.limit, DEFAULT_OPTIONS_LIMIT);
159        request.validate().expect("默认请求应有效");
160
161        let response = RelationOptionsResponse {
162            items: vec![RelationOption {
163                value: json!(7),
164                label: "Alice".to_string(),
165            }],
166            page: 1,
167            limit: 20,
168            total: Some(1),
169        };
170        assert_eq!(
171            serde_json::to_value(response).expect("响应应可序列化"),
172            json!({
173                "items": [{"value": 7, "label": "Alice"}],
174                "page": 1,
175                "limit": 20,
176                "total": 1
177            })
178        );
179    }
180
181    #[test]
182    fn selected_supports_string_and_number_ids_but_rejects_structured_values() {
183        let valid: RelationOptionsRequest = serde_json::from_value(json!({
184            "selected": [7, "user-8"]
185        }))
186        .expect("字符串和数字主键应可解析");
187        valid.validate().expect("字符串和数字主键应有效");
188
189        for selected in [
190            json!([null]),
191            json!([true]),
192            json!([[1]]),
193            json!([{"id": 1}]),
194        ] {
195            let request: RelationOptionsRequest = serde_json::from_value(json!({
196                "selected": selected
197            }))
198            .expect("结构化值应在显式验证阶段拒绝");
199            assert!(matches!(
200                request.validate(),
201                Err(BaseError::ParamInvalid(field, _)) if field == "selected"
202            ));
203        }
204    }
205
206    #[test]
207    fn pagination_search_and_filter_are_bounded() {
208        let cases = [
209            ("page", json!({"page": 0})),
210            ("limit", json!({"limit": 0})),
211            ("limit", json!({"limit": MAX_QUERY_PAGE_SIZE + 1})),
212            (
213                "search",
214                json!({"search": "x".repeat(MAX_SEARCH_CHARS + 1)}),
215            ),
216            ("filter", json!({"filter": {"": 1}})),
217        ];
218        for (expected, value) in cases {
219            let request: RelationOptionsRequest =
220                serde_json::from_value(value).expect("边界请求应在验证阶段处理");
221            assert!(matches!(
222                request.validate(),
223                Err(BaseError::ParamInvalid(field, _)) if field == expected
224            ));
225        }
226
227        let unknown = serde_json::from_value::<RelationOptionsRequest>(json!({"offset": 0}));
228        assert!(unknown.is_err(), "未知字段不得被静默忽略");
229    }
230
231    #[test]
232    fn request_is_directly_decodable_as_action_body_input() {
233        let mut request = Request::new(json!({
234            "search": "alice",
235            "selected": [7],
236            "filter": {"status": "active"},
237            "page": 2,
238            "limit": 30
239        }));
240
241        let input = <RelationOptionsRequest as ParamInput>::decode(&mut request)
242            .expect("关系选项 DTO 应可直接作为 Action body 输入");
243        input.validate().expect("合法请求应通过边界校验");
244        assert_eq!(input.search.as_deref(), Some("alice"));
245        assert_eq!(input.selected, vec![json!(7)]);
246        assert_eq!(input.page, 2);
247        assert_eq!(input.limit, 30);
248        assert!(request.body.is_null(), "输入解码后 body 应被一次性消费");
249    }
250
251    #[test]
252    fn decode_rejects_over_limit_body_without_manual_validate() {
253        // I-4:validate 必须在 decode 默认路径上 fail-closed,handler 忘调 validate
254        // 也不能放行超限输入。
255        let mut request = Request::new(json!({"limit": MAX_QUERY_PAGE_SIZE + 1}));
256        let error = <RelationOptionsRequest as ParamInput>::decode(&mut request)
257            .expect_err("超限 body 必须在 decode 阶段直接拒绝");
258        assert!(
259            matches!(&error, BaseError::ParamInvalid(field, _) if field == "limit"),
260            "拒绝原因必须指向 limit 边界: {error}"
261        );
262
263        let mut request = Request::new(json!({"page": 0}));
264        let error = <RelationOptionsRequest as ParamInput>::decode(&mut request)
265            .expect_err("非法页码必须在 decode 阶段直接拒绝");
266        assert!(
267            matches!(&error, BaseError::ParamInvalid(field, _) if field == "page"),
268            "拒绝原因必须指向 page 边界: {error}"
269        );
270    }
271}