ss-tools/specs/008-migration-ui-improvements/quickstart.md

# Quickstart: Migration UI Improvements

**Date**: 2025-12-27 | **Status**: Draft

## Overview

This guide provides step-by-step instructions for using the new Migration UI Improvements feature.

## Prerequisites

- Running instance of the migration tool
- Valid user session
- At least one migration task (completed or in progress)

## Installation

No additional installation required. The feature is integrated into the existing migration UI.

## Using the Feature

### 1. Viewing Task History

**Steps**:
1. Navigate to the Migration Dashboard
2. Locate the "Recent Tasks" section
3. View the list of your recent migration tasks

**What you'll see**:
- Task ID
- Status (Pending, Running, Success, Failed, Awaiting Input)
- Start time
- "View Logs" action button

**Screenshot**: [Placeholder for task history screenshot]

### 2. Viewing Task Logs

**Steps**:
1. From the task history list, click "View Logs" on any task
2. A modal will open showing detailed logs

**What you'll see**:
- Timestamped log entries
- Log levels (INFO, WARNING, ERROR)
- Detailed error messages
- Context information for errors

**Screenshot**: [Placeholder for log viewer screenshot]

### 3. Handling Database Password Prompts

**Scenario**: A migration fails due to missing database password

**Steps**:
1. Start a migration that requires database passwords
2. When the system detects a missing password error:
   - Task status changes to "Awaiting Input"
   - A notification appears
   - The task shows "Requires Input" indicator
3. Click "View Logs" to see the specific error
4. The system will show a password prompt with:
   - Database name requiring password
   - Original error message
   - Password input field
5. Enter the required password(s)
6. Click "Submit" to resume the migration

**What happens next**:
- The migration resumes with the provided credentials
- Task status changes back to "Running"
- If password is incorrect, you'll be prompted again

**Screenshot**: [Placeholder for password prompt screenshot]

## API Usage Examples

### List Recent Tasks

```bash
curl -X GET \
  'http://localhost:8000/api/tasks?limit=5&offset=0' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/vnd.api.v1+json'
```

### Get Task Logs

```bash
curl -X GET \
  'http://localhost:8000/api/tasks/TASK_ID/logs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/vnd.api.v1+json'
```

### Resume Task with Password

```bash
curl -X POST \
  'http://localhost:8000/api/tasks/TASK_ID/resume' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.api.v1+json' \
  -d '{
    "passwords": {
      "PostgreSQL": "your_secure_password"
    }
  }'
```

## Troubleshooting

### Common Issues

**Issue**: No tasks appearing in history
- **Solution**: Check that you have started at least one migration task
- **Solution**: Verify your session is valid
- **Solution**: Try refreshing the page

**Issue**: Task stuck in "Awaiting Input" state
- **Solution**: Check the task logs for specific error details
- **Solution**: Provide the required input through the UI
- **Solution**: If input was provided but task didn't resume, try again

**Issue**: Password prompt keeps appearing
- **Solution**: Verify the password is correct
- **Solution**: Check for multiple databases requiring passwords
- **Solution**: Contact administrator if issue persists

### Error Messages

- `"Task not found"`: The specified task ID doesn't exist or you don't have permission
- `"Task not awaiting input"`: The task is not in a state that requires user input
- `"Invalid password"`: The provided password was rejected by the target system
- `"Unauthorized"`: Your session has expired or is invalid

## Configuration

### Task Retention

Configure how long completed tasks are retained:

```bash
# In backend configuration
TASK_RETENTION_DAYS=30
TASK_RETENTION_LIMIT=100
```

### Pagination Limits

Adjust default pagination limits:

```bash
# In backend configuration
DEFAULT_TASK_LIMIT=10
MAX_TASK_LIMIT=50
```

## Best Practices

1. **Monitor Tasks**: Regularly check task history for failed migrations
2. **Prompt Response**: Respond to "Awaiting Input" tasks promptly to avoid delays
3. **Log Review**: Always review logs for failed tasks to understand root causes
4. **Password Management**: Use secure password storage for frequently used credentials
5. **Session Management**: Ensure your session is active before starting long migrations

## Integration Guide

### Frontend Integration

```javascript
// Example: Fetching task list
import { getTasks } from '/src/services/taskService'

const fetchTasks = async () => {
  try {
    const response = await getTasks({ limit: 10, offset: 0 })
    setTasks(response.tasks)
    setTotal(response.total)
  } catch (error) {
    console.error('Failed to fetch tasks:', error)
  }
}
```

### Backend Integration

```python
# Example: Extending TaskManager
from backend.src.core.task_manager import TaskManager

class EnhancedTaskManager(TaskManager):
    def get_tasks_for_user(self, user_id, limit=10, offset=0):
        # Implement user-specific task filtering
        pass
```

## Support

For issues not covered in this guide:
- Check the main documentation
- Review API contract specifications
- Contact support team with error details

## Changelog

**2025-12-27**: Initial release
- Added task history viewing
- Added task log inspection
- Added interactive password prompts
- Added API endpoints for task management

## Feedback

Provide feedback on this feature:
- What works well
- What could be improved
- Additional use cases to support

[Feedback Form Link Placeholder]

## Next Steps

1. Try the feature with a test migration
2. Familiarize yourself with the error patterns
3. Integrate with your existing workflows
4. Provide feedback for improvements