Init Repo

2026-02-28 03:22:04 +08:00
commit de59b57ee7
883 changed files with 156857 additions and 0 deletions
@@ -0,0 +1,124 @@
+# Design Document
+
+## Overview
+
+This design establishes consistent detail panel behavior across all entity browsers (shots, assets, tasks) in the VFX Project Management System. The design ensures users have a unified experience when working with detail panels regardless of the entity type.
+
+## Architecture
+
+The detail panel system uses a consistent state management pattern across all entity browsers:
+
+- **Auto-Enable State**: Controls whether panels automatically show on entity selection
+- **Manual Visibility State**: Controls manual panel visibility via keyboard shortcuts
+- **Combined Logic**: Panel shows when either auto-enabled with selection OR manually visible
+
+## Components and Interfaces
+
+### State Variables (Per Browser)
+```typescript
+// Auto-enable toggle state
+const isDetailPanelEnabled = ref(true)
+
+// Manual visibility control
+const isDetailPanelVisible = ref(false)
+
+// Selected entity
+const selectedEntity = ref<Entity | null>(null)
+```
+
+### Panel Visibility Logic
+```typescript
+// Panel shows when:
+// 1. Auto-enabled AND entity selected, OR
+// 2. Manually shown
+const showPanel = computed(() => 
+  selectedEntity.value && (isDetailPanelEnabled.value || isDetailPanelVisible.value)
+)
+```
+
+### Keyboard Handler Interface
+```typescript
+interface KeyboardHandler {
+  handleKeyDown(event: KeyboardEvent): void
+  // Conditions:
+  // - 'i' key pressed
+  // - Entity selected
+  // - No dialogs open
+  // - Not typing in input fields
+}
+```
+
+## Data Models
+
+### Panel State Model
+```typescript
+interface DetailPanelState {
+  isEnabled: boolean      // Auto-enable toggle
+  isVisible: boolean      // Manual visibility
+  selectedEntity: Entity | null
+}
+```
+
+### Entity Selection Model
+```typescript
+interface EntitySelection {
+  entity: Entity
+  preserveManualState: boolean  // Don't reset manual visibility
+}
+```
+
+## 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 1: Manual Panel Persistence
+*For any* entity browser with manually opened detail panel, selecting different entities should keep the panel visible and update content
+**Validates: Requirements 2.1, 2.2, 2.3**
+
+### Property 2: Keyboard Toggle Consistency  
+*For any* entity browser, pressing 'i' key with selected entity should toggle panel visibility consistently
+**Validates: Requirements 4.1**
+
+### Property 3: Auto-Enable Independence
+*For any* combination of auto-enable and manual states, the panel visibility should follow OR logic (show if either condition is true)
+**Validates: Requirements 3.5**
+
+### Property 4: Input Field Protection
+*For any* keyboard event while focused on input fields, the 'i' key should not trigger panel toggle
+**Validates: Requirements 4.2**
+
+### Property 5: Selection State Preservation
+*For any* entity selection while panel is manually visible, the manual visibility state should be preserved
+**Validates: Requirements 2.1**
+
+## Error Handling
+
+### Invalid States
+- No entity selected + manual panel visible → Hide panel
+- Dialog open + keyboard shortcut → Ignore shortcut
+- Input field focused + keyboard shortcut → Ignore shortcut
+
+### State Recovery
+- Invalid combinations reset to safe defaults
+- Manual state cleared when no entity selected
+- Auto-enable state persists across sessions
+
+## Testing Strategy
+
+### Unit Testing
+- Test individual state transitions
+- Test keyboard event handling
+- Test panel visibility logic
+- Test edge cases (no selection, dialogs open)
+
+### Property-Based Testing
+- Generate random entity selections and verify panel behavior
+- Test keyboard events with various application states
+- Verify state consistency across browser types
+- Test auto-enable/manual state combinations
+
+### Integration Testing
+- Test behavior across all entity browsers
+- Test session persistence
+- Test mobile vs desktop behavior
+- Test with real user workflows