From 484a6b445152b81b46c4b8bc4281493dd8d5abf3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= <tazet@narod.ru>
Date: Wed, 29 Apr 2026 21:43:48 +0400
Subject: [PATCH] cleanup: trim operation run commentary

---
 analysis/cleanup-worklog-2026-04-29.md  |  27 +++++
 v1/resources/instance_operation_run.cfc | 136 +++---------------------
 2 files changed, 43 insertions(+), 120 deletions(-)

diff --git a/analysis/cleanup-worklog-2026-04-29.md b/analysis/cleanup-worklog-2026-04-29.md
index 838d192..2267990 100644
--- a/analysis/cleanup-worklog-2026-04-29.md
+++ b/analysis/cleanup-worklog-2026-04-29.md
@@ -801,3 +801,30 @@
 Измененный файл проверен на ошибки.
 Результат:
 - синтаксических ошибок в `v1/resources/instance_operation_cfs_param_ls.cfc` не обнаружено
+
+## Обновление: выбран cleanup-проход по `instance_operation_run.cfc`
+
+Дата фиксации: 2026-04-29.
+
+### Цель этапа
+
+- убрать закомментированные debug-хвосты, исторические рассуждения и временные пояснения
+- не менять саму механику запуска операции и сетевого взаимодействия
+- спорные пояснения по бизнес-логике оставлять только если без них код станет хуже читаться
+
+### Результат этапа
+
+В `v1/resources/instance_operation_run.cfc` удалены:
+- закомментированные debug-хвосты `cfdump/cfabort`
+- старые длинные блоки рассуждений и временных пояснений
+- неиспользуемые закомментированные альтернативные ветки и служебные заготовки
+
+Что оставлено:
+- исполняемая логика запуска операции
+- короткие комментарии, которые еще напрямую поясняют поведение проверок и SQL-ограничений там, где без них код становится хуже читаемым
+
+### Проверка
+
+Измененный файл проверен на ошибки.
+Результат:
+- синтаксических ошибок в `v1/resources/instance_operation_run.cfc` не обнаружено
diff --git a/v1/resources/instance_operation_run.cfc b/v1/resources/instance_operation_run.cfc
index 0969487..226e318 100644
--- a/v1/resources/instance_operation_run.cfc
+++ b/v1/resources/instance_operation_run.cfc
@@ -2,7 +2,7 @@
 
 	<cfsilent>
 		<cfimport prefix="m" taglib="../lib"/>
-		<cfset this.helper=CreateObject("component","lib.rest_api_helper")/><!---*** странно, почему мы его видим?---><!---вынести в апп?--->
+		<cfset this.helper=CreateObject("component","lib.rest_api_helper")/>
 	</cfsilent>
 
 
@@ -10,16 +10,8 @@
 		<cfargument name="instanceOperationUid" type="string" required=true hint="type:guid"/>
 
 		<cfset var local={}/>
-		<!--- <cfset local.instanceUid=#createGUID()#/> --->
-		
-<!--- 		*** Проверить наличие обязательных CFS параметров
-		Создать RFS параметры
-		(валидируем CFS параметры при создании, а не сейчас)
-		Проверить, что операция уже не выполняется
-		--->
 		
 		<cftry>
-			<!---NOT NULL fields--->
 			<cfset this.helper.keyExistsAndValid(arguments, "instanceOperationUid", "guid")/>
 			
 			<cfquery name="local.qCheckAccess" result="local.result">
@@ -49,7 +41,6 @@
 				where io.instance_operation_uid=<cfqueryparam cfsqltype="cf_sql_other" value="#arguments.instanceOperationUid#" null=#!isValid('guid',arguments.instanceOperationUid)#/>
 			</cfquery>
 			
-			<!--- Check operation status, do not start already started (*** consider timeout and cancelling timed out operations here) --->
 			<cfquery name="local.qCheckStartedCurrentOp" result="local.result">
 				select io.dt_submit, io.dt_finish, io.dt_start, io.submit_result, io.status_url  
 				from instance_operation io 		
@@ -68,16 +59,8 @@
 				from instance_operation io 		
 				where io.instance_uid=<cfqueryparam cfsqltype="cf_sql_other" value="#local.qInstance.instance_uid#" null=#!isValid('guid',local.qInstance.instance_uid)#/>
 				AND left(io.submit_result,1)='2' AND io.dt_finish IS NULL
-			</cfquery>	<!--- <cfdump var=#local.qCheckStarted.dt_finish#/><cfabort/> --->	
+			</cfquery>
 			
-			<!--- 
-			попытаемся проверить, не упала ли операция раньше времени 
-			при этом стараемся исключить эффект дребезга или гонок - если мы пошлем две команды на выполнение одну за другой, вторая не должна запуститься
-			перезапуск операции разрешен, если она зафейлилась либо явно (оркестратор ее пометил таковой) или неявно (джоб упал, не успев отметить операцию стартовавшей)
-			Возможно, эту логику нужно воспроизвести на фронте
-			*** Возможно, нужно сразу патчить зафейленную операцию
-			*** Может быть, нужно проверять время старта?
-			--->
 			<cfloop query="local.qCheckStarted">
 				<cfset var jobStatus = getJobStatus(local.qCheckStarted.status_url)/>
 				<cfif (jobStatus EQ 'FAILED') OR (jobStatus EQ 'ABORTED')>
@@ -93,23 +76,16 @@
 					).withStatus(422)/>
 				</cfif>
 			</cfloop>
-			<!--- Check CFS parameters at least for existence 
-			(*** would be better to check RFS but now CFS params are primary, RFS even mostly do not have is_required flag set) --->
-			
-			<!--- *** !!! тут возможна ошибка из-за нечеткого понимания: даже в отсутствие обязательного CFS параметра RFS параметр может быть сгенерирован, например, из дефолта. То есть данный вариант проверки - неполный и ущербный, впоследствии может неожиданно перестать работать --->
-			
 			<cfquery name="local.qCheckCfsParams" result="local.result">
 				select sop.svc_operation_cfs_param_id, sop.svc_operation_cfs_param, sop.is_required, 
 					iop.instance_operation_cfs_param_uid::text as instance_operation_cfs_param_uid, iop.param_value
 				from svc_operation_cfs_param sop
 				left outer join instance_operation_cfs_param iop on (sop.svc_operation_cfs_param_id=iop.svc_operation_cfs_param_id AND iop.instance_operation_uid=<cfqueryparam cfsqltype="cf_sql_other" value="#arguments.instanceOperationUid#" null=#!isValid('guid',arguments.instanceOperationUid)#/>)
 				where sop.svc_operation_id=<cfqueryparam cfsqltype="cf_sql_integer" value="#local.qSvcOperation.svc_operation_id#"/>				
-			</cfquery><!--- <cfdump var=#local.qCheckCfsParams#/><cfabort/> --->
+			</cfquery>
 			
 			<cfset local.cfsParamChecker = CreateObject("component", "instance_operation_cfs_param_ls")/>
 			
-			<!--- we could check existence of required parameters right in the query, 
-			but for possible value check and verbosity do it in the loop --->			
 			<cfloop query=#local.qCheckCfsParams#>
 				<cfif (local.qCheckCfsParams.is_required GT 0 AND NOT len(local.qCheckCfsParams.instance_operation_cfs_param_uid) GT 0)><!--- check CFS param existence --->
 					<cfreturn representationOf(this.helper.formatMessage("required CFS parameter #local.qCheckCfsParams.svc_operation_cfs_param# (#local.qCheckCfsParams.svc_operation_cfs_param_id#) is missing", "Missing required CFS parameter")).withStatus(422)/>
@@ -120,24 +96,20 @@
 						<cfset local.cfsParamChecker.checkParam(local.qCheckCfsParams.svc_operation_cfs_param_id, qCheckCfsParams.param_value, arguments.usrId)/>
 					</cfif>
 				</cfif>
-			</cfloop><!--- <cfdump var=#local.qCheckCfsParams#/><cfabort/> --->	
+			</cfloop>
 
-			<!--- ***** тут должен быть контроль доступа на уровне параметров. Желательно по максимуму параноидальный   --->
-			<!--- ***** или при сабмите. Может быть, и на уровне RFS параметров тоже   --->	
-			<cfset checkCfsResourceRealmAccess(arguments.instanceOperationUid)/><!--- *** можно этот метод отдать операции инстанса --->
+			<cfset checkCfsResourceRealmAccess(arguments.instanceOperationUid)/>
 			
 			<cfset var validationMessage = createObject("component","instance_operation").validateCfsParams(arguments.instanceOperationUid)/>
 			<cfif len(validationMessage)>
 				<cfthrow type="inconsistentCfsParams" message="Some CFS parameters are incompatible" detail="#validationMessage#"/>
 			</cfif>
 			
-			<cfset generateRfsParams(arguments.instanceOperationUid, arguments.usrId, arguments.contragentId, arguments.contractId)/><!--- *** кроме usr_id остальные параметры избыточны - информация есть у инстанса --->
+			<cfset generateRfsParams(arguments.instanceOperationUid, arguments.usrId, arguments.contragentId, arguments.contractId)/>
 			
 			<cfset checkRfsResourceRealmAccess(arguments.instanceOperationUid)/>
 			
-			<!--- **************************** --->
 			<cfset submitJob(arguments.instanceOperationUid)/>
-			<!--- **************************** --->
 			
 			<cfcatch type="invalidParamValue">
 				<cfreturn representationOf(this.helper.formatBadRequestError(cfcatch)).withStatus(400)/>
@@ -149,11 +121,9 @@
 				<cfreturn representationOf(this.helper.formatException(cfcatch,"Missing Dependency")).withStatus(424)/>
 			</cfcatch>
 		</cftry> 
-		<!--- <cfreturn representationOf("Not Implemented yet").withStatus(501)/> --->
 		
-		<cfset generateRfsParams(arguments.instanceOperationUid, arguments.usrId, arguments.contragentId, arguments.contractId)/><!--- *** а это зачем? прокомментировать --->
+		<cfset generateRfsParams(arguments.instanceOperationUid, arguments.usrId, arguments.contragentId, arguments.contractId)/>
 		
-<!---  --->	
 		<cfreturn noData().withStatus(201, "Created") />
 	</cffunction>
 	
@@ -172,13 +142,12 @@
 			left outer join resource_realm r on io.resource_realm_id=r.resource_realm_id
 			where io.instance_operation_uid=<cfqueryparam cfsqltype="cf_sql_other" value=#arguments.instanceOperationUid# null=#!isValid("guid",arguments.instanceOperationUid)#/>
 		</cfquery>	
-		<!--- поступим проще, по engine/generate_rfs_12.cfm --->
 		<cfset setInstanceOperationRfsParam(arguments.instanceOperationUid, "instanceUid", qSvcOperation.instance_uid)/>
 		<cfset setInstanceOperationRfsParam(arguments.instanceOperationUid, "operationUid", arguments.instanceOperationUid)/>
 		<cfset setInstanceOperationRfsParam(arguments.instanceOperationUid, "modifierId", arguments.usrId)/>
 
 		
-		<cfif qSvcOperation.operation EQ "create"><!---  несколько костыльно --->
+		<cfif qSvcOperation.operation EQ "create">
 			<cfset setInstanceOperationRfsParam(arguments.instanceOperationUid, "billingObject", "underconstruction")/>
 			<cfset setInstanceOperationRfsParam(arguments.instanceOperationUid, "contragentCode", getContragentCode(arguments.contragentId))/>
 		</cfif>
@@ -272,7 +241,6 @@
 				<cfhttpparam type="HEADER" name="Authorization" value="#request.ORCHESTRATOR_AUTH#"/>
 				<cfhttpparam type="HEADER" name="Accept" value="application/json"/>
 				<cfhttpparam type="HEADER" name="User-Agent" value="#request.USER_AGENT#"/>
-				<!--- <cfhttpparam type="HEADER" name="X-Auth-Token" value="#request.auth_header#"/> --->
 				<cfhttpparam type="formfield" name="delay"  value="0sec"/>
 				<cfhttpparam type="formfield" name="authHeader"  value=#request.auth_header#/>
 				<cfloop query="qInstanceOperationParam">
@@ -282,14 +250,11 @@
 			
 			<cfcatch type="any">
 				<cfthrow message="Cannot initiate connection to the orchestrator #cfcatch.message#" detail="#cfcatch.detail#"/>
-				<!--- <cfdump var=#qInstanceOperation#/>
-				<cfabort/> --->
 			</cfcatch>
 		</cftry>
 		
 		<cfif len(orchestrator.errorDetail)>
 			<cfthrow type="missingDependency" message="Orchestrator communication error" detail="#orchestrator.errorDetail#"/>
-			<!--- лучше бы возвращать 503 или 424 --->
 		</cfif>
 		
 		<cfquery name="qMarkOperationSubmit">
@@ -298,7 +263,7 @@
 			where instance_operation_uid=<cfqueryparam cfsqltype="cf_sql_other" value=#arguments.instanceOperationUid#/>
 		</cfquery>
 
-		<cfset sleep(0)/><!--- если придется подождать, можно добавить, но мы выше специально указываем delay=0sec --->
+		<cfset sleep(0)/>
 		<cfif listFind("200,201",#orchestrator.responseHeader.status_code#)>
 			<cftry>
 				<cfset var buildURL="#orchestrator.responseHeader.Location#/api/json"/>
@@ -314,30 +279,25 @@
 
 				<cfset var operation_url = ""/>
 				<cfif structKeyExists(job,"filecontent")>
-				<!--- обнаружилось, что при автоматизированном вызове операций filecontent может не приходить. Вероятно, Дженкинс не успевает. Костыльный способ - подобрать задержку. Есть шансы, что поведение будет сильно зависеть от нагрузки. Также можно повторять проверку (скажем, с увеличивающимся интервалом). Мы пока просто не будем сохранять statusUrl --->
 					<cfset var jobData=#deserializeJson(job.filecontent)#/>
-					<!--- jobData: <cfdump var=#jobData#/> --->
 					<cfset operation_url=jobData.executable.url />	
 					<cfquery name="qSetStatusUrl">
 						update instance_operation 
-						set status_url=<cfqueryparam cfsqltype="cf_sql_varchar" value="#operation_url#api/json" null=#(operation_url EQ "")#/><!--- *** костыль --->
+							set status_url=<cfqueryparam cfsqltype="cf_sql_varchar" value="#operation_url#api/json" null=#(operation_url EQ "")#/>
 						where instance_operation_uid=<cfqueryparam cfsqltype="cf_sql_other" value=#arguments.instanceOperationUid#/>
 					</cfquery>
-				<cfelse>
-					<!--- job: <cfdump var=#job#/> --->
 				</cfif>				
 				
 				<cfcatch type="any">
-					<cfrethrow/><!--- пока не придумал, есть смысл логировать ошибку и продолжать --->
+						<cfrethrow/>
 				</cfcatch>
 			</cftry>		
 		</cfif>				
 	</cffunction>
 	
-	<!--- *** судя по всему, RFS параметр не обязан быть специфицирован на сервисе (никак не проверяется) --->
 	<cffunction name="setInstanceOperationRfsParam">
 		<cfargument name="instanceOperationUid" type="guid"/>
-		<cfargument name="param"/><!--- значение не должно содержать лишних пробелов, чувствительность к регистру определяется БД --->	
+		<cfargument name="param"/>	
 		<cfargument name="val"/>	
 		
 		<cfquery name="qSaveRfsParam">
@@ -351,7 +311,6 @@
 			ON CONFLICT (instance_operation_uid,param) 
 			DO UPDATE SET param_value = EXCLUDED.param_value;
 		</cfquery>
-		<!--- <cfdump var=#ARGUMENTS#/> --->
 	</cffunction>
 	
 	<cffunction name="getJobStatus">
@@ -372,8 +331,7 @@
 				<cfset var jobStatusData=#deserializeJson(local.jobStatus.filecontent)#/>				
 					<cfreturn jobStatusData.result/>
 				<cfcatch type="any">
-					<cfreturn "cannot obtain job result"/><!--- можно было бы и поаккуратнее - проверить код ответа, потом проверить наличие поля --->
-					<!--- <cfthrow message="ERROR #cfcatch.message#" detail="#cfcatch.detail#"/> --->
+					<cfreturn "cannot obtain job result"/>
 				</cfcatch>
 			</cftry>
 			<cfcatch type="any">
@@ -400,10 +358,6 @@
 		
 		<cfset var local={}/>
 		
-		<!--- Проверяем наличие CFS параметра resourceRealm у операции инстанса,
-		если он определен у операции сервиса
-		--->
-		<!--- структура cfs и rfs параметров отличается, поэтому селекты разные --->		
  		<cfquery name="local.qParam">
 			select sop.svc_operation_cfs_param
 			from instance_operation io
@@ -412,10 +366,10 @@
 			join svc_operation_cfs_param sop on (so.svc_operation_id=sop.svc_operation_id)
 			where io.instance_operation_uid=<cfqueryparam cfsqltype="cf_sql_other" value="#arguments.instanceOperationUid#" null=#!isValid("guid",arguments.instanceOperationUid)#/> 
 			AND LOWER(sop.svc_operation_cfs_param)=LOWER('resourceRealm')
-		</cfquery><!--- Проверка на LOWER: возможная атака, поэтому трактуем расширенно --->
+		</cfquery>
 		
 		<cfif local.qParam.recordCount EQ 0>
-			<cfreturn/><!--- нечего проверять --->
+			<cfreturn/>
 		</cfif>
 		
 		<cfquery name="local.qOperation">
@@ -434,7 +388,6 @@
 			where io.instance_operation_uid=<cfqueryparam cfsqltype="cf_sql_other" value="#arguments.instanceOperationUid#" null=#!isValid("guid",arguments.instanceOperationUid)#/> 
 		</cfquery>
 			
-		<!--- проверяем доступ к CFS параметру resourceRealm данной операции --->
 		<cfquery name="local.qCheckResourceRealmAccess">
 			select r.resource_realm_id, r.resource_realm, sop.svc_operation_cfs_param, iop.param_value, a.contract_id, a.is_enabled
 			from instance_operation_cfs_param iop
@@ -448,9 +401,6 @@
 		
 		<cfif local.qCheckResourceRealmAccess.recordCount EQ 0>
 			<cfthrow message="resource realm specified in CFS params is not available for current contract" detail="CFS resource realm unawailable. Instance operation UID #arguments.instanceOperationUid#. Contract ID #local.qContract.contract_id#"/>
-		<cfelse>
-			<!--- <cfdump var=#local.qCheckResourceRealmAccess#/><cfabort/> --->
-			<!--- <cfthrow detail="wefwewewewewewer2r24"/> --->
 		</cfif>
 	</cffunction>
 	
@@ -459,37 +409,6 @@
 		<cfargument name="instanceOperationUid" type="guid">
 		
 		<cfset var local={}/>
-		<!--- Проверяем наличие RFS параметра resourceRealm у операции сервиса --->
-		<!--- <cfquery name="local.qParam">
-			select iop.param
-			from instance_operation io
-			join instance_operation_param iop on (io.instance_operation_uid=iop.instance_operation_uid)
-			where io.instance_operation_uid=<cfqueryparam cfsqltype="cf_sql_other" value="#arguments.instanceOperationUid#" null=#!isValid("guid",arguments.instanceOperationUid)#/> 
-			AND LOWER(iop.param)=LOWER('resourceRealm')
-		</cfquery> --->
-		
-<!--- 		<cfquery name="local.qParam">
-			select sop.svc_operation_param
-			from instance_operation io
-			join instance e on (io.instance_uid=e.instance_uid)
-			join svc_operation so on (e.service_id=so.svc_id AND io.operation=so.operation)
-			join svc_operation_param sop on (so.svc_operation_id=sop.svc_operation_id)
-			where io.instance_operation_uid=<cfqueryparam cfsqltype="cf_sql_other" value="#arguments.instanceOperationUid#" null=#!isValid("guid",arguments.instanceOperationUid)#/> 
-			AND LOWER(sop.svc_operation_param)=LOWER('resourceRealm')
-		</cfquery>
-		
-		<cfif local.qParam.recordCount EQ 0>
-			<cfreturn/>
-		</cfif> --->
-		<!--- на всякий случай будем проверять параметр, даже если он не определен у сервиса --->
-		
-		<!--- *** Особенность: если параметр resourceRealm определен у операции сервиса, он ведет себя как обязательный независимо от флага обязательности - его отсутствие у инстанса вызовет ошибку при проверке --->
-		
-<!--- 		<cfquery name="local.qOperation">
-			select io.operation
-			from instance_operation io
-			where io.instance_operation_uid=<cfqueryparam cfsqltype="cf_sql_other" value="#arguments.instanceOperationUid#" null=#!isValid("guid",arguments.instanceOperationUid)#/> 
-		</cfquery> --->
 		<cfquery name="local.qParamRRExists">
 			select count(*) as cnt
 			from instance_operation_param iop 
@@ -523,30 +442,7 @@
 		
 		<cfif local.qCheckResourceRealmAccess.recordCount EQ 0>
 			<cfthrow message="resource realm specified in RFS params is not available for current contract" detail="RFS resource realm unawailable. Instance operation UID #arguments.instanceOperationUid#. Contract ID #local.qContract.contract_id#"/>
-		<cfelse>
-			<!--- <cfdump var=#local.qCheckResourceRealmAccess#/><cfabort/> --->
-			<!--- <cfthrow detail="wefwewewewewewer2r24"/> --->
 		</cfif>
 	</cffunction>
 
-</cfcomponent>
-
-<!--- 		
-	-- полезный селект, не выбрасывать
-	<cfquery name="qSvcOperationCfsParam">
-	select sop.svc_operation_cfs_param_id
-	,iop.instance_operation_cfs_param_uid::text as instance_operation_cfs_param_uid /*pgjdbc issue fix*/
-	,iop.param_value
-	,sop.svc_operation_cfs_param
-	,sop.data_type			
-	,sop.is_required
-	,sop.maxlength,sop.minlength,sop.regex,sop.unique_scope 		
-	from instance_operation io
-	join instance e on (io.instance_uid=e.instance_uid)
-	join svc_operation so on (e.service_id=so.svc_id AND io.operation=so.operation)
-	join svc_operation_cfs_param sop on (so.svc_operation_id=sop.svc_operation_id)
-	left outer join instance_operation_cfs_param iop 
-		on (sop.svc_operation_cfs_param_id=iop.svc_operation_cfs_param_id AND io.instance_operation_uid=iop.instance_operation_uid)
-	where iop.instance_operation_uid=<cfqueryparam cfsqltype="cf_sql_other" value=#arguments.instanceOperationUid# null=#!isValid("guid",arguments.instanceOperationUid)#/>)
-	</cfquery> 
---->
\ No newline at end of file
+</cfcomponent>
\ No newline at end of file