100 lines
6.7 KiB
Markdown
100 lines
6.7 KiB
Markdown
# Feature Specification: Fix UI Styling, WebSocket Port Mismatch, and URL Validation
|
|
|
|
**Feature Branch**: `005-fix-ui-ws-validation`
|
|
**Created**: 2025-12-20
|
|
**Status**: Draft
|
|
**Input**: User description: "UI Styling: Tailwind CSS is not imported in the root layout, causing the unstyled appearance. WebSocket Mismatch: Port mismatch in dev mode is breaking real-time logs. Validation Error: Strict URL validation in superset_tool/models.py requires /api/v1, which caused the connection failure reported in your feedback."
|
|
|
|
## User Scenarios & Testing *(mandatory)*
|
|
|
|
### User Story 1 - Consistent UI Styling (Priority: P1)
|
|
|
|
As a user, I want the application to have a professional and styled appearance so that I can easily navigate and use the interface.
|
|
|
|
**Why this priority**: Unstyled UI makes the application look broken and difficult to use, impacting user trust and usability.
|
|
|
|
**Independent Test**: Can be fully tested by opening the application in a browser and verifying that consistent styling is applied globally across all routes.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** the application is running, **When** I navigate to the home page or settings page, **Then** I should see professional styling applied (e.g., correct fonts, colors, and layout).
|
|
2. **Given** a new component is added, **When** it uses standard styling classes, **Then** those classes should be rendered correctly without additional imports.
|
|
|
|
---
|
|
|
|
### User Story 2 - Real-time Log Monitoring (Priority: P1)
|
|
|
|
As a developer or operator, I want to see real-time logs for running tasks so that I can monitor progress and debug issues effectively.
|
|
|
|
**Why this priority**: Real-time feedback is essential for long-running tasks like migrations or backups; without it, users are left wondering if the process is stuck.
|
|
|
|
**Independent Test**: Can be tested by starting a task and verifying that logs appear in the UI in real-time without requiring a page refresh.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a task is running, **When** I view the task details page, **Then** I should see live log updates streamed via real-time communication.
|
|
2. **Given** the application is running in development mode, **When** a real-time connection is initiated, **Then** it should correctly target the backend service port.
|
|
|
|
---
|
|
|
|
### User Story 3 - Flexible External Service Connection (Priority: P2)
|
|
|
|
As an administrator, I want to connect to external services using their base URL so that I don't have to worry about specific API version paths during configuration.
|
|
|
|
**Why this priority**: Strict validation currently prevents successful connection to valid service instances if the user doesn't provide a very specific suffix, leading to configuration frustration.
|
|
|
|
**Independent Test**: Can be tested by configuring a service connection with a standard base URL and verifying it connects successfully.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a valid service base URL, **When** I save the connection settings, **Then** the system should validate and accept the URL even if it doesn't explicitly end in a specific API version suffix.
|
|
2. **Given** a service URL that already includes an API version suffix, **When** I save the settings, **Then** the system should not duplicate the suffix or fail validation.
|
|
|
|
---
|
|
|
|
### Edge Cases
|
|
|
|
- **Connection Disconnection**: How does the system handle a real-time connection drop during a long-running task? (Assumption: It should attempt to reconnect or show a "Connection Lost" message).
|
|
- **Invalid URL Formats**: How does the system handle URLs that are completely malformed? (Assumption: Standard URL validation should still apply).
|
|
- **Styling Build Failures**: What happens if the styling assets fail to generate? (Assumption: The app should still be functional but may look unstyled; build logs should indicate the failure).
|
|
|
|
## Requirements *(mandatory)*
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: System MUST ensure global styling (Tailwind CSS) is imported in `src/routes/+layout.svelte` to ensure consistent appearance.
|
|
- **FR-002**: System MUST use an environment variable (e.g., `PUBLIC_WS_URL`) with a fallback to the backend port (8000) to determine the WebSocket connection URL.
|
|
- **FR-002.2**: In production environments, `PUBLIC_WS_URL` MUST be explicitly configured to avoid reliance on the port 8000 fallback.
|
|
- **FR-002.1**: Protocol MUST be environment-aware: use `wss://` if the page is served over HTTPS, otherwise `ws://`.
|
|
- **FR-003**: System MUST relax URL validation for external services to allow base URLs and automatically append `/api/v1` if the version suffix is missing.
|
|
- **FR-004**: System MUST provide visual feedback (toast notification and status indicator in log view) when a real-time connection fails to establish.
|
|
- **FR-004.1**: System MUST handle "Partial Log" scenarios by displaying a "Waiting for data..." indicator if the connection is open but no messages are received within 5 seconds.
|
|
- **FR-004.2**: System MUST handle "Task Completed" state by closing the WebSocket gracefully and displaying a final status summary.
|
|
- **FR-004.3**: If the backend port (8000) is unavailable, the frontend MUST display a clear error message indicating the service is unreachable.
|
|
- **FR-005**: System MUST ensure that service clients correctly handle API versioning internally by using the normalized URL.
|
|
|
|
### Key Entities *(include if feature involves data)*
|
|
|
|
- **Service Connection**: Represents the configuration for connecting to an external service.
|
|
- Attributes: Base URL, Credentials (if applicable), Connection Status.
|
|
- **Task Log Stream**: Represents the real-time data flow of logs from the backend to the frontend.
|
|
- Attributes: Task ID, Log Message, Timestamp.
|
|
|
|
## Success Criteria *(mandatory)*
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: 100% of pages render with consistent, professional styling as verified by visual inspection.
|
|
- **SC-002**: Real-time communication success rate is 100% in the development environment when both frontend and backend are running.
|
|
- **SC-003**: Users can successfully configure and save external service connections using only the base domain/IP in 100% of valid cases.
|
|
- **SC-004**: Real-time updates appear in the UI within 500ms of being generated on the backend.
|
|
|
|
## Clarifications
|
|
|
|
### Session 2025-12-20
|
|
- Q: WebSocket Reconnection Strategy → A: Automatic reconnection with exponential backoff (Initial delay: 1s, Multiplier: 2x, Max delay: 30s, Max retries: 10).
|
|
- Q: URL Validation Strictness → A: Automatically append `/api/v1` if missing (Option A).
|
|
- Q: Global Styling Implementation → A: Import in `src/routes/+layout.svelte` (Option A).
|
|
- Q: WebSocket Port Configuration → A: Use environment variable with fallback (Option A).
|
|
- Q: Visual Feedback for Connection Failure → A: Toast notification + Status indicator (Option A).
|