playtool-demo/.kiro/specs/workflow-drag-drop-fix/design.md

Design Document

Overview

The drag and drop functionality issue stems from incorrect vuedraggable configuration between the right panel (node library) and left panel (workflow). The current implementation has mismatched group configurations and improper clone handling that prevents nodes from being successfully transferred from the library to the workflow.

Architecture

The fix involves correcting the vuedraggable configuration to properly support:

1. Clone-based dragging from right panel to left panel
2. Proper group configuration to allow cross-panel transfers
3. Unique ID generation for cloned nodes
4. State management for workflow updates

Components and Interfaces

Vuedraggable Configuration

Right Panel (Node Library)

• Group: { name: 'workflow-nodes', pull: 'clone', put: false }
• Clone function: Custom clone function that generates unique IDs
• Sort: false (prevent reordering in library)
• List: Static node definitions (read-only)

Left Panel (Workflow)

• Group: { name: 'workflow-nodes', pull: true, put: true }
• Sort: true (allow reordering)
• List: Reactive workflow nodes array
• Animation: 200ms for smooth transitions

Node Cloning Logic

const cloneNode = (original: FlowNode): FlowNode => {
	return {
		...original,
		id: `${original.id}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
		config: original.config ? { ...original.config } : undefined
	};
};

Event Handling

Workflow Change Handler

• Triggered when nodes are added, removed, or reordered
• Updates reactive state
• Logs changes for debugging
• Validates workflow integrity

Data Models

FlowNode Interface (Existing)

interface FlowNode {
	id: string // Unique identifier
	name: string // Display name
	type: string // Node type category
	taskId: string // Task execution identifier
	icon: string // Icon name
	backgroundColor: string
	shape: "square" | "circle" | "rounded"
	textColor: string
	category: "控制类" | "设备类" | "媒体类" | "ç<>¯å…‰ç±»" | "延时类"
	config?: Record<string, any>
}

Workflow State

const workflowNodes = ref<FlowNode[]>([]);

Error Handling

Invalid Drop Operations

• Validate node structure before adding to workflow
• Handle malformed node data gracefully
• Provide user feedback for failed operations

ID Collision Prevention

• Generate unique IDs using timestamp and random string
• Validate uniqueness before adding to workflow
• Handle edge cases where ID generation might fail

Configuration Preservation

• Deep clone node configurations to prevent reference issues
• Validate configuration structure
• Handle missing or invalid configuration data

Testing Strategy

Unit Tests

1. Clone Function Tests

   • Verify unique ID generation
   • Confirm property preservation
   • Test configuration deep cloning

2. Drag and Drop Tests

   • Mock drag events
   • Verify node addition to workflow
   • Test reordering functionality

Integration Tests

1. Cross-Panel Transfer

   • Test dragging from right to left panel
   • Verify node appears in workflow
   • Confirm original node remains in library

2. Workflow Management

   • Test node reordering
   • Verify workflow state updates
   • Test node removal functionality

Visual Tests

1. Drag Feedback

   • Verify visual drag indicators
   • Test drop zone highlighting
   • Confirm cursor changes during drag

2. Node Rendering

   • Test node appearance in workflow
   • Verify icon and color preservation
   • Test configuration display

Implementation Notes

Key Changes Required

1. Fix Group Configuration

   • Ensure consistent group names between panels
   • Configure proper pull/put permissions
   • Set up clone functionality for right panel

2. Improve Clone Function

   • Generate more robust unique IDs
   • Ensure deep cloning of configurations
   • Handle edge cases in node structure

3. Update Event Handlers

   • Properly handle workflow change events
   • Add validation for dropped nodes
   • Improve error handling and user feedback

4. Visual Enhancements

   • Add drag state indicators
   • Improve drop zone visual feedback
   • Enhance cursor states during operations

Performance Considerations

• Use efficient ID generation to avoid blocking
• Minimize re-renders during drag operations
• Optimize large workflow handling
• Cache node definitions for better performance