# 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

1. **AppSidebar.vue**
   - Update navigation item title from "Deleted Items" to "Recovery Management"
   - Preserve existing URL path `/admin/deleted-items` for backward compatibility

2. **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

3. **RecoveryManagementPanel.vue** (if exists)
   - Apply consistent terminology updates
   - Ensure alignment with main management view

### New Components

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

### Backend Services

5. **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**
```typescript
interface PermanentDeleteRequest {
  itemType: 'shot' | 'asset'
  itemIds: number[]
  confirmationToken: string
}
```

**PermanentDeleteResult**
```typescript
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