LinkDesk/.kiro/specs/shot-cascading-deletion/requirements.md

Shot Soft Deletion Requirements

Introduction

This specification defines the requirements for implementing comprehensive soft deletion when a shot is "deleted" from the VFX Project Management System. Instead of permanently removing data, the system will mark shots and all related data as deleted while preserving the records in the database for potential recovery and audit purposes.

Glossary

• Shot: A sequence of frames in an episode that represents a specific scene or action
• Task: A work item assigned to a shot (e.g., animation, lighting, compositing)
• Submission: A file uploaded by an artist as work progress for a task
• Attachment: Reference files, documentation, or other files attached to a task
• Production Note: Comments, feedback, or discussion items related to a task
• Review: Approval/feedback records for submissions
• Activity: System-generated log entries tracking changes and actions
• Soft Deletion: Marking records as deleted without removing them from the database
• Cascading Soft Deletion: Automatically marking all related records as deleted when a parent record is soft deleted
• Deleted Flag: A database field indicating whether a record is considered deleted

Requirements

Requirement 1

User Story: As a project coordinator, I want to delete a shot and have all related data automatically marked as deleted, so that it no longer appears in the system while preserving data for potential recovery.

Acceptance Criteria

1. WHEN a coordinator deletes a shot THEN the system SHALL mark the shot as deleted with a timestamp
2. WHEN a shot is marked as deleted THEN the system SHALL mark all associated tasks as deleted
3. WHEN tasks are marked as deleted THEN the system SHALL mark all associated submissions as deleted
4. WHEN tasks are marked as deleted THEN the system SHALL mark all associated production notes as deleted
5. WHEN tasks are marked as deleted THEN the system SHALL mark all associated attachments as deleted
6. WHEN submissions are marked as deleted THEN the system SHALL mark all associated reviews as deleted

Requirement 2

User Story: As a system administrator, I want deleted data to be completely hidden from normal operations, so that users cannot see or interact with deleted content.

Acceptance Criteria

1. WHEN querying shots THEN the system SHALL exclude shots marked as deleted from all results
2. WHEN querying tasks THEN the system SHALL exclude tasks marked as deleted from all results
3. WHEN querying submissions THEN the system SHALL exclude submissions marked as deleted from all results
4. WHEN querying attachments THEN the system SHALL exclude attachments marked as deleted from all results
5. WHEN querying production notes THEN the system SHALL exclude notes marked as deleted from all results
6. WHEN querying reviews THEN the system SHALL exclude reviews marked as deleted from all results

Requirement 3

User Story: As a project coordinator, I want to see what will be marked as deleted before confirming shot deletion, so that I can make an informed decision.

Acceptance Criteria

1. WHEN a coordinator attempts to delete a shot THEN the system SHALL display a confirmation dialog with deletion summary
2. WHEN displaying the summary THEN the system SHALL show the count of tasks that will be marked as deleted
3. WHEN displaying the summary THEN the system SHALL show the count of submissions that will be marked as deleted
4. WHEN displaying the summary THEN the system SHALL show the count of attachments that will be marked as deleted
5. WHEN displaying the summary THEN the system SHALL show the count of production notes that will be marked as deleted

Requirement 4

User Story: As a project coordinator, I want to see which users will be affected by shot deletion, so that I can notify them appropriately.

Acceptance Criteria

1. WHEN displaying deletion summary THEN the system SHALL list all users who have assigned tasks that will be marked as deleted
2. WHEN displaying deletion summary THEN the system SHALL list all users who have submitted work that will be marked as deleted
3. WHEN displaying deletion summary THEN the system SHALL list all users who have written production notes that will be marked as deleted
4. WHEN displaying deletion summary THEN the system SHALL show the most recent activity date for each affected user
5. WHEN no users are affected THEN the system SHALL indicate the shot has no active work

Requirement 5

User Story: As a system administrator, I want activity logs to be preserved but filtered when shots are deleted, so that audit trails are maintained while keeping the activity feed relevant.

Acceptance Criteria

1. WHEN a shot is marked as deleted THEN the system SHALL preserve all existing activity records but exclude them from normal activity feeds
2. WHEN querying activity feeds THEN the system SHALL exclude activities related to deleted shots, tasks, and submissions
3. WHEN the deletion is complete THEN the system SHALL create a new activity record documenting the shot deletion
4. WHEN creating the deletion activity THEN the system SHALL include the shot name, deletion timestamp, and user who performed the deletion
5. WHEN administrators query audit logs THEN the system SHALL provide access to activities related to deleted items

Requirement 6

User Story: As a project coordinator, I want shot deletion to be atomic, so that either all data is marked as deleted successfully or nothing is changed.

Acceptance Criteria

1. WHEN shot deletion begins THEN the system SHALL start a database transaction
2. WHEN any database update fails THEN the system SHALL rollback all changes and report the error
3. WHEN marking records as deleted THEN the system SHALL update all related records within the same transaction
4. WHEN all updates succeed THEN the system SHALL commit the transaction
5. WHEN the transaction commits THEN the system SHALL log the successful soft deletion

Requirement 7

User Story: As a project coordinator, I want to be able to cancel shot deletion if I change my mind, so that I don't accidentally remove important work.

Acceptance Criteria

1. WHEN the deletion confirmation dialog is shown THEN the system SHALL provide a clear "Cancel" option
2. WHEN the user clicks "Cancel" THEN the system SHALL close the dialog without making any changes
3. WHEN the user clicks outside the dialog THEN the system SHALL treat it as a cancellation
4. WHEN deletion is in progress THEN the system SHALL not allow cancellation
5. WHEN deletion completes THEN the system SHALL show a success message with summary of deleted items

Requirement 8

User Story: As a system administrator, I want deletion operations to be logged for audit purposes, so that I can track what was marked as deleted and by whom.

Acceptance Criteria

1. WHEN a shot deletion begins THEN the system SHALL log the deletion attempt with user information
2. WHEN deletion completes successfully THEN the system SHALL log the completion with counts of items marked as deleted
3. WHEN deletion fails THEN the system SHALL log the failure with error details
4. WHEN logging deletion events THEN the system SHALL include shot ID, name, episode, and project information
5. WHEN logging deletion events THEN the system SHALL include the deletion timestamp and user who performed the action

Requirement 9

User Story: As a project coordinator, I want shot deletion to handle edge cases gracefully, so that the system remains stable even with corrupted or missing data.

Acceptance Criteria

1. WHEN a task has already been marked as deleted THEN the system SHALL skip it without failing
2. WHEN database constraints prevent updates THEN the system SHALL provide a clear error message
3. WHEN the shot has already been marked as deleted THEN the system SHALL return a "not found" error
4. WHEN concurrent deletion attempts occur THEN the system SHALL handle them safely without data corruption
5. WHEN related records are missing THEN the system SHALL continue marking other records as deleted

Requirement 10

User Story: As a project coordinator, I want deletion performance to be reasonable, so that the system remains responsive during soft deletion operations.

Acceptance Criteria

1. WHEN marking a shot and related data as deleted THEN the system SHALL complete database operations within 10 seconds
2. WHEN processing many related records THEN the system SHALL update them in efficient batch operations
3. WHEN deletion is in progress THEN the system SHALL show a progress indicator to the user
4. WHEN the operation completes THEN the system SHALL immediately reflect the changes in the user interface
5. WHEN querying data after deletion THEN the system SHALL efficiently exclude deleted records using database indexes

Requirement 11

User Story: As a system administrator, I want the ability to recover deleted shots, so that accidental deletions can be undone.

Acceptance Criteria

1. WHEN a shot is marked as deleted THEN the system SHALL preserve all original data for potential recovery
2. WHEN an administrator needs to recover a shot THEN the system SHALL provide a recovery interface
3. WHEN recovering a shot THEN the system SHALL restore the shot and all related data to active status
4. WHEN recovering data THEN the system SHALL log the recovery operation with user and timestamp information
5. WHEN data is recovered THEN the system SHALL immediately make it visible in the user interface