chore: update semantic contracts and git merge handling

2026-03-16 20:34:28 +03:00
parent c53c3f77cc
commit 7e4124bc3f
19 changed files with 480 additions and 257 deletions
--- a/backend/src/api/routes/tests/test_git_status_route.py
+++ b/backend/src/api/routes/tests/test_git_status_route.py
@@ -3,7 +3,7 @@
 # @SEMANTICS: tests, git, api, status, no_repo
 # @PURPOSE: Validate status endpoint behavior for missing and error repository states.
 # @LAYER: Domain (Tests)
-# @RELATION: CALLS -> src.api.routes.git.get_repository_status
+# @RELATION: VERIFIES -> [backend.src.api.routes.git]

 from fastapi import HTTPException
 import pytest
--- a/backend/src/api/routes/admin.py
+++ b/backend/src/api/routes/admin.py
@@ -1,4 +1,4 @@
-# [DEF:backend.src.api.routes.admin:Module]
+# [DEF:AdminApi:Module]
 #
 # @COMPLEXITY: 3
 # @SEMANTICS: api, admin, users, roles, permissions
@@ -93,6 +93,12 @@ async def create_user(
 # [DEF:update_user:Function]
 # @COMPLEXITY: 3
 # @PURPOSE: Updates an existing user.
+# @PRE: Current user has 'Admin' role.
+# @POST: User record is updated in the database.
+# @PARAM: user_id (str) - Target user UUID.
+# @PARAM: user_in (UserUpdate) - Updated user data.
+# @PARAM: db (Session) - Auth database session.
+# @RETURN: UserSchema - The updated user profile.
@router.put("/users/{user_id}", response_model=UserSchema)
 async def update_user(
    user_id: str,
@@ -128,6 +134,11 @@ async def update_user(
 # [DEF:delete_user:Function]
 # @COMPLEXITY: 3
 # @PURPOSE: Deletes a user.
+# @PRE: Current user has 'Admin' role.
+# @POST: User record is removed from the database.
+# @PARAM: user_id (str) - Target user UUID.
+# @PARAM: db (Session) - Auth database session.
+# @RETURN: None
@router.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_user(
    user_id: str,
@@ -331,4 +342,4 @@ async def create_ad_mapping(
        return new_mapping
 # [/DEF:create_ad_mapping:Function]

-# [/DEF:backend.src.api.routes.admin:Module]
+# [/DEF:AdminApi:Module]
--- a/backend/src/api/routes/clean_release_v2.py
+++ b/backend/src/api/routes/clean_release_v2.py
@@ -1,8 +1,6 @@
 # [DEF:backend.src.api.routes.clean_release_v2:Module]
 # @COMPLEXITY: 3
-# @SEMANTICS: api, clean-release, v2, headless
 # @PURPOSE: Redesigned clean release API for headless candidate lifecycle.
-# @LAYER: API

 from fastapi import APIRouter, Depends, HTTPException, status
 from typing import List, Dict, Any
@@ -18,17 +16,40 @@ from ...services.clean_release.dto import CandidateDTO, ManifestDTO
 router = APIRouter(prefix="/api/v2/clean-release", tags=["Clean Release V2"])


+# [DEF:ApprovalRequest:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Schema for approval request payload.
+# @RELATION: USES -> [CandidateDTO]
 class ApprovalRequest(dict):
    pass
+# [/DEF:ApprovalRequest:Class]


+# [DEF:PublishRequest:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Schema for publication request payload.
+# @RELATION: USES -> [CandidateDTO]
 class PublishRequest(dict):
    pass
+# [/DEF:PublishRequest:Class]


+# [DEF:RevokeRequest:Class]
+# @COMPLEXITY: 1
+# @PURPOSE: Schema for revocation request payload.
+# @RELATION: USES -> [CandidateDTO]
 class RevokeRequest(dict):
    pass
+# [/DEF:RevokeRequest:Class]

+# [DEF:register_candidate:Function]
+# @COMPLEXITY: 3
+# @PURPOSE: Register a new release candidate.
+# @PRE: Payload contains required fields (id, version, source_snapshot_ref, created_by).
+# @POST: Candidate is saved in repository.
+# @RETURN: CandidateDTO
+# @RELATION: CALLS -> [CleanReleaseRepository.save_candidate]
+# @RELATION: USES -> [CandidateDTO]
@router.post("/candidates", response_model=CandidateDTO, status_code=status.HTTP_201_CREATED)
 async def register_candidate(
    payload: Dict[str, Any],
@@ -51,7 +72,14 @@ async def register_candidate(
        created_by=candidate.created_by,
        status=CandidateStatus(candidate.status)
    )
+# [/DEF:register_candidate:Function]

+# [DEF:import_artifacts:Function]
+# @COMPLEXITY: 3
+# @PURPOSE: Associate artifacts with a release candidate.
+# @PRE: Candidate exists.
+# @POST: Artifacts are processed (placeholder).
+# @RELATION: CALLS -> [CleanReleaseRepository.get_candidate]
@router.post("/candidates/{candidate_id}/artifacts")
 async def import_artifacts(
    candidate_id: str,
@@ -75,7 +103,16 @@ async def import_artifacts(
        pass
        
    return {"status": "success"}
+# [/DEF:import_artifacts:Function]

+# [DEF:build_manifest:Function]
+# @COMPLEXITY: 3
+# @PURPOSE: Generate distribution manifest for a candidate.
+# @PRE: Candidate exists.
+# @POST: Manifest is created and saved.
+# @RETURN: ManifestDTO
+# @RELATION: CALLS -> [CleanReleaseRepository.save_manifest]
+# @RELATION: CALLS -> [CleanReleaseRepository.get_candidate]
@router.post("/candidates/{candidate_id}/manifests", response_model=ManifestDTO, status_code=status.HTTP_201_CREATED)
 async def build_manifest(
    candidate_id: str,
@@ -109,7 +146,12 @@ async def build_manifest(
        source_snapshot_ref=manifest.source_snapshot_ref,
        content_json=manifest.content_json
    )
+# [/DEF:build_manifest:Function]

+# [DEF:approve_candidate_endpoint:Function]
+# @COMPLEXITY: 3
+# @PURPOSE: Endpoint to record candidate approval.
+# @RELATION: CALLS -> [approve_candidate]
@router.post("/candidates/{candidate_id}/approve")
 async def approve_candidate_endpoint(
    candidate_id: str,
@@ -128,8 +170,13 @@ async def approve_candidate_endpoint(
        raise HTTPException(status_code=409, detail={"message": str(exc), "code": "APPROVAL_GATE_ERROR"})

    return {"status": "ok", "decision": decision.decision, "decision_id": decision.id}
+# [/DEF:approve_candidate_endpoint:Function]


+# [DEF:reject_candidate_endpoint:Function]
+# @COMPLEXITY: 3
+# @PURPOSE: Endpoint to record candidate rejection.
+# @RELATION: CALLS -> [reject_candidate]
@router.post("/candidates/{candidate_id}/reject")
 async def reject_candidate_endpoint(
    candidate_id: str,
@@ -148,8 +195,13 @@ async def reject_candidate_endpoint(
        raise HTTPException(status_code=409, detail={"message": str(exc), "code": "APPROVAL_GATE_ERROR"})

    return {"status": "ok", "decision": decision.decision, "decision_id": decision.id}
+# [/DEF:reject_candidate_endpoint:Function]


+# [DEF:publish_candidate_endpoint:Function]
+# @COMPLEXITY: 3
+# @PURPOSE: Endpoint to publish an approved candidate.
+# @RELATION: CALLS -> [publish_candidate]
@router.post("/candidates/{candidate_id}/publish")
 async def publish_candidate_endpoint(
    candidate_id: str,
@@ -181,8 +233,13 @@ async def publish_candidate_endpoint(
            "status": publication.status,
        },
    }
+# [/DEF:publish_candidate_endpoint:Function]


+# [DEF:revoke_publication_endpoint:Function]
+# @COMPLEXITY: 3
+# @PURPOSE: Endpoint to revoke a previous publication.
+# @RELATION: CALLS -> [revoke_publication]
@router.post("/publications/{publication_id}/revoke")
 async def revoke_publication_endpoint(
    publication_id: str,
@@ -212,5 +269,6 @@ async def revoke_publication_endpoint(
            "status": publication.status,
        },
    }
+# [/DEF:revoke_publication_endpoint:Function]

 # [/DEF:backend.src.api.routes.clean_release_v2:Module]
--- a/backend/src/api/routes/dashboards.py
+++ b/backend/src/api/routes/dashboards.py
@@ -4,7 +4,7 @@
 # @SEMANTICS: api, dashboards, resources, hub
 # @PURPOSE:   API endpoints for the Dashboard Hub - listing dashboards with Git and task status
 # @LAYER:     API
-# @RELATION:  DEPENDS_ON ->[backend.src.dependencies]
+# @RELATION:  DEPENDS_ON ->[AppDependencies]
 # @RELATION:  DEPENDS_ON ->[backend.src.services.resource_service.ResourceService]
 # @RELATION:  DEPENDS_ON ->[backend.src.core.superset_client.SupersetClient]
 #
--- a/backend/src/api/routes/datasets.py
+++ b/backend/src/api/routes/datasets.py
@@ -4,14 +4,14 @@
 # @SEMANTICS: api, datasets, resources, hub
 # @PURPOSE:   API endpoints for the Dataset Hub - listing datasets with mapping progress
 # @LAYER:     API
-# @RELATION:  DEPENDS_ON ->[backend.src.dependencies]
+# @RELATION:  DEPENDS_ON ->[AppDependencies]
 # @RELATION:  DEPENDS_ON ->[backend.src.services.resource_service.ResourceService]
 # @RELATION:  DEPENDS_ON ->[backend.src.core.superset_client.SupersetClient]
 #
 # @INVARIANT: All dataset responses include last_task metadata

 # [SECTION: IMPORTS]
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Query
 from typing import List, Optional
 from pydantic import BaseModel, Field
 from ...dependencies import get_config_manager, get_task_manager, get_resource_service, has_permission
--- a/backend/src/api/routes/migration.py
+++ b/backend/src/api/routes/migration.py
@@ -1,9 +1,9 @@
-# [DEF:backend.src.api.routes.migration:Module]
+# [DEF:MigrationApi:Module]
 # @COMPLEXITY: 5
 # @SEMANTICS: api, migration, dashboards, sync, dry-run
 # @PURPOSE: HTTP contract layer for migration orchestration, settings, dry-run, and mapping sync endpoints.
 # @LAYER: Infra
-# @RELATION: DEPENDS_ON ->[backend.src.dependencies]
+# @RELATION: DEPENDS_ON ->[AppDependencies]
 # @RELATION: DEPENDS_ON ->[backend.src.core.database]
 # @RELATION: DEPENDS_ON ->[backend.src.core.superset_client.SupersetClient]
 # @RELATION: DEPENDS_ON ->[backend.src.core.migration.dry_run_orchestrator.MigrationDryRunService]
@@ -315,4 +315,4 @@ async def trigger_sync_now(
        }
 # [/DEF:trigger_sync_now:Function]

-# [/DEF:backend.src.api.routes.migration:Module]
+# [/DEF:MigrationApi:Module]
--- a/backend/src/api/routes/reports.py
+++ b/backend/src/api/routes/reports.py
@@ -4,7 +4,7 @@
 # @PURPOSE: FastAPI router for unified task report list and detail retrieval endpoints.
 # @LAYER: UI (API)
 # @RELATION: DEPENDS_ON -> [backend.src.services.reports.report_service.ReportsService]
-# @RELATION: DEPENDS_ON -> [backend.src.dependencies]
+# @RELATION: DEPENDS_ON -> [AppDependencies]
 # @INVARIANT: Endpoints are read-only and do not trigger long-running tasks.
 # @PRE: Reports service and dependencies are initialized.
 # @POST: Router is configured and endpoints are ready for registration.