Files

renolation 7dc66d80fc fix

2025-10-16 17:22:27 +07:00

35 KiB

Raw Blame History

Flutter Retail POS App Expert Guidelines

🎯 App Overview

A Flutter-based Point of Sale (POS) retail application for managing products, categories, inventory, sales transactions, and business analytics with an intuitive tab-based interface and comprehensive inventory management system.

🤖 SUBAGENT DELEGATION SYSTEM 🤖

CRITICAL: BE PROACTIVE WITH SUBAGENTS! YOU HAVE SPECIALIZED EXPERTS AVAILABLE!

🚨 DELEGATION MINDSET

Instead of thinking "I'll handle this myself" Think: "Which specialist is BEST suited for this task?"

📋 AVAILABLE SPECIALISTS

You have access to these expert subagents - USE THEM PROACTIVELY:

MUST BE USED for: Product cards, category grids, cart UI, tab navigation, custom widgets, dashboard charts
Triggers: "create widget", "build UI", "product card", "category grid", "layout", "animation", "chart", "dashboard"

📊 riverpod-expert

MUST BE USED for: Cart state, product selection, category filtering, inventory state, sales state management
Triggers: "state management", "provider", "cart", "async state", "data flow", "sales state", "inventory state"

🗄️ hive-expert

MUST BE USED for: Product storage, category database, sales history, inventory tracking, local cache
Triggers: "database", "cache", "hive", "products", "categories", "persistence", "offline", "inventory"

🌐 api-integration-expert

MUST BE USED for: Product sync, inventory API, order processing, backend integration, CSV import/export
Triggers: "API", "HTTP", "sync", "dio", "REST", "backend", "import", "export"

🏗️ architecture-expert

MUST BE USED for: Feature organization, dependency injection, clean architecture setup
Triggers: "architecture", "structure", "organization", "clean code", "refactor"

⚡ performance-expert

MUST BE USED for: Product image caching, grid scrolling, memory optimization, dashboard performance
Triggers: "performance", "optimization", "memory", "image cache", "slow", "lag", "scroll"

🎯 DELEGATION STRATEGY

BEFORE starting ANY task, ASK YOURSELF:

"Which of my specialists could handle this better?"
"Should I break this into parts for different specialists?"
"Would a specialist complete this faster and better?"

💼 WORK BALANCE RECOMMENDATION:

Simple Tasks (20%): Handle independently - quick fixes, minor updates
Complex Tasks (80%): Delegate to specialists for expert-level results

🔧 HOW TO DELEGATE

# Explicit delegation examples:
> Use the flutter-widget-expert to create the product card widget with price and image
> Have the riverpod-expert design the shopping cart state management
> Ask the hive-expert to create the product and category database schema
> Use the api-integration-expert to implement product sync with backend
> Have the architecture-expert organize the inventory feature structure
> Ask the performance-expert to optimize the product grid scrolling

Flutter Best Practices

Use Flutter 3.x features and Material 3 design
Implement clean architecture with Riverpod for state management
Use Hive CE for local database with online-first strategy (API first, cache fallback)
Follow proper dependency injection with Riverpod providers
Implement proper error handling and user feedback
Follow platform-specific design guidelines
Use proper localization for multi-language support

Retail App Project Structure

lib/
  core/
    constants/
      api_constants.dart          # API endpoints, timeouts
      app_constants.dart          # App config, defaults
      ui_constants.dart           # Spacing, sizes, durations
      storage_constants.dart      # Hive box names, keys
    theme/
      app_theme.dart              # Material 3 theme
      colors.dart                 # Color schemes
      typography.dart             # Text styles
    network/
      dio_client.dart             # HTTP client setup
      api_interceptor.dart        # Auth, logging interceptors
      network_info.dart           # Connectivity status
    errors/
      exceptions.dart             # Custom exceptions
      failures.dart               # Failure classes
    utils/
      formatters.dart             # Price, date formatters
      validators.dart             # Input validation
      extensions.dart             # Dart extensions
      csv_helper.dart             # CSV import/export
    widgets/
      custom_button.dart          # Reusable buttons
      loading_indicator.dart      # Loading states
      error_widget.dart           # Error displays
      empty_state.dart            # Empty list UI
      
  features/
    home/
      data/
        datasources/
          cart_local_datasource.dart
        models/
          cart_item_model.dart
        repositories/
          cart_repository_impl.dart
      domain/
        entities/
          cart_item.dart
        repositories/
          cart_repository.dart
        usecases/
          add_to_cart.dart
          remove_from_cart.dart
          clear_cart.dart
          calculate_total.dart
          apply_discount.dart
      presentation/
        providers/
          cart_provider.dart
          cart_total_provider.dart
          discount_provider.dart
        pages/
          home_page.dart
        widgets/
          product_selector.dart
          cart_item_card.dart
          cart_summary.dart
          checkout_button.dart
          discount_dialog.dart
          
    products/
      data/
        datasources/
          product_remote_datasource.dart
          product_local_datasource.dart
        models/
          product_model.dart
          product_variant_model.dart
          supplier_model.dart
        repositories/
          product_repository_impl.dart
      domain/
        entities/
          product.dart
          product_variant.dart
          supplier.dart
        repositories/
          product_repository.dart
        usecases/
          get_all_products.dart
          get_products_by_category.dart
          search_products.dart
          sync_products.dart
          create_product.dart
          update_product.dart
          delete_product.dart
          manage_variants.dart
          import_products_csv.dart
          export_products_csv.dart
      presentation/
        providers/
          products_provider.dart
          product_search_provider.dart
          product_filter_provider.dart
          product_form_provider.dart
        pages/
          products_page.dart
          product_detail_page.dart
          product_form_page.dart
        widgets:
          product_grid.dart
          product_card.dart
          product_search_bar.dart
          product_filter_chip.dart
          product_form.dart
          variant_list.dart
          
    categories/
      data/
        datasources/
          category_remote_datasource.dart
          category_local_datasource.dart
        models/
          category_model.dart
          tag_model.dart
        repositories/
          category_repository_impl.dart
      domain/
        entities/
          category.dart
          tag.dart
        repositories/
          category_repository.dart
        usecases:
          get_all_categories.dart
          get_category_by_id.dart
          sync_categories.dart
          create_category.dart
          update_category.dart
          delete_category.dart
          manage_tags.dart
      presentation/
        providers/
          categories_provider.dart
          selected_category_provider.dart
          tags_provider.dart
        pages/
          categories_page.dart
          category_form_page.dart
        widgets/
          category_grid.dart
          category_card.dart
          category_form.dart
          tag_chip.dart
          
    inventory/
      data/
        datasources/
          inventory_local_datasource.dart
        models/
          inventory_alert_model.dart
        repositories/
          inventory_repository_impl.dart
      domain/
        entities/
          inventory_alert.dart
        repositories/
          inventory_repository.dart
        usecases:
          get_low_stock_products.dart
          update_stock_levels.dart
          batch_update_stock.dart
      presentation/
        providers:
          inventory_provider.dart
          stock_alerts_provider.dart
        pages:
          low_stock_alerts_page.dart
        widgets:
          stock_level_indicator.dart
          alert_badge.dart
          batch_update_form.dart
          
    orders/
      data/
        datasources/
          order_local_datasource.dart
        models/
          order_model.dart
          order_item_model.dart
        repositories/
          order_repository_impl.dart
      domain/
        entities:
          order.dart
          order_item.dart
        repositories:
          order_repository.dart
        usecases:
          create_order.dart
          get_order_history.dart
      presentation:
        providers:
          orders_provider.dart
        pages:
          order_history_page.dart
        widgets:
          order_card.dart
          
    dashboard/
      data:
        datasources:
          analytics_local_datasource.dart
        models:
          sales_stats_model.dart
          product_performance_model.dart
        repositories:
          analytics_repository_impl.dart
      domain:
        entities:
          sales_stats.dart
          product_performance.dart
        repositories:
          analytics_repository.dart
        usecases:
          get_daily_revenue.dart
          get_monthly_revenue.dart
          get_best_selling_products.dart
          get_category_performance.dart
      presentation:
        providers:
          dashboard_provider.dart
          revenue_provider.dart
          best_sellers_provider.dart
        pages:
          dashboard_page.dart
        widgets:
          revenue_chart.dart
          sales_summary_card.dart
          best_sellers_list.dart
          category_performance_chart.dart
          
    settings/
      data/
        datasources/
          settings_local_datasource.dart
        models/
          app_settings_model.dart
        repositories/
          settings_repository_impl.dart
      domain/
        entities/
          app_settings.dart
        repositories/
          settings_repository.dart
        usecases:
          get_settings.dart
          update_settings.dart
      presentation/
        providers/
          settings_provider.dart
          theme_provider.dart
        pages/
          settings_page.dart
        widgets/
          settings_section.dart
          theme_selector.dart
          language_selector.dart
          
  shared/
    widgets/
      app_bottom_nav.dart         # Tab navigation
      custom_app_bar.dart         # Reusable app bar
      price_display.dart          # Currency formatting
      stock_badge.dart            # Stock level indicator
      
  main.dart
  app.dart                        # Root widget with ProviderScope

test/
  unit/
    features/
      products/
      categories/
      inventory/
      orders/
      dashboard/
  widget/
  integration/

App Context - Retail POS Application

About This App

A comprehensive Flutter-based Point of Sale (POS) application designed for retail businesses. The app enables merchants to manage their complete product inventory with variants, track stock levels, process sales transactions, analyze business performance, and maintain business settings—all through an intuitive tab-based interface optimized for speed and efficiency.

Target Users

Retail Store Owners: Small to medium-sized retail businesses
Cashiers/Sales Staff: Front-line employees processing transactions
Store Managers: Inventory and business configuration management
Mobile Vendors: On-the-go sales at markets, events, or mobile locations

Core Features

Tab 1: Home/POS Screen

Purpose: Primary sales interface for selecting products and processing transactions

Key Components:

Product Selector: Quick access to frequently sold products with variants
Shopping Cart: Real-time cart display with items, quantities, prices
Cart Management: Add, remove, update quantities
Cart Summary: Subtotal, tax, discounts, total calculation
Checkout Flow: Complete transaction and process payment
Quick Actions: Clear cart, apply discounts, process returns, create order
Discount System: Apply percentage or fixed amount discounts to cart or items

State Management:

Cart state (items, quantities, totals)
Selected product and variant state
Discount state (cart-level and item-level)
Transaction state
Order creation state

Data Requirements:

Real-time cart updates
Price calculations with variants
Tax computation
Transaction logging
Order generation

Business Logic:

Calculate subtotals including variants
Apply discounts (percentage, fixed, promotional)
Compute tax based on settings
Generate order from cart
Validate stock before checkout
Process payment and create transaction record

Tab 2: Products Grid

Purpose: Browse, search, and manage all available products

Key Components:

Product Grid: Responsive grid layout with product cards
Product Cards: Image, name, price, stock status, category, variants
Search Bar: Real-time product search across name, description, SKU
Filter Options: Category filter, price range, availability, supplier, tags
Sort Options: Name, price, category, popularity, stock level
Empty States: No products found UI
Quick Actions: Add product, edit product, manage stock
Batch Operations: Select multiple products for bulk updates

Product Management:

Add/Edit Products:
- Basic info (name, description, SKU, barcode)
- Pricing (cost, retail price, sale price)
- Stock levels
- Product images (multiple)
- Category assignment
- Tags for organization
- Supplier information
Product Variants:
- Size variants (S, M, L, XL)
- Color variants
- Custom variant types
- Individual SKU per variant
- Separate pricing per variant
- Separate stock per variant
Supplier Management:
- Add/edit suppliers
- Link products to suppliers
- Track supplier contact info
- View products by supplier

State Management:

Products list state (all products)
Search query state
Filter state (category, price, supplier, tags)
Sort state
Product form state
Variant management state
Supplier state

Data Requirements:

Product list from API (online-first with Hive cache fallback)
Product images (cached with variants)
Product search indexing
Category relationships
Supplier relationships
Tag associations
Variant data with individual stock

Tab 3: Categories Grid

Purpose: View and manage product categories and tags

Key Components:

Category Grid: Visual grid of all categories
Category Cards: Icon/image, name, product count
Category Selection: Navigate to products in category
Empty States: No categories UI
Category Management: Add, edit, delete categories
Tag Management: Create and manage product tags
Quick Actions: Create category, manage tags

Category Management:

Create new categories
Edit category details (name, icon, description)
Delete categories (with product reassignment)
Set category colors
Organize products by category

Tag Management:

Create product tags for organization
Apply multiple tags to products
Filter products by tags
Color-coded tags

State Management:

Categories list state
Selected category state
Products by category state
Tags state
Category form state

Data Requirements:

Category list from Hive
Product count per category
Category images (cached)
Category-product relationships
Tag associations

Tab 4: Settings

Purpose: App configuration and business settings

Key Components:

Theme Settings: Light/dark mode toggle
Language Settings: Multi-language support
Currency Settings: Currency format and symbol
Tax Configuration: Tax rates and rules
Business Info: Store name, contact, address
Data Management: Sync, backup, clear cache, CSV import/export
About: App version, credits, legal

State Management:

App settings state
Theme mode state
Language state
Sync state
Import/export state

Data Requirements:

App settings from Hive
User preferences
Business configuration
CSV templates

📦 Inventory Management (Extended Feature)

Purpose: Basic inventory monitoring and alerts

Key Features:

Low Stock Alerts

Alert Configuration:
- Set minimum stock level per product
- Enable/disable alerts
- Alert threshold (e.g., alert when < 10 units)
Alert Notifications:
- Dashboard badge showing low-stock count
- Low stock products list
- Visual indicators on product cards
- Sort products by stock level

CSV Import/Export

Import Products:
- CSV template download
- Bulk product import
- Validation and error reporting
- Preview before import
- Update existing or create new
Export Products:
- Export all products to CSV
- Export filtered products
- Include variants in export
- Custom field selection

Batch Updates

Multi-Select Mode: Select multiple products
Bulk Operations:
- Update prices (increase/decrease by %)
- Update stock levels
- Change categories
- Apply tags
- Update supplier
- Delete multiple products
Preview Changes: Review before applying

Data Models:

InventoryAlert:
  - productId, alertThreshold, isActive
  - currentStock, minimumStock

State Management:

Inventory state (stock levels)
Low stock alerts state
Import/export progress state
Batch operation state

💰 Orders & Sales Management (Extended Feature)

Purpose: Simple order tracking and basic discounts

Key Features:

Order Management

Create Orders: Convert cart to order
Order Details:
- Order number (auto-generated)
- Order items with quantities
- Subtotal, discount, total
- Payment method
- Order status (completed, cancelled)
- Order date/time
Order History: View all past orders
Order Actions: View details, basic order info

Basic Discount System

Discount Types:
- Percentage discount (e.g., 10% off)
- Fixed amount discount (e.g., $5 off)
- Cart-level discounts only
Apply Discounts: During checkout to entire cart

Order History

Simple List: Chronological display of orders
Order Details: Tap to view full order information
Basic Filter: Filter by date (today, week, month)

Data Models:

Order:
  - id, orderNumber
  - items (List<OrderItem>)
  - subtotal, discount, total
  - paymentMethod, orderStatus
  - createdAt

OrderItem:
  - productId, productName, variantInfo
  - quantity, unitPrice, lineTotal

State Management:

Orders list state
Order creation state
Basic discount state

📊 Sales Dashboard (Extended Feature)

Purpose: Business analytics and performance insights

Key Features:

Revenue Analytics

Daily Revenue:
- Today's total sales
- Number of transactions
- Average transaction value
- Revenue trend chart (hourly)
Monthly Revenue:
- Current month total
- Month-over-month comparison
- Revenue trend chart (daily)
- Projected month-end revenue
Custom Date Range: Select any date range for analysis
Revenue by Payment Method: Cash vs Card breakdown

Best-Selling Products

Top Products:
- Ranked by quantity sold
- Ranked by revenue generated
- Timeframe selector (today, week, month, all-time)
Product Performance:
- Units sold
- Revenue generated
- Average price
- Trend indicators (↑↓)
Visual Display: Charts and lists

Category Performance

Sales by Category:
- Revenue per category
- Units sold per category
- Category comparison
- Pie chart visualization
Category Trends: Growth/decline indicators

Dashboard Widgets

Summary Cards:
- Total Revenue (today/week/month)
- Total Transactions
- Average Transaction Value
- Low Stock Alerts Count
Charts:
- Revenue line chart
- Category pie chart
- Best sellers bar chart
- Sales trend graph
Quick Stats:
- Products sold today
- Most popular product
- Total products in inventory
- Categories count

Data Requirements:

Transaction history from database
Product sales data
Category sales data
Time-series data for charts
Aggregated statistics

State Management:

Dashboard stats state
Revenue data state
Best sellers state
Category performance state
Date range filter state
Chart data state

Analytics Calculations:

Sum revenue by period
Count transactions
Calculate average transaction value
Rank products by sales
Group sales by category
Trend analysis (increase/decrease %)

Technical Architecture

State Management (Riverpod 3.0)

Core Providers

// Cart Management
final cartProvider = NotifierProvider<Cart, List<CartItem>>(Cart.new);
final cartTotalProvider = Provider<double>((ref) { ... });
final discountProvider = NotifierProvider<Discount, DiscountState>(Discount.new);

// Products Management
final productsProvider = AsyncNotifierProvider<Products, List<Product>>(Products.new);
final filteredProductsProvider = Provider<List<Product>>((ref) { ... });
final productFormProvider = NotifierProvider<ProductForm, ProductFormState>(ProductForm.new);
final variantsProvider = NotifierProvider<Variants, List<Variant>>(Variants.new);

// Categories Management
final categoriesProvider = AsyncNotifierProvider<Categories, List<Category>>(Categories.new);
final tagsProvider = NotifierProvider<Tags, List<Tag>>(Tags.new);

// Inventory Management
final inventoryProvider = NotifierProvider<Inventory, Map<String, int>>(Inventory.new);
final stockAlertsProvider = Provider<List<Product>>((ref) { ... });

// Orders Management
final ordersProvider = AsyncNotifierProvider<Orders, List<Order>>(Orders.new);

// Dashboard Analytics
final dashboardStatsProvider = Provider<DashboardStats>((ref) { ... });
final revenueProvider = Provider<RevenueStats>((ref) { ... });
final bestSellersProvider = Provider<List<ProductPerformance>>((ref) { ... });

// Settings Management
final settingsProvider = AsyncNotifierProvider<AppSettings, Settings>(AppSettings.new);

Database Schema (Hive CE)

Core Hive Boxes

// Box Names
const String productsBox = 'products';
const String variantsBox = 'variants';
const String categoriesBox = 'categories';
const String tagsBox = 'tags';
const String suppliersBox = 'suppliers';
const String cartBox = 'cart';
const String ordersBox = 'orders';
const String settingsBox = 'settings';

Product Model (Enhanced)

@HiveType(typeId: 0)
class Product extends HiveObject {
  @HiveField(0) final String id;
  @HiveField(1) final String name;
  @HiveField(2) final String description;
  @HiveField(3) final double price;
  @HiveField(4) final double? costPrice;
  @HiveField(5) final double? salePrice;
  @HiveField(6) final String? sku;
  @HiveField(7) final String? barcode;
  @HiveField(8) final List<String>? imageUrls;
  @HiveField(9) final String categoryId;
  @HiveField(10) final int stockQuantity;
  @HiveField(11) final bool isAvailable;
  @HiveField(12) final List<String> tags;
  @HiveField(13) final String? supplierId;
  @HiveField(14) final bool hasVariants;
  @HiveField(15) final List<String> variantIds;
  @HiveField(16) final int? lowStockThreshold;
  @HiveField(17) final DateTime createdAt;
  @HiveField(18) final DateTime updatedAt;
}

Product Variant Model

@HiveType(typeId: 1)
class ProductVariant extends HiveObject {
  @HiveField(0) final String id;
  @HiveField(1) final String productId;
  @HiveField(2) final String name; // e.g., "Large - Red"
  @HiveField(3) final String? sku;
  @HiveField(4) final double? priceAdjustment;
  @HiveField(5) final int stockQuantity;
  @HiveField(6) final Map<String, String> attributes; // {size: "L", color: "Red"}
  @HiveField(7) final String? imageUrl;
  @HiveField(8) final DateTime createdAt;
}

Category Model

@HiveType(typeId: 2)
class Category extends HiveObject {
  @HiveField(0) final String id;
  @HiveField(1) final String name;
  @HiveField(2) final String? description;
  @HiveField(3) final String? iconPath;
  @HiveField(4) final String? color;
  @HiveField(5) final int productCount;
  @HiveField(6) final DateTime createdAt;
}

Tag Model

@HiveType(typeId: 3)
class Tag extends HiveObject {
  @HiveField(0) final String id;
  @HiveField(1) final String name;
  @HiveField(2) final String? color;
  @HiveField(3) final DateTime createdAt;
}

Supplier Model

@HiveType(typeId: 4)
class Supplier extends HiveObject {
  @HiveField(0) final String id;
  @HiveField(1) final String name;
  @HiveField(2) final String? contactPerson;
  @HiveField(3) final String? email;
  @HiveField(4) final String? phone;
  @HiveField(5) final String? address;
  @HiveField(6) final DateTime createdAt;
}

Order Model

@HiveType(typeId: 5)
class Order extends HiveObject {
  @HiveField(0) final String id;
  @HiveField(1) final String orderNumber;
  @HiveField(2) final List<OrderItem> items;
  @HiveField(3) final double subtotal;
  @HiveField(4) final double discount;
  @HiveField(5) final double total;
  @HiveField(6) final String paymentMethod;
  @HiveField(7) final String orderStatus; // completed, cancelled
  @HiveField(8) final DateTime createdAt;
}

Order Item Model

@HiveType(typeId: 6)
class OrderItem extends HiveObject {
  @HiveField(0) final String id;
  @HiveField(1) final String productId;
  @HiveField(2) final String productName;
  @HiveField(3) final String? variantId;
  @HiveField(4) final String? variantName;
  @HiveField(5) final double price;
  @HiveField(6) final int quantity;
  @HiveField(7) final double lineTotal;
}

UI/UX Design Guidelines

Material 3 Design System

Primary Color: Represents brand identity (customizable)
Secondary Color: Accents and highlights
Surface Colors: Cards, sheets, backgrounds
Typography: Material 3 type scale (Display, Headline, Title, Body, Label)

Product Card Design

// Product card should display:
- Product image (with placeholder/error handling)
- Product name (2 lines max with ellipsis)
- Price (formatted with currency, show sale price if applicable)
- Stock status badge (in stock, low stock, out of stock)
- Category badge
- Variant indicator (if product has variants)
- Add to cart button/icon
- Quick edit button (for managers)
- Tap to view details

Category Card Design

// Category card should display:
- Category icon/image
- Category name
- Product count
- Background color (category-specific)
- Tap to filter products by category

Dashboard Charts

Use fl_chart package for charts
Revenue line chart with time axis
Category pie chart with percentages
Best sellers horizontal bar chart
Responsive chart sizing
Interactive tooltips

Stock Level Indicators

High Stock: Green badge
Medium Stock: Orange badge
Low Stock: Red badge with alert icon
Out of Stock: Grey badge with warning

Performance Optimization

Image Management

Use cached_network_image for product images
Implement proper placeholder and error widgets
Optimize image sizes (thumbnails for grids, full size for details)
Cache images in memory and disk
Lazy load images in grid views

Grid Performance

GridView.builder(
  itemCount: products.length,
  gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
    crossAxisCount: 2,
    childAspectRatio: 0.75,
    crossAxisSpacing: 12,
    mainAxisSpacing: 12,
  ),
  itemBuilder: (context, index) {
    return RepaintBoundary(
      child: ProductCard(product: products[index]),
    );
  },
);

Database Optimization

Use lazy boxes for large product datasets
Implement pagination for product lists
Create indexes for frequent queries
Regular database compaction
Efficient query filtering

State Management Optimization

Use .select() for granular rebuilds
Implement proper provider disposal
Cache computed values
Debounce search queries
Optimize cart calculations

Online-First Strategy

Data Flow

Check Connection: Check if device is online
Try API First: If online, fetch fresh data from API
Update Cache: Save API response to Hive for offline access
Fallback to Cache: If API fails or offline, load from Hive
Show Data: Display data to user (from API or cache)

Implementation Pattern

@riverpod
class Products extends _$Products {
  @override
  Future<List<Product>> build() async {
    // Online-first: Try to load from API first
    final repository = ref.watch(productRepositoryProvider);
    final networkInfo = ref.watch(networkInfoProvider);

    // Check if online
    final isConnected = await networkInfo.isConnected;

    if (isConnected) {
      // Try API first
      try {
        final syncResult = await repository.syncProducts();
        return syncResult.fold(
          (failure) {
            // API failed, fallback to cache
            print('API failed, falling back to cache: ${failure.message}');
            return _loadFromCache();
          },
          (products) => products,
        );
      } catch (e) {
        // API error, fallback to cache
        print('API error, falling back to cache: $e');
        return _loadFromCache();
      }
    } else {
      // Offline, load from cache
      print('Offline, loading from cache');
      return _loadFromCache();
    }
  }

  Future<List<Product>> _loadFromCache() async {
    final repository = ref.read(productRepositoryProvider);
    final result = await repository.getAllProducts();

    return result.fold(
      (failure) {
        print('Cache load failed: ${failure.message}');
        return <Product>[];
      },
      (products) => products,
    );
  }
}

Key Features Implementation

Search Functionality

Real-time search with debouncing (300ms)
Search by product name, description, SKU, barcode
Search across variants
Display search results count
Clear search button
Search history (optional)

Filter System

Category Filter: Filter by one or multiple categories
Price Range: Min/max price slider
Stock Status: In stock, low stock, out of stock
Supplier Filter: Filter by supplier
Tag Filter: Filter by tags
Variant Filter: Show only products with variants

Cart Operations

Add to cart with quantity
Add variant to cart with selected options
Update quantity with +/- buttons
Remove item with swipe or tap
Clear entire cart with confirmation
Calculate totals in real-time
Apply discounts (cart-level or item-level)
Persist cart between sessions

Inventory Operations

Alerts: Show low-stock products
Batch Updates: Update multiple products at once

Order Processing

Validate cart (not empty, stock available)
Select payment method
Apply cart-level discount (optional)
Calculate subtotal and discount
Generate unique order number
Save order to database
Clear cart after successful order

CSV Import/Export

Import:
- Download CSV template
- Select CSV file
- Parse and validate
- Preview import
- Confirm and import
- Handle errors gracefully
Export:
- Select data to export (all, filtered, selected)
- Generate CSV
- Save/share file

Dashboard Analytics

Calculate Revenue: Sum all transactions by period
Best Sellers: Rank products by quantity/revenue
Category Performance: Group sales by category
Trend Analysis: Compare periods (today vs yesterday, month vs last month)
Charts: Generate chart data from transactions

Error Handling

Network Errors

Display user-friendly error messages
Show retry button for failed operations
Indicate offline mode
Queue operations for retry when online

Validation Errors

Validate cart before checkout
Check product availability and stock
Validate quantity inputs
Validate price inputs (product form)
Display inline error messages

Data Errors

Handle empty states (no products, no categories, no orders)
Handle missing images gracefully
Validate data integrity on load
Provide fallback values

Testing Strategy

Unit Tests

Cart calculations (total, tax, discounts)
Search filtering logic
Category filtering logic
Price formatting
Data validation
Stock calculations
Revenue calculations

Product card rendering
Category card rendering
Cart item rendering
Tab navigation
Search bar functionality
Dashboard charts

Integration Tests

Complete checkout flow
Product CRUD operations
Category management
CSV import/export
Order creation and history

Development Workflow

Feature Development Process

Define Requirements: User stories and acceptance criteria
Design Data Layer: Models, repositories, data sources
Implement Domain Layer: Entities, use cases
Create Providers: Riverpod state management
Build UI: Widgets, pages, navigation
Test: Unit, widget, integration tests
Optimize: Performance profiling and optimization

Code Review Checklist

Follows clean architecture principles
Proper error handling implemented
Online-first approach maintained (API first, cache fallback)
Performance optimizations applied
Proper state management with Riverpod
Hive models and adapters properly defined
UI follows Material 3 guidelines
Accessibility considerations addressed
Tests written and passing
Code documentation provided

Future Enhancements (Roadmap)

Phase 1 - Current

✅ Core POS functionality
✅ Product and category management
✅ Product variants support
✅ Basic cart and checkout
✅ Inventory tracking
✅ Stock alerts
✅ Order management
✅ Sales dashboard
✅ CSV import/export
✅ Batch operations
✅ Settings management

Phase 2 - Near Future

🔄 Customer management
🔄 Loyalty program
🔄 Advanced reporting
🔄 Receipt printing
🔄 Barcode scanning
🔄 Multiple payment methods
🔄 Staff management with roles
🔄 Promotional campaigns

Phase 3 - Future

📋 Multi-store support
📋 Cloud sync with backend
📋 Integration with accounting software
📋 Advanced analytics and forecasting
📋 Supplier portal
📋 Purchase order management
📋 Integration with payment gateways
📋 E-commerce integration

Remember: ALWAYS DELEGATE TO SPECIALISTS FOR BETTER RESULTS!

When working on this retail POS app:

UI Tasks → flutter-widget-expert
State Management → riverpod-expert
Database/Caching → hive-expert
API Integration → api-integration-expert
Architecture Decisions → architecture-expert
Performance Issues → performance-expert

Think delegation first, implementation second!

35 KiB Raw Blame History

Flutter Retail POS App Expert Guidelines

🎯 App Overview

🤖 SUBAGENT DELEGATION SYSTEM 🤖

🚨 DELEGATION MINDSET

📋 AVAILABLE SPECIALISTS

🎨 flutter-widget-expert

📊 riverpod-expert

🗄️ hive-expert

🌐 api-integration-expert

🏗️ architecture-expert

⚡ performance-expert

🎯 DELEGATION STRATEGY

💼 WORK BALANCE RECOMMENDATION:

🔧 HOW TO DELEGATE

Flutter Best Practices

Retail App Project Structure

App Context - Retail POS Application

About This App

Target Users

Core Features

📱 Tab-Based Navigation (4 Main Tabs + Extended Features)

Tab 1: Home/POS Screen

Tab 2: Products Grid

Tab 3: Categories Grid

Tab 4: Settings

📦 Inventory Management (Extended Feature)

Low Stock Alerts

CSV Import/Export

Batch Updates

💰 Orders & Sales Management (Extended Feature)

Order Management

Basic Discount System

Order History

📊 Sales Dashboard (Extended Feature)

Revenue Analytics

Best-Selling Products

Category Performance

Dashboard Widgets

Technical Architecture

State Management (Riverpod 3.0)

Core Providers

Database Schema (Hive CE)

Core Hive Boxes

Product Model (Enhanced)

Product Variant Model

Category Model

Tag Model

Supplier Model

Order Model

Order Item Model

UI/UX Design Guidelines

Material 3 Design System

Product Card Design

Category Card Design

Dashboard Charts

Stock Level Indicators

Performance Optimization

Image Management

Grid Performance

Database Optimization

State Management Optimization

Online-First Strategy

Data Flow

Implementation Pattern

Key Features Implementation

Search Functionality

Filter System

Cart Operations

Inventory Operations

Order Processing

CSV Import/Export

Dashboard Analytics

Error Handling

Network Errors

Validation Errors

Data Errors

Testing Strategy

Unit Tests

Widget Tests

35 KiB

Raw Blame History