741 lines
16 KiB
Markdown
741 lines
16 KiB
Markdown
# مستندات کامل 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://85.208.253.135:8000`
|
||
> **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`
|