1use 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#[derive(Debug, Clone, PartialEq, Deserialize, JsonSchema)]
21#[serde(default, deny_unknown_fields)]
22pub struct RelationOptionsRequest {
23 pub search: Option<String>,
25 pub selected: Vec<Value>,
27 pub filter: BTreeMap<String, Value>,
29 pub page: usize,
31 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 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 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#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
127pub struct RelationOption {
128 pub value: Value,
130 pub label: String,
132}
133
134#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
136pub struct RelationOptionsResponse {
137 pub items: Vec<RelationOption>,
139 pub page: usize,
141 pub limit: usize,
143 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 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}