db/herodb/src/models/biz

Business Models

This directory contains the core business models used throughout the application for representing essential business objects like products, sales, and currency.

Overview

The business models are implemented as Rust structs and enums with serialization/deserialization support via Serde. These models implement the SledModel and Storable traits for persistence in the application's database layer.

Model Relationships

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Currency  │◄────┤   Product   │◄────┤  SaleItem   │
└─────────────┘     └─────────────┘     └──────┬──────┘
                          ▲                    │
                          │                    │
                    ┌─────┴──────────┐         │
                    │ProductComponent│         │
                    └────────────────┘         │
                                               ▼
                                        ┌─────────────┐
                                        │    Sale     │
                                        └─────────────┘

Root Objects

• root objects are the one who are stored in the DB
• Root Objects are
  • currency
  • product
  • Sale

Models

Currency (Root Object)

Represents a monetary value with an amount and currency code.

Properties:

• amount: f64 - The monetary amount
• currency_code: String - The currency code (e.g., "USD", "EUR")

Builder:

• CurrencyBuilder - Provides a fluent interface for creating Currency instances

Product

ProductType Enum

Categorizes products:

• Product - Physical product
• Service - Non-physical service

ProductStatus Enum

Tracks product availability:

• Available - Product can be purchased
• Unavailable - Product cannot be purchased

ProductComponent

Represents a component part of a product.

Properties:

• id: u32 - Unique identifier
• name: String - Component name
• description: String - Component description
• quantity: i32 - Number of this component
• created_at: DateTime - Creation timestamp
• updated_at: DateTime - Last update timestamp

Builder:

• ProductComponentBuilder - Provides a fluent interface for creating ProductComponent instances

Product (Root Object)

Represents a product or service offered.

Properties:

• id: u32 - Unique identifier
• name: String - Product name
• description: String - Product description
• price: Currency - Product price
• type_: ProductType - Product or Service
• category: String - Product category
• status: ProductStatus - Available or Unavailable
• created_at: DateTime - Creation timestamp
• updated_at: DateTime - Last update timestamp
• max_amount: u16 - Maximum quantity available
• purchase_till: DateTime - Deadline for purchasing
• active_till: DateTime - When product/service expires
• components: Vec - List of product components

Methods:

• add_component() - Adds a component to this product
• set_purchase_period() - Updates purchase availability timeframe
• set_active_period() - Updates active timeframe
• is_purchasable() - Checks if product is available for purchase
• is_active() - Checks if product is still active

Builder:

• ProductBuilder - Provides a fluent interface for creating Product instances

Database Implementation:

• Implements Storable trait for serialization
• Implements SledModel trait with:
  • get_id() - Returns the ID as a string
  • db_prefix() - Returns "product" as the database prefix

Sale

SaleStatus Enum

Tracks the status of a sale:

• Pending - Sale is in progress
• Completed - Sale has been finalized
• Cancelled - Sale has been cancelled

SaleItem

Represents an item within a sale.

Properties:

• id: u32 - Unique identifier
• sale_id: u32 - Parent sale ID
• product_id: u32 - ID of the product sold
• name: String - Product name at time of sale
• quantity: i32 - Number of items purchased
• unit_price: Currency - Price per unit
• subtotal: Currency - Total price for this item (calculated)
• active_till: DateTime - When item/service expires

Builder:

• SaleItemBuilder - Provides a fluent interface for creating SaleItem instances

Sale (Root Object)

Represents a complete sale transaction.

Properties:

• id: u32 - Unique identifier
• company_id: u32 - ID of the company making the sale
• buyer_name: String - Name of the buyer
• buyer_email: String - Email of the buyer
• total_amount: Currency - Total sale amount
• status: SaleStatus - Current sale status
• sale_date: DateTime - When sale occurred
• created_at: DateTime - Creation timestamp
• updated_at: DateTime - Last update timestamp
• items: Vec - List of items in the sale

Methods:

• add_item() - Adds an item to the sale and updates total
• update_status() - Updates the status of the sale

Builder:

• SaleBuilder - Provides a fluent interface for creating Sale instances

Database Implementation:

• Implements Storable trait for serialization
• Implements SledModel trait with:
  • get_id() - Returns the ID as a string
  • db_prefix() - Returns "sale" as the database prefix

Usage Examples

Creating a Currency

let price = CurrencyBuilder::new()
    .amount(29.99)
    .currency_code("USD")
    .build()
    .expect("Failed to build currency");

Creating a Product

// Create a currency using the builder
let price = CurrencyBuilder::new()
    .amount(29.99)
    .currency_code("USD")
    .build()
    .expect("Failed to build currency");

// Create a component using the builder
let component = ProductComponentBuilder::new()
    .id(1)
    .name("Basic Support")
    .description("24/7 email support")
    .quantity(1)
    .build()
    .expect("Failed to build product component");

// Create a product using the builder
let product = ProductBuilder::new()
    .id(1)
    .name("Premium Service")
    .description("Our premium service offering")
    .price(price)
    .type_(ProductType::Service)
    .category("Services")
    .status(ProductStatus::Available)
    .max_amount(100)
    .validity_days(30)
    .add_component(component)
    .build()
    .expect("Failed to build product");

Creating a Sale

let now = Utc::now();

// Create a currency using the builder
let unit_price = CurrencyBuilder::new()
    .amount(29.99)
    .currency_code("USD")
    .build()
    .expect("Failed to build currency");

// Create a sale item using the builder
let item = SaleItemBuilder::new()
    .id(1)
    .sale_id(1)
    .product_id(1)
    .name("Premium Service")
    .quantity(1)
    .unit_price(unit_price)
    .active_till(now + Duration::days(30))
    .build()
    .expect("Failed to build sale item");

// Create a sale using the builder
let mut sale = SaleBuilder::new()
    .id(1)
    .company_id(101)
    .buyer_name("John Doe")
    .buyer_email("john.doe@example.com")
    .currency_code("USD")
    .status(SaleStatus::Pending)
    .add_item(item)
    .build()
    .expect("Failed to build sale");

// Update the sale status
sale.update_status(SaleStatus::Completed);

Database Operations

The library provides model-specific convenience methods for common database operations:

// Insert a product
db.insert_product(&product).expect("Failed to insert product");

// Retrieve a product by ID
let retrieved_product = db.get_product(1).expect("Failed to retrieve product");

// List all products
let all_products = db.list_products().expect("Failed to list products");

// Delete a product
db.delete_product(1).expect("Failed to delete product");

These methods are available for all root objects:

• insert_product, get_product, delete_product, list_products for Product
• insert_currency, get_currency, delete_currency, list_currencies for Currency
• insert_sale, get_sale, delete_sale, list_sales for Sale