ss-tools/specs/022-sync-id-cross-filters/tasks.md

Tasks: ID Synchronization and Cross-Filter Recovery

Input: Design documents from /specs/022-sync-id-cross-filters/ Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/api.md

Format: [ID] [P?] [Story] Description

• [P]: Can run in parallel (different files, no dependencies)
• [Story]: Which user story this task belongs to (e.g., US1, US2)

---

Phase 1: Setup (Shared Infrastructure)

Purpose: Project initialization and basic structure.

• T001 Initialize database/ORM mapping models structure for the new service in backend/src/models/mappings.py
• T002 Configure APScheduler scaffolding in backend/src/core/mapping_service.py

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Core logic for the IdMappingService that MUST be complete before we can use it in migrations.

• T003 Create ResourceMapping SQLAlchemy or SQLite model in backend/src/models/mappings.py (Include resource_name field)
• T004 Implement IdMappingService.sync_environment(env_id) logic in backend/src/core/mapping_service.py
• T005 Implement IdMappingService.get_remote_ids_batch(...) logic in backend/src/core/mapping_service.py
• T006 Write unit tests for IdMappingService in backend/tests/core/test_mapping_service.py using resource_mapping_record fixture.

Checkpoint: Foundation ready - ID cataloging works independently.

---

Phase 3: User Story 1 - Transparent Migration with Working Cross-Filters (Priority: P1) 🎯 MVP

Goal: As a user migrating a dashboard equipped with cross-filters, I want the system to automatically remap internal Chart and Dataset IDs to the target environment's IDs.

Tests for User Story 1 ⚠️

• T007 [P] [US1] Create unit tests for YAML patching in backend/tests/core/test_migration_engine.py using missing_target_scenario fixture.

Implementation for User Story 1

• T008 [US1] Inject IdMappingService dependency into MigrationEngine in backend/src/core/migration_engine.py
• T009 [US1] Implement MigrationEngine._patch_dashboard_metadata(...) to rewrite integer IDs in json_metadata.
• T010 [US1] Modify MigrationEngine to perform "Target Check" against IDs.
• T011 [US1] Modify MigrationEngine to execute "Dual-Import" sequence if Target Check finds missing IDs.

Checkpoint: At this point, User Story 1 should be fully functional and testable via backend scripts/API calls.

---

Phase 4: User Story 2 - UI Option for Cross-Filter Recovery (Priority: P2)

Goal: As a user initiating a migration, I want a clear option to toggle cross-filter repair.

Implementation for User Story 2

• T012 [US2] Modify backend/src/api/routes/migration.py and DashboardSelection to accept fix_cross_filters boolean (default: True).
• T013 [US2] Modify frontend migration/+page.svelte to include "Исправить связи кросс-фильтрации" checkbox and pass it in API POST payload.

Checkpoint: User controls whether cross-filter patching occurs.

• T014 [US2] Add checkbox to the Migration launch modal in the Frontend component (assuming frontend/src/components/MigrationModal.svelte or similar).

Checkpoint: At this point, User Story 1 and 2 should both work end-to-end.

---

Phase 5: User Story 3 - Settings UI and Mapping Table (Priority: P2)

Goal: As a system administrator, I want to configure the synchronization schedule via Cron and view the current mapping table in the Settings UI.

Implementation for User Story 3

• T015 [P] [US3] Implement GET /api/v1/migration/settings and PUT /api/v1/migration/settings for Cron in backend/src/api/routes/migration.py
• T016 [P] [US3] Implement GET /api/v1/migration/mappings-data endpoint for the table in backend/src/api/routes/migration.py
• T017 [US3] Create Mapping UI directly in Frontend frontend/src/routes/settings/+page.svelte
• T018 [US3] Add Cron configuration input and Mapping Table to the Settings page in frontend/src/routes/settings/+page.svelte
• T019 [US3] Ensure IdMappingService scheduler can be restarted/reconfigured.

Checkpoint: At this point, User Story 3 should be fully functional and the background sync interval can be tuned visually.

---

Phase N: Polish & Cross-Cutting Concerns

Purpose: Improvements that affect multiple user stories

• T020 Verify error handling if "Technical Import" step fails.
• T021 Add debug logging using Molecular Topology ([EXPLORE], [REASON], [REFLECT]) to the mapping and patching processes.

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies - can start immediately
• Foundational (Phase 2): Depends on Setup completion - BLOCKS all user stories
• User Stories (Phase 3+): All depend on Foundational phase completion
• Polish (Final Phase): Depends on all desired user stories being complete

User Story Dependencies

• User Story 1 (P1): Can start after Foundational (Phase 2)
• User Story 2 (P2): Can run in parallel with US1 backend work.
• User Story 3 (P3): Depends on Foundational (Phase 2), specifically the ResourceMapping table being populated, but can run parallel to US1/US2.

Parallel Opportunities

• Frontend UI work (T014, T017, T018) can be done in parallel with backend engine work (T008-T011, T015-T016)
• API route updates can be done in parallel.