openlark_platform/app_engine/apaas/v1/user_task/
query.rs

1//! 查询人工任务
2//!
3//! 文档: <https://open.feishu.cn/document/apaas-v1/flow/user-task/query>
4//! docPath: <https://open.feishu.cn/document/apaas-v1/flow/user-task/query>
5
6use openlark_core::{
7    SDKResult,
8    api::{ApiRequest, ApiResponseTrait, ResponseFormat},
9    config::Config,
10    http::Transport,
11    req_option::RequestOption,
12};
13use serde::{Deserialize, Serialize};
14
15/// 查询人工任务 Builder
16#[derive(Debug, Clone)]
17pub struct UserTaskQueryRequestBuilder {
18    config: Config,
19    /// 任务状态列表
20    statuses: Vec<String>,
21    /// 开始时间
22    start_time: Option<i64>,
23    /// 结束时间
24    end_time: Option<i64>,
25    /// 页码
26    page: Option<u32>,
27    /// 每页数量
28    page_size: Option<u32>,
29    /// 用户 ID
30    user_ids: Vec<String>,
31}
32
33impl UserTaskQueryRequestBuilder {
34    /// 创建新的 Builder
35    pub fn new(config: Config) -> Self {
36        Self {
37            config,
38            statuses: Vec::new(),
39            start_time: None,
40            end_time: None,
41            page: None,
42            page_size: None,
43            user_ids: Vec::new(),
44        }
45    }
46
47    /// 添加任务状态
48    pub fn status(mut self, status: impl Into<String>) -> Self {
49        self.statuses.push(status.into());
50        self
51    }
52
53    /// 添加多个任务状态
54    pub fn statuses(mut self, statuses: impl IntoIterator<Item = impl Into<String>>) -> Self {
55        self.statuses.extend(statuses.into_iter().map(Into::into));
56        self
57    }
58
59    /// 设置开始时间
60    pub fn start_time(mut self, start_time: i64) -> Self {
61        self.start_time = Some(start_time);
62        self
63    }
64
65    /// 设置结束时间
66    pub fn end_time(mut self, end_time: i64) -> Self {
67        self.end_time = Some(end_time);
68        self
69    }
70
71    /// 设置页码
72    pub fn page(mut self, page: u32) -> Self {
73        self.page = Some(page);
74        self
75    }
76
77    /// 设置每页数量
78    pub fn page_size(mut self, page_size: u32) -> Self {
79        self.page_size = Some(page_size);
80        self
81    }
82
83    /// 添加用户 ID
84    pub fn user_id(mut self, user_id: impl Into<String>) -> Self {
85        self.user_ids.push(user_id.into());
86        self
87    }
88
89    /// 添加多个用户 ID
90    pub fn user_ids(mut self, user_ids: impl IntoIterator<Item = impl Into<String>>) -> Self {
91        self.user_ids.extend(user_ids.into_iter().map(Into::into));
92        self
93    }
94
95    /// 执行请求
96    pub async fn execute(self) -> SDKResult<UserTaskQueryResponse> {
97        self.execute_with_options(RequestOption::default()).await
98    }
99
100    /// 使用选项执行请求
101    pub async fn execute_with_options(
102        self,
103        option: RequestOption,
104    ) -> SDKResult<UserTaskQueryResponse> {
105        let url = "/open-apis/apaas/v1/user_task/query".to_string();
106
107        let request = UserTaskQueryRequest {
108            statuses: self.statuses,
109            start_time: self.start_time,
110            end_time: self.end_time,
111            page: self.page,
112            page_size: self.page_size,
113            user_ids: self.user_ids,
114        };
115
116        let req: ApiRequest<UserTaskQueryResponse> =
117            ApiRequest::post(&url).body(serde_json::to_value(&request)?);
118        Transport::request_typed(req, &self.config, Some(option), "Operation").await
119    }
120}
121
122/// 查询请求
123#[derive(Debug, Clone, Deserialize, Serialize)]
124struct UserTaskQueryRequest {
125    /// 任务状态列表
126    #[serde(rename = "statuses", skip_serializing_if = "Vec::is_empty")]
127    statuses: Vec<String>,
128    /// 开始时间
129    #[serde(rename = "start_time", skip_serializing_if = "Option::is_none")]
130    start_time: Option<i64>,
131    /// 结束时间
132    #[serde(rename = "end_time", skip_serializing_if = "Option::is_none")]
133    end_time: Option<i64>,
134    /// 页码
135    #[serde(rename = "page", skip_serializing_if = "Option::is_none")]
136    page: Option<u32>,
137    /// 每页数量
138    #[serde(rename = "page_size", skip_serializing_if = "Option::is_none")]
139    page_size: Option<u32>,
140    /// 用户 ID 列表
141    #[serde(rename = "user_ids", skip_serializing_if = "Vec::is_empty")]
142    user_ids: Vec<String>,
143}
144
145/// 任务信息
146#[derive(Debug, Clone, Deserialize, Serialize)]
147pub struct TaskInfo {
148    /// 任务 ID
149    #[serde(rename = "task_id")]
150    task_id: String,
151    /// 任务标题
152    #[serde(rename = "title")]
153    title: String,
154    /// 任务状态
155    #[serde(rename = "status")]
156    status: String,
157    /// 发起人 ID
158    #[serde(rename = "initiator_id")]
159    initiator_id: String,
160    /// 创建时间
161    #[serde(rename = "created_at")]
162    created_at: i64,
163    /// 更新时间
164    #[serde(rename = "updated_at")]
165    updated_at: i64,
166}
167
168/// 查询响应
169#[derive(Debug, Clone, Deserialize, Serialize)]
170pub struct UserTaskQueryResponse {
171    /// 任务列表
172    #[serde(rename = "tasks")]
173    pub tasks: Vec<TaskInfo>,
174    /// 是否有更多
175    #[serde(rename = "has_more")]
176    pub has_more: bool,
177    /// 页码
178    #[serde(rename = "page")]
179    pub page: u32,
180    /// 每页数量
181    #[serde(rename = "page_size")]
182    pub page_size: u32,
183    /// 总数
184    #[serde(rename = "total_count")]
185    pub total_count: u32,
186}
187
188impl ApiResponseTrait for UserTaskQueryResponse {
189    fn data_format() -> ResponseFormat {
190        ResponseFormat::Data
191    }
192}
193
194/// 旧名兼容别名（将在 v1.0 移除）
195#[deprecated(note = "renamed to UserTaskQueryRequestBuilder, will be removed in v1.0 (#271)")]
196pub type UserTaskQueryBuilder = UserTaskQueryRequestBuilder;
197
198#[cfg(test)]
199mod tests {
200    use super::*;
201
202    /// 端到端：POST .../user_task/query → 强类型 UserTaskQueryResponse。
203    #[tokio::test]
204    async fn test_query_user_task_returns_data_on_success() {
205        use serde_json::json;
206        use wiremock::MockServer;
207        use wiremock::matchers::{method, path};
208        use wiremock::{Mock, ResponseTemplate};
209
210        let server = MockServer::start().await;
211        Mock::given(method("POST"))
212            .and(path("/open-apis/apaas/v1/user_task/query"))
213            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
214                "code": 0,
215                "msg": "success",
216                "data": {
217                    "tasks": [
218                        {
219                            "task_id": "task_001",
220                            "title": "待审批",
221                            "status": "PENDING",
222                            "initiator_id": "u_001",
223                            "created_at": 1717000000_i64,
224                            "updated_at": 1717000100_i64
225                        }
226                    ],
227                    "has_more": false,
228                    "page": 1,
229                    "page_size": 10,
230                    "total_count": 1
231                }
232            })))
233            .mount(&server)
234            .await;
235
236        let config = Config::builder()
237            .app_id("ci_app_id")
238            .app_secret("ci_app_secret")
239            .base_url(server.uri())
240            .enable_token_cache(false)
241            .build();
242
243        let resp = UserTaskQueryRequestBuilder::new(config)
244            .status("PENDING")
245            .user_id("u_001")
246            .page(1)
247            .page_size(10)
248            .execute()
249            .await
250            .expect("查询人工任务应成功");
251        assert_eq!(resp.tasks.len(), 1);
252        assert!(!resp.has_more);
253        assert_eq!(resp.page, 1);
254        assert_eq!(resp.total_count, 1);
255
256        let received = server.received_requests().await.unwrap_or_default();
257        assert_eq!(received.len(), 1);
258        assert_eq!(
259            received[0].url.path(),
260            "/open-apis/apaas/v1/user_task/query"
261        );
262    }
263}
openlark_platform/app_engine/apaas/v1/user_task/query.rs

openlark_platform/app_engine/apaas/v1/user_task/
query.rs
