kontenhumas-be/docs/AUTO_APPROVAL_FLOW_GUIDE.md

Auto Approval Flow Guide

🚀 Overview

Sistem auto approval flow memungkinkan artikel untuk otomatis masuk ke workflow approval yang sesuai dengan user level submitter saat artikel dibuat, tanpa perlu manual submit approval.

🔄 How It Works

1. Artikel Creation Process

Ketika user membuat artikel baru:

curl -X POST "http://localhost:8080/api/articles" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer USER_TOKEN" \
  -d '{
    "title": "Sample Article",
    "content": "Article content here",
    "categoryId": 1,
    "isDraft": false
  }'

Sistem akan otomatis:

1. ✅ Detect User Level - Mengambil user level dari JWT token
2. ✅ Check Approval Requirement - Cek apakah user level memerlukan approval
3. ✅ Get Default Workflow - Mengambil workflow default untuk client
4. ✅ Create Approval Flow - Membuat ArticleApprovalFlows record
5. ✅ Initialize Multi-Branch - Menentukan branch dan step pertama yang sesuai
6. ✅ Set Article Status - Set artikel ke status "Pending Approval"

2. Multi-Branch Logic

Sistem akan otomatis menentukan branch yang sesuai berdasarkan:

• User Level Submitter - Level user yang membuat artikel
• Workflow Conditions - Kondisi yang dikonfigurasi di workflow steps
• Branch Rules - Aturan branching yang sudah disetup

Contoh Flow:

User Level 5 membuat artikel
    ↓
Sistem cek workflow conditions
    ↓
Masuk ke "Branch_A" (Level 2 A Branch)
    ↓
Menunggu approval dari User Level 3
    ↓
Setelah approved → masuk ke "Final_Approval"
    ↓
Menunggu approval dari User Level 2
    ↓
Artikel published

📋 Implementation Details

Database Changes

Sistem menggunakan field baru di ArticleApprovalFlows:

-- Multi-branch support fields
current_branch     VARCHAR(100)  -- Current active branch
branch_path        TEXT          -- JSON array tracking path
is_parallel_flow   BOOLEAN       -- Whether parallel flow
parent_flow_id     INT4          -- For parallel flows

Service Integration

// Articles Service - Auto approval flow creation
func (s *articlesService) Save(authToken string, req request.ArticlesCreateRequest) {
    // ... create article ...
    
    // Auto-create approval flow with multi-branch support
    if createdBy.UserLevel.IsApprovalActive {
        approvalFlow := &entity.ArticleApprovalFlows{
            ArticleId:     article.ID,
            WorkflowId:    defaultWorkflow.ID,
            CurrentStep:   1,
            StatusId:      1, // In Progress
            SubmittedById: user.ID,
            SubmittedAt:   time.Now(),
            // Multi-branch fields
            CurrentBranch:  nil, // Will be determined
            BranchPath:     nil, // Will be populated
            IsParallelFlow: false,
        }
        
        // Initialize multi-branch flow
        s.initializeMultiBranchFlow(authToken, flowId, userLevelId)
    }
}

🎯 User Experience

Before (Manual Submit)

1. User creates article
2. User manually submits for approval
3. System creates approval flow
4. Approval process begins

After (Auto Submit)

1. User creates article
2. System automatically:
   - Creates approval flow
   - Determines correct branch
   - Sets first applicable step
   - Notifies approvers
3. Approval process begins immediately

🔧 Configuration

Workflow Setup

Pastikan workflow sudah dikonfigurasi dengan benar:

{
  "name": "Multi-Branch Article Approval",
  "isActive": true,
  "isDefault": true,
  "steps": [
    {
      "stepOrder": 1,
      "stepName": "Level 2 A Branch",
      "requiredUserLevelId": 3,
      "conditionType": "user_level_hierarchy",
      "conditionValue": "{\"applies_to_levels\": [5]}",
      "branchName": "Branch_A"
    },
    {
      "stepOrder": 1,
      "stepName": "Level 2 B Branch", 
      "requiredUserLevelId": 4,
      "conditionType": "user_level_hierarchy",
      "conditionValue": "{\"applies_to_levels\": [6]}",
      "branchName": "Branch_B"
    },
    {
      "stepOrder": 2,
      "stepName": "Level 1 Final Approval",
      "requiredUserLevelId": 2,
      "conditionType": "always",
      "branchName": "Final_Approval"
    }
  ]
}

User Level Configuration

Pastikan user levels sudah dikonfigurasi dengan benar:

-- Check user levels
SELECT id, level_name, level_number, is_approval_active 
FROM user_levels 
WHERE client_id = 'your-client-id'
ORDER BY level_number;

📊 Monitoring & Debugging

Check Auto-Created Flows

-- Check approval flows created automatically
SELECT 
    aaf.id,
    aaf.article_id,
    aaf.current_step,
    aaf.current_branch,
    aaf.status_id,
    aaf.submitted_at,
    a.title,
    u.name as submitter_name,
    ul.level_name as submitter_level
FROM article_approval_flows aaf
JOIN articles a ON aaf.article_id = a.id
JOIN users u ON aaf.submitted_by_id = u.id
JOIN user_levels ul ON u.user_level_id = ul.id
WHERE aaf.created_at >= NOW() - INTERVAL '1 day'
ORDER BY aaf.created_at DESC;

Check Branch Path

-- Check branch path taken
SELECT 
    id,
    article_id,
    current_branch,
    branch_path,
    current_step
FROM article_approval_flows
WHERE branch_path IS NOT NULL
ORDER BY created_at DESC;

API Endpoints for Monitoring

# Check approval status
curl -X GET "http://localhost:8080/api/articles/{article_id}/approval-status" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Check next steps preview
curl -X GET "http://localhost:8080/api/article-approval-flows/{flow_id}/next-steps-preview" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Check my approval queue
curl -X GET "http://localhost:8080/api/article-approval-flows/my-queue" \
  -H "Authorization: Bearer APPROVER_TOKEN"

🚨 Troubleshooting

Common Issues

1. No Approval Flow Created

   • Check if user level has is_approval_active = true
   • Check if default workflow exists
   • Check logs for errors

2. Wrong Branch Selected

   • Check workflow conditions
   • Check user level hierarchy
   • Check condition value JSON format

3. Flow Not Initialized

   • Check initializeMultiBranchFlow method
   • Check FindNextStepsForBranch method
   • Check database constraints

Debug Commands

# Check user level
curl -X GET "http://localhost:8080/api/users/{user_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" | jq '.data.user_levels'

# Check default workflow
curl -X GET "http://localhost:8080/api/approval-workflows/default" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Check workflow steps
curl -X GET "http://localhost:8080/api/approval-workflows/{workflow_id}/with-steps" \
  -H "Authorization: Bearer YOUR_TOKEN"

🎉 Benefits

1. Better UX - User tidak perlu manual submit approval
2. Automatic Routing - Sistem otomatis menentukan branch yang sesuai
3. Immediate Processing - Approval flow dimulai langsung setelah artikel dibuat
4. Consistent Behavior - Semua artikel mengikuti aturan yang sama
5. Reduced Errors - Mengurangi kemungkinan user lupa submit approval

🔄 Migration from Manual Submit

Jika sebelumnya menggunakan manual submit, sistem akan tetap backward compatible:

• Artikel lama tetap bisa menggunakan manual submit
• Artikel baru akan otomatis menggunakan auto-approval flow
• Kedua sistem bisa berjalan bersamaan

📝 Next Steps

Setelah implementasi auto-approval flow:

1. ✅ Test dengan berbagai user levels
2. ✅ Monitor approval flow creation
3. ✅ Verify branch routing logic
4. ✅ Check notification system
5. ✅ Update user documentation
6. ✅ Train users on new workflow

---

Sistem auto approval flow memberikan pengalaman yang lebih seamless dan otomatis untuk proses approval artikel! 🚀