Files

T

sajad-dev 2a77f90ccd Update Docker Compose ports to 8081 and add new apps and URL routes for crop zoning, plant simulator, pest detection, irrigation recommendation, fertilization recommendation, and farm AI assistant.

2026-02-25 12:21:53 +03:30

42 KiB

Raw Blame History

مستندات API های صفحات منوی عمودی

این مستندات شامل تمام API های مورد نیاز برای صفحات موجود در VerticalMenu است.

توجهات مهم:

صفحات User Management و Roles & Permissions فقط برای ادمین قابل دسترسی است
صفحات Calendar، Kanban، و Todo باید به یکدیگر متصل باشند و تسک‌های غیرروتین در هر سه قابل نمایش باشند
AI Chat باید به تسک‌های Calendar، Kanban، و Todo دسترسی داشته باشد
AI Chat باید نسبت به برخی پیام‌ها حساس باشد (sensitive message handling)
سیستم Authentication جزو این مستندات نیست

1. Chat

Route: /apps/chat

دسترسی: همه کاربران

API های مورد نیاز

1.1. دریافت لیست مخاطبین

Endpoint: GET /api/chat/contacts

Response:

{
  "contacts": [
    {
      "id": number,
      "fullName": "string",
      "role": "string",
      "about": "string",
      "avatar": "string",
      "avatarColor": "primary" | "success" | "error" | "warning" | "info",
      "status": "busy" | "away" | "online" | "offline"
    }
  ]
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`contacts[].id`	number	شناسه یکتا مخاطب
`contacts[].fullName`	string	نام کامل
`contacts[].role`	string	نقش کاربر
`contacts[].about`	string	درباره کاربر
`contacts[].avatar`	string	آواتار (URL)
`contacts[].avatarColor`	ThemeColor	رنگ آواتار (در صورت نبودن تصویر)
`contacts[].status`	StatusType	وضعیت آنلاین/آفلاین

1.2. دریافت چت‌های کاربر

Endpoint: GET /api/chat/conversations

Response:

{
  "chats": [
    {
      "id": number,
      "userId": number,
      "unseenMsgs": number,
      "lastMessage": {
        "message": "string",
        "time": "string",
        "senderId": number,
        "msgStatus": {
          "isSent": boolean,
          "isDelivered": boolean,
          "isSeen": boolean
        }
      }
    }
  ]
}

1.3. دریافت پیام‌های چت

Endpoint: GET /api/chat/conversations/:conversationId/messages

Path Parameters:

conversationId (number, required): شناسه مکالمه

Query Parameters:

page? (number, optional): شماره صفحه
limit? (number, optional): تعداد پیام در هر صفحه

Response:

{
  "messages": [
    {
      "message": "string",
      "time": "string",
      "senderId": number,
      "msgStatus": {
        "isSent": boolean,
        "isDelivered": boolean,
        "isSeen": boolean
      }
    }
  ],
  "pagination": {
    "page": number,
    "limit": number,
    "total": number,
    "totalPages": number
  }
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`messages[].message`	string	متن پیام
`messages[].time`	string	زمان ارسال (ISO 8601)
`messages[].senderId`	number	شناسه فرستنده
`messages[].msgStatus.isSent`	boolean	وضعیت ارسال
`messages[].msgStatus.isDelivered`	boolean	وضعیت تحویل
`messages[].msgStatus.isSeen`	boolean	وضعیت مشاهده

1.4. ارسال پیام جدید

Endpoint: POST /api/chat/conversations/:conversationId/messages

Path Parameters:

conversationId (number, required): شناسه مکالمه

Request Body:

{
  "message": "string"
}

Response:

{
  "message": {
    "id": number,
    "message": "string",
    "time": "string",
    "senderId": number,
    "msgStatus": {
      "isSent": boolean,
      "isDelivered": boolean,
      "isSeen": boolean
    }
  }
}

1.5. به‌روزرسانی وضعیت مشاهده پیام

Endpoint: PUT /api/chat/messages/:messageId/read

Path Parameters:

messageId (number, required): شناسه پیام

Response:

{
  "success": boolean
}

1.6. دریافت اطلاعات پروفایل کاربر

Endpoint: GET /api/chat/profile

Response:

{
  "profileUser": {
    "id": number,
    "role": "string",
    "about": "string",
    "avatar": "string",
    "fullName": "string",
    "status": "busy" | "away" | "online" | "offline",
    "settings": {
      "isNotificationsOn": boolean,
      "isTwoStepAuthVerificationEnabled": boolean
    }
  }
}

2. AI Chat

Route: /apps/ai-chat

دسترسی: همه کاربران

نکات مهم:

AI Chat باید به تسک‌های Calendar، Kanban، و Todo دسترسی داشته باشد
AI Chat باید نسبت به برخی پیام‌ها حساس باشد و پردازش ویژه انجام دهد

API های مورد نیاز

2.1. ارسال پیام به AI

Endpoint: POST /api/ai-chat/messages

Request Body:

{
  "content": "string",
  "images": ["string"],
  "files": [
    {
      "name": "string",
      "data": "string",
      "type": "string",
      "size": number
    }
  ],
  "model": "gpt-4" | "gpt-3.5" | "claude" | "gemini",
  "conversationId": "string"
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`content`	string	متن پیام
`images`	string[]	آرایه URL تصاویر (base64 data URLs)
`files[].name`	string	نام فایل
`files[].data`	string	داده فایل (base64 data URL)
`files[].type`	string	نوع MIME فایل
`files[].size`	number	حجم فایل (بایت)
`model`	string	مدل AI مورد استفاده
`conversationId`	string	شناسه مکالمه (اختیاری)

Response:

{
  "message": {
    "id": "string",
    "role": "user" | "assistant",
    "content": "string",
    "images": ["string"],
    "files": [
      {
        "name": "string",
        "data": "string",
        "type": "string",
        "size": number
      }
    ],
    "timestamp": "string",
    "isSensitive": boolean,
    "sensitiveReason": "string"
  },
  "assistantResponse": {
    "id": "string",
    "role": "assistant",
    "content": "string",
    "timestamp": "string",
    "referencedTasks": [
      {
        "taskId": "string",
        "source": "calendar" | "kanban" | "todo",
        "title": "string"
      }
    ]
  }
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`message.isSensitive`	boolean	آیا پیام حساس است
`message.sensitiveReason`	string	دلیل حساس بودن پیام
`assistantResponse.referencedTasks[].taskId`	string	شناسه تسک
`assistantResponse.referencedTasks[].source`	string	منبع تسک (calendar/kanban/todo)
`assistantResponse.referencedTasks[].title`	string	عنوان تسک

2.2. دریافت تاریخچه مکالمه

Endpoint: GET /api/ai-chat/conversations/:conversationId/messages

Path Parameters:

conversationId (string, required): شناسه مکالمه

Response:

{
  "messages": [
    {
      "id": "string",
      "role": "user" | "assistant",
      "content": "string",
      "images": ["string"],
      "files": [
        {
          "name": "string",
          "data": "string",
          "type": "string",
          "size": number
        }
      ],
      "timestamp": "string"
    }
  ]
}

2.3. دریافت لیست مکالمات

Endpoint: GET /api/ai-chat/conversations

Response:

{
  "conversations": [
    {
      "id": "string",
      "title": "string",
      "lastMessage": "string",
      "timestamp": "string",
      "messageCount": number
    }
  ]
}

2.4. دریافت تسک‌های مرتبط (برای AI Chat)

Endpoint: GET /api/ai-chat/tasks

Query Parameters:

source? (string, optional): منبع تسک (calendar, kanban, todo)
routine? (number, optional): نوع روتین (0: NONE, 1: DAILY, 2: WEEKLY, 3: MONTHLY, 4: YEARLY)

Response:

{
  "tasks": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "deadline": number,
      "routine": 0 | 1 | 2 | 3 | 4,
      "tags": ["string"],
      "source": "calendar" | "kanban" | "todo",
      "status": "string",
      "priority": "high" | "medium" | "low"
    }
  ]
}

نکته: این API تسک‌هایی که routine = 0 دارند را برمی‌گرداند تا در Calendar، Kanban، و Todo مشترک باشند.

3. Calendar

Route: /apps/calendar

دسترسی: همه کاربران

نکات مهم:

Calendar باید با Kanban و Todo متصل باشد
تسک‌هایی که routine = 0 دارند باید در هر سه قابل نمایش باشند

API های مورد نیاز

3.1. دریافت Event ها

Endpoint: GET /api/events

Query Parameters:

start? (string, optional): تاریخ شروع (ISO 8601)
end? (string, optional): تاریخ پایان (ISO 8601)
calendar? (string, optional): فیلتر بر اساس تقویم (Personal, Business, Family, Holiday, ETC)

Response:

{
  "events": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "deadline": number,
      "tags": ["string"],
      "author": {
        "name": "string",
        "image": "string"
      },
      "calendar": "Personal" | "Business" | "Family" | "Holiday" | "ETC",
      "start": "string",
      "end": "string",
      "allDay": boolean,
      "extendedProps": {}
    }
  ]
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`events[].id`	string	شناسه یکتا رویداد
`events[].title`	string	عنوان رویداد
`events[].description`	string	توضیحات رویداد
`events[].deadline`	number	مهلت (Unix timestamp)
`events[].tags`	string[]	برچسب‌ها
`events[].author.name`	string	نام نویسنده
`events[].author.image`	string	تصویر نویسنده (URL)
`events[].calendar`	string	نوع تقویم
`events[].start`	string	زمان شروع (ISO 8601)
`events[].end`	string	زمان پایان (ISO 8601)
`events[].allDay`	boolean	رویداد تمام روز

3.2. ایجاد Event جدید

Endpoint: POST /api/events

Request Body:

{
  "title": "string",
  "description": "string",
  "deadline": number,
  "tags": ["string"],
  "calendar": "Personal" | "Business" | "Family" | "Holiday" | "ETC",
  "start": "string",
  "end": "string",
  "allDay": boolean,
  "extendedProps": {}
}

Response:

{
  "event": {
    "id": "string",
    "title": "string",
    "description": "string",
    "deadline": number,
    "tags": ["string"],
    "author": {
      "name": "string",
      "image": "string"
    },
    "calendar": "string",
    "start": "string",
    "end": "string",
    "allDay": boolean
  }
}

3.3. به‌روزرسانی Event

Endpoint: PUT /api/events/:eventId

Path Parameters:

eventId (string, required): شناسه رویداد

Request Body:

{
  "title": "string",
  "description": "string",
  "deadline": number,
  "tags": ["string"],
  "calendar": "string",
  "start": "string",
  "end": "string",
  "allDay": boolean
}

Response:

{
  "event": {
    "id": "string",
    "title": "string",
    "description": "string",
    "deadline": number,
    "tags": ["string"],
    "author": {
      "name": "string",
      "image": "string"
    },
    "calendar": "string",
    "start": "string",
    "end": "string",
    "allDay": boolean
  }
}

3.4. حذف Event

Endpoint: DELETE /api/events/:eventId

Path Parameters:

eventId (string, required): شناسه رویداد

Response:

{
  "success": boolean
}

3.5. دریافت تسک‌های غیرروتین (مشترک با Kanban و Todo)

Endpoint: GET /api/tasks/non-routine

Response:

{
  "tasks": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "deadline": number,
      "routine": 0,
      "tags": ["string"],
      "author": {
        "name": "string",
        "image": "string"
      },
      "source": "calendar" | "kanban" | "todo",
      "status": "string",
      "priority": "high" | "medium" | "low"
    }
  ]
}

نکته: این API فقط تسک‌هایی با routine = 0 (NONE) را برمی‌گرداند که باید در Calendar، Kanban، و Todo نمایش داده شوند.

4. Kanban

Route: /apps/kanban

دسترسی: همه کاربران

نکات مهم:

Kanban باید با Calendar و Todo متصل باشد
تسک‌هایی که routine = 0 دارند باید در هر سه قابل نمایش باشند

API های مورد نیاز

4.1. دریافت Board Kanban

Endpoint: GET /api/kanban/board

Response:

{
  "columns": [
    {
      "id": number,
      "title": "string",
      "taskIds": [number]
    }
  ],
  "tasks": [
    {
      "id": number,
      "title": "string",
      "badgeText": ["string"],
      "attachments": number,
      "comments": number,
      "assigned": [
        {
          "src": "string",
          "name": "string"
        }
      ],
      "image": "string",
      "dueDate": "string",
      "routine": 0 | 1 | 2 | 3 | 4,
      "description": "string",
      "tags": ["string"],
      "source": "kanban" | "calendar" | "todo"
    }
  ]
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`columns[].id`	number	شناسه یکتا ستون
`columns[].title`	string	عنوان ستون
`columns[].taskIds`	number[]	شناسه‌های تسک‌های موجود در ستون
`tasks[].id`	number	شناسه یکتا تسک
`tasks[].title`	string	عنوان تسک
`tasks[].badgeText`	string[]	برچسب‌های متن
`tasks[].attachments`	number	تعداد پیوست‌ها
`tasks[].comments`	number	تعداد کامنت‌ها
`tasks[].assigned[].src`	string	تصویر اختصاص یافته (URL)
`tasks[].assigned[].name`	string	نام اختصاص یافته
`tasks[].image`	string	تصویر تسک (URL)
`tasks[].dueDate`	string	تاریخ مهلت (ISO 8601)
`tasks[].routine`	number	نوع روتین (0: NONE, 1: DAILY, ...)
`tasks[].description`	string	توضیحات تسک
`tasks[].tags`	string[]	برچسب‌ها
`tasks[].source`	string	منبع تسک

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

Endpoint: POST /api/kanban/columns

Request Body:

{
  "title": "string"
}

Response:

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

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

Endpoint: PUT /api/kanban/columns/:columnId

Path Parameters:

columnId (number, required): شناسه ستون

Request Body:

{
  "title": "string",
  "taskIds": [number]
}

Response:

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

4.4. حذف ستون

Endpoint: DELETE /api/kanban/columns/:columnId

Path Parameters:

columnId (number, required): شناسه ستون

Response:

{
  "success": boolean
}

4.5. ایجاد تسک جدید

Endpoint: POST /api/kanban/tasks

Request Body:

{
  "columnId": number,
  "title": "string",
  "description": "string",
  "badgeText": ["string"],
  "attachments": number,
  "comments": number,
  "assigned": [
    {
      "src": "string",
      "name": "string"
    }
  ],
  "image": "string",
  "dueDate": "string",
  "routine": 0 | 1 | 2 | 3 | 4,
  "tags": ["string"]
}

Response:

{
  "task": {
    "id": number,
    "title": "string",
    "badgeText": ["string"],
    "attachments": number,
    "comments": number,
    "assigned": [
      {
        "src": "string",
        "name": "string"
      }
    ],
    "image": "string",
    "dueDate": "string",
    "routine": number,
    "description": "string",
    "tags": ["string"],
    "source": "kanban"
  }
}

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

Endpoint: PUT /api/kanban/tasks/:taskId

Path Parameters:

taskId (number, required): شناسه تسک

Request Body:

{
  "title": "string",
  "description": "string",
  "badgeText": ["string"],
  "attachments": number,
  "comments": number,
  "assigned": [
    {
      "src": "string",
      "name": "string"
    }
  ],
  "image": "string",
  "dueDate": "string",
  "routine": number,
  "tags": ["string"],
  "columnId": number
}

Response:

{
  "task": {
    "id": number,
    "title": "string",
    "badgeText": ["string"],
    "attachments": number,
    "comments": number,
    "assigned": [
      {
        "src": "string",
        "name": "string"
      }
    ],
    "image": "string",
    "dueDate": "string",
    "routine": number,
    "description": "string",
    "tags": ["string"],
    "source": "string"
  }
}

4.7. حذف تسک

Endpoint: DELETE /api/kanban/tasks/:taskId

Path Parameters:

taskId (number, required): شناسه تسک

Response:

{
  "success": boolean
}

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

Endpoint: PUT /api/kanban/tasks/:taskId/move

Path Parameters:

taskId (number, required): شناسه تسک

Request Body:

{
  "fromColumnId": number,
  "toColumnId": number,
  "position": number
}

Response:

{
  "success": boolean,
  "columns": [
    {
      "id": number,
      "title": "string",
      "taskIds": [number]
    }
  ]
}

5. Todo

Route: /todo/all

دسترسی: همه کاربران

نکات مهم:

Todo باید با Calendar و Kanban متصل باشد
تسک‌هایی که routine = 0 دارند باید در هر سه قابل نمایش باشند

API های مورد نیاز

5.1. دریافت لیست Todo

Endpoint: GET /api/todos

Query Parameters:

status? (string, optional): وضعیت (pending, in-progress, completed)
priority? (string, optional): اولویت (high, medium, low)
label? (string, optional): برچسب
filter? (string, optional): فیلتر (all, starred, important, completed, trashed)
search? (string, optional): جستجو در عنوان و توضیحات

Response:

{
  "todos": [
    {
      "id": number,
      "title": "string",
      "description": "string",
      "status": "pending" | "in-progress" | "completed",
      "priority": "high" | "medium" | "low",
      "startDate": "string",
      "dueDate": "string",
      "createdDate": "string",
      "labels": ["string"],
      "isStarred": boolean,
      "isImportant": boolean,
      "isTrashed": boolean,
      "routine": 0 | 1 | 2 | 3 | 4,
      "source": "todo" | "calendar" | "kanban"
    }
  ],
  "total": number
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`todos[].id`	number	شناسه یکتا todo
`todos[].title`	string	عنوان todo
`todos[].description`	string	توضیحات todo
`todos[].status`	string	وضعیت (pending, in-progress, completed)
`todos[].priority`	string	اولویت (high, medium, low)
`todos[].startDate`	string	تاریخ شروع (ISO 8601)
`todos[].dueDate`	string	تاریخ مهلت (ISO 8601)
`todos[].createdDate`	string	تاریخ ایجاد (ISO 8601)
`todos[].labels`	string[]	برچسب‌ها
`todos[].isStarred`	boolean	نشان شده
`todos[].isImportant`	boolean	مهم
`todos[].isTrashed`	boolean	حذف شده
`todos[].routine`	number	نوع روتین (0: NONE, 1: DAILY, ...)
`todos[].source`	string	منبع todo

5.2. ایجاد Todo جدید

Endpoint: POST /api/todos

Request Body:

{
  "title": "string",
  "description": "string",
  "status": "pending" | "in-progress" | "completed",
  "priority": "high" | "medium" | "low",
  "startDate": "string",
  "dueDate": "string",
  "labels": ["string"],
  "isStarred": boolean,
  "isImportant": boolean,
  "routine": 0 | 1 | 2 | 3 | 4
}

Response:

{
  "todo": {
    "id": number,
    "title": "string",
    "description": "string",
    "status": "string",
    "priority": "string",
    "startDate": "string",
    "dueDate": "string",
    "createdDate": "string",
    "labels": ["string"],
    "isStarred": boolean,
    "isImportant": boolean,
    "isTrashed": boolean,
    "routine": number,
    "source": "todo"
  }
}

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

Endpoint: PUT /api/todos/:todoId

Path Parameters:

todoId (number, required): شناسه todo

Request Body:

{
  "title": "string",
  "description": "string",
  "status": "pending" | "in-progress" | "completed",
  "priority": "high" | "medium" | "low",
  "startDate": "string",
  "dueDate": "string",
  "labels": ["string"],
  "isStarred": boolean,
  "isImportant": boolean,
  "isTrashed": boolean,
  "routine": number
}

Response:

{
  "todo": {
    "id": number,
    "title": "string",
    "description": "string",
    "status": "string",
    "priority": "string",
    "startDate": "string",
    "dueDate": "string",
    "createdDate": "string",
    "labels": ["string"],
    "isStarred": boolean,
    "isImportant": boolean,
    "isTrashed": boolean,
    "routine": number,
    "source": "string"
  }
}

5.4. حذف Todo

Endpoint: DELETE /api/todos/:todoId

Path Parameters:

todoId (number, required): شناسه todo

Response:

{
  "success": boolean
}

5.5. دریافت لیست برچسب‌های موجود

Endpoint: GET /api/todos/labels

Response:

{
  "labels": ["string"]
}

6. User Management

Route: /apps/user/list, /apps/user/view

دسترسی: فقط برای ادمین (Admin)

6.1. User List

Route: /apps/user/list

API های مورد نیاز

6.1.1. دریافت لیست کاربران

Endpoint: GET /api/admin/users

Query Parameters:

role? (string, optional): فیلتر بر اساس نقش (admin, author, editor, maintainer, subscriber)
status? (string, optional): فیلتر بر اساس وضعیت (active, pending, inactive)
search? (string, optional): جستجو در نام، ایمیل، نام کاربری
page? (number, optional): شماره صفحه
limit? (number, optional): تعداد آیتم در هر صفحه

Response:

{
  "users": [
    {
      "id": number,
      "role": "string",
      "email": "string",
      "status": "active" | "pending" | "inactive",
      "avatar": "string",
      "company": "string",
      "country": "string",
      "contact": "string",
      "fullName": "string",
      "username": "string",
      "currentPlan": "string",
      "avatarColor": "primary" | "success" | "error" | "warning" | "info",
      "billing": "string"
    }
  ],
  "pagination": {
    "page": number,
    "limit": number,
    "total": number,
    "totalPages": number
  },
  "stats": {
    "total": number,
    "active": number,
    "pending": number,
    "inactive": number
  }
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`users[].id`	number	شناسه یکتا کاربر
`users[].role`	string	نقش کاربر
`users[].email`	string	ایمیل کاربر
`users[].status`	string	وضعیت کاربر
`users[].avatar`	string	آواتار کاربر (URL)
`users[].company`	string	نام شرکت
`users[].country`	string	کشور
`users[].contact`	string	شماره تماس
`users[].fullName`	string	نام کامل
`users[].username`	string	نام کاربری
`users[].currentPlan`	string	پلن فعلی
`users[].avatarColor`	ThemeColor	رنگ آواتار (در صورت نبودن تصویر)
`users[].billing`	string	روش پرداخت

6.1.2. ایجاد کاربر جدید

Endpoint: POST /api/admin/users

Request Body:

{
  "role": "string",
  "email": "string",
  "fullName": "string",
  "username": "string",
  "contact": "string",
  "company": "string",
  "country": "string",
  "status": "active" | "pending" | "inactive",
  "currentPlan": "string",
  "avatar": "string"
}

Response:

{
  "user": {
    "id": number,
    "role": "string",
    "email": "string",
    "status": "string",
    "avatar": "string",
    "company": "string",
    "country": "string",
    "contact": "string",
    "fullName": "string",
    "username": "string",
    "currentPlan": "string",
    "avatarColor": "string",
    "billing": "string"
  }
}

6.1.3. به‌روزرسانی کاربر

Endpoint: PUT /api/admin/users/:userId

Path Parameters:

userId (number, required): شناسه کاربر

Request Body:

{
  "role": "string",
  "email": "string",
  "fullName": "string",
  "username": "string",
  "contact": "string",
  "company": "string",
  "country": "string",
  "status": "active" | "pending" | "inactive",
  "currentPlan": "string",
  "avatar": "string"
}

Response:

{
  "user": {
    "id": number,
    "role": "string",
    "email": "string",
    "status": "string",
    "avatar": "string",
    "company": "string",
    "country": "string",
    "contact": "string",
    "fullName": "string",
    "username": "string",
    "currentPlan": "string",
    "avatarColor": "string",
    "billing": "string"
  }
}

6.1.4. حذف کاربر

Endpoint: DELETE /api/admin/users/:userId

Path Parameters:

userId (number, required): شناسه کاربر

Response:

{
  "success": boolean
}

6.2. User View

Route: /apps/user/view

API های مورد نیاز

6.2.1. دریافت جزئیات کاربر

Endpoint: GET /api/admin/users/:userId

Path Parameters:

userId (number, required): شناسه کاربر

Response:

{
  "user": {
    "id": number,
    "role": "string",
    "email": "string",
    "status": "string",
    "avatar": "string",
    "company": "string",
    "country": "string",
    "contact": "string",
    "fullName": "string",
    "username": "string",
    "currentPlan": "string",
    "avatarColor": "string",
    "billing": "string",
    "joinDate": "string",
    "lastLogin": "string",
    "twoStepVerification": boolean,
    "recentDevices": [
      {
        "id": "string",
        "device": "string",
        "browser": "string",
        "location": "string",
        "lastActive": "string",
        "ip": "string"
      }
    ],
    "activityTimeline": [
      {
        "id": "string",
        "title": "string",
        "description": "string",
        "time": "string",
        "icon": "string",
        "color": "string"
      }
    ],
    "projects": [
      {
        "id": "string",
        "name": "string",
        "startDate": "string",
        "deadline": "string",
        "status": "string",
        "budget": number,
        "spent": number
      }
    ],
    "invoices": [
      {
        "id": "string",
        "total": number,
        "issuedDate": "string",
        "status": "string",
        "balance": number
      }
    ],
    "connections": [
      {
        "id": "string",
        "app": "string",
        "username": "string",
        "avatar": "string",
        "connected": boolean,
        "connectedAt": "string"
      }
    ],
    "notifications": {
      "email": {
        "newComment": boolean,
        "newAnswer": boolean,
        "followMe": boolean,
        "answerOnForm": boolean,
        "productUpdate": boolean,
        "productNewFeature": boolean,
        "productAnnouncement": boolean
      },
      "phone": {
        "newComment": boolean,
        "newAnswer": boolean,
        "followMe": boolean,
        "answerOnForm": boolean
      }
    }
  }
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`user.joinDate`	string	تاریخ عضویت (ISO 8601)
`user.lastLogin`	string	آخرین ورود (ISO 8601)
`user.twoStepVerification`	boolean	فعال‌سازی احراز هویت دو مرحله‌ای
`user.recentDevices[].id`	string	شناسه دستگاه
`user.recentDevices[].device`	string	نام دستگاه
`user.recentDevices[].browser`	string	مرورگر
`user.recentDevices[].location`	string	موقعیت جغرافیایی
`user.recentDevices[].lastActive`	string	آخرین فعالیت (ISO 8601)
`user.recentDevices[].ip`	string	آدرس IP
`user.activityTimeline[].id`	string	شناسه فعالیت
`user.activityTimeline[].title`	string	عنوان فعالیت
`user.activityTimeline[].description`	string	توضیحات فعالیت
`user.activityTimeline[].time`	string	زمان فعالیت (ISO 8601)
`user.activityTimeline[].icon`	string	آیکون
`user.activityTimeline[].color`	string	رنگ
`user.projects[].id`	string	شناسه پروژه
`user.projects[].name`	string	نام پروژه
`user.projects[].startDate`	string	تاریخ شروع (ISO 8601)
`user.projects[].deadline`	string	تاریخ مهلت (ISO 8601)
`user.projects[].status`	string	وضعیت پروژه
`user.projects[].budget`	number	بودجه
`user.projects[].spent`	number	هزینه شده
`user.invoices[].id`	string	شناسه فاکتور
`user.invoices[].total`	number	مبلغ کل
`user.invoices[].issuedDate`	string	تاریخ صدور (ISO 8601)
`user.invoices[].status`	string	وضعیت فاکتور
`user.invoices[].balance`	number	مانده حساب
`user.connections[].id`	string	شناسه اتصال
`user.connections[].app`	string	نام اپلیکیشن
`user.connections[].username`	string	نام کاربری
`user.connections[].avatar`	string	آواتار (URL)
`user.connections[].connected`	boolean	وضعیت اتصال
`user.connections[].connectedAt`	string	تاریخ اتصال (ISO 8601)
`user.notifications.email.*`	boolean	تنظیمات اطلاع‌رسانی ایمیل
`user.notifications.phone.*`	boolean	تنظیمات اطلاع‌رسانی تلفن

6.2.2. به‌روزرسانی تنظیمات امنیتی کاربر

Endpoint: PUT /api/admin/users/:userId/security

Path Parameters:

userId (number, required): شناسه کاربر

Request Body:

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

Response:

{
  "success": boolean
}

6.2.3. به‌روزرسانی تنظیمات اطلاع‌رسانی

Endpoint: PUT /api/admin/users/:userId/notifications

Path Parameters:

userId (number, required): شناسه کاربر

Request Body:

{
  "email": {
    "newComment": boolean,
    "newAnswer": boolean,
    "followMe": boolean,
    "answerOnForm": boolean,
    "productUpdate": boolean,
    "productNewFeature": boolean,
    "productAnnouncement": boolean
  },
  "phone": {
    "newComment": boolean,
    "newAnswer": boolean,
    "followMe": boolean,
    "answerOnForm": boolean
  }
}

Response:

{
  "success": boolean
}

7. Roles & Permissions

Route: /apps/roles, /apps/permissions

دسترسی: فقط برای ادمین (Admin)

7.1. Roles

Route: /apps/roles

API های مورد نیاز

7.1.1. دریافت لیست نقش‌ها

Endpoint: GET /api/admin/roles

Response:

{
  "roles": [
    {
      "id": "string",
      "name": "string",
      "totalUsers": number,
      "avatars": ["string"],
      "description": "string"
    }
  ],
  "roleStats": {
    "administrator": number,
    "author": number,
    "editor": number,
    "maintainer": number,
    "subscriber": number
  }
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`roles[].id`	string	شناسه یکتا نقش
`roles[].name`	string	نام نقش
`roles[].totalUsers`	number	تعداد کاربران دارای این نقش
`roles[].avatars`	string[]	آواتارهای کاربران (URL)
`roles[].description`	string	توضیحات نقش
`roleStats.*`	number	آمار کاربران هر نقش

7.1.2. دریافت کاربران بر اساس نقش

Endpoint: GET /api/admin/roles/:roleName/users

Path Parameters:

roleName (string, required): نام نقش

Response:

{
  "users": [
    {
      "id": number,
      "fullName": "string",
      "username": "string",
      "email": "string",
      "avatar": "string",
      "role": "string",
      "status": "string"
    }
  ]
}

7.1.3. ایجاد نقش جدید

Endpoint: POST /api/admin/roles

Request Body:

{
  "name": "string",
  "description": "string",
  "permissions": ["string"]
}

Response:

{
  "role": {
    "id": "string",
    "name": "string",
    "description": "string",
    "totalUsers": number,
    "avatars": [],
    "permissions": ["string"]
  }
}

7.1.4. به‌روزرسانی نقش

Endpoint: PUT /api/admin/roles/:roleId

Path Parameters:

roleId (string, required): شناسه نقش

Request Body:

{
  "name": "string",
  "description": "string",
  "permissions": ["string"]
}

Response:

{
  "role": {
    "id": "string",
    "name": "string",
    "description": "string",
    "totalUsers": number,
    "avatars": ["string"],
    "permissions": ["string"]
  }
}

7.1.5. حذف نقش

Endpoint: DELETE /api/admin/roles/:roleId

Path Parameters:

roleId (string, required): شناسه نقش

Response:

{
  "success": boolean
}

7.2. Permissions

Route: /apps/permissions

API های مورد نیاز

7.2.1. دریافت لیست Permission ها

Endpoint: GET /api/admin/permissions

Query Parameters:

search? (string, optional): جستجو در نام permission

Response:

{
  "permissions": [
    {
      "id": number,
      "name": "string",
      "createdDate": "string",
      "assignedTo": "string" | ["string"]
    }
  ],
  "total": number
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`permissions[].id`	number	شناسه یکتا permission
`permissions[].name`	string	نام permission
`permissions[].createdDate`	string	تاریخ ایجاد (ISO 8601)
`permissions[].assignedTo`	string \| string[]	نقش یا نقش‌های اختصاص یافته

7.2.2. ایجاد Permission جدید

Endpoint: POST /api/admin/permissions

Request Body:

{
  "name": "string",
  "assignedTo": "string" | ["string"]
}

Response:

{
  "permission": {
    "id": number,
    "name": "string",
    "createdDate": "string",
    "assignedTo": "string" | ["string"]
  }
}

7.2.3. به‌روزرسانی Permission

Endpoint: PUT /api/admin/permissions/:permissionId

Path Parameters:

permissionId (number, required): شناسه permission

Request Body:

{
  "name": "string",
  "assignedTo": "string" | ["string"]
}

Response:

{
  "permission": {
    "id": number,
    "name": "string",
    "createdDate": "string",
    "assignedTo": "string" | ["string"]
  }
}

7.2.4. حذف Permission

Endpoint: DELETE /api/admin/permissions/:permissionId

Path Parameters:

permissionId (number, required): شناسه permission

Response:

{
  "success": boolean
}

8. Sensor Hub

Route: تب مرکز سنسور در Account Settings

دسترسی: کاربران احراز هویت شده

API های مورد نیاز

8.1. دریافت لیست سنسورها

Endpoint: GET /api/sensor-hub/

Response:

{
  "data": [
    {
      "name": "string",
      "uuid_sensor": "string",
      "last_updated": "string"
    }
  ]
}

یا در صورت برگرداندن تک سنسور:

{
  "data": {
    "name": "string",
    "uuid_sensor": "string",
    "last_updated": "string"
  }
}

8.2. افزودن سنسور جدید

Endpoint: POST /api/sensor-hub/

Request Body:

{
  "name": "string",
  "uuid_sensor": "string",
  "plant_type": "string",
  "plant_name": "string",
  "area_geojson": {},
  "area_m2": number
}

توضیحات فیلدها:

فیلد	نوع	الزامی	توضیحات
`name`	string	بله	نام سنسور
`uuid_sensor`	string	بله	شناسه یکتای سنسور
`plant_type`	string	خیر	نوع محصول (مثل گندم، جو، ذرت)
`plant_name`	string	خیر	رقم/نام محصول (وابسته به plant_type)
`area_geojson`	object	خیر	محدوده GeoJSON رسم‌شده روی نقشه
`area_m2`	number	خیر	مساحت به متر مربع

8.3. دریافت انواع محصول و ارقام (Plant Types & Varieties)

Endpoint: GET /api/sensor-hub/plant-types

توضیح: این API لیست انواع محصول و ارقام/رقم‌های هر نوع را برمی‌گرداند. فرانت‌اند در فرم افزودن سنسور از این داده برای Autocomplete نوع محصول و رقم استفاده می‌کند.

Response:

{
  "plant_types": [
    "گندم",
    "جو",
    "ذرت",
    "برنج",
    "پنبه",
    "چغندر قند",
    "سیب‌زمینی",
    "گوجه‌فرنگی",
    "پیاز",
    "سبزیجات"
  ],
  "plant_names_by_type": {
    "گندم": ["رقم آذر", "رقم شریف", "رقم مروارید", "رقم بهار", "رقم الوند"],
    "جو": ["رقم سرداری", "رقم زاگرس", "رقم کرج", "رقم ریجاب"],
    "ذرت": ["رقم سینگل کراس ۷۰۴", "رقم سینگل کراس ۷۰۷", "رقم ماکزیما"],
    "برنج": ["رقم فجر", "رقم خزر", "رقم طارم"],
    "پنبه": ["رقم ورامین", "رقم ساحل", "رقم سپید"],
    "چغندر قند": ["رقم اکباتان", "رقم شیرین", "رقم پاییزه"],
    "سیب‌زمینی": ["رقم آگریا", "رقم مارفونا", "رقم ساوالان"],
    "گوجه‌فرنگی": ["رقم چری", "رقم روتگرز", "رقم پامیس"],
    "پیاز": ["رقم قرمز آذرشهر", "رقم سفید قم", "رقم زرد"],
    "سبزیجات": ["کاهو", "جعفری", "شوید", "تره", "ریحان"]
  }
}

توضیحات فیلدها:

فیلد	نوع	توضیحات
`plant_types`	string[]	آرایه انواع محصول برای انتخاب در Autocomplete
`plant_names_by_type`	Record<string, string[]>	نگاشت نوع محصول به لیست ارقام/نام‌های آن

نکته: داده‌های نمونه بالا باید از بک‌اند قابل ویرایش و مدیریت باشند. فرانت‌اند این مقادیر را به‌طور ثابت ندارد و از این API دریافت می‌کند.

خلاصه نکات مهم

Sensor Hub: فرم افزودن سنسور شامل نوع محصول و رقم می‌شود. لیست plant_types و plant_names_by_type باید از API دریافت شود، نه به‌صورت ثابت در فرانت.
User Management & Roles & Permissions: فقط برای ادمین قابل دسترسی هستند
Calendar, Kanban, Todo: این سه صفحه باید به یکدیگر متصل باشند و تسک‌هایی با routine = 0 (NONE) در هر سه قابل نمایش باشند
AI Chat: باید به تسک‌های Calendar، Kanban، و Todo دسترسی داشته باشد و نسبت به برخی پیام‌ها حساس باشد
Authentication: سیستم Authentication جزو این مستندات نیست

Enum ها و Type های مشترک

Routine Enum

enum Routine {
  NONE = 0,
  DAILY = 1,
  WEEKLY = 2,
  MONTHLY = 3,
  YEARLY = 4
}

ThemeColor Type

type ThemeColor = "primary" | "success" | "error" | "warning" | "info"

Status Type (Chat)

type StatusType = "busy" | "away" | "online" | "offline"

Todo Status Type

type TodoStatusType = "pending" | "in-progress" | "completed"

Todo Priority Type

type TodoPriorityType = "high" | "medium" | "low"

Calendar Type

type CalendarFiltersType = "Personal" | "Business" | "Family" | "Holiday" | "ETC"

User Role Type

type UserRoleType = "admin" | "author" | "editor" | "maintainer" | "subscriber"

User Status Type

type UserStatusType = "active" | "pending" | "inactive"

تاریخ ایجاد مستندات: 2024 نسخه: 1.0.0

42 KiB Raw Blame History

مستندات API های صفحات منوی عمودی

فهرست مطالب

1. Chat

API های مورد نیاز

1.1. دریافت لیست مخاطبین

1.2. دریافت چت‌های کاربر

1.3. دریافت پیام‌های چت

1.4. ارسال پیام جدید

1.5. به‌روزرسانی وضعیت مشاهده پیام

1.6. دریافت اطلاعات پروفایل کاربر

2. AI Chat

API های مورد نیاز

2.1. ارسال پیام به AI

2.2. دریافت تاریخچه مکالمه

2.3. دریافت لیست مکالمات

2.4. دریافت تسک‌های مرتبط (برای AI Chat)

3. Calendar

API های مورد نیاز

3.1. دریافت Event ها

3.2. ایجاد Event جدید

3.3. به‌روزرسانی Event

3.4. حذف Event

3.5. دریافت تسک‌های غیرروتین (مشترک با Kanban و Todo)

4. Kanban

API های مورد نیاز

4.1. دریافت Board Kanban

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

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

4.4. حذف ستون

4.5. ایجاد تسک جدید

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

4.7. حذف تسک

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

5. Todo

API های مورد نیاز

5.1. دریافت لیست Todo

5.2. ایجاد Todo جدید

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

5.4. حذف Todo

5.5. دریافت لیست برچسب‌های موجود

6. User Management

6.1. User List

API های مورد نیاز

6.1.1. دریافت لیست کاربران

6.1.2. ایجاد کاربر جدید

6.1.3. به‌روزرسانی کاربر

6.1.4. حذف کاربر

6.2. User View

API های مورد نیاز

6.2.1. دریافت جزئیات کاربر

6.2.2. به‌روزرسانی تنظیمات امنیتی کاربر

6.2.3. به‌روزرسانی تنظیمات اطلاع‌رسانی

7. Roles & Permissions

7.1. Roles

API های مورد نیاز

7.1.1. دریافت لیست نقش‌ها

7.1.2. دریافت کاربران بر اساس نقش

7.1.3. ایجاد نقش جدید

7.1.4. به‌روزرسانی نقش

7.1.5. حذف نقش

7.2. Permissions

API های مورد نیاز

7.2.1. دریافت لیست Permission ها

7.2.2. ایجاد Permission جدید

7.2.3. به‌روزرسانی Permission

7.2.4. حذف Permission

8. Sensor Hub

API های مورد نیاز

8.1. دریافت لیست سنسورها

8.2. افزودن سنسور جدید

8.3. دریافت انواع محصول و ارقام (Plant Types & Varieties)

خلاصه نکات مهم

Enum ها و Type های مشترک

Routine Enum

ThemeColor Type

Status Type (Chat)

Todo Status Type

Todo Priority Type

Calendar Type

42 KiB

Raw Blame History