LinkDesk/.kiro/specs/shot-project-id-enhancement/requirements.md

Requirements Document

Introduction

This feature enhances the shot table schema by adding a direct project_id column to prevent shots with the same name from being created across different projects. Currently, shots are only linked to episodes, which can lead to naming conflicts when the same shot name exists in different projects.

Glossary

• Shot: A sequence or scene in a VFX project that represents a specific portion of work
• Project: A top-level container for organizing episodes, shots, and assets
• Episode: A subdivision of a project containing multiple shots
• VFX_System: The VFX Project Management System backend and frontend
• Database_Schema: The SQLAlchemy model definitions and database structure

Requirements

Requirement 1

User Story: As a project coordinator, I want shot names to be unique within each project, so that I can avoid naming conflicts when managing multiple projects with similar shot naming conventions.

Acceptance Criteria

1. WHEN a shot is created, THE VFX_System SHALL enforce uniqueness of shot names within the project scope
2. WHEN a shot is created, THE VFX_System SHALL automatically populate the project_id from the associated episode
3. WHEN querying shots, THE VFX_System SHALL include project_id in all shot responses
4. WHEN validating shot names, THE VFX_System SHALL check for duplicates within the same project only
5. WHEN migrating existing data, THE VFX_System SHALL populate project_id for all existing shots based on their episode relationships

Requirement 2

User Story: As a database administrator, I want the shot table to have proper foreign key constraints to the project table, so that data integrity is maintained across the system.

Acceptance Criteria

1. WHEN the database schema is updated, THE VFX_System SHALL add a non-nullable project_id column to the shots table
2. WHEN the database schema is updated, THE VFX_System SHALL create a foreign key constraint from shots.project_id to projects.id
3. WHEN the database schema is updated, THE VFX_System SHALL create an index on the project_id column for query performance
4. WHEN the migration runs, THE VFX_System SHALL preserve all existing shot data without loss
5. WHEN the migration completes, THE VFX_System SHALL validate that all shots have valid project_id values

Requirement 3

User Story: As a frontend developer, I want the shot API responses to include project information, so that I can display project context in shot management interfaces.

Acceptance Criteria

1. WHEN retrieving shots via API, THE VFX_System SHALL include project_id in the response payload
2. WHEN creating shots via API, THE VFX_System SHALL accept project_id as an optional parameter for validation
3. WHEN updating shots via API, THE VFX_System SHALL maintain project_id consistency with the episode relationship
4. WHEN filtering shots, THE VFX_System SHALL support filtering by project_id parameter
5. WHEN bulk creating shots, THE VFX_System SHALL validate that all shots belong to the same project as the episode

Requirement 4

User Story: As a system user, I want existing shot functionality to continue working seamlessly after the schema change, so that my workflow is not disrupted.

Acceptance Criteria

1. WHEN accessing existing shot endpoints, THE VFX_System SHALL maintain backward compatibility for all current API operations
2. WHEN creating shots through existing workflows, THE VFX_System SHALL automatically derive project_id from episode_id
3. WHEN displaying shots in the frontend, THE VFX_System SHALL show project context where appropriate
4. WHEN performing shot operations, THE VFX_System SHALL maintain all existing access control and permission checks
5. WHEN soft deleting shots, THE VFX_System SHALL preserve project_id information for recovery operations