update database
This commit is contained in:
Phuoc Nguyen
423
HIVE_MODELS_REFERENCE.md
Normal file
423
HIVE_MODELS_REFERENCE.md
Normal file
@@ -0,0 +1,423 @@
|
||||
# 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:
|
||||
|
||||
```dart
|
||||
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`:
|
||||
|
||||
```dart
|
||||
// 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`:
|
||||
|
||||
```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:
|
||||
|
||||
```dart
|
||||
// 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:
|
||||
|
||||
```dart
|
||||
// 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:
|
||||
|
||||
```dart
|
||||
// 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```dart
|
||||
// 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
|
||||
Reference in New Issue
Block a user