sajad-dev/Frontend

Fork 0

Files

T

sajad-dev 52e6a90319 CI/CD

2026-03-21 19:37:13 +03:30

16 KiB

Raw Blame History

مستندات کامل 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:

{
  "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:

{
  "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:

{
  "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 (همه فیلدها اختیاری):

{
  "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:

{
  "success": true
}

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

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

۲.۱ دریافت Board

GET /api/kanban/board

Response:

{
  "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:

{
  "title": "string"
}

Response:

{
  "column": {
    "id": 1,
    "title": "string",
    "taskIds": []
  }
}

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

PUT /api/kanban/columns/{columnId}

Path Parameters:

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

Request Body (هر دو اختیاری):

{
  "title": "string",
  "taskIds": [1, 2, 3]
}

۲.۴ حذف ستون

DELETE /api/kanban/columns/{columnId}

Path Parameters:

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

Response:

{
  "success": true
}

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

POST /api/kanban/tasks

Request Body (Backend - snake_case):

{
  "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, همه اختیاری):

{
  "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:

{
  "success": true
}

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

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

Path Parameters:

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

Request Body:

{
  "fromColumnId": 1,
  "toColumnId": 2,
  "position": 0
}

Response:

{
  "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:

{
  "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):

{
  "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:

{
  "todo": {
    "id": 1,
    "title": "string",
    ...
  }
}

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

PUT /api/todos/{todoId}

Path Parameters:

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

Request Body (Backend - snake_case, همه اختیاری):

{
  "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:

{
  "success": true
}

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

GET /api/todos/labels

Response:

{
  "labels": ["Personal", "Work", "Urgent"]
}

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

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

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

GET /api/admin/users/{userId}

Path Parameters:

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

Response:

{
  "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:

{
  "fullName": "string",
  "email": "string",
  "contact": "string",
  "avatar": "string"
}

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

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

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

Request Body:

{
  "currentPassword": "string",
  "newPassword": "string",
  "twoStepVerification": false
}

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

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

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

GET ${API_URL}/pages/pricing

Response (فرمت مورد انتظار):

{
  "pricingPlans": [],
  "currentPlan": null
}

GET ${API_URL}/apps/invoice

Response (فرمت مورد انتظار):

{
  "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

16 KiB Raw Blame History Unescape Escape

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

۱. Calendar API (تقویم)

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

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

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

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

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

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

۲.۱ دریافت Board

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

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

۲.۴ حذف ستون

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

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

۲.۷ حذف تسک

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

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

۳.۱ لیست Todoها

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

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

۳.۴ حذف Todo

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

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

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

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

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

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

خلاصه Endpointها

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

Calendar

Kanban

Todo

16 KiB

Raw Blame History