# Advanced Order Management API Documentation

## Overview

The Advanced Order Management API provides comprehensive functionality for managing orders beyond basic operations. This includes partial refunds, void operations, and bill splitting capabilities.

## Features

- ✅ **Partial Refund**: Refund specific items from paid orders
- ✅ **Void Order**: Cancel ongoing orders (per item or entire order)
- ✅ **Split Bill**: Split orders by items or amounts
- ✅ **Order Status Management**: Support for PARTIAL and VOIDED statuses
- ✅ **Transaction Tracking**: Complete audit trail for all operations
- ✅ **Validation**: Comprehensive validation for all operations

## API Endpoints

### 1. Partial Refund

**POST** `/order/partial-refund`

Refund specific items from a paid order while keeping the remaining items.

#### Request Body

```json
{
  "order_id": 123,
  "reason": "Customer returned damaged items",
  "items": [
    {
      "order_item_id": 456,
      "quantity": 2
    },
    {
      "order_item_id": 789,
      "quantity": 1
    }
  ]
}
```

#### Request Parameters

| Parameter | Type   | Required | Description                    |
|-----------|--------|----------|--------------------------------|
| order_id  | int64  | Yes      | ID of the order to refund      |
| reason    | string | Yes      | Reason for the partial refund  |
| items     | array  | Yes      | Array of items to refund       |

#### Item Parameters

| Parameter     | Type   | Required | Description                    |
|---------------|--------|----------|--------------------------------|
| order_item_id | int64  | Yes      | ID of the order item to refund |
| quantity      | int    | Yes      | Quantity to refund (min: 1)    |

#### Response

**Success (200 OK)**

```json
{
  "success": true,
  "status": 200,
  "data": {
    "order_id": 123,
    "status": "PARTIAL",
    "refunded_amount": 75000,
    "remaining_amount": 25000,
    "reason": "Customer returned damaged items",
    "refunded_at": "2024-01-15T10:30:00Z",
    "customer_name": "John Doe",
    "payment_type": "CASH",
    "refunded_items": [
      {
        "order_item_id": 456,
        "item_name": "Bakso Special",
        "quantity": 2,
        "unit_price": 25000,
        "total_price": 50000
      },
      {
        "order_item_id": 789,
        "item_name": "Es Teh Manis",
        "quantity": 1,
        "unit_price": 25000,
        "total_price": 25000
      }
    ]
  }
}
```

### 2. Void Order

**POST** `/order/void`

Void an ongoing order (NEW or PENDING status) either entirely or by specific items.

#### Request Body

**Void Entire Order:**
```json
{
  "order_id": 123,
  "reason": "Customer cancelled order",
  "type": "ALL"
}
```

**Void Specific Items:**
```json
{
  "order_id": 123,
  "reason": "Customer changed mind about some items",
  "type": "ITEM",
  "items": [
    {
      "order_item_id": 456,
      "quantity": 1
    }
  ]
}
```

#### Request Parameters

| Parameter | Type   | Required | Description                    |
|-----------|--------|----------|--------------------------------|
| order_id  | int64  | Yes      | ID of the order to void        |
| reason    | string | Yes      | Reason for voiding             |
| type      | string | Yes      | Type: "ALL" or "ITEM"          |
| items     | array  | No       | Required if type is "ITEM"     |

#### Response

**Success (200 OK)**

```json
{
  "success": true,
  "status": 200,
  "data": {
    "order_id": 123,
    "status": "VOIDED",
    "reason": "Customer cancelled order",
    "voided_at": "2024-01-15T10:30:00Z",
    "customer_name": "John Doe",
    "voided_items": [
      {
        "order_item_id": 456,
        "item_name": "Bakso Special",
        "quantity": 1,
        "unit_price": 25000,
        "total_price": 25000
      }
    ]
  }
}
```

### 3. Split Bill

**POST** `/order/split-bill`

Split an order into a separate order by items or amounts.

#### Request Body

**Split by Items:**
```json
{
  "order_id": 123,
  "type": "ITEM",
  "payment_method": "CASH",
  "payment_provider": "CASH",
  "items": [
    {
      "order_item_id": 789,
      "quantity": 2
    },
    {
      "order_item_id": 101,
      "quantity": 1
    }
  ]
}
```

**Split by Amount:**
```json
{
  "order_id": 123,
  "type": "AMOUNT",
  "payment_method": "CASH",
  "payment_provider": "CASH",
  "amount": 50000
}
```

#### Request Parameters

| Parameter        | Type   | Required | Description                    |
|------------------|--------|----------|--------------------------------|
| order_id         | int64  | Yes      | ID of the order to split       |
| type             | string | Yes      | Type: "ITEM" or "AMOUNT"       |
| payment_method   | string | Yes      | Payment method for split order |
| payment_provider | string | No       | Payment provider for split order|
| items            | array  | No       | Required if type is "ITEM"     |
| amount           | float  | No       | Required if type is "AMOUNT" (must be less than order total) |

#### Item Parameters

| Parameter     | Type   | Required | Description                    |
|---------------|--------|----------|--------------------------------|
| order_item_id | int64  | Yes      | ID of the order item to split  |
| quantity      | int    | Yes      | Quantity to split (min: 1)     |

#### Response

**Success (200 OK)**

```json
{
  "success": true,
  "status": 200,
  "data": {
    "id": 124,
    "partner_id": 1,
    "status": "PAID",
    "amount": 100000,
    "total": 110000,
    "tax": 10000,
    "customer_id": 456,
    "customer_name": "John Doe",
    "payment_type": "CASH",
    "payment_provider": "CASH",
    "source": "POS",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "order_items": [
      {
        "id": 789,
        "item_id": 1,
        "item_name": "Bakso Special",
        "price": 50000,
        "quantity": 2,
        "subtotal": 100000
      }
    ]
  }
}
```

## Business Logic

### Partial Refund Process

1. **Validation**
   - Verify order exists and belongs to partner
   - Ensure order status is "PAID"
   - Validate refund items exist and quantities are valid

2. **Item Updates**
   - Reduce quantities of refunded items
   - Remove items completely if quantity becomes 0
   - Recalculate order totals

3. **Order Status Update**
   - Set status to "PARTIAL" if items remain
   - Set status to "REFUNDED" if all items refunded

4. **Transaction Creation**
   - Create refund transaction with negative amount
   - Track refund details

### Void Order Process

1. **Validation**
   - Verify order exists and belongs to partner
   - Ensure order status is "NEW" or "PENDING"
   - Validate void items if type is "ITEM"

2. **Void Operations**
   - **ALL**: Set order status to "VOIDED"
   - **ITEM**: Reduce quantities and recalculate totals

3. **Status Management**
   - Set status to "PARTIAL" if items remain
   - Set status to "VOIDED" if all items voided

### Split Bill Process

1. **Validation**
   - Verify order exists and belongs to partner
   - Ensure order status is "NEW" or "PENDING"
   - Validate split configuration

2. **Split Operations**
   - **ITEM**: Create new PAID order with specified items, reduce quantities in original order
   - **AMOUNT**: Create new PAID order with specified amount, reduce amount in original order

3. **Order Management**
   - Original order remains PENDING with reduced items/amount
   - New split order becomes PAID with specified payment method
   - Recalculate totals for both orders

## Order Status Flow

```
NEW → PENDING → PAID → REFUNDED
  ↓      ↓        ↓
VOIDED  VOIDED   PARTIAL
```

## Error Handling

### Common Error Responses

**Order Not Found (404)**
```json
{
  "success": false,
  "status": 404,
  "message": "order not found"
}
```

**Invalid Order Status (400)**
```json
{
  "success": false,
  "status": 400,
  "message": "only paid order can be partially refunded"
}
```

**Invalid Quantity (400)**
```json
{
  "success": false,
  "status": 400,
  "message": "refund quantity 3 exceeds available quantity 2 for item 456"
}
```

**Split Amount Mismatch (400)**
```json
{
  "success": false,
  "status": 400,
  "message": "split amount 95000 must be less than order total 100000"
}
```

## Database Schema Updates

### Orders Table

```sql
-- New statuses supported
ALTER TABLE orders ADD CONSTRAINT check_status 
CHECK (status IN ('NEW', 'PENDING', 'PAID', 'REFUNDED', 'VOIDED', 'PARTIAL'));
```

### Order Items Table

```sql
-- Support for quantity updates
ALTER TABLE order_items ADD COLUMN updated_at TIMESTAMP DEFAULT NOW();
```

## Constants

### Order Status

```go
const (
    New      OrderStatus = "NEW"
    Paid     OrderStatus = "PAID"
    Cancel   OrderStatus = "CANCEL"
    Pending  OrderStatus = "PENDING"
    Refunded OrderStatus = "REFUNDED"
    Voided   OrderStatus = "VOIDED"    // New
    Partial  OrderStatus = "PARTIAL"   // New
)
```

## Testing Examples

### cURL Examples

**Partial Refund:**
```bash
curl -X POST http://localhost:8080/api/v1/order/partial-refund \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "order_id": 123,
    "reason": "Customer returned damaged items",
    "items": [
      {
        "order_item_id": 456,
        "quantity": 2
      }
    ]
  }'
```

**Void Order:**
```bash
curl -X POST http://localhost:8080/api/v1/order/void \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "order_id": 123,
    "reason": "Customer cancelled order",
    "type": "ALL"
  }'
```

**Split Bill:**
```bash
curl -X POST http://localhost:8080/api/v1/order/split-bill \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "order_id": 123,
    "type": "ITEM",
    "payment_method": "CASH",
    "payment_provider": "CASH",
    "items": [
      {
        "order_item_id": 456,
        "quantity": 1
      },
      {
        "order_item_id": 789,
        "quantity": 1
      }
    ]
  }'
```

## Security Considerations

1. **Authorization**: Only authorized users can perform these operations
2. **Audit Trail**: All operations are logged with user and timestamp
3. **Validation**: Strict validation prevents invalid operations
4. **Data Integrity**: Transaction-based operations ensure consistency

## Future Enhancements

1. **Bulk Operations**: Support for bulk partial refunds/voids
2. **Approval Workflow**: Multi-level approval for large operations
3. **Notification System**: Customer notifications for refunds/voids
4. **Analytics**: Dashboard for operation trends and analysis
5. **Integration**: Integration with inventory management systems

## Support

For questions or issues with the Advanced Order Management API, please contact the development team or create an issue in the project repository.