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        let resp = Transport::request(req, &self.config, Some(option)).await?;
119        resp.data
120            .ok_or_else(|| openlark_core::error::validation_error("Operation", "响应数据为空"))
121    }
122}
123
124/// 查询请求
125#[derive(Debug, Clone, Deserialize, Serialize)]
126struct UserTaskQueryRequest {
127    /// 任务状态列表
128    #[serde(rename = "statuses", skip_serializing_if = "Vec::is_empty")]
129    statuses: Vec<String>,
130    /// 开始时间
131    #[serde(rename = "start_time", skip_serializing_if = "Option::is_none")]
132    start_time: Option<i64>,
133    /// 结束时间
134    #[serde(rename = "end_time", skip_serializing_if = "Option::is_none")]
135    end_time: Option<i64>,
136    /// 页码
137    #[serde(rename = "page", skip_serializing_if = "Option::is_none")]
138    page: Option<u32>,
139    /// 每页数量
140    #[serde(rename = "page_size", skip_serializing_if = "Option::is_none")]
141    page_size: Option<u32>,
142    /// 用户 ID 列表
143    #[serde(rename = "user_ids", skip_serializing_if = "Vec::is_empty")]
144    user_ids: Vec<String>,
145}
146
147/// 任务信息
148#[derive(Debug, Clone, Deserialize, Serialize)]
149pub struct TaskInfo {
150    /// 任务 ID
151    #[serde(rename = "task_id")]
152    task_id: String,
153    /// 任务标题
154    #[serde(rename = "title")]
155    title: String,
156    /// 任务状态
157    #[serde(rename = "status")]
158    status: String,
159    /// 发起人 ID
160    #[serde(rename = "initiator_id")]
161    initiator_id: String,
162    /// 创建时间
163    #[serde(rename = "created_at")]
164    created_at: i64,
165    /// 更新时间
166    #[serde(rename = "updated_at")]
167    updated_at: i64,
168}
169
170/// 查询响应
171#[derive(Debug, Clone, Deserialize, Serialize)]
172pub struct UserTaskQueryResponse {
173    /// 任务列表
174    #[serde(rename = "tasks")]
175    pub tasks: Vec<TaskInfo>,
176    /// 是否有更多
177    #[serde(rename = "has_more")]
178    pub has_more: bool,
179    /// 页码
180    #[serde(rename = "page")]
181    pub page: u32,
182    /// 每页数量
183    #[serde(rename = "page_size")]
184    pub page_size: u32,
185    /// 总数
186    #[serde(rename = "total_count")]
187    pub total_count: u32,
188}
189
190impl ApiResponseTrait for UserTaskQueryResponse {
191    fn data_format() -> ResponseFormat {
192        ResponseFormat::Data
193    }
194}
195
196/// 旧名兼容别名（将在 v1.0 移除）
197#[deprecated(note = "renamed to UserTaskQueryRequestBuilder, will be removed in v1.0 (#271)")]
198pub type UserTaskQueryBuilder = UserTaskQueryRequestBuilder;
199
200#[cfg(test)]
201mod tests {
202    use super::*;
203
204    /// 端到端：POST .../user_task/query → 强类型 UserTaskQueryResponse。
205    #[tokio::test]
206    async fn test_query_user_task_returns_data_on_success() {
207        use serde_json::json;
208        use wiremock::MockServer;
209        use wiremock::matchers::{method, path};
210        use wiremock::{Mock, ResponseTemplate};
211
212        let server = MockServer::start().await;
213        Mock::given(method("POST"))
214            .and(path("/open-apis/apaas/v1/user_task/query"))
215            .respond_with(ResponseTemplate::new(200).set_body_json(json!({
216                "code": 0,
217                "msg": "success",
218                "data": {
219                    "tasks": [
220                        {
221                            "task_id": "task_001",
222                            "title": "待审批",
223                            "status": "PENDING",
224                            "initiator_id": "u_001",
225                            "created_at": 1717000000_i64,
226                            "updated_at": 1717000100_i64
227                        }
228                    ],
229                    "has_more": false,
230                    "page": 1,
231                    "page_size": 10,
232                    "total_count": 1
233                }
234            })))
235            .mount(&server)
236            .await;
237
238        let config = Config::builder()
239            .app_id("ci_app_id")
240            .app_secret("ci_app_secret")
241            .base_url(server.uri())
242            .enable_token_cache(false)
243            .build();
244
245        let resp = UserTaskQueryRequestBuilder::new(config)
246            .status("PENDING")
247            .user_id("u_001")
248            .page(1)
249            .page_size(10)
250            .execute()
251            .await
252            .expect("查询人工任务应成功");
253        assert_eq!(resp.tasks.len(), 1);
254        assert!(!resp.has_more);
255        assert_eq!(resp.page, 1);
256        assert_eq!(resp.total_count, 1);
257
258        let received = server.received_requests().await.unwrap_or_default();
259        assert_eq!(received.len(), 1);
260        assert_eq!(
261            received[0].url.path(),
262            "/open-apis/apaas/v1/user_task/query"
263        );
264    }
265}
openlark_platform/app_engine/apaas/v1/user_task/query.rs

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