# BuyerKiosk Live Data Models

This directory contains Freezed data models for the BuyerKiosk Live Flutter application.

## Structure

```
lib/data/models/
├── buyer_stats_model.dart          # Buyer performance metrics model
├── completed_buy_model.dart        # Completed transaction model
├── queue_item_model.dart           # Buy queue item model
├── shift_note_model.dart           # Shift note/task model with enums
├── store_detail_model.dart         # Detailed store metrics model
├── store_model.dart                # Store dashboard data model
├── models.dart                     # Barrel export file
└── mappers/                        # Model-Entity conversion extensions
    ├── buyer_stats_mapper.dart
    ├── completed_buy_mapper.dart
    ├── queue_item_mapper.dart
    ├── shift_note_mapper.dart
    ├── store_detail_mapper.dart
    └── store_mapper.dart
```

## Usage Examples

### Parsing JSON Response

```dart
import 'package:buyer_kiosk_live/data/models/models.dart';

// Parse a store from JSON
final json = {
  'typeNum': 'PC80000',
  'storeName': 'Portland Store',
  'numBuyers': 5,
  'numSorters': 3,
  'inQueue': 12,
  'salesGoal': 25000.00,
  'salesActual': 18500.50,
  'buysGoal': 150.00,
  'buysActual': 120.00,
  'waitTime': 15,
};

final storeModel = StoreModel.fromJson(json);
```

### Converting Model to Entity

```dart
import 'package:buyer_kiosk_live/data/models/models.dart';

// Convert model to domain entity
final store = storeModel.toEntity();

// Access entity properties and methods
print(store.salesPercentage);  // 74.0
print(store.normalizedTypeNum); // 'PC00' (PC80000 -> PC00)
```

### Converting Entity to Model

```dart
import 'package:buyer_kiosk_live/domain/entities/entities.dart';
import 'package:buyer_kiosk_live/data/models/models.dart';

// Convert entity back to model
final model = store.toModel();

// Serialize to JSON
final json = model.toJson();
```

### Working with Shift Notes

```dart
import 'package:buyer_kiosk_live/data/models/models.dart';

final noteJson = {
  'id': '123',
  'title': 'Check inventory',
  'comment': 'Count bins in section A',
  'type': 'task',
  'status': 'open',
  'priority': 'high',
  'submitter': 'John Doe',
  'startDate': '2025-12-01T08:00:00Z',
  'endDate': '2025-12-01T17:00:00Z',
  'createdAt': '2025-12-01T07:30:00Z',
};

final noteModel = ShiftNoteModel.fromJson(noteJson);
final note = noteModel.toEntity();

// Access entity helper methods
print(note.isTask);           // true
print(note.isOverdue);        // false
print(note.priorityLabel);    // 'High'
print(note.statusLabel);      // 'Open'
```

### Working with Queue Items

```dart
import 'package:buyer_kiosk_live/data/models/models.dart';

final queueJson = {
  'customerName': 'Jane Smith',
  'buyerName': 'Mike Johnson',
  'numContainers': 10,
  'processedContainers': 6,
  'waitTime': 20,
  'inStore': true,
};

final queueItemModel = QueueItemModel.fromJson(queueJson);
final queueItem = queueItemModel.toEntity();

// Access entity helper properties
print(queueItem.progressPercentage);   // 60.0
print(queueItem.remainingContainers);  // 4
print(queueItem.isInProgress);         // true
print(queueItem.isCompleted);          // false
```

## Special Handling

### Store Type Normalization

The `Store` entity includes a `normalizedTypeNum` getter that maps "PC80000" to "PC00" for URL usage, as required by the backend API.

```dart
final store = Store(
  typeNum: 'PC80000',
  // ... other fields
);

// Use normalized version for API calls
final url = 'https://api.example.com/stores/${store.normalizedTypeNum}';
// Results in: https://api.example.com/stores/PC00
```

## Generated Files

The following files are automatically generated by `build_runner`:

- `*.freezed.dart` - Freezed immutable class implementation
- `*.g.dart` - JSON serialization/deserialization code

To regenerate after making changes:

```bash
flutter pub run build_runner build --delete-conflicting-outputs
```

## Model Features

All models include:

- **Immutability** - Using Freezed's `@freezed` annotation
- **JSON Serialization** - Automatic `fromJson` and `toJson` methods
- **Copy With** - Generated `copyWith` method for updates
- **Equality** - Automatic equality comparison
- **toString** - Human-readable string representation

All entities include:

- **Immutability** - Using `const` constructors
- **Equality** - Using Equatable for value comparison
- **Helper Methods** - Business logic and computed properties
- **No Dependencies** - Pure domain objects with no external dependencies