Merge branch 'development_add_incremental_mode_to_heromodels'

heromodels_core/src/lib.rs

@@ -64,15 +64,6 @@ pub trait Model:
     /// Get a mutable reference to the base_data field
     fn base_data_mut(&mut self) -> &mut BaseModelData;
 
-    /// Set the ID for this model
-    fn id(mut self, id: u32) -> Self
-    where
-        Self: Sized,
-    {
-        self.base_data_mut().id = id;
-        self
-    }
-
     /// Build the model, updating the modified timestamp
     fn build(mut self) -> Self
     where
@@ -95,9 +86,47 @@ pub trait Index {
 }
 
 /// Base struct that all models should include
+///
+/// # ID Management
+///
+/// The `id` field is managed automatically by OurDB when using incremental mode:
+///
+/// 1. When creating a new model, the `id` field is initialized to 0.
+/// 2. When saving the model to the database with `set()`, OurDB will:
+///    - If the ID is 0, auto-generate a new ID and update the model.
+///    - If the ID is not 0, use the provided ID for updates.
+///
+/// # Important Notes
+///
+/// - Never manually set the `id` field to a specific value. Always use 0 for new models.
+/// - The ID 0 is reserved for new models and should not be used for existing models.
+/// - After saving a model, use the ID returned by `set()` to retrieve the model from the database.
+/// - The original model passed to `set()` is not modified; you need to retrieve the updated model.
+///
+/// # Example
+///
+/// ```rust
+/// // Create a new model with ID 0
+/// let user = User::new()
+///     .username("johndoe")
+///     .email("john.doe@example.com")
+///     .build();
+///
+/// // Save the model and get the assigned ID
+/// let user_id = db.collection().set(&user).expect("Failed to save user");
+///
+/// // Retrieve the model with the assigned ID
+/// let db_user = db.collection().get_by_id(user_id).expect("Failed to get user");
+/// ```
 #[derive(Debug, Serialize, Deserialize, PartialEq, Clone)]
 pub struct BaseModelData {
-    /// Unique incremental ID per circle
+    /// Unique incremental ID - will be auto-generated by OurDB
+    ///
+    /// This field is automatically managed by OurDB:
+    /// - For new models, set this to 0 and OurDB will auto-generate an ID.
+    /// - For existing models, this will be the ID assigned by OurDB.
+    ///
+    /// Do not manually set this field to a specific value.
     pub id: u32,
 
     /// Unix epoch timestamp for creation time
@@ -111,11 +140,12 @@ pub struct BaseModelData {
 }
 
 impl BaseModelData {
-    /// Create a new BaseModelData instance
-    pub fn new(id: u32) -> Self {
+    /// Create a new BaseModelData instance with ID set to 0
+    /// The ID will be auto-generated by OurDB when the model is saved
+    pub fn new() -> Self {
         let now = chrono::Utc::now().timestamp();
         Self {
-            id,
+            id: 0, // This will be replaced by OurDB with an auto-generated ID
             created_at: now,
             modified_at: now,
             comments: Vec::new(),
@@ -123,8 +153,8 @@ impl BaseModelData {
     }
 
     /// Create a new BaseModelDataBuilder
-    pub fn builder(id: u32) -> BaseModelDataBuilder {
-        BaseModelDataBuilder::new(id)
+    pub fn builder() -> BaseModelDataBuilder {
+        BaseModelDataBuilder::new()
     }
 
     /// Add a comment to this model
@@ -143,6 +173,11 @@ impl BaseModelData {
     pub fn update_modified(&mut self) {
         self.modified_at = chrono::Utc::now().timestamp();
     }
+
+    /// Update the ID of this model
+    pub fn update_id(&mut self, id: u32) {
+        self.id = id;
+    }
 }
 
 pub mod base_data_builder;
@@ -150,7 +185,6 @@ pub use base_data_builder::BaseModelDataOps;
 
 /// Builder for BaseModelData
 pub struct BaseModelDataBuilder {
-    id: u32,
     created_at: Option<i64>,
     modified_at: Option<i64>,
     comments: Vec<u32>,
@@ -158,9 +192,8 @@ pub struct BaseModelDataBuilder {
 
 impl BaseModelDataBuilder {
     /// Create a new BaseModelDataBuilder
-    pub fn new(id: u32) -> Self {
+    pub fn new() -> Self {
         Self {
-            id,
             created_at: None,
             modified_at: None,
             comments: Vec::new(),
@@ -195,7 +228,7 @@ impl BaseModelDataBuilder {
     pub fn build(self) -> BaseModelData {
         let now = chrono::Utc::now().timestamp();
         BaseModelData {
-            id: self.id,
+            id: 0, // This will be replaced by OurDB with an auto-generated ID
             created_at: self.created_at.unwrap_or(now),
             modified_at: self.modified_at.unwrap_or(now),
             comments: self.comments,