502 lines
10 KiB
Markdown
502 lines
10 KiB
Markdown
# Quick Start Guide - Retail POS App
|
|
|
|
## Prerequisites
|
|
|
|
1. **Flutter SDK** (3.35.x or higher)
|
|
```bash
|
|
flutter --version
|
|
```
|
|
|
|
2. **Dart SDK** (3.9.2 or higher)
|
|
```bash
|
|
dart --version
|
|
```
|
|
|
|
3. **Connected Device or Emulator**
|
|
```bash
|
|
flutter devices
|
|
```
|
|
|
|
---
|
|
|
|
## Initial Setup
|
|
|
|
### 1. Install Dependencies
|
|
```bash
|
|
cd /Users/ssg/project/retail
|
|
flutter pub get
|
|
```
|
|
|
|
### 2. Generate Code
|
|
This step is **CRITICAL** - the app won't run without it!
|
|
|
|
```bash
|
|
# Generate all Riverpod and Hive code
|
|
flutter pub run build_runner build --delete-conflicting-outputs
|
|
```
|
|
|
|
**What this does:**
|
|
- Generates `.g.dart` files for all providers
|
|
- Generates Hive type adapters
|
|
- Creates necessary code for dependency injection
|
|
|
|
**Watch mode** (for development):
|
|
```bash
|
|
# Automatically regenerates when files change
|
|
flutter pub run build_runner watch --delete-conflicting-outputs
|
|
```
|
|
|
|
### 3. Verify Code Generation
|
|
Check that these files exist:
|
|
```bash
|
|
# Check providers were generated
|
|
ls lib/features/home/presentation/providers/*.g.dart
|
|
ls lib/features/products/presentation/providers/*.g.dart
|
|
ls lib/features/categories/presentation/providers/*.g.dart
|
|
ls lib/features/settings/presentation/providers/*.g.dart
|
|
|
|
# Check models were generated
|
|
ls lib/features/home/data/models/*.g.dart
|
|
ls lib/features/products/data/models/*.g.dart
|
|
ls lib/features/categories/data/models/*.g.dart
|
|
ls lib/features/settings/data/models/*.g.dart
|
|
```
|
|
|
|
---
|
|
|
|
## Running the App
|
|
|
|
### Option 1: Default Device
|
|
```bash
|
|
flutter run
|
|
```
|
|
|
|
### Option 2: Specific Device
|
|
```bash
|
|
# List available devices
|
|
flutter devices
|
|
|
|
# Run on specific device
|
|
flutter run -d <device-id>
|
|
|
|
# Examples:
|
|
flutter run -d chrome # Web
|
|
flutter run -d macos # macOS
|
|
flutter run -d emulator-5554 # Android emulator
|
|
flutter run -d "iPhone 15" # iOS simulator
|
|
```
|
|
|
|
### Option 3: Release Mode
|
|
```bash
|
|
flutter run --release
|
|
```
|
|
|
|
### Option 4: With Hot Reload (Development)
|
|
```bash
|
|
# Run in debug mode with hot reload enabled
|
|
flutter run
|
|
|
|
# While running:
|
|
# Press 'r' to hot reload
|
|
# Press 'R' to hot restart
|
|
# Press 'h' for help
|
|
# Press 'q' to quit
|
|
```
|
|
|
|
---
|
|
|
|
## Development Workflow
|
|
|
|
### Run with Watch Mode
|
|
Open **two terminals**:
|
|
|
|
**Terminal 1:** Run build_runner in watch mode
|
|
```bash
|
|
cd /Users/ssg/project/retail
|
|
flutter pub run build_runner watch --delete-conflicting-outputs
|
|
```
|
|
|
|
**Terminal 2:** Run the app
|
|
```bash
|
|
cd /Users/ssg/project/retail
|
|
flutter run
|
|
```
|
|
|
|
This allows:
|
|
- Automatic code regeneration when you modify providers
|
|
- Hot reload for UI changes
|
|
- Continuous development without manual rebuilds
|
|
|
|
---
|
|
|
|
## Common Commands
|
|
|
|
### Clean Build
|
|
```bash
|
|
# Clean build artifacts
|
|
flutter clean
|
|
|
|
# Get dependencies again
|
|
flutter pub get
|
|
|
|
# Regenerate code
|
|
flutter pub run build_runner build --delete-conflicting-outputs
|
|
|
|
# Run app
|
|
flutter run
|
|
```
|
|
|
|
### Analyze Code
|
|
```bash
|
|
# Check for issues
|
|
flutter analyze
|
|
|
|
# Format code
|
|
dart format .
|
|
|
|
# Fix formatting
|
|
dart fix --apply
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
# Run all tests
|
|
flutter test
|
|
|
|
# Run specific test
|
|
flutter test test/path/to/test_file.dart
|
|
|
|
# With coverage
|
|
flutter test --coverage
|
|
```
|
|
|
|
### Build for Production
|
|
|
|
**Android APK:**
|
|
```bash
|
|
flutter build apk --release
|
|
# Output: build/app/outputs/flutter-apk/app-release.apk
|
|
```
|
|
|
|
**Android App Bundle:**
|
|
```bash
|
|
flutter build appbundle --release
|
|
# Output: build/app/outputs/bundle/release/app-release.aab
|
|
```
|
|
|
|
**iOS:**
|
|
```bash
|
|
flutter build ios --release
|
|
```
|
|
|
|
**macOS:**
|
|
```bash
|
|
flutter build macos --release
|
|
```
|
|
|
|
**Web:**
|
|
```bash
|
|
flutter build web --release
|
|
# Output: build/web/
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Issue: "No providers found" or "Provider not generated"
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Delete old generated files
|
|
flutter clean
|
|
|
|
# Reinstall dependencies
|
|
flutter pub get
|
|
|
|
# Regenerate all code
|
|
flutter pub run build_runner build --delete-conflicting-outputs
|
|
```
|
|
|
|
### Issue: "MissingPluginException"
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Stop the app
|
|
# Clean and rebuild
|
|
flutter clean
|
|
flutter pub get
|
|
flutter run
|
|
```
|
|
|
|
### Issue: Hive errors
|
|
|
|
**Solution:**
|
|
Check that Hive boxes are registered in `main.dart`:
|
|
```dart
|
|
// Ensure these are uncommented after code generation:
|
|
Hive.registerAdapter(ProductModelAdapter());
|
|
Hive.registerAdapter(CategoryModelAdapter());
|
|
Hive.registerAdapter(CartItemModelAdapter());
|
|
Hive.registerAdapter(AppSettingsModelAdapter());
|
|
```
|
|
|
|
### Issue: Build runner conflicts
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Use delete-conflicting-outputs flag
|
|
flutter pub run build_runner build --delete-conflicting-outputs
|
|
```
|
|
|
|
### Issue: Hot reload not working
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Press 'R' for hot restart instead of 'r'
|
|
# Or restart the app entirely
|
|
flutter run
|
|
```
|
|
|
|
---
|
|
|
|
## App Features Overview
|
|
|
|
Once running, you can:
|
|
|
|
### 1. Home Tab (POS)
|
|
- View available products in a grid
|
|
- Tap product to add to cart
|
|
- Adjust quantity before adding
|
|
- View cart with items and total
|
|
- Manage cart quantities
|
|
- Clear cart
|
|
- Checkout (when implemented)
|
|
|
|
### 2. Products Tab
|
|
- Search products by name/description
|
|
- Filter by category using chips
|
|
- Sort products (name, price, date)
|
|
- Pull to refresh
|
|
- Responsive grid layout
|
|
|
|
### 3. Categories Tab
|
|
- View all categories in a grid
|
|
- See product count per category
|
|
- Tap category to filter products
|
|
- Pull to refresh
|
|
|
|
### 4. Settings Tab
|
|
- Change theme (Light/Dark/System)
|
|
- Select language
|
|
- Choose currency
|
|
- Set store name
|
|
- Configure tax rate
|
|
- Sync data
|
|
- Clear cache
|
|
- View app info
|
|
|
|
---
|
|
|
|
## Development Tips
|
|
|
|
### 1. Use VS Code Extensions
|
|
- **Flutter** (Dart-Code.flutter)
|
|
- **Dart** (Dart-Code.dart-code)
|
|
- **Flutter Riverpod Snippets**
|
|
- **Error Lens** (usernamehw.errorlens)
|
|
|
|
### 2. Enable DevTools
|
|
```bash
|
|
# While app is running
|
|
flutter run
|
|
|
|
# Open DevTools in browser
|
|
# Click the URL shown in terminal (e.g., http://127.0.0.1:9101/)
|
|
```
|
|
|
|
### 3. Use Flutter Inspector
|
|
- Open DevTools
|
|
- Click "Flutter Inspector" tab
|
|
- Inspect widget tree
|
|
- Debug layout issues
|
|
- Toggle debug paint
|
|
- Measure render times
|
|
|
|
### 4. Performance Profiling
|
|
```bash
|
|
# Run in profile mode
|
|
flutter run --profile
|
|
|
|
# Open DevTools > Performance
|
|
# Record timeline
|
|
# Analyze frame rendering
|
|
```
|
|
|
|
### 5. Hot Reload Tips
|
|
- Works for UI changes
|
|
- Doesn't work for:
|
|
- Adding new dependencies
|
|
- Changing provider annotations
|
|
- Modifying main()
|
|
- Use Hot Restart (R) for those changes
|
|
|
|
---
|
|
|
|
## Project Structure Quick Reference
|
|
|
|
```
|
|
lib/
|
|
├── main.dart # Entry point - START HERE
|
|
├── app.dart # App shell with tabs
|
|
│
|
|
├── features/
|
|
│ ├── home/presentation/pages/home_page.dart # Home/POS page
|
|
│ ├── products/presentation/pages/products_page.dart # Products page
|
|
│ ├── categories/presentation/pages/categories_page.dart # Categories page
|
|
│ └── settings/presentation/pages/settings_page.dart # Settings page
|
|
│
|
|
└── core/
|
|
├── theme/app_theme.dart # Material 3 themes
|
|
└── constants/ # App constants
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Commands Cheat Sheet
|
|
|
|
```bash
|
|
# Setup
|
|
flutter pub get # Install dependencies
|
|
flutter pub run build_runner build --delete-conflicting-outputs # Generate code
|
|
|
|
# Run
|
|
flutter run # Run app
|
|
flutter run -d chrome # Run on web
|
|
flutter run --release # Release mode
|
|
|
|
# Development
|
|
flutter pub run build_runner watch --delete-conflicting-outputs # Watch mode
|
|
dart format . # Format code
|
|
flutter analyze # Analyze code
|
|
|
|
# Build
|
|
flutter build apk --release # Android APK
|
|
flutter build appbundle --release # Android Bundle
|
|
flutter build ios --release # iOS
|
|
flutter build web --release # Web
|
|
|
|
# Testing
|
|
flutter test # Run tests
|
|
flutter test --coverage # With coverage
|
|
|
|
# Maintenance
|
|
flutter clean # Clean build
|
|
flutter doctor # Check environment
|
|
flutter upgrade # Upgrade Flutter
|
|
```
|
|
|
|
---
|
|
|
|
## Environment Verification
|
|
|
|
Before running, verify your setup:
|
|
|
|
```bash
|
|
# Check Flutter installation
|
|
flutter doctor -v
|
|
|
|
# Should show:
|
|
# ✓ Flutter (version 3.35.x or higher)
|
|
# ✓ Dart (version 3.9.2 or higher)
|
|
# ✓ Android toolchain (if targeting Android)
|
|
# ✓ Xcode (if targeting iOS/macOS)
|
|
# ✓ Connected devices
|
|
|
|
# Check dependencies
|
|
flutter pub get
|
|
|
|
# Verify pubspec.lock exists
|
|
ls pubspec.lock
|
|
|
|
# Check generated files
|
|
ls lib/**/*.g.dart
|
|
```
|
|
|
|
---
|
|
|
|
## Expected Output
|
|
|
|
When running successfully, you should see:
|
|
|
|
```
|
|
Launching lib/main.dart on <device> in debug mode...
|
|
Running Gradle task 'assembleDebug'...
|
|
✓ Built build/app/outputs/flutter-apk/app-debug.apk.
|
|
|
|
Flutter run key commands.
|
|
r Hot reload.
|
|
R Hot restart.
|
|
h List all available interactive commands.
|
|
d Detach (terminate "flutter run" but leave application running).
|
|
c Clear the screen
|
|
q Quit (terminate the application on the device).
|
|
|
|
An Observatory debugger and profiler on <device> is available at: http://127.0.0.1:xxxxx/
|
|
The Flutter DevTools debugger and profiler on <device> is available at: http://127.0.0.1:9100/
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps After Running
|
|
|
|
1. **Explore the App:**
|
|
- Navigate through all 4 tabs
|
|
- Try adding products to cart
|
|
- Search and filter products
|
|
- Change theme in settings
|
|
|
|
2. **Check Functionality:**
|
|
- Add items to cart
|
|
- Remove items from cart
|
|
- Filter by category
|
|
- Search products
|
|
- Sort products
|
|
- Change settings
|
|
|
|
3. **Test Responsiveness:**
|
|
- Resize window (if on desktop/web)
|
|
- Try portrait and landscape (if on mobile)
|
|
- Check different screen sizes
|
|
|
|
4. **Review Code:**
|
|
- Check generated `.g.dart` files
|
|
- Review provider implementations
|
|
- Understand the flow
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
If you encounter issues:
|
|
|
|
1. Check `flutter doctor` output
|
|
2. Ensure code generation completed successfully
|
|
3. Review error messages in the terminal
|
|
4. Check PAGES_SUMMARY.md for known issues
|
|
5. Verify all dependencies in pubspec.yaml are compatible
|
|
|
|
---
|
|
|
|
**Ready to Go!**
|
|
|
|
```bash
|
|
# Quick start (copy-paste):
|
|
cd /Users/ssg/project/retail && \
|
|
flutter pub get && \
|
|
flutter pub run build_runner build --delete-conflicting-outputs && \
|
|
flutter run
|
|
```
|
|
|
|
Happy coding! 🚀
|