EAS-202310715274-DimasHendriPamungkas/MAINTENANCE_GUIDE.md

# 🔄 MAINTENANCE & UPDATE GUIDE

## 📋 Overview
Panduan untuk developer yang ingin membuat update, bug fix, atau enhancement di masa depan.

---

## 🐛 Bug Fix Procedure

### Step 1: Identify the Bug
```
Which screen?     → LoginScreen, MenuScreen, AttendanceScreen, SuccessScreen
What's wrong?     → Visual, Logic, Navigation, Data, Other
Severity?         → Critical, High, Medium, Low
Reproducible?     → Always, Sometimes, Rarely, Never
```

### Step 2: Find Relevant Documentation
1. Check QUICK_REFERENCE_UI.md - quick overview
2. Check specific screen docs in UI_IMPLEMENTATION_SUMMARY.md
3. Check TESTING_GUIDE.md - expected behavior
4. Check MOCKUP_IMPLEMENTATION.md - design specs

### Step 3: Locate Code File
```
LoginScreen issues     → app/src/main/java/.../presentation/screens/LoginScreen.kt
MenuScreen issues      → app/src/main/java/.../presentation/screens/MenuScreen.kt
AttendanceScreen issues → app/src/main/java/.../presentation/screens/AttendanceScreen.kt
SuccessScreen issues   → app/src/main/java/.../presentation/screens/SuccessScreen.kt
Navigation issues      → app/src/main/java/.../MainActivity.kt
Mata kuliah issues     → AttendanceScreen.kt + MainActivity.kt
```

### Step 4: Make Changes
```kotlin
// Before making changes:
1. Read the complete function/composable
2. Understand the current flow
3. Identify root cause
4. Make minimal changes only

// Example bug fix structure:
@Composable
fun ScreenName() {
    // ... existing code ...
    
    // BUG FIX: Description of bug and fix
    // Old: if (isLoading) { ... }
    // New: if (isLoading && photo != null) { ... }
    
    // ... rest of code ...
}
```

### Step 5: Test the Fix
```
1. Follow relevant test cases from TESTING_GUIDE.md
2. Test the specific feature that was fixed
3. Test surrounding features (regression)
4. Test navigation related to the bug
5. Document test results
```

### Step 6: Update Documentation (if needed)
```
If behavior changed:
  → Update TESTING_GUIDE.md
  → Update relevant doc file
  → Update QUICK_REFERENCE_UI.md

If visual changed:
  → Update MOCKUP_IMPLEMENTATION.md
  → Update UI_IMPLEMENTATION_SUMMARY.md
```

---

## ✨ Feature Addition Procedure

### Step 1: Plan the Feature
```
Feature name:     _________________
Affects screens:  _________________
New files needed: _________________
Related features: _________________
Database changes: _________________
```

### Step 2: Study Existing Patterns

#### Pattern 1: Input Field (Like Mata Kuliah)
```kotlin
// Location: AttendanceScreen.kt, line ~340

Card(
    modifier = Modifier.fillMaxWidth(),
    colors = CardDefaults.cardColors(
        containerColor = Color(0xFF2E7D32).copy(alpha = 0.1f)
    ),
    shape = RoundedCornerShape(8.dp)
) {
    Column(modifier = Modifier.padding(12.dp)) {
        // Icon + Title
        Row(
            modifier = Modifier.fillMaxWidth(),
            verticalAlignment = Alignment.CenterVertically,
            horizontalArrangement = Arrangement.spacedBy(8.dp)
        ) {
            Icon(Icons.Default.Info, ...)
            Text("Field Name", style = MaterialTheme.typography.labelMedium)
        }
        Spacer(modifier = Modifier.height(8.dp))
        
        // Input
        OutlinedTextField(
            value = fieldValue,
            onValueChange = { fieldValue = it },
            modifier = Modifier.fillMaxWidth().height(40.dp),
            placeholder = { Text("Placeholder", fontSize = 12.sp) },
            singleLine = true,
            enabled = !isLoading
        )
    }
}
```

#### Pattern 2: Action Button
```kotlin
Button(
    onClick = { /* action */ },
    modifier = Modifier
        .fillMaxWidth()
        .height(44.dp),
    enabled = !isLoading && condition,
    colors = ButtonDefaults.buttonColors(
        containerColor = Color(0xFF2E7D32),
        contentColor = Color.White
    ),
    shape = RoundedCornerShape(8.dp)
) {
    if (isLoading) {
        CircularProgressIndicator(modifier = Modifier.size(18.dp), ...)
    } else {
        Icon(Icons.Default.Something, ..., modifier = Modifier.size(16.dp), ...)
        Spacer(modifier = Modifier.width(8.dp))
        Text("BUTTON TEXT", fontSize = 14.sp, fontWeight = FontWeight.Bold)
    }
}
```

#### Pattern 3: Status Card
```kotlin
Card(
    modifier = Modifier.fillMaxWidth(),
    colors = CardDefaults.cardColors(
        containerColor = Color(0xFF2E7D32).copy(alpha = 0.1f)
    ),
    shape = RoundedCornerShape(8.dp)
) {
    Column(modifier = Modifier.padding(12.dp)) {
        Row(
            modifier = Modifier.fillMaxWidth(),
            verticalAlignment = Alignment.CenterVertically,
            horizontalArrangement = Arrangement.spacedBy(8.dp)
        ) {
            Icon(
                Icons.Default.CheckCircle,
                tint = if (isValid) Color(0xFF4CAF50) else Color(0xFFf44336),
                modifier = Modifier.size(20.dp)
            )
            Text(
                text = if (isValid) "Status: Valid" else "Status: Invalid",
                style = MaterialTheme.typography.labelMedium,
                color = if (isValid) Color(0xFF4CAF50) else Color(0xFFf44336)
            )
        }
    }
}
```

### Step 3: Implement Feature
```
1. Create input field or button following pattern
2. Add state variable (var feature by remember { mutableStateOf(...) })
3. Add validation logic
4. Add event handler
5. Update submit validation if needed
6. Test with existing flows
```

### Step 4: Update Navigation (if new screen)
```kotlin
// In MainActivity.kt

composable("new_screen") {
    if (currentNpm != null && currentNama != null) {
        NewScreen(
            npm = currentNpm!!,
            nama = currentNama!!,
            onNavigateBack = {
                navController.navigateUp()
            }
        )
    }
}

// Add route from existing screen:
onNewFeature = {
    navController.navigate("new_screen")
}
```

### Step 5: Test Feature
```
1. Unit test (if applicable)
2. Integration test with existing screens
3. Navigation test
4. Data persistence test
5. Error handling test
```

### Step 6: Document Feature
```
Create/Update:
  1. QUICK_REFERENCE_UI.md - add to feature list
  2. New feature doc (like MATA_KULIAH_FEATURE.md)
  3. TESTING_GUIDE.md - add test cases
  4. IMPLEMENTATION_CHECKLIST.md - update status
  5. MOCKUP_IMPLEMENTATION.md - if visual change
```

---

## 🎨 UI/Design Update Procedure

### Step 1: Identify What Changed
```
What needs to change?
  [ ] Colors (#2E7D32, #FFFFFF, #4CAF50, #f44336)
  [ ] Spacing (12dp, 16dp, 24dp)
  [ ] Font sizes
  [ ] Border radius
  [ ] Icons
  [ ] Layout structure
```

### Step 2: Update Colors Globally
```kotlin
// If primary color needs change:
// Search for: Color(0xFF2E7D32)
// Replace with: Color(0xFFNEWCOLOR)

// Files to check:
// - All screen files
// - MainActivity.kt
// - Any theme files
```

### Step 3: Update Typography
```kotlin
// If font size needs change:
// Example: fontSize = 14.sp → fontSize = 16.sp

// Common sizes used:
// Button text: 14sp (bold)
// Labels: 12-14sp
// Titles: 20-28sp
// Body: 14-16sp
```

### Step 4: Update Spacing
```kotlin
// If padding needs change:
// Example: padding = 16.dp → padding = 20.dp

// Common spacing:
// Inside cards: 12dp
// Between items: 12-16dp
// Page margins: 24dp
// Border radius: 8-12dp
```

### Step 5: Verify Consistency
```
After changes, check:
[ ] All screens have same primary color
[ ] All buttons same size and style
[ ] All cards same padding and radius
[ ] Text hierarchy consistent
[ ] Icons same size throughout
[ ] Colors match design system
```

### Step 6: Update Documentation
```
Update these files:
  1. MOCKUP_IMPLEMENTATION.md - design specs
  2. UI_IMPLEMENTATION_SUMMARY.md - color section
  3. QUICK_REFERENCE_UI.md - visual changes
  4. TESTING_GUIDE.md - visual test cases
```

---

## 📦 Database/Backend Changes

### If Mata Kuliah Storage Changes
```kotlin
// File: Attendance.kt
data class Attendance(
    val npm: String,
    val nama: String,
    val latitude: Double,
    val longitude: Double,
    val timestamp: Long,
    val fotoBase64: String,
    val mataPelajaran: String,  // Already exists!
    val status: String
)

// No changes needed if field already exists
```

### If New Field Added
```kotlin
// 1. Update Attendance model
data class Attendance(
    // ... existing fields ...
    val mataPelajaran: String,
    val newField: String  // ← Add new field
)

// 2. Update Room DAO
// 3. Update AttendanceRepository
// 4. Update N8N webhook format
// 5. Update database migration (if needed)
// 6. Update TESTING_GUIDE.md
```

### If N8N Integration Changes
```
1. Update repository.sendToN8n() in AttendanceRepository.kt
2. Update JSON structure in N8N_WEBHOOK_GUIDE.md
3. Test with actual N8N endpoint
4. Verify data arrives correctly
5. Update documentation
```

---

## 🧪 Testing After Changes

### Minimal Testing (Bug Fix)
```
1. Test affected screen
2. Test navigation from/to affected screen
3. Test data related to fix
4. Follow specific test case from TESTING_GUIDE.md
```

### Standard Testing (Small Feature)
```
1. Test new feature functionality
2. Test integration with existing features
3. Test navigation flow
4. Test data persistence
5. Follow related test cases from TESTING_GUIDE.md
```

### Comprehensive Testing (Large Feature)
```
1. Follow all test cases in TESTING_GUIDE.md
2. Test all navigation paths
3. Test all data flows
4. Test error conditions
5. Test on multiple device sizes
6. Test on multiple Android versions
```

---

## 📝 Documentation Update Checklist

After any change:
```
[ ] Updated relevant code file(s)
[ ] Updated QUICK_REFERENCE_UI.md (if major change)
[ ] Updated specific feature doc (if applicable)
[ ] Updated TESTING_GUIDE.md (add/remove test cases)
[ ] Updated IMPLEMENTATION_CHECKLIST.md (status)
[ ] Updated MOCKUP_IMPLEMENTATION.md (if visual change)
[ ] Updated DOCUMENTATION_INDEX.md (if new doc)
[ ] Added comments in code
[ ] Updated this file if new pattern
```

---

## 🚀 Deployment Process

### Before Deployment
```
[ ] All tests pass
[ ] No compilation errors
[ ] No warnings
[ ] Code review approved
[ ] Documentation updated
[ ] QA sign-off received
[ ] Mata kuliah feature verified (if changed)
```

### Deployment Steps
```
1. Create release branch: git checkout -b release/v1.1.0
2. Update version number (if applicable)
3. Create release notes
4. Tag release: git tag v1.1.0
5. Deploy to production
6. Monitor for issues
7. Document any issues
```

### Post-Deployment
```
[ ] Monitor for user reports
[ ] Check N8N webhook receiving data correctly
[ ] Verify mata kuliah data saved in database
[ ] Check server logs for errors
[ ] Gather user feedback
[ ] Plan next improvements
```

---

## 📚 Documentation File Reference

When making changes, which file to update:

| Change Type | Primary | Secondary |
|------------|---------|-----------|
| New screen | QUICK_REFERENCE_UI, UI_IMPLEMENTATION_SUMMARY | MOCKUP_IMPLEMENTATION |
| New feature | Feature doc (new or existing) | TESTING_GUIDE, QUICK_REFERENCE_UI |
| Bug fix | Code only | None (unless behavior change) |
| Color change | UI_IMPLEMENTATION_SUMMARY | All screen docs |
| Layout change | UI_IMPLEMENTATION_SUMMARY | MOCKUP_IMPLEMENTATION |
| Navigation | QUICK_REFERENCE_UI | UI_IMPLEMENTATION_SUMMARY |
| Mata kuliah change | MATA_KULIAH_FEATURE | TESTING_GUIDE |
| Testing change | TESTING_GUIDE | None |

---

## 🔗 Quick Links

Documentation Files:
- Main entry: `DOCUMENTATION_INDEX.md`
- Quick info: `QUICK_REFERENCE_UI.md`
- Design specs: `UI_IMPLEMENTATION_SUMMARY.md`
- Feature docs: `MATA_KULIAH_FEATURE.md`
- Testing: `TESTING_GUIDE.md`
- Status: `IMPLEMENTATION_CHECKLIST.md`

Code Files:
- Login: `presentation/screens/LoginScreen.kt`
- Menu: `presentation/screens/MenuScreen.kt`
- Attendance: `presentation/screens/AttendanceScreen.kt`
- Success: `presentation/screens/SuccessScreen.kt`
- Navigation: `MainActivity.kt`

---

## 💡 Tips for Maintainers

### When Making Changes
```
✅ DO:
  - Read existing code first
  - Follow established patterns
  - Update documentation
  - Test thoroughly
  - Keep changes focused
  - Add helpful comments
  - Consider backward compatibility

❌ DON'T:
  - Make random changes
  - Skip testing
  - Ignore documentation
  - Break existing features
  - Change colors randomly
  - Remove comments
  - Make massive changes at once
```

### Code Review Checklist
```
[ ] Code follows existing patterns
[ ] Color scheme consistent
[ ] Navigation correct
[ ] Data properly handled
[ ] Error cases handled
[ ] Comments clear
[ ] Documentation updated
[ ] Tests pass
[ ] No breaking changes
```

---

## 📞 Troubleshooting Maintenance Issues

### Issue: Color looks wrong
**Check**: 
1. Hex code correct (#2E7D32)?
2. Alpha value correct (.copy(alpha = 0.1f))?
3. Used in right place (button, card, background)?

### Issue: Feature doesn't work
**Check**:
1. State variable initialized?
2. Event handler attached?
3. Navigation route correct?
4. Data passed correctly?

### Issue: Navigation broken
**Check**:
1. Route name spelled correctly?
2. onNavigate callback correct?
3. NavController reference correct?
4. Pop-up behavior correct?

### Issue: Documentation mismatch
**Check**:
1. Code matches doc?
2. Changes documented?
3. Test cases updated?
4. All files consistent?

---

## 📋 Version History

| Version | Date | Changes | Status |
|---------|------|---------|--------|
| 1.0.0 | 2026-01-14 | Initial implementation | ✅ |
| Future | TBD | Enhancement ideas | 📋 |

---

## 🎓 Learning Resources for Maintainers

### Kotlin & Compose
- Official Kotlin docs: https://kotlinlang.org/docs/
- Jetpack Compose: https://developer.android.com/jetpack/compose
- Material 3: https://m3.material.io/

### Android Development
- Android Developers: https://developer.android.com/
- Navigation: https://developer.android.com/guide/navigation
- Coroutines: https://kotlinlang.org/docs/coroutines-overview.html

### Design Patterns
- MVVM: Model-View-ViewModel architecture
- Repository: Separation of concerns
- Dependency Injection: Loose coupling

---

**Last Updated**: January 14, 2026
**Maintained by**: Development Team
**Status**: Ready for use