apskel-pos-backend/TABLE_MANAGEMENT_API.md

# Table Management API

This document describes the Table Management API endpoints for managing restaurant tables in the POS system.

## Overview

The Table Management API allows you to:
- Create, read, update, and delete tables
- Manage table status (available, occupied, reserved, cleaning, maintenance)
- Occupy and release tables with orders
- Track table positions and capacity
- Get available and occupied tables for specific outlets

## Table Entity

A table has the following properties:

```json
{
  "id": "uuid",
  "organization_id": "uuid",
  "outlet_id": "uuid",
  "table_name": "string",
  "start_time": "datetime (optional)",
  "status": "available|occupied|reserved|cleaning|maintenance",
  "order_id": "uuid (optional)",
  "payment_amount": "decimal",
  "position_x": "decimal",
  "position_y": "decimal",
  "capacity": "integer (1-20)",
  "is_active": "boolean",
  "metadata": "object",
  "created_at": "datetime",
  "updated_at": "datetime",
  "order": "OrderResponse (optional)"
}
```

## API Endpoints

### 1. Create Table

**POST** `/api/v1/tables`

Create a new table for an outlet.

**Request Body:**
```json
{
  "outlet_id": "uuid",
  "table_name": "string",
  "position_x": "decimal",
  "position_y": "decimal",
  "capacity": "integer (1-20)",
  "metadata": "object (optional)"
}
```

**Response:** `201 Created`
```json
{
  "id": "uuid",
  "organization_id": "uuid",
  "outlet_id": "uuid",
  "table_name": "string",
  "status": "available",
  "position_x": "decimal",
  "position_y": "decimal",
  "capacity": "integer",
  "is_active": true,
  "metadata": "object",
  "created_at": "datetime",
  "updated_at": "datetime"
}
```

### 2. Get Table by ID

**GET** `/api/v1/tables/{id}`

Get table details by ID.

**Response:** `200 OK`
```json
{
  "id": "uuid",
  "organization_id": "uuid",
  "outlet_id": "uuid",
  "table_name": "string",
  "start_time": "datetime (optional)",
  "status": "string",
  "order_id": "uuid (optional)",
  "payment_amount": "decimal",
  "position_x": "decimal",
  "position_y": "decimal",
  "capacity": "integer",
  "is_active": "boolean",
  "metadata": "object",
  "created_at": "datetime",
  "updated_at": "datetime",
  "order": "OrderResponse (optional)"
}
```

### 3. Update Table

**PUT** `/api/v1/tables/{id}`

Update table details.

**Request Body:**
```json
{
  "table_name": "string (optional)",
  "status": "available|occupied|reserved|cleaning|maintenance (optional)",
  "position_x": "decimal (optional)",
  "position_y": "decimal (optional)",
  "capacity": "integer (1-20) (optional)",
  "is_active": "boolean (optional)",
  "metadata": "object (optional)"
}
```

**Response:** `200 OK` - Updated table object

### 4. Delete Table

**DELETE** `/api/v1/tables/{id}`

Delete a table. Cannot delete occupied tables.

**Response:** `204 No Content`

### 5. List Tables

**GET** `/api/v1/tables`

Get paginated list of tables with optional filters.

**Query Parameters:**
- `organization_id` (optional): Filter by organization
- `outlet_id` (optional): Filter by outlet
- `status` (optional): Filter by status
- `is_active` (optional): Filter by active status
- `search` (optional): Search in table names
- `page` (default: 1): Page number
- `limit` (default: 10, max: 100): Page size

**Response:** `200 OK`
```json
{
  "tables": [
    {
      "id": "uuid",
      "table_name": "string",
      "status": "string",
      "capacity": "integer",
      "is_active": "boolean",
      "created_at": "datetime",
      "updated_at": "datetime"
    }
  ],
  "total_count": "integer",
  "page": "integer",
  "limit": "integer",
  "total_pages": "integer"
}
```

### 6. Occupy Table

**POST** `/api/v1/tables/{id}/occupy`

Occupy a table with an order.

**Request Body:**
```json
{
  "order_id": "uuid",
  "start_time": "datetime"
}
```

**Response:** `200 OK` - Updated table object with order information

### 7. Release Table

**POST** `/api/v1/tables/{id}/release`

Release a table and record payment amount.

**Request Body:**
```json
{
  "payment_amount": "decimal"
}
```

**Response:** `200 OK` - Updated table object

### 8. Get Available Tables

**GET** `/api/v1/outlets/{outlet_id}/tables/available`

Get list of available tables for a specific outlet.

**Response:** `200 OK`
```json
[
  {
    "id": "uuid",
    "table_name": "string",
    "status": "available",
    "capacity": "integer",
    "position_x": "decimal",
    "position_y": "decimal"
  }
]
```

### 9. Get Occupied Tables

**GET** `/api/v1/outlets/{outlet_id}/tables/occupied`

Get list of occupied tables for a specific outlet.

**Response:** `200 OK`
```json
[
  {
    "id": "uuid",
    "table_name": "string",
    "status": "occupied",
    "start_time": "datetime",
    "order_id": "uuid",
    "capacity": "integer",
    "position_x": "decimal",
    "position_y": "decimal",
    "order": "OrderResponse"
  }
]
```

## Table Statuses

- **available**: Table is free and ready for use
- **occupied**: Table is currently in use with an order
- **reserved**: Table is reserved for future use
- **cleaning**: Table is being cleaned
- **maintenance**: Table is under maintenance

## Business Rules

1. **Table Creation**: Tables must have unique names within an outlet
2. **Table Occupation**: Only available or cleaning tables can be occupied
3. **Table Release**: Only occupied tables can be released
4. **Table Deletion**: Occupied tables cannot be deleted
5. **Capacity**: Table capacity must be between 1 and 20
6. **Position**: Tables have X and Y coordinates for layout positioning

## Error Responses

**400 Bad Request:**
```json
{
  "error": "Error description",
  "message": "Detailed error message"
}
```

**404 Not Found:**
```json
{
  "error": "Table not found",
  "message": "Table with specified ID does not exist"
}
```

**500 Internal Server Error:**
```json
{
  "error": "Failed to create table",
  "message": "Database error or other internal error"
}
```

## Authentication

All endpoints require authentication via JWT token in the Authorization header:

```
Authorization: Bearer <jwt_token>
```

## Authorization

All table management endpoints require admin or manager role permissions.

## Example Usage

### Creating a Table
```bash
curl -X POST http://localhost:8080/api/v1/tables \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "outlet_id": "123e4567-e89b-12d3-a456-426614174000",
    "table_name": "Table 1",
    "position_x": 100.0,
    "position_y": 200.0,
    "capacity": 4
  }'
```

### Occupying a Table
```bash
curl -X POST http://localhost:8080/api/v1/tables/123e4567-e89b-12d3-a456-426614174000/occupy \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "order_id": "123e4567-e89b-12d3-a456-426614174001",
    "start_time": "2024-01-15T10:30:00Z"
  }'
```

### Getting Available Tables
```bash
curl -X GET http://localhost:8080/api/v1/outlets/123e4567-e89b-12d3-a456-426614174000/tables/available \
  -H "Authorization: Bearer <token>"
```