From 44daae628d24502730745a94f2f3665474f22c4a Mon Sep 17 00:00:00 2001
From: Naeel <tazet@narod.ru>
Date: Wed, 29 Apr 2026 20:57:39 +0400
Subject: [PATCH] cleanup: trim list resources and remaining helper comments

---
 analysis/cleanup-worklog-2026-04-29.md    | 39 +++++++++++++++++++++++
 v1/lib/field.cfm                          |  4 +--
 v1/lib/filter_build.cfm                   |  4 +--
 v1/resources/catalog_service_ls.cfc       | 18 +++--------
 v1/resources/catalog_service_param_ls.cfc | 21 +++---------
 5 files changed, 53 insertions(+), 33 deletions(-)

diff --git a/analysis/cleanup-worklog-2026-04-29.md b/analysis/cleanup-worklog-2026-04-29.md
index c749a8b..c90a3df 100644
--- a/analysis/cleanup-worklog-2026-04-29.md
+++ b/analysis/cleanup-worklog-2026-04-29.md
@@ -403,3 +403,42 @@
 - посмотреть текущее diff-состояние cleanup-ветки
 - зафиксировать сделанные этапы в коммитах
 - затем перейти к следующей группе файлов, начиная с наиболее контролируемых resource-компонентов
+
+## Обновление: зафиксирован второй локальный cleanup-коммит
+
+Дата фиксации: 2026-04-29 20:55:00 +0400.
+
+### Что зафиксировано коммитом
+
+Создан локальный коммит:
+- `7b98eee156c3251bdd37a4d22d3596ba671a447c`
+- сообщение: `cleanup: remove reasoning comments and translate helper docs`
+
+В него вошли:
+- `analysis/cleanup-worklog-2026-04-29.md`
+- `v1/lib/TokenGenerator.cfc`
+- `v1/lib/field_set.cfm`
+- `v1/lib/order_build.cfm`
+- `v1/lib/rest_api_helper.cfc`
+- `v1/resources/svc_default.cfc`
+
+### Что выяснилось после фиксации
+
+После проверки рабочего дерева остались незакоммиченными только:
+- `v1/lib/field.cfm`
+- `v1/lib/filter_build.cfm`
+
+Это не новый смысловой слой, а остаток предыдущего helper-прохода, который не попал во второй коммит из-за ручной выборочной индексации в условиях нестабильного `git commit`.
+
+### Решение на следующий проход
+
+Следующий этап делать так:
+- сохранить эти два helper-файла вместе с новой небольшой порцией resource-файлов
+- не заходить пока в тяжелые и рискованные компоненты вроде `v1/Application.cfc` и `v1/resources/instance.cfc`
+- брать только компактные list-resource, где видно много безопасно удаляемых комментариев и отладочных хвостов
+
+### Следующий практический шаг
+
+- очистить `catalog_service_ls.cfc` и `catalog_service_param_ls.cfc`
+- затем проверить синтаксис измененных файлов
+- после этого собрать третий локальный commit-stage
diff --git a/v1/lib/field.cfm b/v1/lib/field.cfm
index c170012..d9b2dd9 100644
--- a/v1/lib/field.cfm
+++ b/v1/lib/field.cfm
@@ -2,7 +2,7 @@
 <cffunction name="passThrough"	
 	returntype="any" 
 	output="false"
-	hint="just return argument">	
+	hint="Возвращает аргумент без изменений">	
 	<cfargument name="x" type="ANY" required="true"/>
 	<cfreturn #ARGUMENTS.x#/>	
 </cffunction>
@@ -32,7 +32,7 @@
 </cfif>
 
 <cffunction name="getCfSqlType">
-	<!---Translate CF type understandable by isValid to CF_SQL_*--->
+	<!--- Преобразует тип CF, понимаемый isValid, в CF_SQL_* --->
 	<cfargument name="type"/>
 
 		<cfswitch expression=#ARGUMENTS.type#>
diff --git a/v1/lib/filter_build.cfm b/v1/lib/filter_build.cfm
index 1756315..cd6deed 100644
--- a/v1/lib/filter_build.cfm
+++ b/v1/lib/filter_build.cfm
@@ -1,4 +1,4 @@
-<!--- build query filter string --->
+<!--- Формирует строку фильтра для запроса --->
 
 <cfparam name="ATTRIBUTES.filter" type="array"/>
 <cfloop array=#ATTRIBUTES.filter# index="fltr"><!--- неинтуитивный синтаксис, в индексе не индекс массива, а значение --->
@@ -33,7 +33,7 @@
 		 ---><cfcase value="IN"> IN (<cfqueryparam cfsqltype=#getCfSqLType(fltr.ftype)# list=true value="#fltr.val#"/>)<cfcontinue/></cfcase><!--- 
 		 ---><cfdefaultcase> = <cfoutput> #fltr.field#</cfoutput><cfcontinue/><!---***криво---></cfdefaultcase><!--- 
 		 ---></cfswitch><cfqueryparam cfsqltype=#getCfSqLType(fltr.ftype)# value="#fltr.val#"/><cfcontinue/>
-		</cfif><!--- *** ILIKE POSTGRESQL SPECIFIC --->
+		</cfif><!--- ILIKE зависит от PostgreSQL --->
 </cfloop>
 <cfexit method="exittag"/>
 
diff --git a/v1/resources/catalog_service_ls.cfc b/v1/resources/catalog_service_ls.cfc
index 0658a52..c975cc7 100644
--- a/v1/resources/catalog_service_ls.cfc
+++ b/v1/resources/catalog_service_ls.cfc
@@ -2,10 +2,10 @@
 
 	<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>
 
-	<!---спецификация полей, пригодных для фильтрации (?и сортировки)--->
+	<!--- Спецификация полей, пригодных для фильтрации и сортировки --->
 	<cfset this.fieldsSpec={
 		 service_id={prefix="s", type="cf_sql_integer"}
 		,business_line_id={prefix="s", type="cf_sql_integer"}
@@ -45,17 +45,16 @@
 		<cfargument name="orderBy" type="string" hint="type:string, description:comma-separated list of fields to sort by, example:fld1.ASC,fld2.DESC,fld3.ASC" default=""/>
 
 		<cfset var local={}/>
-		<cftry>	<!--- отладка на время проблемы 404 --->	
+		<cftry>
 						
 		
-			<!---parse and validate request parameters--->
+			<!--- Разбор и проверка параметров запроса --->
 			<cftry>
 				<cfset this.helper.validateField(arguments, "pageSize", "integer")/>
 				<cfset this.helper.validateField(arguments, "page", "integer")/>
 				
-				<!---мы мирно игнорируем поля, отсутствующие в спецификации, что позволяет не делать исключения для orderBy и т.п.--->
+				<!--- Поля вне спецификации игнорируются, чтобы не добавлять отдельные исключения для orderBy и похожих параметров. --->
 				<cfset var filter=this.helper.parseFilterParams(this.fieldsSpec)/>
-				<!--- <cfset var order=this.helper.parseOrderBy(this.fieldsSpec, arguments.orderBy)/> --->
 				
 				<cfcatch type="invalidParamValue">
 					<cfreturn representationOf(this.helper.formatBadRequestError(cfcatch)).withStatus(400)/>
@@ -69,8 +68,6 @@
 			<cfset var maxrows=arguments.pageSize*arguments.page/>
 			<cfset var startrow=arguments.pageSize*(arguments.page-1)+1/>
 			
-			<!--- <cfset request.locateIamService()/>  --->		
-			
 			<cfquery name="local.qRead" result="local.result">
 				select 
 				<m:field_set titleMapOut="local.titleMap" lengthOut="local.fieldCount">
@@ -109,10 +106,8 @@
 				, abstract_service
 				, service_id
 				, coalesce(sort,0)
-				<!--- , modifier_id --->					
 				limit #maxrows#
 			</cfquery>
-			<!--- <cfdump var=#local.qRead#/><cfabort/> --->
 			<cfquery name="local.qTotal">
 				select count(*) as cnt
 				from service_catalog.service s		
@@ -152,17 +147,14 @@
 	function plain2htm(s) {
 		return replace(replace(s, chr(13),'',"ALL"),chr(10),'<br/>', "ALL"); 
 	}
-	//request.plain2htm = plain2htm;
 
 	function htm2plain(s) {
 		return replaceNoCase(s, '<br/>', '#chr(13)##chr(10)#', "ALL"); 
 	}
-	//request.htm2plain = htm2plain;
 
 	function cleanHtm(s) {
 		return replaceList(s, '<,>,"', '&lt;,&gt;,&quot;'); 
 	}
-	//request.cleanHtm = cleanHtm;
 	</cfscript>
 	
 	<cffunction name="plain2HtmClean">
diff --git a/v1/resources/catalog_service_param_ls.cfc b/v1/resources/catalog_service_param_ls.cfc
index ac18d18..0a1c249 100644
--- a/v1/resources/catalog_service_param_ls.cfc
+++ b/v1/resources/catalog_service_param_ls.cfc
@@ -2,10 +2,10 @@
 
 	<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>
 
-	<!---спецификация полей, пригодных для фильтрации (?и сортировки)--->
+	<!--- Спецификация полей, пригодных для фильтрации и сортировки --->
 	<cfset this.fieldsSpec={
 		 service_param_id={prefix="p", type="cf_sql_integer"}
 		,service_id={prefix="p", type="cf_sql_integer"}
@@ -40,7 +40,6 @@
 		
 		,service_status_id={prefix="s", type="cf_sql_integer"}
 		,service_status={prefix="s", type="cf_sql_varchar"}
-		<!--- ,measure_short={prefix="s", type="cf_sql_varchar"} --->
 		,sort={prefix="s", type="cf_sql_integer"}
 		,vat_perc={prefix="s", type="cf_sql_integer"}
 		,vat_free={prefix="s", type="cf_sql_bit"}
@@ -59,17 +58,16 @@
 		<cfargument name="orderBy" type="string" hint="type:string, description:comma-separated list of fields to sort by, example:fld1.ASC,fld2.DESC,fld3.ASC" default=""/>
 
 		<cfset var local={}/>
-		<cftry>	<!--- отладка на время проблемы 404 --->	
+		<cftry>
 						
 		
-			<!---parse and validate request parameters--->
+			<!--- Разбор и проверка параметров запроса --->
 			<cftry>
 				<cfset this.helper.validateField(arguments, "pageSize", "integer")/>
 				<cfset this.helper.validateField(arguments, "page", "integer")/>
 				
-				<!---мы мирно игнорируем поля, отсутствующие в спецификации, что позволяет не делать исключения для orderBy и т.п.--->
+				<!--- Поля вне спецификации игнорируются, чтобы не добавлять отдельные исключения для orderBy и похожих параметров. --->
 				<cfset var filter=this.helper.parseFilterParams(this.fieldsSpec)/>
-				<!--- <cfset var order=this.helper.parseOrderBy(this.fieldsSpec, arguments.orderBy)/> --->
 				
 				<cfcatch type="invalidParamValue">
 					<cfreturn representationOf(this.helper.formatBadRequestError(cfcatch)).withStatus(400)/>
@@ -83,8 +81,6 @@
 			<cfset var maxrows=arguments.pageSize*arguments.page/>
 			<cfset var startrow=arguments.pageSize*(arguments.page-1)+1/>
 			
-			<!--- <cfset request.locateIamService()/>  --->		
-			
 			<cfquery name="local.qRead" result="local.result">
 				select 
 				<m:field_set titleMapOut="local.titleMap" lengthOut="local.fieldCount">
@@ -119,10 +115,8 @@
 					<m:field title="service">s.service</m:field>
 					<m:field title="modifier">s.modifier</m:field>
 					<m:field title="modifier_code">s.modifier_code</m:field>
-					<!--- <m:field title="measure_id">s.measure_id</m:field> --->
 					<m:field title="service_status_id">s.service_status_id</m:field>
 					<m:field title="service_status">s.service_status</m:field>
-					<!--- <m:field title="measure_short">s.measure_short</m:field> --->
 					<m:field title="sort">s.sort</m:field>
 					<m:field title="vat_perc">s.vat_perc</m:field>
 					<m:field title="vat_free">s.vat_free</m:field>
@@ -138,10 +132,8 @@
 				, abstract_service
 				, service_id
 				, coalesce(sort,0)
-				<!--- , modifier_id --->					
 				limit #maxrows#
 			</cfquery>
-			<!--- <cfdump var=#local.qRead#/><cfabort/> --->	
 			<cfquery name="local.qTotal">
 				select count(*) as cnt
 				from service_catalog.service_param p
@@ -181,17 +173,14 @@
 	function plain2htm(s) {
 		return replace(replace(s, chr(13),'',"ALL"),chr(10),'<br/>', "ALL"); 
 	}
-	//request.plain2htm = plain2htm;
 
 	function htm2plain(s) {
 		return replaceNoCase(s, '<br/>', '#chr(13)##chr(10)#', "ALL"); 
 	}
-	//request.htm2plain = htm2plain;
 
 	function cleanHtm(s) {
 		return replaceList(s, '<,>,"', '&lt;,&gt;,&quot;'); 
 	}
-	//request.cleanHtm = cleanHtm;
 	</cfscript>
 	
 	<cffunction name="plain2HtmClean">