# Requirements Document

## Introduction

This feature optimizes the SQL schema and query patterns for shot and asset data fetching by including task status information in a single query operation. Currently, fetching shot or asset data requires separate queries to retrieve associated task statuses, which creates performance bottlenecks when displaying data tables with many rows. This optimization will consolidate task status data into the primary shot/asset queries, significantly improving table rendering performance.

## Glossary

- **Shot**: A sequence unit in a VFX project containing multiple tasks
- **Asset**: A reusable element (character, prop, environment) in a VFX project containing multiple tasks
- **Task**: A work unit assigned to users with a specific status (e.g., "Not Started", "In Progress", "Complete")
- **Task Status**: The current state of a task (default statuses or custom project-specific statuses)
- **Data Table**: Frontend components that display lists of shots or assets with their task status information
- **Query Optimization**: Reducing the number of database queries by consolidating related data fetching
- **Task Status Aggregation**: Collecting all task statuses for a shot/asset into a single data structure

## Requirements

### Requirement 1

**User Story:** As a coordinator viewing the shots table, I want task status information to load quickly with the shot data, so that I can efficiently review project progress without waiting for multiple data requests.

#### Acceptance Criteria

1. WHEN the system fetches shot data for table display, THE system SHALL include all associated task statuses in a single query operation
2. WHEN displaying the shots table, THE system SHALL show task status information without additional API calls per row
3. WHEN a shot has multiple tasks, THE system SHALL aggregate all task statuses into the shot data response
4. WHEN custom task statuses exist for a project, THE system SHALL include both default and custom status information in the aggregated data
5. WHEN the shots table loads, THE system SHALL complete data fetching in under 500ms for up to 100 shots with their task statuses

### Requirement 2

**User Story:** As a coordinator viewing the assets table, I want task status information to load quickly with the asset data, so that I can efficiently review asset progress without waiting for multiple data requests.

#### Acceptance Criteria

1. WHEN the system fetches asset data for table display, THE system SHALL include all associated task statuses in a single query operation
2. WHEN displaying the assets table, THE system SHALL show task status information without additional API calls per row
3. WHEN an asset has multiple tasks, THE system SHALL aggregate all task statuses into the asset data response
4. WHEN custom task statuses exist for a project, THE system SHALL include both default and custom status information in the aggregated data
5. WHEN the assets table loads, THE system SHALL complete data fetching in under 500ms for up to 100 assets with their task statuses

### Requirement 3

**User Story:** As a developer maintaining the system, I want the database schema to support efficient task status aggregation, so that query performance remains optimal as projects scale.

#### Acceptance Criteria

1. WHEN querying shots or assets, THE system SHALL use optimized SQL joins to fetch task status data in a single database round trip
2. WHEN the database contains thousands of tasks, THE system SHALL maintain query performance through proper indexing strategies
3. WHEN task statuses are updated, THE system SHALL ensure data consistency between individual task updates and aggregated views
4. WHEN new task types are added to a project, THE system SHALL automatically include them in the aggregated task status queries
5. WHEN the system performs task status aggregation, THE system SHALL use database-level aggregation functions rather than application-level processing

### Requirement 4

**User Story:** As a frontend developer, I want the API to return task status data embedded within shot/asset responses, so that I can build responsive data tables without managing complex state synchronization.

#### Acceptance Criteria

1. WHEN the API returns shot data, THE response SHALL include a task_statuses field containing all associated task information
2. WHEN the API returns asset data, THE response SHALL include a task_statuses field containing all associated task information
3. WHEN task status data is embedded, THE response SHALL include task type, current status, assignee, and last updated information
4. WHEN the frontend receives shot/asset data, THE system SHALL provide task status information in a format optimized for table rendering
5. WHEN task statuses change, THE system SHALL provide real-time updates to the aggregated data without requiring full table refreshes

### Requirement 5

**User Story:** As a system administrator, I want the optimization to maintain backward compatibility, so that existing functionality continues to work while benefiting from improved performance.

#### Acceptance Criteria

1. WHEN the optimization is implemented, THE system SHALL maintain all existing API endpoints and response formats
2. WHEN legacy code requests individual task data, THE system SHALL continue to support separate task status queries
3. WHEN the optimized queries are used, THE system SHALL return data in formats compatible with existing frontend components
4. WHEN database migrations are applied, THE system SHALL preserve all existing data relationships and constraints
5. WHEN the optimization is deployed, THE system SHALL provide configuration options to enable or disable the new query patterns for testing purposes