Development Guidelines

Panduan development untuk kontributor MStore Mobile.

🎯 Development Workflow

1. Setup Development Environment

# Clone repository
git clone <repository-url>
cd mstore_mobile

# Install dependencies
flutter pub get

# Generate code
flutter pub run build_runner build --delete-conflicting-outputs

# Run development
flutter run --flavor development -t lib/main_development.dart

2. Branch Strategy

main (production)
  ↓
develop (staging)
  ↓
feature/feature-name
fix/bug-description
hotfix/critical-fix

Branch Naming:

feature/cashier-barcode-scan - New features
fix/inventory-sync-issue - Bug fixes
hotfix/payment-crash - Critical production fixes
refactor/bloc-architecture - Code refactoring
docs/api-documentation - Documentation updates

3. Commit Convention

Gunakan Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation
style: Code style (formatting, etc)
refactor: Code refactoring
perf: Performance improvement
test: Adding tests
chore: Maintenance tasks

Examples:

feat(cashier): add barcode scanning support

- Implement mobile_scanner integration
- Add barcode search in product list
- Update UI for scanner button

Closes #123

---

fix(inventory): resolve stock sync issue

The inventory was not syncing properly when offline.
Now using queue-based sync with retry mechanism.

Fixes #456

---

docs(api): update authentication endpoints

Added documentation for refresh token flow
and device registration endpoint.

4. Pull Request Process

Before Creating PR

# Update from develop
git checkout develop
git pull origin develop

# Rebase your feature branch
git checkout feature/your-feature
git rebase develop

# Run tests
flutter test

# Run code analysis
flutter analyze

# Format code
flutter format .

# Build to ensure no errors
flutter build apk --flavor development -t lib/main_development.dart

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests added/updated
- [ ] Widget tests added/updated
- [ ] Manual testing completed

## Screenshots (if applicable)
[Add screenshots here]

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings
- [ ] Tests pass locally

## Related Issues
Closes #123

🏗️ Project Structure

Feature Module Structure

features/
└── feature_name/
    ├── bloc/
    │   ├── feature_bloc.dart
    │   ├── feature_event.dart
    │   └── feature_state.dart
    ├── pages/
    │   ├── feature_list_page.dart
    │   └── feature_detail_page.dart
    ├── widgets/
    │   ├── feature_card.dart
    │   └── feature_form.dart
    └── models/
        └── feature_model.dart

Core Module Structure

core/
└── domain_name/
    ├── domain_api.dart           # Retrofit API
    ├── domain_repository.dart    # Repository interface
    ├── domain_service.dart       # Business logic
    └── models/
        ├── domain_model.dart
        └── domain_dto.dart

📝 Coding Standards

Dart Style Guide

// ✅ Good
class ProductCard extends StatelessWidget {
  final Product product;
  final VoidCallback? onTap;

  const ProductCard({
    super.key,
    required this.product,
    this.onTap,
  });

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: onTap,
      child: Card(
        child: Column(
          children: [
            Text(product.name),
            Text('Rp ${product.price}'),
          ],
        ),
      ),
    );
  }
}

// ❌ Bad
class productcard extends StatelessWidget {
  Product product;
  Function onTap;

  productcard(this.product, this.onTap);

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: () => onTap(),
      child: Card(
        child: Column(
          children: [
            Text(product.name),
            Text('Rp ' + product.price.toString()),
          ],
        ),
      ),
    );
  }
}

BLoC Pattern

// ✅ Good: Clear event and state naming
abstract class ProductEvent extends Equatable {}

class LoadProducts extends ProductEvent {
  const LoadProducts();
  
  @override
  List<Object?> get props => [];
}

class LoadProductById extends ProductEvent {
  final String productId;
  
  const LoadProductById(this.productId);
  
  @override
  List<Object?> get props => [productId];
}

// ❌ Bad: Unclear naming
class ProductEvent {}
class Load extends ProductEvent {}
class Get extends ProductEvent {
  String id;
  Get(this.id);
}

Repository Pattern

// ✅ Good: Use Either for error handling
abstract class ProductRepository {
  Future<Either<Failure, List<Product>>> getProducts();
  Future<Either<Failure, Product>> getProductById(String id);
}

class ProductRepositoryImpl implements ProductRepository {
  final ProductApi _api;
  
  @override
  Future<Either<Failure, List<Product>>> getProducts() async {
    try {
      final response = await _api.getProducts();
      return Right(response.data);
    } on DioException catch (e) {
      return Left(NetworkException.fromDioError(e));
    }
  }
}

// ❌ Bad: Throw exceptions
abstract class ProductRepository {
  Future<List<Product>> getProducts(); // Can throw
}

🧪 Testing

Unit Tests

// test/features/product/bloc/product_bloc_test.dart
void main() {
  group('ProductBloc', () {
    late ProductBloc bloc;
    late MockProductRepository mockRepository;

    setUp(() {
      mockRepository = MockProductRepository();
      bloc = ProductBloc(productRepository: mockRepository);
    });

    tearDown(() {
      bloc.close();
    });

    test('initial state is ProductInitial', () {
      expect(bloc.state, equals(const ProductInitial()));
    });

    blocTest<ProductBloc, ProductState>(
      'emits [ProductLoading, ProductLoaded] when LoadProducts succeeds',
      build: () {
        when(() => mockRepository.getProducts()).thenAnswer(
          (_) async => Right([Product(id: '1', name: 'Test')]),
        );
        return bloc;
      },
      act: (bloc) => bloc.add(const LoadProducts()),
      expect: () => [
        const ProductLoading(),
        isA<ProductLoaded>(),
      ],
    );
  });
}

// test/features/product/widgets/product_card_test.dart
void main() {
  testWidgets('ProductCard displays product info', (tester) async {
    final product = Product(
      id: '1',
      name: 'Test Product',
      price: 50000,
    );

    await tester.pumpWidget(
      MaterialApp(
        home: Scaffold(
          body: ProductCard(product: product),
        ),
      ),
    );

    expect(find.text('Test Product'), findsOneWidget);
    expect(find.text('Rp 50.000'), findsOneWidget);
  });

  testWidgets('ProductCard calls onTap when tapped', (tester) async {
    var tapped = false;
    final product = Product(id: '1', name: 'Test', price: 50000);

    await tester.pumpWidget(
      MaterialApp(
        home: Scaffold(
          body: ProductCard(
            product: product,
            onTap: () => tapped = true,
          ),
        ),
      ),
    );

    await tester.tap(find.byType(ProductCard));
    expect(tapped, isTrue);
  });
}

Integration Tests

// integration_test/cashier_flow_test.dart
void main() {
  IntegrationTestWidgetsFlutterBinding.ensureInitialized();

  testWidgets('Complete cashier flow', (tester) async {
    app.main();
    await tester.pumpAndSettle();

    // Navigate to cashier
    await tester.tap(find.text('Cashier'));
    await tester.pumpAndSettle();

    // Add product to cart
    await tester.tap(find.byKey(Key('product_1')));
    await tester.pumpAndSettle();

    // Verify cart
    expect(find.text('1 item'), findsOneWidget);

    // Checkout
    await tester.tap(find.text('Checkout'));
    await tester.pumpAndSettle();

    // Select payment method
    await tester.tap(find.text('Cash'));
    await tester.pumpAndSettle();

    // Complete payment
    await tester.tap(find.text('Process Payment'));
    await tester.pumpAndSettle();

    // Verify success
    expect(find.text('Payment Success'), findsOneWidget);
  });
}

🔍 Code Review Checklist

For Authors

For Reviewers

🚀 Performance Guidelines

// ✅ Good: Use const constructors
const Text('Hello World')
const SizedBox(height: 16)

// ✅ Good: Extract widgets
class ProductList extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ListView.builder(
      itemBuilder: (context, index) => ProductCard(product: products[index]),
    );
  }
}

// ❌ Bad: Inline complex widgets
ListView.builder(
  itemBuilder: (context, index) {
    return Card(
      child: Column(
        children: [
          // ... many nested widgets
        ],
      ),
    );
  },
)

2. State Management

// ✅ Good: Specific BlocBuilder
BlocBuilder<ProductBloc, ProductState>(
  buildWhen: (previous, current) => previous.products != current.products,
  builder: (context, state) => ProductList(products: state.products),
)

// ❌ Bad: Rebuild entire tree
BlocBuilder<ProductBloc, ProductState>(
  builder: (context, state) => EntireApp(state: state),
)

3. Network Optimization

// ✅ Good: Implement caching
@override
Future<Either<Failure, List<Product>>> getProducts() async {
  // Try local cache first
  final cached = await _localRepository.getProducts();
  if (cached.isNotEmpty) {
    // Return cached data immediately
    _syncInBackground();
    return Right(cached);
  }
  
  // Fetch from API
  final result = await _api.getProducts();
  result.fold(
    (failure) => null,
    (products) => _localRepository.saveProducts(products),
  );
  return result;
}

📊 Monitoring & Logging

Logging Best Practices

// ✅ Good: Structured logging
AppLog.i('cashier', 'transaction_completed', meta: {
  'transaction_id': transaction.id,
  'total': transaction.total,
  'items_count': transaction.items.length,
  'duration_ms': duration.inMilliseconds,
});

// ❌ Bad: Unstructured logging
print('Transaction completed: ${transaction.id}');

Error Tracking

// ✅ Good: Report to Crashlytics
try {
  await repository.createTransaction(transaction);
} catch (e, stackTrace) {
  AppLog.e('transaction', 'create_failed', e, stackTrace);
  FirebaseCrashlytics.instance.recordError(e, stackTrace);
  rethrow;
}

🔐 Security Guidelines

No Hardcoded Secrets

// ❌ Bad
const apiKey = 'sk_live_abc123';

// ✅ Good
final apiKey = dotenv.env['API_KEY'];

Validate User Input

// ✅ Good
if (email.isEmpty || !email.contains('@')) {
  return 'Invalid email';
}

Secure Storage

// ✅ Good: Use encrypted storage
await ConfigLocalService().saveToken(token);

📱 Platform-Specific Guidelines

iOS

Follow iOS Human Interface Guidelines
Use Cupertino widgets when appropriate
Test on multiple iOS versions
Handle safe area insets

Android

Follow Material Design guidelines
Test on different screen sizes
Handle back button properly
Request permissions properly

Next Steps

Remember:

✅ Write clean, readable code
✅ Test your changes
✅ Document complex logic
✅ Follow conventions
✅ Ask for help when needed

Best Practices

Development Guidelines

Development Guidelines

🎯 Development Workflow

1. Setup Development Environment

2. Branch Strategy

3. Commit Convention

4. Pull Request Process

Before Creating PR

PR Template

🏗️ Project Structure

Feature Module Structure

Core Module Structure

📝 Coding Standards

Dart Style Guide

BLoC Pattern

Repository Pattern

🧪 Testing

Unit Tests

Widget Tests

Integration Tests

🔍 Code Review Checklist

For Authors

For Reviewers

🚀 Performance Guidelines

1. Widget Optimization

2. State Management

3. Network Optimization

📊 Monitoring & Logging

Logging Best Practices

Error Tracking

🔐 Security Guidelines

📱 Platform-Specific Guidelines

iOS

Android

Next Steps

Best Practices

Documentation Index

​Development Guidelines

​🎯 Development Workflow

​1. Setup Development Environment

​2. Branch Strategy

​3. Commit Convention

​4. Pull Request Process

​Before Creating PR

​PR Template

​🏗️ Project Structure

​Feature Module Structure

​Core Module Structure

​📝 Coding Standards

​Dart Style Guide

​BLoC Pattern

​Repository Pattern

​🧪 Testing

​Unit Tests

​Widget Tests

​Integration Tests

​🔍 Code Review Checklist

​For Authors

​For Reviewers

​🚀 Performance Guidelines

​1. Widget Optimization

​2. State Management

​3. Network Optimization

​📊 Monitoring & Logging

​Logging Best Practices

​Error Tracking

​🔐 Security Guidelines

​📱 Platform-Specific Guidelines

​iOS

​Android

​Next Steps

Development Guidelines

🎯 Development Workflow

1. Setup Development Environment

2. Branch Strategy

3. Commit Convention

4. Pull Request Process

Before Creating PR

PR Template

🏗️ Project Structure

Feature Module Structure

Core Module Structure

📝 Coding Standards

Dart Style Guide

BLoC Pattern

Repository Pattern

🧪 Testing

Unit Tests

Widget Tests

Integration Tests

🔍 Code Review Checklist

For Authors

For Reviewers

🚀 Performance Guidelines

1. Widget Optimization

2. State Management

3. Network Optimization

📊 Monitoring & Logging

Logging Best Practices

Error Tracking

🔐 Security Guidelines

📱 Platform-Specific Guidelines

iOS

Android

Next Steps