198 lines
8.3 KiB
Markdown
198 lines
8.3 KiB
Markdown
# 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 |