# Task Management - REST API Documentation This document describes all REST API endpoints available in the Task Management, with special focus on authentication, role-based access control, task lifecycle management, date-wise assignee workload scheduling, and conflict detection. --- ## 1. Overview & Interactive Documentation - **Interactive Swagger UI**: `GET /api/docs` (served directly via [api-docs.html](file:///Users/nilanjanmondal/projects/eveApplication/public/api-docs.html)) - **OpenAPI 3.0 Specification**: `GET /api/swagger.json` (served directly via [swagger.json](file:///Users/nilanjanmondal/projects/eveApplication/public/swagger.json)) - **Base API URL**: `/api` ### Authentication Scheme All protected endpoints require a JWT Bearer token in the `Authorization` header: ```http Authorization: Bearer ``` --- ## 2. Authentication Endpoints ### 2.1 Register - **Endpoint**: `POST /api/register` or `POST /api/register/bulk` - **Access**: Public - **Single User Payload**: ```json { "name": "John Doe", "email": "johndoe@example.com", "mobile_number": "9876543210", "password": "password123", "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "class_id": "optional-uuid", "subject_id": "optional-uuid", "roles": ["user"] } ``` *(Accepts `mobile_number` or `mobileNumber`)* - **Multiple Users Payload (with Shared Department)**: ```json { "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "users": [ { "name": "User One", "email": "user1@example.com", "mobile_number": "9876543210", "password": "password123" }, { "name": "User Two", "email": "user2@example.com", "mobile_number": "9876543211", "password": "password123", "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } ``` *(Also accepts a raw JSON array of users `[ { ... }, { ... } ]`)* - **Single User Response `201 Created`**: ```json { "success": true, "message": "Registration successful.", "token": "eyJ0eXAiOiJKV1QiLC...", "token_type": "Bearer", "expires_in": 86400, "refresh_token": "...", "userDetails": { "id": "9a1b2c3d-...", "name": "John Doe", "email": "johndoe@example.com", "mobile_number": "9876543210", "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": ["user"] } } ``` - **Multiple Users Response `201 Created`**: ```json { "success": true, "message": "2 users registered successfully.", "count": 2, "users": [ { "token": "eyJ0eXAiOiJKV1QiLC...", "token_type": "Bearer", "expires_in": 86400, "refresh_token": "...", "userDetails": { "id": "uuid-1", "name": "User One", "email": "user1@example.com", "mobile_number": "9876543210", "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": ["user"] } }, { "token": "eyJ0eXAiOiJKV1QiLC...", "token_type": "Bearer", "expires_in": 86400, "refresh_token": "...", "userDetails": { "id": "uuid-2", "name": "User Two", "email": "user2@example.com", "mobile_number": "9876543211", "department_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "roles": ["user"] } } ], "data": [...] } ``` ### 2.2 Login - **Endpoint**: `POST /api/login` - **Access**: Public - **Payload**: ```json { "mobileNumber": "9999999999", "password": "password123" } ``` *(Accepts `email` or `mobileNumber` interchangeably)* - **Response `200 OK`**: ```json { "success": true, "message": "Login successful.", "token": "eyJ0eXAiOiJKV1QiLC...", "userDetails": { "id": "9a1b2c3d-...", "name": "Admin User", "email": "admin@eveapplication.com", "mobile_number": "9999999999", "roles": ["admin"] } } ``` ### 2.3 Fresh Token / Refresh Token (OAuth 2.0 Flow) - **Endpoint**: `POST /api/fresh-token` *(Aliases: `POST /api/refresh-token`, `POST /api/refresh`)* - **Access**: Public (requires valid `refresh_token`) - **Headers**: ```http Content-Type: application/json X-Refresh-Token: ``` - **Payload**: ```json { "refresh_token": "eyJ0eXAiOiJKV1QiLC..." } ``` *(Accepts `refresh_token`, camelCase `refreshToken`, `X-Refresh-Token` header, or `Authorization: Bearer `)* - **Response `200 OK`**: ```json { "success": true, "message": "Token refreshed successfully.", "responseMessage": "Token refreshed successfully.", "token": "eyJ0eXAiOiJKV1QiLC...", "access_token": "eyJ0eXAiOiJKV1QiLC...", "token_type": "Bearer", "expires_in": 86400, "refresh_token": "eyJ0eXAiOiJKV1QiLC...", "userDetails": { ... }, } ``` - **Security Features & Best Practices**: - **Token Type Isolation**: Refresh tokens cannot be used to call protected APIs; access tokens cannot be used to refresh. - **Refresh Token Rotation (RTR)**: Upon every refresh, a new refresh token is issued and the old one is invalidated. - **Replay Attack Detection**: If a previously consumed or revoked refresh token is re-submitted, it is blocked immediately. - **Concurrency Grace Window**: Parallel requests (common in React & Flutter when multiple widgets fire simultaneously) share the same fresh token pair within a 30-second window, preventing race-condition 401 logouts. ### 2.4 Current User - **Endpoint**: `GET /api/me` - **Access**: Authenticated (`Bearer `) - **Response `200 OK`**: Returns authenticated user profile, assigned roles, and relations. ### 2.5 Logout - **Endpoint**: `POST /api/logout` - **Access**: Authenticated (`Bearer `) - **Response `200 OK`**: ```json { "success": true, "message": "Successfully logged out." } ``` --- ## 3. Tasks & Date-Wise Workload Management ### 3.1 List Tasks - **Endpoint**: `GET /api/tasks` - **Query Parameters**: - `status` (`pending`, `in_progress`, `revision`, `review`, `completed`, `approved`, `cancelled`) - `priority` (`low`, `medium`, `high`, `urgent`) - `assigned_to` (UUID) - `department_id` (Integer) - `search` (String) - `start_date` (`YYYY-MM-DD`, exact start date match) - `start_date_from` (`YYYY-MM-DD`, tasks starting on or after) - `start_date_to` (`YYYY-MM-DD`, tasks starting on or before) - `due_date_from` (`YYYY-MM-DD`, tasks due on or after) - `due_date_to` (`YYYY-MM-DD`, tasks due on or before) ### 3.2 Create Task - **Endpoint**: `POST /api/tasks` - **Payload**: ```json { "title": "Color Grading Physics Class 10", "description": "Adjust color grading and tone curve.", "assigned_to": "9a1b2c3d-0000-0000-0000-000000000001", "department_id": 1, "priority": "urgent", "status": "pending", "start_date": "2026-10-05 4:20 P.M", "due_date": "2026-10-15 4:25 P.M" } ``` ### 3.3 Date-Wise Assignee Workload & Conflict Schedule (New ✨) Provides real-time date-wise task assignment schedule for an assignee, total active/overdue task counters, and collision detection against a chosen due date. #### Option A: Path Parameter with Date Query - **Endpoint**: `GET /api/tasks/user-workload/{userId}?date=2026-09-30` - **Parameters**: - `userId` (Path, UUID, required): Target user ID - `date` (Query, `YYYY-MM-DD`, optional): Target due date for conflict calculation - **Response `200 OK`**: ```json { "success": true, "message": "User workload retrieved successfully.", "data": { "user": { "id": "9a1b2c3d-0000-0000-0000-000000000001", "name": "Nilanjan Mondal", "email": "nilanjan@eveapplication.com", "department": "Video Production" }, "summary": { "total_assigned": 8, "active_tasks": 4, "completed_tasks": 3, "overdue_tasks": 1 }, "conflict_check": { "checked_date": "2026-09-30", "has_conflict": true, "conflict_count": 2, "tasks_on_date": [ { "id": 12, "title": "Intro Montage Animation", "priority": "high", "status": "in_progress", "due_date": "2026-09-30 14:00:00" }, { "id": 15, "title": "Audio Mastering Chapter 2", "priority": "medium", "status": "pending", "due_date": "2026-09-30 17:30:00" } ] }, "datewise_tasks": { "2026-09-29": { "date": "2026-09-29", "date_formatted": "Sep 29, 2026 (Tue)", "task_count": 1, "active_count": 1, "tasks": [ ... ] }, "2026-09-30": { "date": "2026-09-30", "date_formatted": "Sep 30, 2026 (Wed)", "task_count": 2, "active_count": 2, "tasks": [ ... ] } } } } ``` #### Option B: Query Parameters - **Endpoint**: `GET /api/tasks/workload?user_id={userId}&date=2026-09-30` ### 3.4 Single API: User Tasks & Subtasks in One Call (New ✨) Retrieve all tasks (with nested subtasks) and all direct subtasks assigned to a specific user, complete with department details and aggregate KPI counters. - **Endpoint**: `GET /api/user/{userId}/tasks` *(Alias: `GET /api/users/{userId}/tasks`)* - **Parameters**: - `userId` (Path, UUID, required): Target user ID - `status` (Query, string, optional): `pending`, `in_progress`, `revision`, `review`, `completed`, `approved`, `cancelled` - **Response `200 OK`**: ```json { "success": true, "message": "User tasks and subtasks retrieved successfully.", "user": { "id": "9d36a992-0bca-4b08-9df2-51a44e548232", "name": "Nilanjan Mondal", "email": "nilanjan@example.com", "department": { "id": "uuid", "name": "Editorial Department", "code": "EDIT" } }, "summary": { "tasks": { "total": 5, "pending": 1, "in_progress": 3, "completed": 1, "overdue": 0 }, "subtasks": { "total": 8, "pending": 2, "in_progress": 4, "completed": 2 } }, "tasks": [ ... ], "subtasks": [ ... ] } ``` ### 3.5 Quick Status & Quick Assign - **Endpoint**: `PATCH /api/tasks/{id}/status` - Payload: `{"status": "in_progress"}` - **Endpoint**: `PATCH /api/tasks/{id}/assign` - Payload: `{"assigned_to": "9a1b2c3d-..."}` - **Endpoint**: `PATCH /api/tasks/{id}/workflow-stage` - Transition task directly to a specific workflow section/stage. - Payload: `{"stage": "Quality Check"}` - **Endpoint**: `POST /api/tasks/{id}/advance-stage` - Advance task sequentially to the next workflow stage in its assigned pipeline. - **Endpoint**: `PATCH /api/tasks/{id}/workflow` - Assign or reassign workflow pipeline to task. - Payload: `{"workflow_id": 1}` --- ## 4. Multi-Person Subtasks & Comments ### 4.1 Subtasks - `GET /api/tasks/{taskId}/subtasks` - List subtasks for a task (filterable by `page_no`, `assigned_to`, `department_id`, `status`, `search`, and `per_page`) - `GET /api/tasks/{taskId}/subtasks/{subtaskId}` - Retrieve single subtask details - `POST /api/tasks/subtasks` or `POST /api/tasks/{taskId}/subtasks` - Create subtasks with `page_no` and JSON `due_date`: ```json { "task_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "subtasks": [ { "title": "Audio Sync & Sound Design", "description": "Sync audio tracks with video timeline and balance audio levels.", "page_no": "12-15", "assigned_to": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "status": "pending", "due_date": { "from": "2026-07-02", "to": "2026-07-04" } }, { "title": "Color Grading", "description": "Balance saturation, match camera profiles, and export LUT.", "page_no": "16-20", "assigned_to": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "status": "pending", "due_date": { "from": "2026-10-15", "to": "2026-10-15" } } ] } ``` - `POST /api/tasks/subtasks/bulk` - Bulk create subtasks across multiple parent tasks (with `page_no`) - `PUT /api/tasks/{taskId}/subtasks/{subtaskId}` or `PATCH /api/tasks/{taskId}/subtasks/{subtaskId}` - **Unified Subtask Management (One API)**: - Update standard fields (`title`, `description`, `page_no`, `assigned_to`, `due_date`, `status`) - **Request Revision**: Pass `{ "revision_date": "2026-10-25 18:00:00", "revision_notes": "Color correction needed" }` to automatically set `status: "revision"`, increment `extension_count`, and update schedule deadlines. - **Approve Subtask**: Pass `{ "status": "approved" }` or `{ "action": "approve" }` to set `approved_at: now()`, `approved_by: `, and finalize subtask. - **Update Revision Notes/Extensions**: Directly update `revision_notes` or `extension_count`. - `POST /api/tasks/{taskId}/subtasks/{subtaskId}/revision` - Dedicated subtask revision request endpoint (`revision_date` required, `revision_notes` optional) - `POST /api/tasks/{taskId}/subtasks/{subtaskId}/approve` - Dedicated subtask approve endpoint - `PATCH /api/tasks/{taskId}/subtasks/{subtaskId}/toggle` - Toggle subtask completion status - `DELETE /api/tasks/{taskId}/subtasks/{subtaskId}` - Remove subtask ### 4.2 Comments & Audit Trail - `GET /api/tasks/{taskId}/comments` - Discussion comments & system change audit logs - `POST /api/tasks/{taskId}/comments` - Post comment - `DELETE /api/tasks/{taskId}/comments/{commentId}` - Delete comment --- ## 5. Workflows Master API The Workflow Master entity enables organizations to define structured, multi-section lifecycle pipelines with custom sequential stages (e.g., Drafting -> Review -> Proofing -> Final Approval -> Completed). ### 5.1 Endpoints - `GET /api/workflows` - List all workflows with search and department filtering - `POST /api/workflows` - Create a new workflow pipeline with custom stages/sections ```json { "name": "Video Production Pipeline", "code": "VIDEO_PIPELINE", "description": "Multi-stage video editing and QA pipeline", "department_id": 2, "stages": [ "1. Audio Prep & Sound Sync", "2. Color Grading & Tone", "3. Voiceover & Subtitles", "4. Quality Inspection", "5. Final Sign-off & Delivery" ], "is_active": true } ``` - `GET /api/workflows/{id}` - Retrieve details of a workflow - `PUT /api/workflows/{id}` - Update a workflow pipeline and its stages - `DELETE /api/workflows/{id}` - Delete a workflow (unlinks associated tasks safely) - `GET /api/workflows/{id}/stages` - Get ordered stages array for dropdowns/steppers --- ## 6. Task Types Master API The Task Types Master entity manages task classifications (such as Book, Video, Audio Podcast, etc.). Allows listing with associated task counts, creating, updating via dedicated or unified save endpoints, and safely deleting task types with auto-nullification of references on existing tasks. ### 6.1 Endpoints - `GET /api/task-types` - List all task types with optional keyword `search` and `is_active` filter - `POST /api/task-types` - Create a new task type - `POST /api/task-types/save` - **Unified Save API**: Create new task type or update existing if `id` is provided in payload - `GET /api/task-types/{id}` - Retrieve details of a task type by UUID or unique code - `PUT /api/task-types/{id}` or `PATCH /api/task-types/{id}` - Update a task type - `DELETE /api/task-types/{id}` - Delete a task type (safely disassociates tasks by setting `task_type_id: null`) ```json { "name": "Audio Podcast", "code": "audio_podcast", "description": "Podcast production and sound engineering", "is_active": true } ``` --- ## 7. Other Modular Resources | Section | Endpoints | Key Capabilities | |---|---|---| | **Task Types** | `/api/task-types` (`GET`, `POST`), `/api/task-types/save` (`POST`), `/api/task-types/{id}` (`GET`, `PUT`, `PATCH`, `DELETE`) | Master categories (Book, Video, etc.) with task counts & safe delete | | **Workflows** | `/api/workflows` (`GET`, `POST`, `PUT`, `DELETE`), `/api/workflows/{id}/stages` | Multi-section lifecycle pipelines and stages | | **Departments** | `/api/departments` (`GET`, `POST`), `/api/departments/tree` (`GET`), `/api/departments/parent/{parentId}` (`GET`), `/api/departments/{id}/sub-departments` (`GET`), `/api/departments/{id}` (`GET`, `PUT`, `DELETE`) | Manage parent departments & sub-departments, parent-wise tree, direct child sub-departments, circular check & team leads | | **Classes** | `/api/classes` (`GET`, `POST`, `PUT`, `DELETE`) | Academic classes breakdown | | **Subjects** | `/api/subjects` (`GET`, `POST`, `PUT`, `DELETE`) | Curriculum subjects under classes | | **Access Control** | `/api/roles` (`GET`, `POST`), `/api/roles/{id}` (`GET`, `PUT`, `PATCH`, `DELETE`), `/api/roles/{id}/toggle-status` (`PATCH`), `/api/roles/{id}/status` (`PUT`, `PATCH`), `/api/permissions` (`GET`), `/api/roles/{id}/permissions` (`POST`), `/api/users/{id}/roles` (`POST`) | RBAC synchronization, role active/deactive status management (`is_active` filter & toggle, superadmin protection), and user role assignment | | **Settings** | `/api/settings` (`GET`, `POST`) | System configuration key-value storage | | **Audit Logs** | `/api/audit-logs` (`GET`), `/api/audit-logs/{id}` (`GET`) | Full audit trail and change inspector | | **Dashboard** | `/api/dashboard/stats`, `/api/reports/analytics` | High-level metrics and workload charts | | **Menus** | `/api/menus` (`GET`, `POST`, `PUT`, `DELETE`) | Navigation hierarchies and role permissions | | **Notifications** | `/api/notifications`, `/api/notifications/{id}/read`, `/api/notifications/mark-all-read` | User notifications | | **Resource Attachment** | `/api/attach_resources` (`POST`, aliases: `/api/attach_respurces`, `/api/attach-resources`), `/api/detach_resources` (`POST`), `/api/attached_resources` (`GET`) | Attach and detach multiple polymorphic resources (departments, subjects) to/from users and models (`user_id`, `resource_id`, `department`, `subject`) |