speckit update

specs/022-id-sync-cross-filter/spec.md

@@ -0,0 +1,165 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Reference UX**: `[ux_reference.md]` (See specific folder)
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]
+
+---
+
+## Test Data Fixtures *(recommended for CRITICAL components)*
+
+<!--
+  Define reference/fixture data for testing CRITICAL tier components.
+  This data will be used by the Tester Agent when writing unit tests.
+  Format: JSON or YAML that matches the component's data structures.
+-->
+
+### Fixtures
+
+```yaml
+# Example fixture format
+fixture_name:
+  description: "Description of this test data"
+  data:
+    # JSON or YAML data structure
+```
+
+### Example: Dashboard API
+
+```yaml
+valid_dashboard:
+  description: "Valid dashboard object for API responses"
+  data:
+    id: 1
+    title: "Sales Report"
+    slug: "sales"
+    git_status:
+      branch: "main"
+      sync_status: "OK"
+    last_task:
+      task_id: "task-123"
+      status: "SUCCESS"
+
+empty_dashboards:
+  description: "Empty dashboard list response"
+  data:
+    dashboards: []
+    total: 0
+    page: 1
+
+error_not_found:
+  description: "404 error response"
+  data:
+    detail: "Dashboard not found"
+```

specs/022-id-sync-cross-filter/ux_reference.md

@@ -0,0 +1,57 @@
+# UX Reference: ID Sync Service & Cross-Filter Restoration
+
+**Feature Branch**: `022-id-sync-cross-filter`
+**Created**: 2026-02-25
+**Status**: Draft
+
+## 1. User Persona & Context
+
+*   **Who is the user?**: Data Engineer / Superset Administrator.
+*   **What is their goal?**: Migrate dashboards between environments (e.g., DEV to PROD) while ensuring that cross-filters remain functional without manual fixing.
+*   **Context**: Using the Migration Dashboard UI to trigger a dashboard transfer.
+
+## 2. The "Happy Path" Narrative
+
+The user selects a dashboard for migration and notices a pre-checked option: "Fix Cross-Filters". They proceed with the migration. Behind the scenes, the system identifies that some charts are new on the target environment. It performs an initial import, automatically fetches the newly assigned IDs, patches the dashboard's internal metadata, and re-imports it. The user receives a success notification, opens the dashboard on the target environment, and finds that all cross-filters work perfectly on the first try.
+
+## 3. Interface Mockups
+
+### UI Layout & Flow
+
+**Screen/Component**: Migration Launch Modal
+
+*   **Key Elements**:
+    *   **[Checkbox] Fix Cross-Filters**:
+        *   **Label**: "Исправить связи кросс-фильтрации (Fix Cross-Filters)"
+        *   **Default**: Checked.
+        *   **Description**: "Автоматически заменяет ID чартов и датасетов во внутренних настройках дашборда, чтобы фильтры работали корректно на целевом стенде".
+    *   **[Button] Start Migration**: Primary action.
+
+*   **States**:
+    *   **Processing**: A multi-step progress bar shows:
+        1. Exporting from Source...
+        2. Analyzing Metadata...
+        3. [If New Objects] Performing Preliminary Import...
+        4. Syncing Remote IDs...
+        5. Patching Cross-Filters...
+        6. Finalizing Migration...
+    *   **Success**: Toast notification: "Migration complete. Cross-filters successfully mapped and fixed."
+
+## 4. The "Error" Experience
+
+### Scenario A: Mapping Conflict
+
+*   **User Action**: Starts migration.
+*   **System Response**:
+    *   (UI) Error message: "Conflict detected: Multiple UUIDs found for the same resource name on Target. Please verify environment sync."
+*   **Recovery**: User is directed to the "Environment Sync" status page to trigger a manual refresh or resolve duplicates.
+
+### Scenario B: ID Sync Failure
+
+*   **System Response**: "Unable to retrieve new IDs from Target Superset after initial import. Migration paused."
+*   **Recovery**: "Retry Sync" button or "Continue without Fixing" option.
+
+## 5. Tone & Voice
+
+*   **Style**: Professional, Technical, Reassuring.
+*   **Terminology**: Use "Target Environment", "Integer ID", "UUID", "Cross-Filtering".