busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

semantics

Browse Source
This commit is contained in:
busya
2026-05-26 09:30:41 +03:00
parent 1e7bcecaea
commit 9ffa8af1dc
623 changed files with 28045 additions and 26557 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
backend/src/api/routes/migration.py
View File

@@ -1,6 +1,6 @@
# #region MigrationApi [C:5] [TYPE Module] [SEMANTICS fastapi, migration, api, sync, search, mapping]
# @BRIEF HTTP contract layer for migration orchestration, settings, dry-run, and mapping sync endpoints.
# @LAYER: Infra
# @LAYER Infrastructure
# @RELATION DEPENDS_ON -> [AppDependencies]
# @RELATION DEPENDS_ON -> [DatabaseModule]
# @RELATION DEPENDS_ON -> [DashboardSelection]
@@ -8,18 +8,18 @@
# @RELATION DEPENDS_ON -> [MigrationDryRunService]
# @RELATION DEPENDS_ON -> [IdMappingService]
# @RELATION DEPENDS_ON -> [ResourceMapping]
# @INVARIANT: Migration endpoints never execute with invalid environment references and always return explicit HTTP errors on guard failures.
# @PRE: Backend core services initialized and Database session available.
# @POST: Migration tasks are enqueued or dry-run results are computed and returned.
# @SIDE_EFFECT: Enqueues long-running tasks, potentially mutates ResourceMapping table, and performs remote Superset API calls.
# @DATA_CONTRACT: [DashboardSelection | QueryParams] -> [TaskResponse | DryRunResult | MappingSummary]
# @TEST_CONTRACT: [DashboardSelection + configured envs] -> [task_id | dry-run result | sync summary]
# @TEST_SCENARIO: [invalid_environment] -> [HTTP_400_or_404]
# @TEST_SCENARIO: [valid_execution] -> [success_payload_with_required_fields]
# @TEST_EDGE: [missing_field] ->[HTTP_400]
# @TEST_EDGE: [invalid_type] ->[validation_error]
# @TEST_EDGE: [external_fail] ->[HTTP_500]
# @TEST_INVARIANT: [EnvironmentValidationBeforeAction] -> VERIFIED_BY: [invalid_environment, valid_execution]
# @INVARIANT Migration endpoints never execute with invalid environment references and always return explicit HTTP errors on guard failures.
# @PRE Backend core services initialized and Database session available.
# @POST Migration tasks are enqueued or dry-run results are computed and returned.
# @SIDE_EFFECT Enqueues long-running tasks, potentially mutates ResourceMapping table, and performs remote Superset API calls.
# @DATA_CONTRACT [DashboardSelection | QueryParams] -> [TaskResponse | DryRunResult | MappingSummary]
# @TEST_CONTRACT [DashboardSelection + configured envs] -> [task_id | dry-run result | sync summary]
# @TEST_SCENARIO [invalid_environment] -> [HTTP_400_or_404]
# @TEST_SCENARIO [valid_execution] -> [success_payload_with_required_fields]
# @TEST_EDGE [missing_field] ->[HTTP_400]
# @TEST_EDGE [invalid_type] ->[validation_error]
# @TEST_EDGE [external_fail] ->[HTTP_500]
# @TEST_INVARIANT [EnvironmentValidationBeforeAction] -> VERIFIED_BY: [invalid_environment, valid_execution]
from typing import Any, cast
@@ -42,11 +42,11 @@ router = APIRouter(prefix="/api", tags=["migration"])
# #region get_dashboards [C:3] [TYPE Function]
# @BRIEF Fetch dashboard metadata from a requested environment for migration selection UI.
# @PRE: env_id is provided and exists in configured environments.
# @POST: Returns List[DashboardMetadata] for the resolved environment; emits HTTP_404 when environment is absent.
# @SIDE_EFFECT: Reads environment configuration and performs remote Superset metadata retrieval over network.
# @DATA_CONTRACT: Input[str env_id] -> Output[List[DashboardMetadata]]
# @RELATION CALLS -> [SupersetClient.get_dashboards_summary]
# @PRE env_id is provided and exists in configured environments.
# @POST Returns List[DashboardMetadata] for the resolved environment; emits HTTP_404 when environment is absent.
# @SIDE_EFFECT Reads environment configuration and performs remote Superset metadata retrieval over network.
# @DATA_CONTRACT Input[str env_id] -> Output[List[DashboardMetadata]]
# @RELATION CALLS -> [EXT:method:SupersetClient.get_dashboards_summary]
@router.get("/environments/{env_id}/dashboards", response_model=list[DashboardMetadata])
async def get_dashboards(
env_id: str,
@@ -73,13 +73,13 @@ async def get_dashboards(
# #region execute_migration [C:5] [TYPE Function]
# @BRIEF Validate migration selection and enqueue asynchronous migration task execution.
# @PRE: DashboardSelection payload is valid and both source/target environments exist.
# @POST: Returns {"task_id": str, "message": str} when task creation succeeds; emits HTTP_400/HTTP_500 on failure.
# @SIDE_EFFECT: Reads configuration, writes task record through task manager, and writes operational logs.
# @DATA_CONTRACT: Input[DashboardSelection] -> Output[Dict[str, str]]
# @PRE DashboardSelection payload is valid and both source/target environments exist.
# @POST Returns {"task_id": str, "message": str} when task creation succeeds; emits HTTP_400/HTTP_500 on failure.
# @SIDE_EFFECT Reads configuration, writes task record through task manager, and writes operational logs.
# @DATA_CONTRACT Input[DashboardSelection] -> Output[Dict[str, str]]
# @RELATION CALLS -> [create_task]
# @RELATION DEPENDS_ON -> [DashboardSelection]
# @INVARIANT: Migration task dispatch never occurs before source and target environment ids pass guard validation.
# @INVARIANT Migration task dispatch never occurs before source and target environment ids pass guard validation.
@router.post("/migration/execute")
async def execute_migration(
selection: DashboardSelection,
@@ -136,13 +136,13 @@ async def execute_migration(
# #region dry_run_migration [C:5] [TYPE Function]
# @BRIEF Build pre-flight migration diff and risk summary without mutating target systems.
# @PRE: DashboardSelection is valid, source and target environments exist, differ, and selected_ids is non-empty.
# @POST: Returns deterministic dry-run payload; emits HTTP_400 for guard violations and HTTP_500 for orchestrator value errors.
# @SIDE_EFFECT: Reads local mappings from DB and fetches source/target metadata via Superset API.
# @DATA_CONTRACT: Input[DashboardSelection] -> Output[Dict[str, Any]]
# @PRE DashboardSelection is valid, source and target environments exist, differ, and selected_ids is non-empty.
# @POST Returns deterministic dry-run payload; emits HTTP_400 for guard violations and HTTP_500 for orchestrator value errors.
# @SIDE_EFFECT Reads local mappings from DB and fetches source/target metadata via Superset API.
# @DATA_CONTRACT Input[DashboardSelection] -> Output[Dict[str, Any]]
# @RELATION DEPENDS_ON -> [DashboardSelection]
# @RELATION DEPENDS_ON -> [MigrationDryRunService]
# @INVARIANT: Dry-run flow remains read-only and rejects identical source/target environments before service execution.
# @INVARIANT Dry-run flow remains read-only and rejects identical source/target environments before service execution.
@router.post("/migration/dry-run", response_model=dict[str, Any])
async def dry_run_migration(
selection: DashboardSelection,
@@ -202,10 +202,10 @@ async def dry_run_migration(
# #region get_migration_settings [C:3] [TYPE Function]
# @BRIEF Read and return configured migration synchronization cron expression.
# @PRE: Configuration store is available and requester has READ permission.
# @POST: Returns {"cron": str} reflecting current persisted settings value.
# @SIDE_EFFECT: Reads configuration from config manager.
# @DATA_CONTRACT: Input[None] -> Output[Dict[str, str]]
# @PRE Configuration store is available and requester has READ permission.
# @POST Returns {"cron": str} reflecting current persisted settings value.
# @SIDE_EFFECT Reads configuration from config manager.
# @DATA_CONTRACT Input[None] -> Output[Dict[str, str]]
# @RELATION DEPENDS_ON -> [AppDependencies]
@router.get("/migration/settings", response_model=dict[str, str])
async def get_migration_settings(
@@ -223,10 +223,10 @@ async def get_migration_settings(
# #region update_migration_settings [C:3] [TYPE Function]
# @BRIEF Validate and persist migration synchronization cron expression update.
# @PRE: Payload includes "cron" key and requester has WRITE permission.
# @POST: Returns {"cron": str, "status": "updated"} and persists updated cron value.
# @SIDE_EFFECT: Mutates configuration and writes persisted config through config manager.
# @DATA_CONTRACT: Input[Dict[str, str]] -> Output[Dict[str, str]]
# @PRE Payload includes "cron" key and requester has WRITE permission.
# @POST Returns {"cron": str, "status": "updated"} and persists updated cron value.
# @SIDE_EFFECT Mutates configuration and writes persisted config through config manager.
# @DATA_CONTRACT Input[Dict[str, str]] -> Output[Dict[str, str]]
# @RELATION DEPENDS_ON -> [AppDependencies]
@router.put("/migration/settings", response_model=dict[str, str])
async def update_migration_settings(
@@ -254,10 +254,10 @@ async def update_migration_settings(
# #region get_resource_mappings [C:3] [TYPE Function]
# @BRIEF Fetch synchronized resource mappings with optional filters and pagination for migration mappings view.
# @PRE: skip>=0, 1<=limit<=500, DB session is active, requester has READ permission.
# @POST: Returns {"items": [...], "total": int} where items reflect applied filters and pagination.
# @SIDE_EFFECT: Executes database read queries against ResourceMapping table.
# @DATA_CONTRACT: Input[QueryParams] -> Output[Dict[str, Any]]
# @PRE skip>=0, 1<=limit<=500, DB session is active, requester has READ permission.
# @POST Returns {"items": [...], "total": int} where items reflect applied filters and pagination.
# @SIDE_EFFECT Executes database read queries against ResourceMapping table.
# @DATA_CONTRACT Input[QueryParams] -> Output[Dict[str, Any]]
# @RELATION DEPENDS_ON -> [ResourceMapping]
@router.get("/migration/mappings-data", response_model=dict[str, Any])
async def get_resource_mappings(
@@ -326,10 +326,10 @@ async def get_resource_mappings(
# #region trigger_sync_now [C:3] [TYPE Function]
# @BRIEF Trigger immediate ID synchronization for every configured environment.
# @PRE: At least one environment is configured and requester has EXECUTE permission.
# @POST: Returns sync summary with synced/failed counts after attempting all environments.
# @SIDE_EFFECT: Upserts Environment rows, commits DB transaction, performs network sync calls, and writes logs.
# @DATA_CONTRACT: Input[None] -> Output[Dict[str, Any]]
# @PRE At least one environment is configured and requester has EXECUTE permission.
# @POST Returns sync summary with synced/failed counts after attempting all environments.
# @SIDE_EFFECT Upserts Environment rows, commits DB transaction, performs network sync calls, and writes logs.
# @DATA_CONTRACT Input[None] -> Output[Dict[str, Any]]
# @RELATION DEPENDS_ON -> [IdMappingService]
# @RELATION CALLS -> [sync_environment]
@router.post("/migration/sync-now", response_model=dict[str, Any])