# مستندات کامل APIهای مورد نیاز Views

این document شامل تمام APIهایی است که توسط viewهای زیر استفاده می‌شوند:

- **Calendar** (`views/apps/calendar`)
- **Kanban** (`views/apps/kanban`)
- **Todo** (`views/apps/todo`)
- **Account Settings** (`views/pages/account-settings`)

> **Base URL:** `NEXT_PUBLIC_API_URL` یا `ENVOY_GATEWAY_URL` یا `http://localhost:9035`  
> **Authentication:** تمام درخواست‌ها نیاز به هدر `Authorization: Bearer {token}` دارند (توکن از `localStorage.auth_token` خوانده می‌شود)

---

## ۱. Calendar API (تقویم)

**سرویس:** `eventService`  
**Slice:** `redux-store/slices/calendar.ts`

### ۱.۱ لیست رویدادها

```
GET /api/events
```

**Query Parameters (اختیاری):**

| پارامتر   | نوع   | توضیحات                                   |
|-----------|-------|-------------------------------------------|
| `start`   | string | ISO 8601 - تاریخ شروع فیلتر                |
| `end`     | string | ISO 8601 - تاریخ پایان فیلتر               |
| `calendar`| string | فیلتر بر اساس تقویم: `Personal`, `Business`, `Family`, `Holiday`, `ETC` |

**مثال:**
```
GET /api/events?start=2025-01-01T00:00:00.000Z&end=2025-01-31T23:59:59.000Z&calendar=Business
```

**Response:**
```json
{
  "events": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "deadline": 1704067200,
      "tags": ["string"],
      "author": {
        "name": "string",
        "image": "string"
      },
      "calendar": "Personal | Business | Family | Holiday | ETC",
      "start": "2025-01-15T09:00:00.000Z",
      "end": "2025-01-15T10:00:00.000Z",
      "allDay": false,
      "extendedProps": {}
    }
  ]
}
```

---

### ۱.۲ ایجاد رویداد جدید

```
POST /api/events
```

**Request Body:**
```json
{
  "title": "string",           // الزامی
  "description": "string",     // اختیاری
  "calendar": "Personal | Business | Family | Holiday | ETC",  // الزامی
  "start": "2025-01-15T09:00:00.000Z",   // ISO 8601
  "end": "2025-01-15T10:00:00.000Z",     // ISO 8601
  "allDay": false,             // اختیاری، پیش‌فرض: false
  "deadline": 1704067200,      // اختیاری - Unix timestamp
  "tags": ["string"],          // اختیاری
  "extendedProps": {}          // اختیاری
}
```

**Response:**
```json
{
  "event": {
    "id": "string",
    "title": "string",
    "description": "string",
    "calendar": "string",
    "start": "string",
    "end": "string",
    "allDay": boolean,
    "deadline": number,
    "tags": ["string"],
    "author": {},
    "extendedProps": {}
  }
}
```

---

### ۱.۳ دریافت یک رویداد

```
GET /api/events/{id}
```

**Path Parameters:**

| پارامتر | نوع   | توضیحات   |
|---------|-------|-----------|
| `id`    | string | شناسه رویداد |

---

### ۱.۴ به‌روزرسانی رویداد

```
PUT /api/events/{id}
```

**Path Parameters:**

| پارامتر | نوع   | توضیحات   |
|---------|-------|-----------|
| `id`    | string | شناسه رویداد |

**Request Body (همه فیلدها اختیاری):**
```json
{
  "title": "string",
  "description": "string",
  "calendar": "Personal | Business | Family | Holiday | ETC",
  "start": "2025-01-15T09:00:00.000Z",
  "end": "2025-01-15T10:00:00.000Z",
  "allDay": false,
  "deadline": 1704067200,
  "tags": ["string"],
  "extendedProps": {}
}
```

---

### ۱.۵ حذف رویداد

```
DELETE /api/events/{id}
```

**Path Parameters:**

| پارامتر | نوع   | توضیحات   |
|---------|-------|-----------|
| `id`    | string | شناسه رویداد |

**Response:**
```json
{
  "success": true
}
```

---

## ۲. Kanban API (کانبان)

**سرویس:** `kanbanService`  
**Slice:** `redux-store/slices/kanban.ts`

### ۲.۱ دریافت Board

```
GET /api/kanban/board
```

**Response:**
```json
{
  "columns": [
    {
      "id": 1,
      "title": "string",
      "taskIds": [1, 2, 3]
    }
  ],
  "tasks": [
    {
      "id": 1,
      "title": "string",
      "badgeText": ["string"],
      "attachments": 0,
      "comments": 0,
      "assigned": [{"src": "string", "name": "string"}],
      "image": "string",
      "dueDate": "2025-01-15T00:00:00.000Z",
      "routine": 0,
      "description": "string",
      "tags": ["string"],
      "priority": "high | medium | low",
      "status": "pending | in-progress | completed",
      "source": "kanban | calendar | todo"
    }
  ]
}
```

> **نکته:** Backend ممکن است از `badge_text` و `due_date` (snake_case) استفاده کند. سرویس frontend به‌طور خودکار تبدیل می‌کند.

---

### ۲.۲ ایجاد ستون جدید

```
POST /api/kanban/columns
```

**Request Body:**
```json
{
  "title": "string"
}
```

**Response:**
```json
{
  "column": {
    "id": 1,
    "title": "string",
    "taskIds": []
  }
}
```

---

### ۲.۳ به‌روزرسانی ستون

```
PUT /api/kanban/columns/{columnId}
```

**Path Parameters:**

| پارامتر    | نوع   | توضیحات   |
|------------|-------|-----------|
| `columnId` | number | شناسه ستون |

**Request Body (هر دو اختیاری):**
```json
{
  "title": "string",
  "taskIds": [1, 2, 3]
}
```

---

### ۲.۴ حذف ستون

```
DELETE /api/kanban/columns/{columnId}
```

**Path Parameters:**

| پارامتر    | نوع   | توضیحات   |
|------------|-------|-----------|
| `columnId` | number | شناسه ستون |

**Response:**
```json
{
  "success": true
}
```

---

### ۲.۵ ایجاد تسک جدید

```
POST /api/kanban/tasks
```

**Request Body (Backend - snake_case):**
```json
{
  "column_id": 1,              // الزامی
  "title": "string",           // الزامی
  "description": "string",     // اختیاری
  "badge_text": ["string"],    // اختیاری
  "attachments": 0,            // اختیاری
  "comments": 0,               // اختیاری
  "assigned": [{"src": "string", "name": "string"}],  // اختیاری
  "image": "string",           // اختیاری
  "due_date": "2025-01-15T00:00:00.000Z",  // اختیاری - ISO 8601
  "routine": 0,                // اختیاری - 0|1|2|3|4
  "tags": ["string"],          // اختیاری
  "priority": 0,               // اختیاری - 0: high, 1: medium, 2: low
  "status": 0                  // اختیاری - 0: pending, 1: in-progress, 2: completed
}
```

---

### ۲.۶ به‌روزرسانی تسک

```
PUT /api/kanban/tasks/{taskId}
```

**Path Parameters:**

| پارامتر | نوع   | توضیحات  |
|---------|-------|----------|
| `taskId`| number | شناسه تسک |

**Request Body (Backend - snake_case, همه اختیاری):**
```json
{
  "title": "string",
  "description": "string",
  "badge_text": ["string"],
  "attachments": 0,
  "comments": 0,
  "assigned": [],
  "image": "string",
  "due_date": "string",
  "routine": 0,
  "tags": ["string"],
  "priority": 0,
  "status": 0,
  "column_id": 1
}
```

---

### ۲.۷ حذف تسک

```
DELETE /api/kanban/tasks/{taskId}
```

**Path Parameters:**

| پارامتر | نوع   | توضیحات  |
|---------|-------|----------|
| `taskId`| number | شناسه تسک |

**Response:**
```json
{
  "success": true
}
```

---

### ۲.۸ جابجایی تسک بین ستون‌ها

```
PUT /api/kanban/tasks/{taskId}/move
```

**Path Parameters:**

| پارامتر | نوع   | توضیحات  |
|---------|-------|----------|
| `taskId`| number | شناسه تسک |

**Request Body:**
```json
{
  "fromColumnId": 1,
  "toColumnId": 2,
  "position": 0
}
```

**Response:**
```json
{
  "success": true,
  "columns": [
    {
      "id": 1,
      "title": "string",
      "taskIds": []
    }
  ]
}
```

---

## ۳. Todo API (کارهای انجام‌دادنی)

**سرویس:** `todoService`  
**استفاده مستقیم:** بدون Redux

### ۳.۱ لیست Todoها

```
GET /api/todos
```

**Query Parameters (اختیاری):**

| پارامتر  | نوع   | توضیحات                                                          |
|----------|-------|------------------------------------------------------------------|
| `status` | string | `pending`, `in-progress`, `completed`                            |
| `priority`| string | `high`, `medium`, `low`                                         |
| `label`  | string | فیلتر بر اساس برچسب                                              |
| `filter` | string | `all`, `starred`, `important`, `completed`, `trashed`            |
| `search` | string | جستجو در عنوان و توضیحات                                         |

**مثال:**
```
GET /api/todos?filter=all&search=meeting
```

**Response:**
```json
{
  "todos": [
    {
      "id": 1,
      "title": "string",
      "description": "string",
      "status": "pending | in-progress | completed",
      "priority": "high | medium | low",
      "startDate": "2025-01-01T00:00:00.000Z",
      "dueDate": "2025-01-15T00:00:00.000Z",
      "createdDate": "2025-01-01T00:00:00.000Z",
      "labels": ["string"],
      "tags": ["string"],
      "isStarred": false,
      "isImportant": false,
      "isTrashed": false,
      "isKanban": false,
      "routine": 0,
      "source": "todo | calendar | kanban"
    }
  ],
  "total": 10
}
```

> **نکته:** Backend از `start_date`, `due_date`, `created_date`, `is_starred`, `is_important`, `is_trashed`, `is_kanban` (snake_case) استفاده می‌کند.

---

### ۳.۲ ایجاد Todo جدید

```
POST /api/todos
```

**Request Body (Backend - snake_case):**
```json
{
  "title": "string",           // الزامی
  "description": "string",     // اختیاری
  "status": 0,                 // اختیاری - 0: pending, 1: in-progress, 2: completed
  "priority": 1,               // اختیاری - 0: high, 1: medium, 2: low
  "start_date": "string",      // اختیاری - ISO 8601
  "due_date": "string",        // اختیاری - ISO 8601
  "labels": ["string"],        // اختیاری
  "tags": ["string"],          // اختیاری
  "is_starred": false,         // اختیاری
  "is_important": false,       // اختیاری
  "is_kanban": false,          // اختیاری
  "routine": 0                 // اختیاری - 0|1|2|3|4
}
```

**Response:**
```json
{
  "todo": {
    "id": 1,
    "title": "string",
    ...
  }
}
```

---

### ۳.۳ به‌روزرسانی Todo

```
PUT /api/todos/{todoId}
```

**Path Parameters:**

| پارامتر | نوع   | توضیحات   |
|---------|-------|-----------|
| `todoId`| number | شناسه Todo |

**Request Body (Backend - snake_case, همه اختیاری):**
```json
{
  "title": "string",
  "description": "string",
  "status": 0,
  "priority": 0,
  "start_date": "string",
  "due_date": "string",
  "labels": ["string"],
  "tags": ["string"],
  "is_starred": false,
  "is_important": false,
  "is_trashed": false,
  "is_kanban": false,
  "routine": 0
}
```

---

### ۳.۴ حذف Todo

```
DELETE /api/todos/{todoId}
```

**Path Parameters:**

| پارامتر | نوع   | توضیحات   |
|---------|-------|-----------|
| `todoId`| number | شناسه Todo |

**Response:**
```json
{
  "success": true
}
```

---

### ۳.۵ لیست برچسب‌ها

```
GET /api/todos/labels
```

**Response:**
```json
{
  "labels": ["Personal", "Work", "Urgent"]
}
```

---

## ۴. Account Settings API (تنظیمات حساب)

### ۴.۱ دریافت اطلاعات کاربر (Account Details)

**سرویس:** `userManagementService`  
**استفاده در:** `AccountDetails.tsx`

```
GET /api/admin/users/{userId}
```

**Path Parameters:**

| پارامتر | نوع   | توضیحات      |
|---------|-------|--------------|
| `userId`| number | شناسه کاربر |

**Response:**
```json
{
  "user": {
    "id": 1,
    "role": "string",
    "email": "string",
    "status": "active | pending | inactive",
    "avatar": "string",
    "company": "string",
    "country": "string",
    "contact": "string",
    "fullName": "string",
    "username": "string",
    "currentPlan": "string",
    "billing": "string",
    "joinDate": "2025-01-01T00:00:00.000Z",
    "lastLogin": "2025-01-15T00:00:00.000Z",
    "twoStepVerification": false,
    "recentDevices": [],
    "activityTimeline": [],
    "projects": [],
    "invoices": [],
    "connections": [],
    "notifications": {}
  }
}
```

> **توجه:** AccountDetails از `userManagementService.getUser(authUser.id)` استفاده می‌کند و اطلاعات کاربر لاگین‌شده را نمایش می‌دهد. endpoint فعلی admin است؛ برای پروفایل کاربر لاگین‌شده ممکن است نیاز به `/api/users/me` باشد.

---

### ۴.۲ به‌روزرسانی کاربر (Save Changes در Account Details)

**نکته:** دکمه "Save Changes" در AccountDetails در حال حاضر API call ندارد. برای ذخیره باید از endpoint زیر استفاده شود:

```
PUT /api/admin/users/{userId}
```

**Path Parameters:**

| پارامتر | نوع   | توضیحات      |
|---------|-------|--------------|
| `userId`| number | شناسه کاربر |

**Request Body:**
```json
{
  "fullName": "string",
  "email": "string",
  "contact": "string",
  "avatar": "string"
}
```

---

### ۴.۳ تغییر رمز عبور (Security)

**نکته:** کامپوننت `ChangePasswordCard` در حال حاضر API call ندارد. برای پیاده‌سازی:

```
PUT /api/admin/users/{userId}/security
```

**Request Body:**
```json
{
  "currentPassword": "string",
  "newPassword": "string",
  "twoStepVerification": false
}
```

---

### ۴.۴ Billing Plans (پلن‌ها و صورتحساب)

**وضعیت فعلی:** از Server Actions با داده static استفاده می‌کند (`getPricingData`, `getInvoiceData`).

**APIهای پیشنهادی (در صورت استفاده از API واقعی):**

```
GET ${API_URL}/pages/pricing
```

**Response (فرمت مورد انتظار):**
```json
{
  "pricingPlans": [],
  "currentPlan": null
}
```

```
GET ${API_URL}/apps/invoice
```

**Response (فرمت مورد انتظار):**
```json
{
  "invoices": [],
  "stats": {
    "totalInvoices": 0,
    "paidInvoices": 0,
    "pendingInvoices": 0,
    "pastDueInvoices": 0
  }
}
```

---

## خلاصه Endpointها

| View | Method | Endpoint | استفاده |
|------|--------|----------|---------|
| Calendar | GET | `/api/events` | لیست رویدادها |
| Calendar | POST | `/api/events` | ایجاد رویداد |
| Calendar | PUT | `/api/events/{id}` | به‌روزرسانی رویداد |
| Calendar | DELETE | `/api/events/{id}` | حذف رویداد |
| Kanban | GET | `/api/kanban/board` | دریافت Board |
| Kanban | POST | `/api/kanban/columns` | ایجاد ستون |
| Kanban | PUT | `/api/kanban/columns/{id}` | به‌روزرسانی ستون |
| Kanban | DELETE | `/api/kanban/columns/{id}` | حذف ستون |
| Kanban | POST | `/api/kanban/tasks` | ایجاد تسک |
| Kanban | PUT | `/api/kanban/tasks/{id}` | به‌روزرسانی تسک |
| Kanban | DELETE | `/api/kanban/tasks/{id}` | حذف تسک |
| Kanban | PUT | `/api/kanban/tasks/{id}/move` | جابجایی تسک |
| Todo | GET | `/api/todos` | لیست Todoها |
| Todo | GET | `/api/todos/labels` | لیست برچسب‌ها |
| Todo | POST | `/api/todos` | ایجاد Todo |
| Todo | PUT | `/api/todos/{id}` | به‌روزرسانی Todo |
| Todo | DELETE | `/api/todos/{id}` | حذف Todo |
| Account | GET | `/api/admin/users/{id}` | دریافت اطلاعات کاربر |
| Account | PUT | `/api/admin/users/{id}` | به‌روزرسانی کاربر |
| Account | PUT | `/api/admin/users/{id}/security` | تغییر رمز/تنظیمات امنیتی |

---

## تبدیل‌های Frontend ↔ Backend

### Calendar
- Frontend از `calendar` با مقادیر `Personal | Business | Family | Holiday | ETC` استفاده می‌کند.
- `start` و `end` به صورت ISO 8601 ارسال می‌شوند.

### Kanban
- **status:** `pending`→0, `in-progress`→1, `completed`→2
- **priority:** `high`→0, `medium`→1, `low`→2
- **snake_case در Backend:** `column_id`, `badge_text`, `due_date`

### Todo
- **status:** `pending`→0, `in-progress`→1, `completed`→2
- **priority:** `high`→0, `medium`→1, `low`→2
- **snake_case در Backend:** `start_date`, `due_date`, `created_date`, `is_starred`, `is_important`, `is_trashed`, `is_kanban`