runable
This commit is contained in:
Phuoc Nguyen
501
docs/RUN_APP.md
Normal file
501
docs/RUN_APP.md
Normal file
@@ -0,0 +1,501 @@
|
||||
# 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! 🚀
|
||||
Reference in New Issue
Block a user