kontenhumas-be/docs/ENHANCED_APPROVAL_ACTIONS_API.md

# Enhanced Approval Actions API

## 🚀 **Overview**

API ini telah ditingkatkan untuk mendukung 3 jenis action approval yang berbeda: **Approve**, **Request Update**, dan **Reject**. Setiap action memiliki behavior yang berbeda sesuai dengan kebutuhan workflow.

## 📋 **Endpoint**

```
POST /api/article-approval-flows/articles/{articleId}/approve
```

## 🔧 **Request Body**

```json
{
  "action": "approve",
  "message": "Content looks good, approved for next level"
}
```

## 📝 **Action Types**

### **1. Approve (`approve`)**
- **Behavior**: Naik ke step berikutnya dalam workflow
- **Use Case**: Content sudah sesuai dan siap untuk step selanjutnya
- **Result**: Article akan diproses menggunakan multi-branch logic

### **2. Revision (`revision`)**
- **Behavior**: Mundur 1 step dalam workflow
- **Use Case**: Content perlu diperbaiki tapi masih bisa diperbaiki
- **Result**: Article akan kembali ke step sebelumnya untuk revisi

### **3. Reject (`reject`)**
- **Behavior**: Balik ke status Draft
- **Use Case**: Content tidak sesuai dan perlu dibuat ulang
- **Result**: Article akan dikembalikan ke status draft dan workflow dihentikan

## 📤 **Response Examples**

### **Approve Response (200):**
```json
{
  "success": true,
  "messages": ["Article successfully approve through active approval flow"],
  "data": {
    "article_id": 123,
    "flow_id": 456,
    "action": "approve",
    "current_step": 2,
    "current_branch": "Branch_A",
    "workflow_id": 1
  }
}
```

### **Revision Response (200):**
```json
{
  "success": true,
  "messages": ["Article successfully revision through active approval flow"],
  "data": {
    "article_id": 123,
    "flow_id": 456,
    "action": "revision",
    "current_step": 1,
    "current_branch": "Branch_A",
    "workflow_id": 1
  }
}
```

### **Reject Response (200):**
```json
{
  "success": true,
  "messages": ["Article successfully reject through active approval flow"],
  "data": {
    "article_id": 123,
    "flow_id": 456,
    "action": "reject",
    "current_step": 1,
    "current_branch": "Branch_A",
    "workflow_id": 1
  }
}
```

## 🧪 **Curl Examples**

### **1. Approve Article:**
```bash
curl -X POST "http://localhost:8080/api/article-approval-flows/articles/123/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "action": "approve",
    "message": "Content reviewed and approved. Ready for next level."
  }'
```

### **2. Request Revision:**
```bash
curl -X POST "http://localhost:8080/api/article-approval-flows/articles/123/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "action": "revision",
    "message": "Please fix the grammar and improve the conclusion section."
  }'
```

### **3. Reject Article:**
```bash
curl -X POST "http://localhost:8080/api/article-approval-flows/articles/123/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "action": "reject",
    "message": "Content does not meet our quality standards. Please rewrite the entire article."
  }'
```

## 🔄 **Workflow Behavior**

### **Approve Flow:**
1. **Input**: `{"action": "approve", "message": "..."}`
2. **Process**: Menggunakan multi-branch approval logic
3. **Result**: Article naik ke step berikutnya
4. **Status**: Workflow berlanjut

### **Revision Flow:**
1. **Input**: `{"action": "revision", "message": "..."}`
2. **Process**: 
   - Current step dikurangi 1
   - `revision_requested` = true
   - `revision_message` = message
3. **Result**: Article kembali ke step sebelumnya
4. **Status**: Workflow berlanjut tapi mundur 1 step

### **Reject Flow:**
1. **Input**: `{"action": "reject", "message": "..."}`
2. **Process**:
   - Flow status = rejected (3)
   - Article status = draft (1)
   - `is_draft` = true
   - `workflow_id` = null
   - `current_approval_step` = null
3. **Result**: Article dikembalikan ke draft
4. **Status**: Workflow dihentikan

## 📊 **Database Changes**

### **Article Approval Flows Table:**
- `revision_requested`: Boolean flag untuk request update
- `revision_message`: Pesan untuk revisi
- `rejection_reason`: Alasan penolakan
- `completed_at`: Timestamp ketika workflow selesai

### **Articles Table:**
- `status_id`: 1 (draft), 2 (published), 3 (rejected)
- `is_draft`: Boolean flag untuk draft status
- `workflow_id`: Null ketika di-reject
- `current_approval_step`: Null ketika di-reject

### **Article Approval Step Logs Table:**
- `action`: "approve", "request_update", "reject"
- `message`: Pesan dari approver
- `action_by_id`: ID user yang melakukan action

## 🎯 **Use Cases**

### **1. Content Review Process:**
```bash
# Step 1: Editor review
curl -X POST "http://localhost:8080/api/article-approval-flows/articles/123/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer EDITOR_TOKEN" \
  -d '{"action": "approve", "message": "Content is good"}'

# Step 2: Senior Editor review
curl -X POST "http://localhost:8080/api/article-approval-flows/articles/123/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SENIOR_EDITOR_TOKEN" \
  -d '{"action": "request_update", "message": "Please add more examples"}'

# Step 3: After revision, approve again
curl -X POST "http://localhost:8080/api/article-approval-flows/articles/123/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SENIOR_EDITOR_TOKEN" \
  -d '{"action": "approve", "message": "Much better now"}'
```

### **2. Quality Control Process:**
```bash
# Quality check fails
curl -X POST "http://localhost:8080/api/article-approval-flows/articles/123/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer QUALITY_CHECKER_TOKEN" \
  -d '{"action": "reject", "message": "Content does not meet quality standards"}'
```

## 🔒 **Validation Rules**

### **Action Validation:**
- `action` harus salah satu dari: `approve`, `request_update`, `reject`
- `action` adalah field required

### **Message Validation:**
- `message` adalah optional
- Jika ada, akan disimpan dalam step log

### **Authorization Validation:**
- User harus memiliki permission untuk approve
- User level harus sesuai dengan step yang sedang berjalan

## 🚨 **Error Handling**

### **Invalid Action (400):**
```json
{
  "success": false,
  "messages": ["Validation failed: [Action must be one of: approve, request_update, reject]"]
}
```

### **No Active Flow (400):**
```json
{
  "success": false,
  "messages": ["No active approval flow found for this article"]
}
```

### **Unauthorized (401):**
```json
{
  "success": false,
  "messages": ["Invalid authorization token"]
}
```

## 🔄 **Migration from Old API**

### **Before (Only Approve):**
```bash
curl -X POST "http://localhost:8080/api/article-approval-flows/articles/123/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"message": "Approved"}'
```

### **After (3 Actions):**
```bash
# Approve
curl -X POST "http://localhost:8080/api/article-approval-flows/articles/123/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"action": "approve", "message": "Approved"}'

# Revision
curl -X POST "http://localhost:8080/api/article-approval-flows/articles/123/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"action": "revision", "message": "Please fix grammar"}'

# Reject
curl -X POST "http://localhost:8080/api/article-approval-flows/articles/123/approve" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"action": "reject", "message": "Content not suitable"}'
```

## 🎉 **Benefits**

1. **Flexible Workflow**: Support untuk berbagai jenis feedback
2. **Better User Experience**: User bisa memberikan feedback yang lebih spesifik
3. **Improved Quality Control**: Reject option untuk content yang tidak sesuai
4. **Revision Support**: Revision untuk perbaikan tanpa menghentikan workflow
5. **Audit Trail**: Semua action dicatat dalam step logs

---

**🎉 Enhanced Approval Actions API memberikan kontrol yang lebih baik atas workflow approval dengan 3 pilihan action yang berbeda!**

Sekarang approver bisa memilih apakah akan approve, revision, atau reject artikel dengan behavior yang sesuai untuk setiap pilihan. 🚀