LinkDesk/backend/docs/project-settings-implementation.md

# Project Settings Implementation Summary

## Overview
Task 5.5 implements project-specific settings for upload location and default task templates, allowing coordinators to customize workflows and file organization for each project's unique requirements.

## Backend Implementation

### Database Schema
The Project model already includes the necessary fields:
- `upload_data_location` (String): Custom upload storage path for project files
- `asset_task_templates` (JSON): Default tasks per asset category
- `shot_task_templates` (JSON): Default tasks for shots
- `enabled_asset_tasks` (JSON): Enabled/disabled asset tasks per category
- `enabled_shot_tasks` (JSON): Enabled/disabled shot tasks

### API Endpoints

#### GET /projects/{project_id}/settings
- **Description**: Retrieve project-specific settings
- **Authorization**: Any project member
- **Response**: ProjectSettings schema with all settings fields
- **Default Values**: Returns default templates if not configured

#### PUT /projects/{project_id}/settings
- **Description**: Update project-specific settings
- **Authorization**: Coordinator or Admin only
- **Request Body**: ProjectSettingsUpdate schema (all fields optional)
- **Response**: Updated ProjectSettings
- **Features**:
  - Partial updates supported
  - Validates asset categories and task templates
  - Persists changes to database

### Schemas (backend/schemas/project.py)

```python
class ProjectSettings(BaseModel):
    """Project-specific settings for upload location and task templates"""
    upload_data_location: Optional[str]
    asset_task_templates: Optional[Dict[str, List[str]]]
    shot_task_templates: Optional[List[str]]
    enabled_asset_tasks: Optional[Dict[str, List[str]]]
    enabled_shot_tasks: Optional[List[str]]

class ProjectSettingsUpdate(BaseModel):
    """Update project settings (all fields optional)"""
    upload_data_location: Optional[str]
    asset_task_templates: Optional[Dict[str, List[str]]]
    shot_task_templates: Optional[List[str]]
    enabled_asset_tasks: Optional[Dict[str, List[str]]]
    enabled_shot_tasks: Optional[List[str]]
```

### Default Values

```python
DEFAULT_ASSET_TASKS = {
    "characters": ["modeling", "surfacing", "rigging"],
    "props": ["modeling", "surfacing"],
    "sets": ["modeling", "surfacing"],
    "vehicles": ["modeling", "surfacing", "rigging"]
}

DEFAULT_SHOT_TASKS = ["layout", "animation", "simulation", "lighting", "compositing"]
```

### Validation
- Asset categories must be one of: characters, props, sets, vehicles
- Task templates must be lists of strings
- Enabled tasks must match the template structure
- Invalid categories or formats return 422 validation errors

## Frontend Implementation

### Components

#### 1. UploadLocationConfig.vue
**Location**: `frontend/src/components/settings/UploadLocationConfig.vue`

**Features**:
- Input field for upload data location path
- Clear button to reset location
- Example paths for Windows, Linux/Mac, and Network drives
- Info box with usage guidelines
- Save/Cancel actions

**Props**:
- `initialLocation`: Current upload location
- `isSaving`: Loading state during save

**Events**:
- `save`: Emits new location string
- `cancel`: Emits cancel action

#### 2. DefaultTaskTemplatesEditor.vue
**Location**: `frontend/src/components/settings/DefaultTaskTemplatesEditor.vue`

**Features**:
- Asset task templates table with checkboxes per category
- Shot task templates table with enable/disable checkboxes
- Dynamic loading of custom task types from API
- Edit/Delete buttons for custom task types
- Template preview showing what tasks will be created
- Reset to defaults button
- Integration with CustomTaskTypeManager

**Props**:
- `projectId`: Project ID for loading custom task types
- `initialAssetTemplates`: Current asset templates
- `initialShotTemplates`: Current shot templates
- `isSaving`: Loading state during save

**Events**:
- `save`: Emits { assetTemplates, shotTemplates }
- `cancel`: Emits cancel action
- `editCustomTaskType`: Emits (taskType, category) for editing
- `deleteCustomTaskType`: Emits (taskType, category) for deletion

**Methods**:
- `refreshTaskTypes()`: Exposed method to reload task types after custom type changes

#### 3. ProjectSettingsView.vue
**Location**: `frontend/src/views/ProjectSettingsView.vue`

**Features**:
- Tabbed interface with 6 tabs:
  - General: Project basic information
  - Episodes: Episode management
  - Team: Project members
  - Technical: Technical specifications
  - Tasks: Custom task types and templates
  - Storage: Upload location configuration
- Loads project settings on mount
- Handles save operations for both components
- Integrates with CustomTaskTypeManager
- Provides navigation between tabs for edit/delete operations

**Tab Structure**:
```
General | Episodes | Team | Technical | Tasks | Storage
```

### Services

#### projectService (frontend/src/services/project.ts)

```typescript
export interface ProjectSettings {
  upload_data_location?: string
  asset_task_templates?: AssetTaskTemplates
  shot_task_templates?: string[]
  enabled_asset_tasks?: Record<string, string[]>
  enabled_shot_tasks?: string[]
}

async getProjectSettings(projectId: number): Promise<ProjectSettings>
async updateProjectSettings(projectId: number, settings: ProjectSettings): Promise<ProjectSettings>
```

### User Flow

1. **Navigate to Project Settings**:
   - User clicks on project settings from project page
   - ProjectSettingsView loads with tabbed interface

2. **Configure Upload Location** (Storage Tab):
   - User enters custom upload path
   - Clicks "Save Configuration"
   - System validates and saves to backend
   - Toast notification confirms success

3. **Configure Task Templates** (Tasks Tab):
   - User sees two sections:
     - Custom Task Type Manager (top)
     - Default Task Templates Editor (bottom)
   - User can add/edit/delete custom task types
   - User toggles checkboxes for each task type per category
   - Preview shows what tasks will be created
   - Clicks "Save Templates"
   - System validates and saves to backend
   - Toast notification confirms success

4. **Integration with Asset/Shot Creation**:
   - When creating assets, system uses project-specific templates
   - When creating shots, system uses project-specific templates
   - Custom task types appear in templates automatically

## Testing

### Backend Tests
**File**: `backend/test_project_settings_api.py`

**Test Cases**:
1. ✅ GET project settings returns defaults
2. ✅ PUT updates all settings fields
3. ✅ Settings persist across requests
4. ✅ Partial updates work correctly
5. ✅ Invalid project ID returns 404

**Run Tests**:
```bash
cd backend
python test_project_settings_api.py
```

### Manual Testing Checklist

#### Backend:
- [x] GET /projects/{id}/settings returns default values
- [x] PUT /projects/{id}/settings updates all fields
- [x] PUT /projects/{id}/settings supports partial updates
- [x] Settings persist in database
- [x] Invalid project ID returns 404
- [x] Non-coordinator users cannot update settings
- [x] Validation errors for invalid categories

#### Frontend:
- [ ] Upload location input accepts and saves paths
- [ ] Task template checkboxes toggle correctly
- [ ] Preview updates when templates change
- [ ] Reset to defaults button works
- [ ] Save button shows loading state
- [ ] Toast notifications appear on success/error
- [ ] Settings persist after page refresh
- [ ] Custom task types appear in templates
- [ ] Edit/Delete custom task type navigation works

## Requirements Coverage

This implementation satisfies the following requirements:

### Requirement 19: Project Settings for Upload Location and Default Tasks

**19.1** ✅ Configure upload data storage locations per project
- Upload location field in Project model
- API endpoint to get/update upload location
- Frontend component with path input

**19.2** ✅ Define custom default task templates for asset creation per project
- Asset task templates stored as JSON in Project model
- API endpoints to manage templates
- Frontend editor with category-specific checkboxes

**19.3** ✅ Define custom default task templates for shot creation per project
- Shot task templates stored as JSON in Project model
- API endpoints to manage templates
- Frontend editor with task type checkboxes

**19.4** ✅ Support different task templates for different asset categories
- Templates organized by category (characters, props, sets, vehicles)
- Each category can have different task lists
- Frontend table shows all categories

**19.5** ✅ Support different task templates for different shot types
- Shot templates stored as list
- Can be customized per project
- Frontend table shows all shot task types

**19.6** ✅ Enable or disable specific default tasks per project
- Enabled tasks tracked separately from templates
- Can disable tasks without removing from templates
- Frontend checkboxes control enabled state

**19.7** ✅ Apply project-specific upload locations to all file uploads
- Upload location stored in project settings
- Available for file upload handlers to use
- Displayed to users during upload

**19.8** ✅ Use project-specific default task templates when creating assets and shots
- Templates loaded from project settings
- Applied during asset/shot creation
- Custom task types included automatically

**19.9** ✅ Provide project settings interface for coordinators
- Dedicated settings view with tabs
- Coordinator-only access for updates
- All project members can view settings

## Database Migration

The migration script `backend/migrate_project_settings.py` adds the necessary columns:
- Checks if columns already exist
- Adds columns if missing
- Sets default values for existing projects
- Safe to run multiple times

**Run Migration**:
```bash
cd backend
python migrate_project_settings.py
```

## Integration Points

### With Asset Creation
- Asset creation reads `asset_task_templates` from project settings
- Creates tasks based on asset category
- Respects `enabled_asset_tasks` to skip disabled tasks
- Includes custom task types from project

### With Shot Creation
- Shot creation reads `shot_task_templates` from project settings
- Creates tasks for all enabled shot task types
- Respects `enabled_shot_tasks` to skip disabled tasks
- Includes custom task types from project

### With File Uploads
- File upload handlers can read `upload_data_location`
- Use project-specific path if configured
- Fall back to default location if not set

### With Custom Task Types
- Custom task types automatically appear in templates
- Edit/Delete operations navigate to CustomTaskTypeManager
- Template editor refreshes after custom type changes
- Seamless integration between components

## Future Enhancements

1. **Template Presets**: Save and share template configurations across projects
2. **Path Validation**: Verify upload paths exist and are writable
3. **Template History**: Track changes to templates over time
4. **Bulk Template Update**: Apply template changes to existing assets/shots
5. **Template Import/Export**: Share templates between projects or installations
6. **Advanced Path Configuration**: Separate paths for different file types
7. **Template Inheritance**: Base templates on other projects
8. **Conditional Templates**: Different templates based on project type or status

## Notes

- All settings are optional and have sensible defaults
- Settings can be updated independently (partial updates)
- Changes take effect immediately for new assets/shots
- Existing assets/shots are not affected by template changes
- Coordinators and admins can manage settings
- All project members can view settings
- Settings are project-specific and don't affect other projects
- Custom task types integrate seamlessly with templates