2026-02-19 01:15:36 +03:30
# مستندات کامل APIهای مورد نیاز Views
این document شامل تمام APIهایی است که توسط viewهای زیر استفاده میشوند:
- **Calendar** (`views/apps/calendar` )
- **Kanban** (`views/apps/kanban` )
- **Todo** (`views/apps/todo` )
- **Account Settings** (`views/pages/account-settings` )
2026-03-21 19:37:13 +03:30
> **Base URL:** `NEXT_PUBLIC_API_URL` یا `ENVOY_GATEWAY_URL` یا `http://85.208.253.135:8000`
2026-02-19 01:15:36 +03:30
> **Authentication:** تمام درخواستها نیاز به هدر `Authorization: Bearer {token}` دارند (توکن از `localStorage.auth_token` خوانده میشود)
---
## ۱
**سرویس: ** `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" : b o o l e a n ,
"deadline" : n u m b e r ,
"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`
### ۲.۱
```
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
### ۳.۱
```
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`
