kontenhumas-be/docs/MULTI_BRANCH_IMPLEMENTATION_README.md

# Multi-Branch Approval System Implementation

## 🎯 Overview

Sistem Multi-Branch Approval telah berhasil diimplementasikan untuk mendukung workflow approval yang dapat bercabang berdasarkan User Level dari submitter artikel. Implementasi ini memungkinkan:

- **Conditional Routing**: Approval flow mengikuti jalur berbeda berdasarkan level user yang submit artikel
- **Hierarchical Branching**: Support untuk struktur cabang yang kompleks dengan multiple level
- **Dynamic Configuration**: Workflow dapat dikonfigurasi secara dinamis tanpa mengubah kode
- **Backward Compatibility**: Sistem lama tetap berfungsi tanpa perubahan

## 🚀 Quick Start

### 1. Database Migration

Jalankan script migration untuk menambahkan support multi-branch:

```bash
# Jalankan migration script
psql -d your_database -f docs/migrations/add_multi_branch_support.sql
```

### 2. Create Multi-Branch Workflow

```bash
curl -X POST "http://localhost:8080/api/approval-workflows/with-steps" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Multi-Branch Article Approval",
    "description": "Workflow dengan cabang berdasarkan user level",
    "isActive": true,
    "steps": [
      {
        "stepOrder": 1,
        "stepName": "Level 2 Branch",
        "requiredUserLevelId": 2,
        "conditionType": "user_level_hierarchy",
        "conditionValue": "{\"applies_to_levels\": [4,5,6,7,8,9]}",
        "branchName": "Branch_A"
      },
      {
        "stepOrder": 1,
        "stepName": "Level 3 Branch",
        "requiredUserLevelId": 3,
        "conditionType": "user_level_hierarchy",
        "conditionValue": "{\"applies_to_levels\": [10,11,12,13,14,15]}",
        "branchName": "Branch_B"
      },
      {
        "stepOrder": 2,
        "stepName": "Level 1 Final Approval",
        "requiredUserLevelId": 1,
        "conditionType": "always",
        "branchName": "Final_Approval"
      }
    ]
  }'
```

### 3. Submit Article untuk Approval

```bash
curl -X POST "http://localhost:8080/api/articles/123/submit-approval" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "workflowId": 1
  }'
```

### 4. Process Multi-Branch Approval

```bash
curl -X POST "http://localhost:8080/api/article-approval-flows/456/multi-branch-approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "message": "Article looks good, approved for next level"
  }'
```

## 📁 File Changes

### Database Entities

1. **`app/database/entity/approval_workflow_steps.entity.go`**
   - Added multi-branch support fields
   - Added parent-child relationships
   - Added condition types and values

2. **`app/database/entity/article_approval_flows.entity.go`**
   - Added branch tracking fields
   - Added parallel flow support
   - Added parent-child flow relationships

### Service Layer

3. **`app/module/approval_workflow_steps/repository/approval_workflow_steps.repository.go`**
   - Added multi-branch query methods
   - Added condition-based filtering
   - Added branch-specific queries

4. **`app/module/article_approval_flows/service/article_approval_flows.service.go`**
   - Added multi-branch approval processing
   - Added condition evaluation logic
   - Added branch determination methods

### API Layer

5. **`app/module/approval_workflows/request/approval_workflows.request.go`**
   - Added multi-branch fields to request structures
   - Updated entity conversion methods

6. **`app/module/article_approval_flows/controller/article_approval_flows.controller.go`**
   - Added multi-branch approval endpoints
   - Added next steps preview endpoint

## 🔧 Configuration

### Condition Types

1. **`user_level`**: Steps berlaku untuk user level tertentu
   ```json
   "conditionValue": "[4, 5, 6]"
   ```

2. **`user_level_hierarchy`**: Steps berlaku berdasarkan hierarki
   ```json
   "conditionValue": "{\"applies_to_levels\": [4,5,6], \"min_level\": 4, \"max_level\": 9}"
   ```

3. **`always`**: Steps selalu berlaku
   ```json
   "conditionValue": "{}"
   ```

4. **`custom`**: Steps dengan kondisi custom (untuk ekstensi masa depan)

### Branch Configuration

- **`branchName`**: Nama cabang untuk identifikasi
- **`branchOrder`**: Urutan dalam cabang yang sama
- **`parentStepId`**: ID step parent untuk hierarchical branching
- **`isParallel`**: Apakah step ini berjalan parallel

## 📊 Flow Examples

### Example 1: User Level 5 Submit Article

```
User Level 5 → Branch A (Level 2) → Final Approval (Level 1)
```

### Example 2: User Level 8 Submit Article

```
User Level 8 → Branch A (Level 2) → Final Approval (Level 1)
```

### Example 3: User Level 12 Submit Article

```
User Level 12 → Branch B (Level 3) → Final Approval (Level 1)
```

## 🧪 Testing

### Test Scenarios

1. **Basic Branching Test**:
   ```bash
   # Submit dari user level 5
   curl -X POST "http://localhost:8080/api/articles/123/submit-approval" \
     -H "Authorization: Bearer USER_LEVEL_5_TOKEN" \
     -d '{"workflowId": 1}'
   
   # Check next steps
   curl -X GET "http://localhost:8080/api/article-approval-flows/456/next-steps-preview" \
     -H "Authorization: Bearer USER_LEVEL_5_TOKEN"
   ```

2. **Multiple Branch Test**:
   ```bash
   # Test dengan user level berbeda
   curl -X POST "http://localhost:8080/api/articles/124/submit-approval" \
     -H "Authorization: Bearer USER_LEVEL_12_TOKEN" \
     -d '{"workflowId": 1}'
   ```

### Performance Testing

```bash
# Load testing dengan multiple submissions
for i in {1..100}; do
  curl -X POST "http://localhost:8080/api/articles/$i/submit-approval" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -d '{"workflowId": 1}' &
done
wait
```

## 🔍 Monitoring

### Check Workflow Status

```bash
# Get workflow dengan steps
curl -X GET "http://localhost:8080/api/approval-workflows/1/with-steps" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get next steps preview
curl -X GET "http://localhost:8080/api/article-approval-flows/456/next-steps-preview" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Dashboard Statistics

```bash
# Get approval statistics
curl -X GET "http://localhost:8080/api/article-approval-flows/dashboard-stats" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## 🚨 Error Handling

### Common Errors

1. **No Applicable Steps**:
   ```json
   {
     "success": false,
     "messages": ["No applicable next steps found for this user level"],
     "error": "NO_APPLICABLE_STEPS"
   }
   ```

2. **Invalid Condition Value**:
   ```json
   {
     "success": false,
     "messages": ["Invalid condition value format"],
     "error": "CONDITION_VALUE_INVALID"
   }
   ```

3. **Workflow Not Found**:
   ```json
   {
     "success": false,
     "messages": ["Workflow not found"],
     "error": "WORKFLOW_NOT_FOUND"
   }
   ```

## 🔄 Migration Guide

### From Linear to Multi-Branch

1. **Backup existing data**:
   ```sql
   CREATE TABLE approval_workflow_steps_backup AS SELECT * FROM approval_workflow_steps;
   CREATE TABLE article_approval_flows_backup AS SELECT * FROM article_approval_flows;
   ```

2. **Run migration script**:
   ```bash
   psql -d your_database -f docs/migrations/add_multi_branch_support.sql
   ```

3. **Test migration**:
   - Verify existing workflows still work
   - Test new multi-branch functionality
   - Rollback if issues found

### Rollback (if needed)

```sql
-- Uncomment rollback section in migration script
-- Run rollback commands to revert changes
```

## 📈 Performance Considerations

### Database Indexes

```sql
-- Indexes untuk performance
CREATE INDEX idx_approval_workflow_steps_condition ON approval_workflow_steps(condition_type, branch_name);
CREATE INDEX idx_article_approval_flows_branch ON article_approval_flows(current_branch);
```

### Caching Strategy

- Cache workflow steps by condition type
- Cache user level mappings
- Cache branch determination results

## 🔒 Security

### Access Control

- Validate user permissions for each approval step
- Ensure users can only approve steps they're authorized for
- Log all approval actions for audit

### Data Validation

- Validate condition values before processing
- Sanitize JSON input in condition_value
- Check for SQL injection in dynamic queries

## 🐛 Troubleshooting

### Common Issues

1. **Steps Not Found**:
   - Check condition_type and condition_value
   - Verify user level mapping
   - Check workflow activation status

2. **Infinite Loops**:
   - Validate step dependencies
   - Check for circular references in parent_step_id
   - Ensure proper step ordering

3. **Performance Issues**:
   - Check database indexes
   - Optimize condition evaluation queries
   - Consider caching strategies

### Debug Commands

```bash
# Check workflow steps
curl -X GET "http://localhost:8080/api/approval-workflows/1/with-steps" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Check user level
curl -X GET "http://localhost:8080/api/users/456" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Check approval flow status
curl -X GET "http://localhost:8080/api/article-approval-flows/123" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## 🚀 Future Enhancements

1. **Visual Workflow Designer**: UI untuk membuat workflow secara visual
2. **Condition Builder**: UI untuk membuat kondisi tanpa JSON manual
3. **Workflow Templates**: Template workflow untuk berbagai use case
4. **Advanced Branching**: Support untuk conditional branching yang lebih kompleks
5. **Parallel Processing**: True parallel approval processing
6. **Workflow Analytics**: Analytics untuk workflow performance dan bottlenecks

## 📚 Documentation

- [Multi-Branch Approval Guide](docs/MULTI_BRANCH_APPROVAL_GUIDE.md)
- [Curl Examples](docs/MULTI_BRANCH_CURL_EXAMPLES.md)
- [Database Migration](docs/migrations/add_multi_branch_support.sql)

## 🤝 Support

Untuk pertanyaan atau masalah dengan implementasi multi-branch approval system, silakan:

1. Check dokumentasi lengkap di `docs/` folder
2. Review curl examples untuk testing
3. Check troubleshooting section
4. Contact development team untuk support lebih lanjut

---

**Status**: ✅ Implementasi selesai dan siap untuk production
**Version**: 1.0.0
**Last Updated**: $(date)