kontenhumas
/
kontenhumas-be
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
kontenhumas-be/docs/MULTI_BRANCH_APPROVAL_GUIDE.md

15 KiB
Raw Permalink Blame History

Multi-Branch Approval System Documentation

Overview

Sistem Multi-Branch Approval memungkinkan pembuatan workflow approval yang dapat bercabang berdasarkan User Level dari submitter artikel. Sistem ini mendukung:

  • Conditional Routing: Approval flow dapat mengikuti jalur berbeda berdasarkan level user yang submit artikel
  • Hierarchical Branching: Support untuk struktur cabang yang kompleks dengan multiple level
  • Parallel Processing: Kemampuan untuk menjalankan multiple approval secara parallel
  • Dynamic Configuration: Workflow dapat dikonfigurasi secara dinamis tanpa mengubah kode

Database Schema Changes

1. ApprovalWorkflowSteps Table

Field baru yang ditambahkan untuk mendukung multi-branch:

-- Multi-branch support fields
ALTER TABLE approval_workflow_steps ADD COLUMN parent_step_id INT REFERENCES approval_workflow_steps(id);
ALTER TABLE approval_workflow_steps ADD COLUMN condition_type VARCHAR(50); -- 'user_level', 'user_level_hierarchy', 'always', 'custom'
ALTER TABLE approval_workflow_steps ADD COLUMN condition_value TEXT; -- JSON string for conditions
ALTER TABLE approval_workflow_steps ADD COLUMN is_parallel BOOLEAN DEFAULT false;
ALTER TABLE approval_workflow_steps ADD COLUMN branch_name VARCHAR(100);
ALTER TABLE approval_workflow_steps ADD COLUMN branch_order INT; -- Order within the same branch

2. ArticleApprovalFlows Table

Field baru untuk tracking branch:

-- Multi-branch support fields
ALTER TABLE article_approval_flows ADD COLUMN current_branch VARCHAR(100); -- Current active branch
ALTER TABLE article_approval_flows ADD COLUMN branch_path TEXT; -- JSON array tracking the path taken
ALTER TABLE article_approval_flows ADD COLUMN is_parallel_flow BOOLEAN DEFAULT false; -- Whether this is a parallel approval flow
ALTER TABLE article_approval_flows ADD COLUMN parent_flow_id INT REFERENCES article_approval_flows(id); -- For parallel flows

API Endpoints

1. Create Multi-Branch Workflow

Endpoint: POST /api/approval-workflows/with-steps

Description: Membuat workflow dengan steps yang mendukung multi-branch routing

Request Body:

{
  "name": "Multi-Branch Article Approval",
  "description": "Approval workflow dengan cabang berdasarkan user level",
  "isActive": true,
  "isDefault": false,
  "requiresApproval": true,
  "autoPublish": false,
  "steps": [
    {
      "stepOrder": 1,
      "stepName": "Level 2 Branch",
      "requiredUserLevelId": 2,
      "canSkip": false,
      "isActive": true,
      "conditionType": "user_level_hierarchy",
      "conditionValue": "{\"applies_to_levels\": [4,5,6,7,8,9]}",
      "branchName": "Branch_A",
      "branchOrder": 1
    },
    {
      "stepOrder": 1,
      "stepName": "Level 3 Branch",
      "requiredUserLevelId": 3,
      "canSkip": false,
      "isActive": true,
      "conditionType": "user_level_hierarchy",
      "conditionValue": "{\"applies_to_levels\": [10,11,12,13,14,15]}",
      "branchName": "Branch_B",
      "branchOrder": 1
    },
    {
      "stepOrder": 2,
      "stepName": "Level 1 Final Approval",
      "requiredUserLevelId": 1,
      "canSkip": false,
      "isActive": true,
      "conditionType": "always",
      "branchName": "Final_Approval",
      "branchOrder": 1
    }
  ]
}

Curl Example:

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": "Approval workflow dengan cabang berdasarkan user level",
    "isActive": true,
    "isDefault": false,
    "requiresApproval": true,
    "autoPublish": false,
    "steps": [
      {
        "stepOrder": 1,
        "stepName": "Level 2 Branch",
        "requiredUserLevelId": 2,
        "canSkip": false,
        "isActive": true,
        "conditionType": "user_level_hierarchy",
        "conditionValue": "{\"applies_to_levels\": [4,5,6,7,8,9]}",
        "branchName": "Branch_A",
        "branchOrder": 1
      },
      {
        "stepOrder": 1,
        "stepName": "Level 3 Branch",
        "requiredUserLevelId": 3,
        "canSkip": false,
        "isActive": true,
        "conditionType": "user_level_hierarchy",
        "conditionValue": "{\"applies_to_levels\": [10,11,12,13,14,15]}",
        "branchName": "Branch_B",
        "branchOrder": 1
      },
      {
        "stepOrder": 2,
        "stepName": "Level 1 Final Approval",
        "requiredUserLevelId": 1,
        "canSkip": false,
        "isActive": true,
        "conditionType": "always",
        "branchName": "Final_Approval",
        "branchOrder": 1
      }
    ]
  }'

2. Submit Article for Multi-Branch Approval

Endpoint: POST /api/articles/{id}/submit-approval

Description: Submit artikel untuk approval dengan multi-branch workflow

Curl Example:

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

3. Process Multi-Branch Approval

Endpoint: POST /api/article-approval-flows/{id}/multi-branch-approve

Description: Proses approval dengan multi-branch logic

Request Body:

{
  "message": "Article looks good, approved for next level"
}

Curl Example:

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"
  }'

4. Get Next Steps Preview

Endpoint: GET /api/article-approval-flows/{id}/next-steps-preview

Description: Mendapatkan preview next steps berdasarkan user level submitter

Curl Example:

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

Response Example:

{
  "success": true,
  "messages": ["Next steps preview successfully retrieved"],
  "data": {
    "current_step": 1,
    "submitter_level_id": 5,
    "next_steps": [
      {
        "id": 2,
        "stepOrder": 2,
        "stepName": "Level 1 Final Approval",
        "requiredUserLevelId": 1,
        "branchName": "Final_Approval",
        "conditionType": "always"
      }
    ],
    "total_next_steps": 1
  }
}

Condition Types

1. user_level

Steps yang berlaku untuk user level tertentu.

Condition Value Format:

[4, 5, 6, 7, 8, 9]

2. user_level_hierarchy

Steps yang berlaku berdasarkan hierarki user level dengan kondisi yang lebih kompleks.

Condition Value Format:

{
  "applies_to_levels": [4, 5, 6, 7, 8, 9],
  "min_level": 4,
  "max_level": 9
}

3. always

Steps yang selalu berlaku untuk semua user level.

Condition Value: null atau "{}"

4. custom

Steps dengan kondisi custom (untuk ekstensi masa depan).

Workflow Examples

Example 1: Simple Two-Branch Workflow

{
  "name": "Simple Two-Branch Approval",
  "description": "Workflow dengan 2 cabang berdasarkan user level",
  "steps": [
    {
      "stepOrder": 1,
      "stepName": "Branch A - Level 2",
      "requiredUserLevelId": 2,
      "conditionType": "user_level_hierarchy",
      "conditionValue": "{\"applies_to_levels\": [4,5,6]}",
      "branchName": "Branch_A"
    },
    {
      "stepOrder": 1,
      "stepName": "Branch B - Level 3",
      "requiredUserLevelId": 3,
      "conditionType": "user_level_hierarchy",
      "conditionValue": "{\"applies_to_levels\": [7,8,9]}",
      "branchName": "Branch_B"
    },
    {
      "stepOrder": 2,
      "stepName": "Final Approval",
      "requiredUserLevelId": 1,
      "conditionType": "always",
      "branchName": "Final"
    }
  ]
}

Example 2: Complex Multi-Level Branching

{
  "name": "Complex Multi-Level Branching",
  "description": "Workflow dengan multiple level branching",
  "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": "Sub-branch A1",
      "requiredUserLevelId": 4,
      "parentStepId": 1,
      "conditionType": "user_level_hierarchy",
      "conditionValue": "{\"applies_to_levels\": [4,5,6]}",
      "branchName": "SubBranch_A1"
    },
    {
      "stepOrder": 2,
      "stepName": "Sub-branch A2",
      "requiredUserLevelId": 5,
      "parentStepId": 1,
      "conditionType": "user_level_hierarchy",
      "conditionValue": "{\"applies_to_levels\": [7,8,9]}",
      "branchName": "SubBranch_A2"
    },
    {
      "stepOrder": 3,
      "stepName": "Level 1 Final Approval",
      "requiredUserLevelId": 1,
      "conditionType": "always",
      "branchName": "Final_Approval"
    }
  ]
}

Flow Logic

1. Article Submission Flow

  1. User dengan level tertentu submit artikel
  2. Sistem menentukan workflow yang akan digunakan
  3. Sistem mencari step pertama yang applicable berdasarkan user level submitter
  4. Artikel masuk ke approval flow dengan step yang sesuai

2. Approval Processing Flow

  1. Approver melakukan approval pada step saat ini
  2. Sistem mencari next steps yang applicable berdasarkan:
    • User level submitter
    • Condition type dan value
    • Branch logic
  3. Jika ada multiple next steps, sistem akan:
    • Untuk parallel branches: buat multiple approval flows
    • Untuk sequential branches: pilih step pertama yang applicable
  4. Update artikel status sesuai dengan step yang dicapai

3. Branch Determination Logic

func IsStepApplicableForLevel(step *ApprovalWorkflowSteps, submitterLevelId uint) bool {
    switch step.ConditionType {
    case "user_level":
        // Check if submitter level is in allowed levels
        return contains(allowedLevels, submitterLevelId)
    
    case "user_level_hierarchy":
        // Check based on hierarchy rules
        return checkHierarchyRules(submitterLevelId, step.ConditionValue)
    
    case "always":
        return true
    
    default:
        return true
    }
}

Error Handling

Common Error Responses

  1. Invalid Condition Value:
{
  "success": false,
  "messages": ["Invalid condition value format"],
  "error": "CONDITION_VALUE_INVALID"
}
  1. No Applicable Steps:
{
  "success": false,
  "messages": ["No applicable next steps found for this user level"],
  "error": "NO_APPLICABLE_STEPS"
}
  1. Workflow Not Found:
{
  "success": false,
  "messages": ["Workflow not found"],
  "error": "WORKFLOW_NOT_FOUND"
}

Testing

Test Scenarios

  1. Basic Branching Test:

    • Submit artikel dari user level 5
    • Verify artikel masuk ke Branch A (Level 2)
    • Approve dan verify masuk ke Final Approval

  2. Multiple Branch Test:

    • Submit artikel dari user level 8
    • Verify artikel masuk ke Branch A (Level 2)
    • Submit artikel dari user level 12
    • Verify artikel masuk ke Branch B (Level 3)

  3. Condition Validation Test:

    • Test dengan condition value yang invalid
    • Test dengan user level yang tidak ada di condition
    • Test dengan condition type yang tidak supported

Test Data Setup

-- Insert test user levels
INSERT INTO user_levels (name, level_number, is_active) VALUES
('Level 1', 1, true),
('Level 2', 2, true),
('Level 3', 3, true),
('Level 4', 4, true),
('Level 5', 5, true);

-- Insert test users
INSERT INTO users (username, email, user_level_id) VALUES
('user_level_5', 'user5@test.com', 5),
('user_level_8', 'user8@test.com', 8),
('user_level_12', 'user12@test.com', 12);

Migration Guide

From Linear to Multi-Branch

  1. Backup existing data:
CREATE TABLE approval_workflow_steps_backup AS SELECT * FROM approval_workflow_steps;
CREATE TABLE article_approval_flows_backup AS SELECT * FROM article_approval_flows;
  1. Add new columns:
-- Run the ALTER TABLE statements mentioned above
  1. Migrate existing workflows:
-- Set default values for existing steps
UPDATE approval_workflow_steps SET 
  condition_type = 'always',
  branch_name = 'default_branch',
  branch_order = step_order
WHERE condition_type IS NULL;
  1. Test migration:
    • Verify existing workflows still work
    • Test new multi-branch functionality
    • Rollback if issues found

Performance Considerations

  1. Database Indexes:
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);

  1. Caching:

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

  2. Query Optimization:

    • Use proper JOINs for branch queries
    • Limit result sets with pagination
    • Use prepared statements for repeated queries

Security Considerations

  1. 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

  2. Data Validation:

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

  3. Audit Trail:

    • Log all branch decisions
    • Track condition evaluations
    • Maintain approval history with branch information

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

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

# Check next steps for specific flow
curl -X GET "http://localhost:8080/api/article-approval-flows/123/next-steps-preview" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Check user level
curl -X GET "http://localhost:8080/api/users/456" \
  -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