LinkDesk/backend/docs/custom-task-status-create-endpoint.md

Custom Task Status Creation Endpoint Implementation

Overview

Implemented the POST endpoint for creating custom task statuses in projects. This allows coordinators and admins to define project-specific task statuses beyond the built-in system statuses.

Implementation Details

Endpoint

• Route: POST /projects/{project_id}/task-statuses
• Status Code: 201 Created
• Authorization: Requires coordinator or admin role

Features Implemented

1. Status Name Uniqueness Validation

• Validates that the status name is unique within the project
• Case-insensitive comparison to prevent duplicates like "In Review" and "in review"
• Checks against both existing custom statuses and system statuses
• Returns 409 Conflict if duplicate found

2. Auto-Assign Color from Palette

• Defines a default color palette with 10 distinct colors:
  • Purple (#8B5CF6)
  • Pink (#EC4899)
  • Teal (#14B8A6)
  • Orange (#F97316)
  • Cyan (#06B6D4)
  • Lime (#84CC16)
  • Violet (#A855F7)
  • Rose (#F43F5E)
  • Sky (#22D3EE)
  • Yellow (#FACC15)
• Automatically assigns the first unused color from the palette
• If all colors are used, cycles back through the palette
• Users can override by providing a custom color in hex format

3. Unique Status ID Generation

• Generates unique IDs using UUID4 with format: custom_{8-char-hex}
• Example: custom_0c7ba931
• Ensures no ID collisions

4. JSON Column Updates

• Uses SQLAlchemy's flag_modified() to properly track changes to JSON columns
• Ensures database updates are persisted correctly

5. Status Ordering

• Automatically assigns order based on existing statuses
• New statuses are appended to the end (max_order + 1)
• Maintains consistent ordering for UI display

Request Schema

{
  "name": "Ready for Review",
  "color": "#8B5CF6"  // Optional - auto-assigned if not provided
}

Response Schema

{
  "message": "Custom task status 'Ready for Review' created successfully",
  "status": {
    "id": "custom_0c7ba931",
    "name": "Ready for Review",
    "color": "#EC4899",
    "order": 3,
    "is_default": false
  },
  "all_statuses": {
    "statuses": [...],  // All custom statuses
    "system_statuses": [...],  // Built-in system statuses
    "default_status_id": "not_started"
  }
}

Validation Rules

Name Validation (via Pydantic schema)

• Minimum length: 1 character
• Maximum length: 50 characters
• Whitespace is trimmed
• Cannot be empty after trimming

Color Validation (via Pydantic schema)

• Must be valid hex color code format: #RRGGBB
• Example: #FF5733
• Normalized to uppercase
• Optional field

Error Responses

404 Not Found

{
  "detail": "Project not found"
}

409 Conflict - Duplicate Name

{
  "detail": "Status with name 'Ready for Review' already exists in this project"
}

409 Conflict - System Status Name

{
  "detail": "Status name 'In Progress' conflicts with a system status"
}

422 Unprocessable Entity - Validation Error

{
  "detail": "1 validation error for CustomTaskStatusCreate\nname\n  String should have at least 1 character..."
}

Testing

Test Results

All validation and functionality tests passed:

1. ✅ Create status without color (auto-assigned from palette)
2. ✅ Create status with custom color
3. ✅ Reject duplicate status names (409 Conflict)
4. ✅ Reject empty status names (422 Validation Error)
5. ✅ Reject invalid color formats (422 Validation Error)
6. ✅ Reject system status name conflicts (409 Conflict)
7. ✅ Proper ordering of statuses
8. ✅ Unique ID generation
9. ✅ JSON column updates with flag_modified

Test Files

• backend/test_create_custom_task_status.py - Comprehensive test suite
• backend/test_custom_status_validation.py - Validation-focused tests

Database Schema

The custom task statuses are stored in the projects.custom_task_statuses JSON column:

[
  {
    "id": "custom_review",
    "name": "In Review",
    "color": "#8B5CF6",
    "order": 0,
    "is_default": false
  },
  {
    "id": "custom_blocked",
    "name": "Blocked",
    "color": "#DC2626",
    "order": 1,
    "is_default": false
  }
]

Requirements Satisfied

• ✅ Requirement 1.2: Create new custom task status
• ✅ Requirement 1.3: Validate status name uniqueness within project
• ✅ Requirement 1.4: Auto-assign color from palette if not provided

Next Steps

The following endpoints still need to be implemented:

• PUT endpoint for updating custom status (Task 5)
• DELETE endpoint for deleting custom status (Task 6)
• PATCH endpoint for reordering statuses (Task 7)