rating.rs (2641B)
1 //! Product rating models 2 //! 3 //! This module defines the data structures for product ratings and reviews. 4 //! Ratings are enforced at 1 rating per user per product via database constraints. 5 6 use chrono::{DateTime, Utc}; 7 use serde::{Deserialize, Serialize}; 8 use sqlx::FromRow; 9 use uuid::Uuid; 10 11 /// Product rating entity stored in the database 12 /// 13 /// # Database Constraints 14 /// - One user can only have one rating per product (unique constraint on product_id + user_id) 15 /// - Rating value must be between 1 and 5 16 /// - User must exist in the users table (foreign key constraint) 17 /// - Product must exist in the products table (foreign key constraint) 18 /// 19 /// # Update Behavior 20 /// When a user rates the same product again, the existing rating is updated 21 /// and the `updated_at` timestamp is refreshed. 22 #[derive(Debug, Clone, Serialize, Deserialize, FromRow)] 23 pub struct Rating { 24 /// Internal database ID 25 pub id: i32, 26 27 /// External UUID identifier 28 pub uuid: Uuid, 29 30 /// Reference to the product being rated 31 pub product_id: i32, 32 33 /// UUID of the user who created this rating 34 pub user_id: Uuid, 35 36 /// Rating value (1-5 stars) 37 pub rating: i32, 38 39 /// Optional text review/comment 40 pub review: Option<String>, 41 42 /// When the rating was first created 43 pub created_at: DateTime<Utc>, 44 45 /// When the rating was last updated 46 /// If equal to created_at, the rating has never been modified 47 pub updated_at: DateTime<Utc>, 48 } 49 50 /// Request body for creating or updating a product rating 51 /// 52 /// # Validation 53 /// - `rating` must be between 1 and 5 (validated in handler) 54 /// - `user_id` must reference an existing user 55 /// - `review` is optional but can contain user's comments 56 /// 57 /// # Example JSON 58 /// ```json 59 /// { 60 /// "user_id": "123e4567-e89b-12d3-a456-426614174000", 61 /// "rating": 5, 62 /// "review": "Excellent product! Highly recommend." 63 /// } 64 /// ``` 65 #[derive(Debug, Deserialize)] 66 pub struct UpsertRatingRequest { 67 /// UUID of the user creating/updating the rating 68 pub user_id: Uuid, 69 70 /// Star rating (1-5) 71 /// 1 = Poor, 2 = Fair, 3 = Good, 4 = Very Good, 5 = Excellent 72 pub rating: i32, 73 74 /// Optional text review 75 pub review: Option<String>, 76 } 77 78 /// Response after successfully creating or updating a rating 79 /// 80 /// Includes the complete rating object and a message indicating 81 /// whether it was created or updated. 82 #[derive(Debug, Serialize)] 83 pub struct RatingResponse { 84 /// The created or updated rating 85 pub rating: Rating, 86 87 /// Human-readable message ("Rating created successfully" or "Rating updated successfully") 88 pub message: String, 89 }