semantic markup update

backend/src/api/routes/mappings.py

@@ -53,13 +53,16 @@ class SuggestRequest(BaseModel):
 
 # [DEF:get_mappings:Function]
 # @PURPOSE: List all saved database mappings.
+# @PRE:     db session is injected.
+# @POST:    Returns filtered list of DatabaseMapping records.
 @router.get("", response_model=List[MappingResponse])
 async def get_mappings(
     source_env_id: Optional[str] = None,
     target_env_id: Optional[str] = None,
     db: Session = Depends(get_db)
 ):
-    query = db.query(DatabaseMapping)
+    with belief_scope("get_mappings"):
+        query = db.query(DatabaseMapping)
     if source_env_id:
         query = query.filter(DatabaseMapping.source_env_id == source_env_id)
     if target_env_id:
@@ -69,42 +72,48 @@ async def get_mappings(
 
 # [DEF:create_mapping:Function]
 # @PURPOSE: Create or update a database mapping.
+# @PRE:     mapping is valid MappingCreate, db session is injected.
+# @POST:    DatabaseMapping created or updated in database.
 @router.post("", response_model=MappingResponse)
 async def create_mapping(mapping: MappingCreate, db: Session = Depends(get_db)):
-    # Check if mapping already exists
-    existing = db.query(DatabaseMapping).filter(
-        DatabaseMapping.source_env_id == mapping.source_env_id,
-        DatabaseMapping.target_env_id == mapping.target_env_id,
-        DatabaseMapping.source_db_uuid == mapping.source_db_uuid
-    ).first()
-    
-    if existing:
-        existing.target_db_uuid = mapping.target_db_uuid
-        existing.target_db_name = mapping.target_db_name
+    with belief_scope("create_mapping"):
+        # Check if mapping already exists
+        existing = db.query(DatabaseMapping).filter(
+            DatabaseMapping.source_env_id == mapping.source_env_id,
+            DatabaseMapping.target_env_id == mapping.target_env_id,
+            DatabaseMapping.source_db_uuid == mapping.source_db_uuid
+        ).first()
+        
+        if existing:
+            existing.target_db_uuid = mapping.target_db_uuid
+            existing.target_db_name = mapping.target_db_name
+            db.commit()
+            db.refresh(existing)
+            return existing
+        
+        new_mapping = DatabaseMapping(**mapping.dict())
+        db.add(new_mapping)
         db.commit()
-        db.refresh(existing)
-        return existing
-    
-    new_mapping = DatabaseMapping(**mapping.dict())
-    db.add(new_mapping)
-    db.commit()
-    db.refresh(new_mapping)
-    return new_mapping
+        db.refresh(new_mapping)
+        return new_mapping
 # [/DEF:create_mapping:Function]
 
 # [DEF:suggest_mappings_api:Function]
 # @PURPOSE: Get suggested mappings based on fuzzy matching.
+# @PRE:     request is valid SuggestRequest, config_manager is injected.
+# @POST:    Returns mapping suggestions.
 @router.post("/suggest")
 async def suggest_mappings_api(
     request: SuggestRequest,
     config_manager=Depends(get_config_manager)
 ):
-    from backend.src.services.mapping_service import MappingService
-    service = MappingService(config_manager)
-    try:
-        return await service.get_suggestions(request.source_env_id, request.target_env_id)
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+    with belief_scope("suggest_mappings_api"):
+        from backend.src.services.mapping_service import MappingService
+        service = MappingService(config_manager)
+        try:
+            return await service.get_suggestions(request.source_env_id, request.target_env_id)
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e))
 # [/DEF:suggest_mappings_api:Function]
 
 # [/DEF:backend.src.api.routes.mappings:Module]