busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
migration
ss-tools/specs/005-fix-ui-ws-validation/spec.md
busya 43b4c75e36 worked backup
2025-12-21 00:16:12 +03:00

6.7 KiB
Raw Permalink Blame History

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).