LinkDesk/backend/docs/bulk-actions-implementation.md

Bulk Actions Implementation

Overview

This document describes the implementation of bulk action endpoints for the task management system. These endpoints allow coordinators and admins to perform batch operations on multiple tasks simultaneously.

Endpoints

1. Bulk Status Update

Endpoint: PUT /tasks/bulk/status

Request Body:

{
  "task_ids": [1, 2, 3],
  "status": "in_progress"
}

Response:

{
  "success_count": 3,
  "failed_count": 0,
  "errors": null
}

Permissions:

• Coordinators and admins can update any tasks
• Artists can only update their own assigned tasks

Features:

• Atomic transaction handling - either all tasks update or none
• Permission validation for all tasks before making changes
• Detailed error reporting for failed tasks

2. Bulk Assignment

Endpoint: PUT /tasks/bulk/assign

Request Body:

{
  "task_ids": [1, 2, 3],
  "assigned_user_id": 5
}

Response:

{
  "success_count": 3,
  "failed_count": 0,
  "errors": null
}

Permissions:

• Only coordinators and admins can perform bulk assignments

Features:

• Atomic transaction handling
• Validates user is a member of all task projects
• Sends notifications to assigned user for each task
• Detailed error reporting for failed tasks

Schemas

BulkStatusUpdate

class BulkStatusUpdate(BaseModel):
    task_ids: List[int] = Field(..., min_length=1)
    status: TaskStatus

BulkAssignment

class BulkAssignment(BaseModel):
    task_ids: List[int] = Field(..., min_length=1)
    assigned_user_id: int

BulkActionResult

class BulkActionResult(BaseModel):
    success_count: int
    failed_count: int
    errors: Optional[List[dict]] = None

Atomicity

Both endpoints implement atomic transactions:

1. All tasks are fetched in a single query
2. All validations (permissions, project membership) are performed before any changes
3. If any validation fails, the transaction is rolled back and no changes are made
4. Only if all validations pass are the changes committed

This ensures that partial updates never occur - either all tasks are updated successfully or none are.

Error Handling

Errors are returned in a structured format:

{
  "success_count": 1,
  "failed_count": 2,
  "errors": [
    {
      "task_id": 99,
      "error": "Task not found"
    },
    {
      "task_id": 100,
      "error": "Not authorized to update this task"
    }
  ]
}

Common error scenarios:

• Task not found
• Insufficient permissions
• User not a project member (for assignments)

Testing

A comprehensive test script is available at backend/test_bulk_actions.py that tests:

1. Successful bulk status updates
2. Successful bulk assignments
3. Error handling with invalid task IDs
4. Atomicity with mixed valid/invalid IDs
5. Permission validation

Run tests with:

python test_bulk_actions.py

Implementation Notes

Route Ordering

The bulk action endpoints are placed BEFORE the /{task_id} routes in the router to prevent FastAPI from trying to match "bulk" as a task_id parameter.

Transaction Management

SQLAlchemy's session management is used for transactions:

• db.commit() commits all changes
• db.rollback() reverts all changes if errors occur

Notifications

The bulk assignment endpoint sends individual notifications for each assigned task using the existing notification_service.notify_task_assigned() function.

Requirements Validated

This implementation satisfies the following requirements from the spec:

• 4.2: Bulk status update with atomic transaction handling
• 4.4: Error handling and rollback on failure
• 5.3: Bulk assignment with atomic transaction handling
• 5.5: Error handling and rollback on failure