feat(recent): add cursor + groupby support

src/application/dtos/recent_dto.rs

@@ -1,10 +1,14 @@
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
-use utoipa::ToSchema;
+use utoipa::{IntoParams, ToSchema};
+use uuid::Uuid;
 
+use super::cursor::{CursorListResponse, CursorQuery, PageCursor};
 use super::display_helpers::{
     category_for, format_file_size, icon_class_for, icon_special_class_for,
 };
+use super::grant_dto::{ResourceContentDto, ResourceTypeDto};
+use crate::domain::services::authorization::ResourceKind;
 
 /// DTO for recent items, enriched with item metadata via SQL JOIN
 /// so the frontend does not need N+1 requests to resolve names/sizes.
@@ -84,3 +88,109 @@ impl RecentItemDto {
         self
     }
 }
+
+// ════════════════════════════════════════════════════════════════════════════
+// Cursor-paginated recent resources  (GET /api/recent/resources)
+// ════════════════════════════════════════════════════════════════════════════
+
+/// Raw row returned by the UNION ALL query for `/api/recent/resources`.
+pub struct RecentResourceRow {
+    pub resource_type: String, // "file" | "folder"
+    pub resource_id: Uuid,
+    pub name: String,
+    pub parent_id: Option<Uuid>,
+    pub mime_type: Option<String>,
+    /// `-1` for folders, actual byte-count for files.
+    pub size: i64,
+    pub resource_created_at: DateTime<Utc>,
+    pub modified_at: DateTime<Utc>,
+    pub owner_id: Uuid,
+    /// `true` when `owner_id == requesting user_id`.
+    pub is_owner: bool,
+    pub accessed_at: DateTime<Utc>,
+    /// Human-readable path. Always populated in the row; the handler clears it
+    /// to `""` when `is_owner` is false.
+    pub path: Option<String>,
+    // Pre-computed sort fields for cursor construction.
+    pub sort_str: Option<String>,
+    pub sort_int: Option<i64>,
+    pub sort_ts: Option<DateTime<Utc>>,
+}
+
+/// Opaque keyset-pagination cursor for `GET /api/recent/resources`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RecentCursor {
+    /// Sort dimension active when this cursor was produced.
+    /// Values: `"accessed_at"` (default), `"name"`, `"type"`, `"modified_at"`, `"size"`, `"owner"`.
+    #[serde(default = "RecentCursor::default_order")]
+    pub order_by: String,
+    /// UUID of the last item on the previous page (tie-breaker).
+    pub resource_id: Uuid,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sort_str: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sort_int: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sort_ts: Option<DateTime<Utc>>,
+    #[serde(default)]
+    pub reverse: bool,
+}
+
+impl RecentCursor {
+    fn default_order() -> String {
+        "accessed_at".to_owned()
+    }
+}
+
+impl PageCursor for RecentCursor {}
+
+/// Query parameters for `GET /api/recent/resources`.
+#[derive(Debug, Deserialize, IntoParams)]
+pub struct RecentResourcesQuery {
+    /// Maximum items per page (1–200, default 50).
+    #[serde(default = "CursorQuery::default_limit")]
+    pub limit: u32,
+    /// Opaque cursor from a previous response. Omit to start from the first page.
+    pub cursor: Option<String>,
+    /// Sort / group-by dimension. Supported: `"accessed_at"` (default), `"name"`,
+    /// `"type"`, `"modified_at"`, `"size"`, `"owner"`.
+    pub order_by: Option<String>,
+    /// Comma-separated resource types to include, e.g. `"file,folder"`.
+    /// Omit to include both.
+    pub resource_types: Option<String>,
+    /// Reverse the sort order. Default `false`.
+    #[serde(default)]
+    pub reverse: bool,
+}
+
+impl RecentResourcesQuery {
+    pub fn limit_clamped(&self) -> usize {
+        self.limit.clamp(1, 200) as usize
+    }
+
+    pub fn decode_cursor(&self) -> Option<RecentCursor> {
+        self.cursor.as_deref().and_then(RecentCursor::decode)
+    }
+
+    /// Returns `None` when `resource_types` is absent (= include all).
+    pub fn resource_kinds(&self) -> Option<Vec<ResourceKind>> {
+        self.resource_types.as_deref().map(|s| {
+            s.split(',')
+                .filter_map(|t| ResourceKind::parse(t.trim()))
+                .collect()
+        })
+    }
+}
+
+/// One item in a `GET /api/recent/resources` page.
+#[derive(Debug, Serialize, ToSchema)]
+pub struct RecentResourceItemDto {
+    pub resource_type: ResourceTypeDto,
+    /// When the resource was last accessed.
+    pub accessed_at: DateTime<Utc>,
+    /// Full resource details — shape determined by `resource_type`.
+    pub resource: ResourceContentDto,
+}
+
+/// Response envelope for `GET /api/recent/resources`.
+pub type RecentResourcesDto = CursorListResponse<RecentResourceItemDto>;