8.3 KiB

Raw Permalink Blame History

Recovery Management Rename - Design Document

Overview

This design document outlines the approach for renaming "Deleted Items Management" to "Recovery Management" throughout the VFX Project Management System. The change focuses on updating user-facing text and labels while preserving all existing functionality, file names, and API endpoints to maintain backward compatibility and minimize code changes.

Architecture

The rename operation will be implemented as a pure UI/UX change that affects only the presentation layer. The underlying architecture remains unchanged:

Frontend Components: Update display text, labels, and messages in Vue components
Navigation System: Modify sidebar navigation labels while preserving route paths
Page Titles: Update browser tab titles and page headers
User Messages: Revise loading states, empty states, and notification text

Components and Interfaces

Affected Components

AppSidebar.vue
- Update navigation item title from "Deleted Items" to "Recovery Management"
- Preserve existing URL path /admin/deleted-items for backward compatibility
DeletedItemsManagementView.vue
- Update page title from "Deleted Items Management" to "Recovery Management"
- Revise page description to use recovery-focused language
- Update loading messages, empty states, and filter labels
- Add permanent delete actions for individual items
- Add bulk permanent delete functionality
- Add confirmation dialogs for permanent deletion
- Maintain all existing functionality and component structure
RecoveryManagementPanel.vue (if exists)
- Apply consistent terminology updates
- Ensure alignment with main management view

New Components

PermanentDeleteConfirmDialog.vue
- Confirmation dialog for permanent deletion operations
- Warning messages about irreversible data loss
- Support for both individual and bulk operations

Backend Services

Recovery Service Extensions
- Add permanent delete methods for shots and assets
- Implement cascading deletion for related data
- Add file system cleanup for associated files
- Ensure transactional integrity during deletion

Interface Preservation

All existing interfaces will be preserved:

Component props and events remain unchanged
Service method signatures stay the same
API endpoints maintain existing paths
Database queries and models are unaffected

Data Models

Existing Models (Preserved)

All existing models remain unchanged for backward compatibility:

DeletedShot interface preserved
DeletedAsset interface preserved
RecoveryInfo interface preserved
Database tables and columns unchanged
API response formats maintained

New Interfaces

PermanentDeleteRequest

interface PermanentDeleteRequest {
  itemType: 'shot' | 'asset'
  itemIds: number[]
  confirmationToken: string
}

PermanentDeleteResult

interface PermanentDeleteResult {
  successful_deletions: number
  failed_deletions: number
  deleted_items: Array<{
    id: number
    name: string
    type: 'shot' | 'asset'
  }>
  errors: Array<{
    id: number
    error: string
  }>
  files_deleted: number
  database_records_deleted: number
}

Database Operations

Permanent deletion will involve cascading deletes across multiple tables:

Primary item record (shots/assets)
Related tasks and their submissions
Attachments and associated files
Notes and reviews
Activity records
File system cleanup

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property Reflection

After reviewing the acceptance criteria, several properties can be consolidated:

Multiple criteria test similar text display functionality (page titles, labels, messages)
Navigation and routing properties can be combined into comprehensive tests
Terminology consistency can be verified through systematic text validation

Property 1: Navigation displays recovery terminology For any admin user viewing the navigation menu, the menu should display "Recovery Management" and not display "Deleted Items" Validates: Requirements 1.1

Property 2: Navigation functionality preserved For any valid navigation interaction, clicking the recovery management menu item should navigate to the correct interface and maintain existing route functionality Validates: Requirements 1.2, 1.3

Property 3: Page content uses recovery terminology For any text element on the recovery management page, the content should use recovery-focused language and not contain deletion-focused terms Validates: Requirements 1.4, 2.2, 2.5, 3.2, 3.3, 3.4, 3.5

Property 4: API endpoints remain functional For any existing API endpoint used by the recovery management system, the endpoint should continue to return expected responses with unchanged functionality Validates: Requirements 4.2, 4.3

Property 5: Permanent deletion removes all related data For any soft-deleted item that is permanently deleted, all associated database records and files should be completely removed from the system Validates: Requirements 6.4, 7.1, 7.2, 7.3, 7.4

Property 6: Permanent deletion is transactional For any permanent deletion operation, either all related data is successfully removed or the entire operation is rolled back with no partial deletions Validates: Requirements 8.1, 8.4

Property 7: Permanent delete actions are available For any soft-deleted item displayed in the recovery interface, permanent delete actions should be available both individually and for bulk operations Validates: Requirements 6.1, 6.2

Property 8: Permanent deletion requires confirmation For any permanent deletion operation, a confirmation dialog with data loss warnings should be displayed before proceeding Validates: Requirements 6.3

Property 9: Permanent deletion provides feedback For any completed permanent deletion operation, the system should display success messages and update the interface to reflect the changes Validates: Requirements 6.5, 8.3

Error Handling

Error handling remains unchanged from the existing implementation:

Network Errors: Maintain existing error messages with updated terminology
Authentication Errors: Preserve existing auth error handling
Permission Errors: Keep existing permission validation
Data Loading Errors: Update error messages to use recovery terminology
Recovery Operation Errors: Maintain existing error handling with terminology updates

Testing Strategy

Unit Testing Approach

Unit tests will focus on:

Text Content Verification: Test that components render correct terminology
Navigation Behavior: Verify navigation items work correctly
Route Preservation: Ensure existing routes continue to function
Component Props: Verify component interfaces remain unchanged

Property-Based Testing Approach

Property-based tests will use Vitest with fast-check for JavaScript/TypeScript property testing. Each property-based test will run a minimum of 100 iterations.

Property Test Requirements:

Each property-based test must be tagged with a comment referencing the design document property
Tag format: **Feature: recovery-management-rename, Property {number}: {property_text}**
Tests will generate various UI states and verify terminology consistency
Navigation tests will verify route functionality across different scenarios

Dual Testing Approach:

Unit tests will verify specific examples of correct terminology display
Property tests will verify universal properties hold across all UI states
Together they provide comprehensive coverage: unit tests catch specific text issues, property tests verify systematic terminology consistency

Test Configuration

Framework: Vitest for unit and property-based testing
Property Testing Library: fast-check for generating test scenarios
Minimum Iterations: 100 iterations per property-based test
Coverage: Focus on UI text content, navigation behavior, and API compatibility

8.3 KiB Raw Permalink Blame History