# Comprehensive Approval Workflow API

## Overview
This document describes the new comprehensive API endpoint that creates approval workflows along with all their dependencies (client approval settings) in a single API call.

## Endpoint Details

### POST `/approval-workflows/with-client-settings`

**Description**: Creates a comprehensive approval workflow with workflow steps and client approval settings in a single transaction.

**Authentication**: Bearer token required

**Request Body**:
```json
{
  "name": "Standard Article Approval",
  "description": "Standard approval workflow for articles",
  "isActive": true,
  "isDefault": true,
  "requiresApproval": true,
  "autoPublish": false,
  "steps": [
    {
      "stepOrder": 1,
      "stepName": "Editor Review",
      "requiredUserLevelId": 2,
      "canSkip": false,
      "autoApproveAfterHours": null,
      "isActive": true,
      "parentStepId": null,
      "conditionType": "always",
      "conditionValue": null,
      "isParallel": false,
      "branchName": null,
      "branchOrder": null
    },
    {
      "stepOrder": 2,
      "stepName": "Manager Approval",
      "requiredUserLevelId": 3,
      "canSkip": false,
      "autoApproveAfterHours": 24,
      "isActive": true,
      "parentStepId": null,
      "conditionType": "always",
      "conditionValue": null,
      "isParallel": false,
      "branchName": null,
      "branchOrder": null
    }
  ],
  "clientApprovalSettings": {
    "requiresApproval": true,
    "autoPublishArticles": false,
    "approvalExemptUsers": [],
    "approvalExemptRoles": [],
    "approvalExemptCategories": [],
    "requireApprovalFor": ["article", "news"],
    "skipApprovalFor": ["announcement"],
    "isActive": true
  }
}
```

**Response**:
```json
{
  "success": true,
  "messages": ["Comprehensive approval workflow with client settings successfully created"],
  "data": {
    "workflow": {
      "id": 1,
      "name": "Standard Article Approval",
      "description": "Standard approval workflow for articles",
      "isActive": true,
      "isDefault": true,
      "requiresApproval": true,
      "autoPublish": false,
      "clientId": "uuid-here",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    },
    "clientSettings": {
      "id": 1,
      "clientId": "uuid-here",
      "requiresApproval": true,
      "defaultWorkflowId": 1,
      "autoPublishArticles": false,
      "approvalExemptUsers": [],
      "approvalExemptRoles": [],
      "approvalExemptCategories": [],
      "requireApprovalFor": ["article", "news"],
      "skipApprovalFor": ["announcement"],
      "isActive": true,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    },
    "message": "Comprehensive approval workflow with client settings created successfully"
  }
}
```

## Features

### 1. Atomic Transaction
- Creates workflow, workflow steps, and client approval settings in a single transaction
- Automatic rollback if any step fails
- Ensures data consistency

### 2. Comprehensive Validation
- Validates workflow structure and steps
- Checks for existing client approval settings
- Validates multi-branch workflow logic
- Ensures proper step ordering

### 3. Multi-Branch Support
- Supports complex approval workflows with parallel branches
- Conditional step execution
- Parent-child step relationships
- Branch naming and ordering

### 4. Client Settings Integration
- Automatically links workflow to client approval settings
- Sets default workflow if specified
- Configures approval exemptions
- Sets content type approval rules

### 5. Error Handling
- Comprehensive error messages
- Automatic cleanup on failure
- Detailed logging for debugging
- Graceful degradation

## Request Structure Details

### Workflow Fields
- `name`: Workflow name (required)
- `description`: Workflow description (required)
- `isActive`: Whether workflow is active
- `isDefault`: Whether to set as default workflow
- `requiresApproval`: Whether workflow requires approval
- `autoPublish`: Whether to auto-publish after approval

### Step Fields
- `stepOrder`: Order of the step in workflow
- `stepName`: Name of the approval step
- `requiredUserLevelId`: User level required for this step
- `canSkip`: Whether this step can be skipped
- `autoApproveAfterHours`: Auto-approve after specified hours
- `isActive`: Whether step is active

### Multi-Branch Fields
- `parentStepId`: Parent step for branching
- `conditionType`: Condition type (user_level, user_level_hierarchy, always, custom)
- `conditionValue`: JSON condition value
- `isParallel`: Whether step runs in parallel
- `branchName`: Name of the branch
- `branchOrder`: Order within branch

### Client Settings Fields
- `requiresApproval`: Global approval requirement
- `autoPublishArticles`: Auto-publish after creation
- `approvalExemptUsers`: User IDs exempt from approval
- `approvalExemptRoles`: Role IDs exempt from approval
- `approvalExemptCategories`: Category IDs exempt from approval
- `requireApprovalFor`: Content types requiring approval
- `skipApprovalFor`: Content types skipping approval
- `isActive`: Whether settings are active

## Usage Examples

### Basic Workflow
```bash
curl -X POST "https://api.example.com/approval-workflows/with-client-settings" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Simple Approval",
    "description": "Two-step approval process",
    "isActive": true,
    "isDefault": true,
    "steps": [
      {
        "stepOrder": 1,
        "stepName": "Editor Review",
        "requiredUserLevelId": 2,
        "canSkip": false,
        "isActive": true
      },
      {
        "stepOrder": 2,
        "stepName": "Manager Approval",
        "requiredUserLevelId": 3,
        "canSkip": false,
        "isActive": true
      }
    ],
    "clientApprovalSettings": {
      "requiresApproval": true,
      "autoPublishArticles": false,
      "isActive": true
    }
  }'
```

### Complex Multi-Branch Workflow
```bash
curl -X POST "https://api.example.com/approval-workflows/with-client-settings" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Complex Multi-Branch Approval",
    "description": "Complex workflow with parallel branches",
    "isActive": true,
    "isDefault": false,
    "steps": [
      {
        "stepOrder": 1,
        "stepName": "Initial Review",
        "requiredUserLevelId": 2,
        "canSkip": false,
        "isActive": true
      },
      {
        "stepOrder": 2,
        "stepName": "Technical Review",
        "requiredUserLevelId": 4,
        "canSkip": false,
        "isActive": true,
        "parentStepId": 1,
        "conditionType": "user_level",
        "conditionValue": "{\"minLevel\": 4}",
        "isParallel": true,
        "branchName": "technical",
        "branchOrder": 1
      },
      {
        "stepOrder": 2,
        "stepName": "Content Review",
        "requiredUserLevelId": 3,
        "canSkip": false,
        "isActive": true,
        "parentStepId": 1,
        "conditionType": "user_level",
        "conditionValue": "{\"minLevel\": 3}",
        "isParallel": true,
        "branchName": "content",
        "branchOrder": 2
      },
      {
        "stepOrder": 3,
        "stepName": "Final Approval",
        "requiredUserLevelId": 5,
        "canSkip": false,
        "isActive": true
      }
    ],
    "clientApprovalSettings": {
      "requiresApproval": true,
      "autoPublishArticles": false,
      "approvalExemptUsers": [1],
      "approvalExemptRoles": [1],
      "approvalExemptCategories": [1],
      "requireApprovalFor": ["article", "news", "blog"],
      "skipApprovalFor": ["announcement", "update"],
      "isActive": true
    }
  }'
```

## Error Responses

### Validation Error
```json
{
  "success": false,
  "messages": ["Validation failed: [\"Workflow name is required\", \"Workflow must have at least one step\"]"],
  "data": null
}
```

### Client Settings Already Exist
```json
{
  "success": false,
  "messages": ["client approval settings already exist for this client"],
  "data": null
}
```

### Authentication Error
```json
{
  "success": false,
  "messages": ["clientId not found in auth token"],
  "data": null
}
```

## Implementation Details

### Files Modified/Created
1. `app/module/approval_workflows/request/approval_workflows.request.go` - Added comprehensive request structs
2. `app/module/approval_workflows/service/approval_workflows.service.go` - Added service method with transaction logic
3. `app/module/approval_workflows/controller/approval_workflows.controller.go` - Added controller method
4. `app/module/approval_workflows/approval_workflows.module.go` - Added route registration

### Dependencies
- Client Approval Settings Repository
- Approval Workflow Steps Repository
- Users Repository
- Validation utilities
- Response utilities

### Transaction Safety
- Automatic rollback on any failure
- Comprehensive error handling
- Detailed logging for debugging
- Data consistency guarantees

This comprehensive API endpoint provides a single, atomic way to create complete approval workflows with all necessary dependencies, ensuring data consistency and providing a better developer experience.