worker/HIVE_MODELS_REFERENCE.md

Hive CE Data Models Reference

This document provides a complete reference for all Hive CE data models in the Worker app, mapped to the database schema.

Summary of Created Models

✅ Completed Models

1. UserModel (lib/features/auth/data/models/user_model.dart) - Type ID: 0
2. UserSessionModel (lib/features/auth/data/models/user_session_model.dart) - Type ID: 1
3. ProductModel (lib/features/products/data/models/product_model.dart) - Type ID: 2
4. StockLevelModel (lib/features/products/data/models/stock_level_model.dart) - Type ID: 3

📋 Models To Be Created

The following model files need to be created following the same pattern:

Cart Models

• lib/features/cart/data/models/cart_model.dart - Type ID: 4
• lib/features/cart/data/models/cart_item_model.dart - Type ID: 5

Order Models

• lib/features/orders/data/models/order_model.dart - Type ID: 6
• lib/features/orders/data/models/order_item_model.dart - Type ID: 7
• lib/features/orders/data/models/invoice_model.dart - Type ID: 8
• lib/features/orders/data/models/payment_line_model.dart - Type ID: 9

Loyalty Models

• lib/features/loyalty/data/models/loyalty_point_entry_model.dart - Type ID: 10
• lib/features/loyalty/data/models/gift_catalog_model.dart - Type ID: 11
• lib/features/loyalty/data/models/redeemed_gift_model.dart - Type ID: 12
• lib/features/loyalty/data/models/points_record_model.dart - Type ID: 13

Project Models

• lib/features/projects/data/models/project_submission_model.dart - Type ID: 14
• lib/features/projects/data/models/design_request_model.dart - Type ID: 15

Quote Models

• lib/features/quotes/data/models/quote_model.dart - Type ID: 16
• lib/features/quotes/data/models/quote_item_model.dart - Type ID: 17

Chat Models

• lib/features/chat/data/models/chat_room_model.dart - Type ID: 18
• lib/features/chat/data/models/message_model.dart - Type ID: 19

Other Models

• lib/features/notifications/data/models/notification_model.dart - Type ID: 20
• lib/features/showrooms/data/models/showroom_model.dart - Type ID: 21
• lib/features/showrooms/data/models/showroom_product_model.dart - Type ID: 22
• lib/features/account/data/models/payment_reminder_model.dart - Type ID: 23
• lib/features/account/data/models/audit_log_model.dart - Type ID: 24

Model Template

Each Hive model should follow this structure:

import 'dart:convert';
import 'package:hive_ce/hive.dart';
import 'package:worker/core/constants/storage_constants.dart';
import 'package:worker/core/database/models/enums.dart'; // If using enums

part 'model_name.g.dart';

/// Model Name
///
/// Hive CE model for caching [entity] data locally.
/// Maps to the '[table_name]' table in the database.
///
/// Type ID: [X]
@HiveType(typeId: HiveTypeIds.modelName)
class ModelName extends HiveObject {
  ModelName({
    required this.id,
    required this.field1,
    this.field2,
    // ... other fields
  });

  /// Primary key
  @HiveField(0)
  final String id;

  /// Field description
  @HiveField(1)
  final String field1;

  /// Optional field description
  @HiveField(2)
  final String? field2;

  // Add @HiveField for each database column with sequential numbering

  // =========================================================================
  // JSON SERIALIZATION
  // =========================================================================

  factory ModelName.fromJson(Map<String, dynamic> json) {
    return ModelName(
      id: json['id'] as String,
      field1: json['field_1'] as String,
      field2: json['field_2'] as String?,
      // Map all fields from JSON (snake_case keys)
    );
  }

  Map<String, dynamic> toJson() {
    return {
      'id': id,
      'field_1': field1,
      'field_2': field2,
      // Map all fields to JSON (snake_case keys)
    };
  }

  // =========================================================================
  // HELPER METHODS
  // =========================================================================

  // Add helper methods for:
  // - Parsing JSONB fields (use jsonEncode/jsonDecode)
  // - Computed properties
  // - Validation checks
  // - Formatting methods

  // =========================================================================
  // COPY WITH
  // =========================================================================

  ModelName copyWith({
    String? id,
    String? field1,
    String? field2,
  }) {
    return ModelName(
      id: id ?? this.id,
      field1: field1 ?? this.field1,
      field2: field2 ?? this.field2,
    );
  }

  @override
  String toString() {
    return 'ModelName(id: $id, field1: $field1)';
  }

  @override
  bool operator ==(Object other) {
    if (identical(this, other)) return true;
    return other is ModelName && other.id == id;
  }

  @override
  int get hashCode => id.hashCode;
}

Important Notes

JSONB Field Handling

For JSONB fields in the database, store as String in Hive using jsonEncode:

// In model:
@HiveField(X)
final String? jsonbField;

// In fromJson:
jsonbField: json['jsonb_field'] != null
    ? jsonEncode(json['jsonb_field'])
    : null,

// In toJson:
'jsonb_field': jsonbField != null ? jsonDecode(jsonbField!) : null,

// Helper method:
Map<String, dynamic>? get jsonbFieldMap {
  if (jsonbField == null) return null;
  try {
    return jsonDecode(jsonbField!) as Map<String, dynamic>;
  } catch (e) {
    return null;
  }
}

Enum Handling

Use the enums defined in lib/core/database/models/enums.dart:

// In model:
@HiveField(X)
final OrderStatus status;

// In fromJson:
status: OrderStatus.values.firstWhere(
  (e) => e.name == (json['status'] as String),
  orElse: () => OrderStatus.pending,
),

// In toJson:
'status': status.name,

DateTime Handling

Hive CE supports DateTime natively:

// In model:
@HiveField(X)
final DateTime createdAt;

@HiveField(Y)
final DateTime? updatedAt;

// In fromJson:
createdAt: DateTime.parse(json['created_at'] as String),
updatedAt: json['updated_at'] != null
    ? DateTime.parse(json['updated_at'] as String)
    : null,

// In toJson:
'created_at': createdAt.toIso8601String(),
'updated_at': updatedAt?.toIso8601String(),

Numeric Fields

Handle numeric precision:

// For numeric(12,2) fields:
@HiveField(X)
final double amount;

// In fromJson:
amount: (json['amount'] as num).toDouble(),

Array Fields (Lists)

For JSONB arrays, store as JSON string:

// In model:
@HiveField(X)
final String? participants; // JSONB array

// Helper:
List<String>? get participantsList {
  if (participants == null) return null;
  try {
    final decoded = jsonDecode(participants!) as List;
    return decoded.map((e) => e.toString()).toList();
  } catch (e) {
    return null;
  }
}

Database Table to Model Mapping

Table Name	Model Name	Type ID	Feature	Status
users	UserModel	0	auth	✅ Created
user_sessions	UserSessionModel	1	auth	✅ Created
products	ProductModel	2	products	✅ Created
stock_levels	StockLevelModel	3	products	✅ Created
carts	CartModel	4	cart	📋 To Do
cart_items	CartItemModel	5	cart	📋 To Do
orders	OrderModel	6	orders	📋 To Do
order_items	OrderItemModel	7	orders	📋 To Do
invoices	InvoiceModel	8	orders	📋 To Do
payment_lines	PaymentLineModel	9	orders	📋 To Do
loyalty_point_entries	LoyaltyPointEntryModel	10	loyalty	📋 To Do
gift_catalog	GiftCatalogModel	11	loyalty	📋 To Do
redeemed_gifts	RedeemedGiftModel	12	loyalty	📋 To Do
points_records	PointsRecordModel	13	loyalty	📋 To Do
project_submissions	ProjectSubmissionModel	14	projects	📋 To Do
design_requests	DesignRequestModel	15	projects	📋 To Do
quotes	QuoteModel	16	quotes	📋 To Do
quote_items	QuoteItemModel	17	quotes	📋 To Do
chat_rooms	ChatRoomModel	18	chat	📋 To Do
chat_messages	MessageModel	19	chat	📋 To Do
notifications	NotificationModel	20	notifications	📋 To Do
showrooms	ShowroomModel	21	showrooms	📋 To Do
showroom_products	ShowroomProductModel	22	showrooms	📋 To Do
payment_reminders	PaymentReminderModel	23	account	📋 To Do
audit_logs	AuditLogModel	24	account	📋 To Do

Enum Type IDs (30-59)

All enum types are defined in lib/core/database/models/enums.dart:

Enum Name	Type ID	Values
UserRole	30	customer, distributor, admin, staff
UserStatus	31	active, inactive, suspended, pending
LoyaltyTier	32	bronze, silver, gold, platinum, diamond, titan
OrderStatus	33	draft, pending, confirmed, processing, shipped, delivered, completed, cancelled, refunded
InvoiceType	34	sales, proforma, creditNote, debitNote
InvoiceStatus	35	draft, issued, partiallyPaid, paid, overdue, cancelled, refunded
PaymentMethod	36	cash, bankTransfer, creditCard, debitCard, eWallet, cheque, creditTerm
PaymentStatus	37	pending, processing, completed, failed, refunded, cancelled
EntryType	38	earn, redeem, adjustment, expiry, refund
EntrySource	39	purchase, referral, promotion, bonus, giftRedemption, projectSubmission, pointsRecord, manualAdjustment
ComplaintStatus	40	none, pending, investigating, resolved, rejected
GiftCategory	41	voucher, product, service, discount, experience
GiftStatus	42	active, used, expired, cancelled
PointsStatus	43	pending, approved, rejected
ProjectType	44	residential, commercial, industrial, infrastructure, renovation, interior, exterior
SubmissionStatus	45	pending, reviewing, approved, rejected, needsRevision
DesignStatus	46	pending, assigned, inProgress, reviewing, completed, cancelled, onHold
QuoteStatus	47	draft, sent, viewed, accepted, rejected, expired, converted, cancelled
RoomType	48	support, sales, orderInquiry, quoteDiscussion, general
ContentType	49	text, image, file, video, audio, productReference, orderReference, quoteReference
ReminderType	50	beforeDue, dueDate, overdue, final

Code Generation

After creating all models, run the Hive code generator:

# Generate adapter files for all models
dart run build_runner build --delete-conflicting-outputs

# OR watch for changes
dart run build_runner watch --delete-conflicting-outputs

This will generate .g.dart files for all models with the @HiveType annotation.

Hive Box Registration

Register all type adapters in the main initialization:

// In lib/core/database/hive_service.dart or similar

Future<void> initializeHive() async {
  await Hive.initFlutter();

  // Register enum adapters
  Hive.registerAdapter(UserRoleAdapter());
  Hive.registerAdapter(UserStatusAdapter());
  Hive.registerAdapter(LoyaltyTierAdapter());
  Hive.registerAdapter(OrderStatusAdapter());
  // ... register all enum adapters

  // Register model adapters
  Hive.registerAdapter(UserModelAdapter());
  Hive.registerAdapter(UserSessionModelAdapter());
  Hive.registerAdapter(ProductModelAdapter());
  Hive.registerAdapter(StockLevelModelAdapter());
  // ... register all model adapters

  // Open boxes
  await Hive.openBox(HiveBoxNames.userBox);
  await Hive.openBox(HiveBoxNames.productBox);
  await Hive.openBox(HiveBoxNames.cartBox);
  // ... open all boxes
}

Next Steps

1. Create all remaining model files following the template above
2. Ensure all typeIds are unique and match HiveTypeIds constants
3. Run code generation: dart run build_runner build --delete-conflicting-outputs
4. Register all adapters in Hive initialization
5. Test model serialization/deserialization
6. Create datasource implementations to use these models

File Paths Reference

lib/features/
├── auth/data/models/
│   ├── user_model.dart ✅
│   └── user_session_model.dart ✅
├── products/data/models/
│   ├── product_model.dart ✅
│   └── stock_level_model.dart ✅
├── cart/data/models/
│   ├── cart_model.dart 📋
│   └── cart_item_model.dart 📋
├── orders/data/models/
│   ├── order_model.dart 📋
│   ├── order_item_model.dart 📋
│   ├── invoice_model.dart 📋
│   └── payment_line_model.dart 📋
├── loyalty/data/models/
│   ├── loyalty_point_entry_model.dart 📋
│   ├── gift_catalog_model.dart 📋
│   ├── redeemed_gift_model.dart 📋
│   └── points_record_model.dart 📋
├── projects/data/models/
│   ├── project_submission_model.dart 📋
│   └── design_request_model.dart 📋
├── quotes/data/models/
│   ├── quote_model.dart 📋
│   └── quote_item_model.dart 📋
├── chat/data/models/
│   ├── chat_room_model.dart 📋
│   └── message_model.dart 📋
├── notifications/data/models/
│   └── notification_model.dart 📋
├── showrooms/data/models/
│   ├── showroom_model.dart 📋
│   └── showroom_product_model.dart 📋
└── account/data/models/
    ├── payment_reminder_model.dart 📋
    └── audit_log_model.dart 📋

---

Legend:

• ✅ Created and complete
• 📋 To be created following the template