cleanup: remove legacy headers and commented alternatives

analysis/cleanup-worklog-2026-04-29.md

@@ -0,0 +1,314 @@
+# Рабочий журнал по задаче очистки и компоновки svc-api-x
+
+## Статус
+
+- Дата и время начала журнала: 2026-04-29 20:33:49 +0400
+- Текущая рабочая ветка: `naeel`
+- Репозиторий уже отвязан от исходного origin и перенаправлен в пользовательскую репу
+- Пуш в оригинальный репозиторий не выполняется
+
+## Исходная постановка задачи
+
+Нужно:
+- очистить исходники `deck/svc-api`
+- делать работу по этапам
+- фиксировать каждый этап отдельным коммитом
+- не торопиться и действовать аккуратно
+- в конце собрать оглавление и единый документ со всеми исходниками
+- после выполнения подготовить уточняющие вопросы заказчику
+
+Дополнительное текущее указание:
+- документировать все действия отдельно в папке `analysis`
+- журнал должен показывать понятный ход мыслей и действий
+
+## Что уже сделано до начала основной зачистки
+
+### 1. Проверен git-контекст
+
+Проверено:
+- текущий origin
+- текущая ветка
+- upstream ветки
+- направление push
+- отсутствие submodule
+
+Результат:
+- репозиторий обычный, без подмодулей
+- origin перенастроен на пользовательскую репу
+- создана и запушена рабочая ветка `naeel`
+
+### 2. Проверен размер и состав репозитория
+
+Проверено:
+- общий размер рабочей директории
+- размер `.git`
+- примерный объем данных по файлам
+
+Это было нужно, чтобы понимать масштаб последующей склейки исходников в единый документ.
+
+### 3. Выполнен анализ истории проекта
+
+Созданы отдельные файлы анализа:
+- `analysis/project-history-analysis.md`
+- `analysis/project-history-analysis-careful-2026-04-29.md`
+
+В результате установлено:
+- проект является внутренним backend-сервисом `deck`
+- технологическая база: Lucee + CFML + Taffy + PostgreSQL
+- вендорный framework Taffy хранится внутри репозитория в `v1/taffy`
+- история проекта выглядит как импорт готового внутреннего кода с последующей эволюцией
+
+## Рабочие выводы перед зачисткой
+
+### 1. Задача рискованная
+
+Причины:
+- нужно удалять комментарии и закомментированный код
+- часть комментариев может содержать архитектурный контекст
+- часть файлов может выглядеть неиспользуемой, но реально участвовать в runtime через динамическое подключение или convention-based маршрутизацию Taffy
+- в проекте есть вендорный код framework, backup-файлы и исторические артефакты
+
+### 2. Без уточнений заказчика нужно действовать консервативно
+
+Текущая стратегия по умолчанию:
+- не удалять `cfm/cfc`-файлы автоматически на первом проходе
+- сначала чистить только явно безопасные вещи:
+  - закомментированные фрагменты кода
+  - старые version-header комментарии
+  - комментарии-размышления
+  - английские комментарии, которые можно перевести без потери смысла
+- вендорный Taffy не трогать до отдельного решения
+- список подозрительных на удаление файлов собирать отдельно, но не удалять автоматически без дополнительной уверенности
+
+### 3. Результат лучше собирать в Markdown
+
+Причины:
+- Markdown проще генерировать и поддерживать
+- его легче диффить по коммитам
+- он подходит для последующей конвертации в docx при необходимости
+- для восстановления проекта он лучше, чем непрозрачный бинарный формат Word
+
+## План исполнения
+
+### Этап A. Подготовка рабочего контура
+
+Сделать:
+- зафиксировать рабочую ветку
+- зафиксировать текущее состояние файлов
+- собрать список `cfm/cfc/sql`-файлов
+- отдельно отметить вендорный код и прикладной код
+
+Ожидаемый результат:
+- понятная карта того, что именно можно и нельзя чистить автоматически
+
+### Этап B. Инвентаризация комментариев и закомментированного кода
+
+Сделать:
+- определить типовые паттерны комментариев в `cfm/cfc`
+- выделить:
+  - закомментированный код
+  - комментарии-рассуждения
+  - старые version-history блоки
+  - полезные технические комментарии
+  - английские комментарии, пригодные для перевода
+
+Ожидаемый результат:
+- набор правил для безопасной массовой чистки
+
+### Этап C. Первая безопасная зачистка
+
+Сделать:
+- удалить закомментированные фрагменты кода там, где это однозначно код, а не документация
+- удалить старые version-header комментарии
+- удалить очевидные комментарии в формате внутренних рассуждений
+
+Ожидаемый результат:
+- первый чистовой проход без изменения прикладной логики
+
+### Этап D. Перевод оставшихся комментариев
+
+Сделать:
+- перевести оставшиеся английские комментарии на русский
+- сохранить технический смысл формулировок
+- не добавлять новых рассуждений от себя в код
+
+Ожидаемый результат:
+- единообразный русскоязычный комментарийный слой там, где комментарии реально остаются
+
+### Этап E. Сводный документ
+
+Сделать:
+- собрать оглавление всех файлов с путями
+- собрать все итоговые исходники в единый `md`
+- сохранить структуру так, чтобы проект можно было теоретически восстановить
+
+Ожидаемый результат:
+- единый комплект исходников в одном документе
+
+### Этап F. Коммиты и вопросы заказчику
+
+Сделать:
+- оформить поэтапные локальные коммиты
+- подготовить список вопросов по неоднозначным местам
+- отдельно указать, какие решения были приняты по умолчанию без уточнения заказчика
+
+## Принятые допущения на текущий момент
+
+1. Работу нужно вести в отдельной ветке, а не в `dev`.
+2. Пуш в пользовательскую репу допустим позже, после локальной проверки.
+3. Удаление файлов `cfm/cfc` пока не выполняется автоматически.
+4. Вендорный код `v1/taffy` пока считается отдельным слоем и не чистится без крайней необходимости.
+5. Итоговая сборка будет делаться в `md`, если позже не будет явного требования о `docx`.
+
+## Что сделать следующим шагом
+
+Следующий практический шаг:
+- собрать полный список `cfm`, `cfc`, `sql`-файлов
+- отделить прикладной код от framework/vendor и backup-артефактов
+- начать инвентаризацию комментариев и закомментированного кода
+
+## Примечание
+
+Этот журнал не является скрытым chain-of-thought. Это внешний рабочий лог: решения, допущения, шаги и причины действий, достаточные для понимания хода работы.
+
+## Обновление: первая инвентаризация файлов и комментариев
+
+Дата фиксации: 2026-04-29 20:35:23 +0400.
+
+### Что проверено
+
+- собран список всех `cfc`, `cfm`, `sql`-файлов
+- отдельно замечено, что `git status` в этом окружении периодически подвисает, поэтому для дальнейшей работы лучше опираться на прямой обход файлов и точечные git-команды
+- выполнен поиск по типовым признакам проблемных комментариев и закомментированного кода
+
+### Что найдено по структуре
+
+Слои репозитория сейчас выглядят так:
+
+1. Прикладной код:
+   - `v1/Application.cfc`
+   - `v1/lib/*`
+   - `v1/resources/*`
+   - `health.cfm`
+   - `v1/index.cfm`
+
+2. Явные backup/исторические артефакты:
+   - `v1/etc/bk/*`
+   - `v1/resources/bk/*`
+
+3. Вендорный framework и его примеры/тесты:
+   - `v1/taffy/core/*`
+   - `v1/taffy/bonus/*`
+   - `v1/taffy/dashboard/*`
+   - `v1/taffy/examples/*`
+   - `v1/taffy/tests/*`
+   - `v1/taffy/verify/*`
+
+### Промежуточный вывод
+
+Нельзя делать одну общую массовую чистку по всем `cfc/cfm` подряд.
+
+Причины:
+- внутри репозитория есть собственный код и внешний Taffy
+- есть backup-каталоги, которые могут быть кандидатами на удаление, но это уже отдельный шаг и отдельный риск
+- часть английских комментариев относится к Taffy и их перевод без отдельного решения заказчика может быть ошибкой
+
+### Первые hotspot-файлы по комментариям
+
+Наиболее насыщенные неоднозначными комментариями и закомментированными фрагментами:
+
+- `v1/Application.cfc`
+  - очень много рассуждений, временных пояснений, костылей, TODO и закомментированных блоков
+  - смешение русского и английского
+  - есть куски, унаследованные или переписанные из Taffy
+
+- `v1/lib/field_set.cfm`
+  - большой header с version-history
+  - технические пояснения и опасения автора по реализации
+
+- `v1/lib/filter_build.cfm`
+  - version-history в начале
+  - плотный инлайновый комментарийный слой
+  - есть фрагменты в стиле “закомментированная логика в потоке шаблона”
+
+- `v1/lib/rest_api_helper.cfc`
+  - version-history в начале
+  - смешанные русско-английские комментарии по поведению API и фильтрации
+
+- `v1/resources/svc_default.cfc`
+  - рассуждения по зависимости и закомментированные альтернативные строки
+
+### Рабочее решение после первой инвентаризации
+
+1. Вендорный `v1/taffy` пока не чистить.
+2. Backup-каталоги пока не удалять автоматически.
+3. Первый реальный этап чистки делать только по прикладному слою:
+   - `v1/Application.cfc`
+   - `v1/lib/*`
+   - `v1/resources/*`
+   - за исключением `v1/resources/bk/*`
+4. Перед массовыми правками создать отдельную cleanup-ветку.
+
+### Следующий шаг
+
+- создать отдельную ветку под зачистку
+- собрать более узкую выборку только по прикладным `v1/lib` и `v1/resources`
+- начать безопасную зачистку с наиболее очевидных header-version комментариев и закомментированных фрагментов
+
+## Обновление: выделена отдельная cleanup-ветка и выполнен первый безопасный проход
+
+Дата фиксации: 2026-04-29 20:39:57 +0400.
+
+### Ветка
+
+Создана отдельная рабочая ветка:
+- `cleanup/svc-api-package`
+
+Смысл:
+- история аналитики отделена от истории самой зачистки
+- дальше можно делать поэтапные коммиты именно под задачу заказчика
+
+### Что сделано на первом проходе
+
+Первый проход был намеренно консервативным. Убраны только:
+- старые version-history комментарии в начале файлов
+- явные закомментированные альтернативные строки и блоки, не влияющие на текущую логику
+
+Изменены файлы:
+- `v1/lib/field_set.cfm`
+- `v1/lib/filter_build.cfm`
+- `v1/resources/svc_default.cfc`
+- `v1/lib/rest_api_helper.cfc`
+- `v1/lib/field.cfm`
+- `v1/lib/order_build.cfm`
+
+### Что сознательно не трогалось на этом этапе
+
+- `v1/Application.cfc`
+  - файл большой и содержит смесь прикладной логики, Taffy-override и спорных комментариев
+
+- крупные `v1/resources/*.cfc`
+  - сначала нужен более точный проход по типам комментариев
+
+- `v1/taffy/*`
+  - vendor layer
+
+- backup-каталоги
+  - `v1/etc/bk/*`
+  - `v1/resources/bk/*`
+
+### Проверка
+
+После правок проверены измененные файлы на ошибки.
+Результат:
+- синтаксических ошибок в этих шести файлах не обнаружено
+
+### Вывод по этапу
+
+Подход с малыми безопасными правками подтвержден: можно убирать исторические version-header блоки и закомментированные альтернативы без риска немедленно сломать синтаксис.
+
+### Следующий шаг
+
+- сделать второй проход по прикладным файлам
+- удалить комментарии в формате рассуждений там, где они явно не нужны для понимания текущей логики
+- отдельно обработать `v1/Application.cfc` как специальный случай

v1/lib/field.cfm

@@ -1,11 +1,4 @@
 <cfsilent>
-<!--- 20181209 v0.3 --->
-<!---v0.3 добавлен атрибут cfSqlType--->
-<!---v0.4 добавлен атрибут container for json---> 
-<!---v0.5 добавлен атрибут type и трансляция в CF_SQL_---> 
-<!--- 20210326 v0.8 formatter --->	
-<!--- 20260312 v0.9 type="list" added as workaround--->	
-
 <cffunction name="passThrough"	
 	returntype="any" 
 	output="false"

v1/lib/field_set.cfm

@@ -1,11 +1,4 @@
 <cfsilent></cfsilent>
-<!--- 20181209 v0.3 добавлено поле cfSqlType--->
-<!--- 20201029 v0.5  все атрибуты необязательные--->
-<!--- 20201114 v0.6 добавлен атрибут "container" for json--->
-<!--- 20201201 v0.7 исправлен listOut--->
-<!--- 20210326 v0.8 formatter --->
-<!--- 20210326 v0.9 listOutKeepContent --->
-<!--- 20210326 v0.10 listOutKeepContent, listOut, nameListOut fixes --->
 <!--- Используется в селекте для структурирования списка полей. Выводит вместо себя список через запятую, экспортирует Map со структурами выражение+заголовок, с ключом, соответствующим имени колонки в селекте (ключ вычисляется регулярным выражением)  --->
 
 	<cfset var local={}/> <!--- *** есть опасения, что это не будет работать в модуле .cfm (вообще var ведет себе странно) --->
@@ -59,11 +52,6 @@
 			<cfset "CALLER.#ATTRIBUTES.nameListOut#"=#local.nameList#/>
 		</cfif>
 		
-		<!--- <cfif len(ATTRIBUTES.listOut)>
-			<cfset "CALLER.#ATTRIBUTES.listOut#"=preserveSingleQuotes(list)/>
-			<cfset thisTag.generatedContent=""/>
-		</cfif> --->
-		
 		<cfif len(ATTRIBUTES.listOut)><!--- *** некрасиво --->
 			<cfset "CALLER.#ATTRIBUTES.listOut#"=local.expressionList/>
 			<cfif ATTRIBUTES.listOutKeepContent>

v1/lib/filter_build.cfm

@@ -1,15 +1,8 @@
-<!--- version 2.01---><!---15:25 31.01.2019--->
-<!--- version 3---><!---16:42 16.11.2020--->
-<!--- version 4---><!---2025-09-06 19:15:50 больше не нужно объявлять параметр как list, достаточно оператора IN--->
-<!--- version 5---><!---2025-11-20 ILIKE - потеря совместимости со стандартным SQL (можно вернуться к совместимости через lower, но будут проблемы с индексами)--->
-<!--- version 6---><!---2025-11-20 ***** фильтр стал массивом вместо структуры, чтобы поддержать множественные вхождения поля --->
-
 <!--- build query filter string --->
 
 <cfparam name="ATTRIBUTES.filter" type="array"/>
 <cfloop array=#ATTRIBUTES.filter# index="fltr"><!--- неинтуитивный синтаксис, в индексе не индекс массива, а значение --->
 	<cfsilent>
-		<!--- <cfset fltr=structFind(ATTRIBUTES.filter,item)>	 --->	
 		<cfparam name="fltr.ftype"/>	
 		<cfparam name="fltr.field"/>
 		<cfparam name="fltr.compare" default="EQ"/> 

v1/lib/order_build.cfm

@@ -1,9 +1,5 @@
 <cfsilent>
 <!--- build query sort string --->
-<!---v2 11:21 16.11.2020--->
-<!---v3 14:15 16.11.2020 input struct instead of array--->
-<!---v4 2024-10-15 input ANY--->
-<!---v5 2024-12-23 default order --->
 
 	<cfparam name="ATTRIBUTES.sortCollection" type="any">
 	<cfparam name="ATTRIBUTES.fieldCount" type="integer" default=0>

v1/lib/rest_api_helper.cfc

@@ -2,13 +2,6 @@
     displayname="ReST API helper"
     output="true"
     hint="Static helper methods for ReST API">
-	<!--- v0.02 2024-10-15 --->
-	<!--- v0.03 2024-11-27 --->
-	<!--- v0.04 2025-11-20 columns--->
-	<!--- v0.05 2025-11-20 multiple field entries in filter, filter became array instead of structure--->	
-	<!--- v0.06 2025-11-22 custom url parser used to prevent comma collision in lists--->	
-	<!--- v0.06 2026-01-22 json-type field validation (isValidX)--->	
-	<!--- v0.06 2026-03-12 empty2null off--->	
 	
 <cffunction name="empty2null" 
 	access="public" 
@@ -71,14 +64,7 @@
 		</cfif>
 		
 		<cfif queryColumnExists(ARGUMENTS.query, local.col)>
-			
-			<!--- <cfif type EQ "list"> --->
-				<!--- *** workaround for empty lists - keep them empty strings or arrays instead of null - should designate field type as list --->
-				<!--- *** правда, для CFS параметров это не работает - тип поля может меняться в зависимости от условий --->
-				<!--- <cfset obj[ARGUMENTS.fieldNameDecorator(local.col)]=formatter(ARGUMENTS.query[local.col][ARGUMENTS.query.currentRow])/>
-			<cfelse> --->
-				<cfset obj[ARGUMENTS.fieldNameDecorator(local.col)]=empty2null(formatter(ARGUMENTS.query[local.col][ARGUMENTS.query.currentRow]))/>
-<!--- 			</cfif> --->
+			<cfset obj[ARGUMENTS.fieldNameDecorator(local.col)]=empty2null(formatter(ARGUMENTS.query[local.col][ARGUMENTS.query.currentRow]))/>
 			<!--- *** преобразование пустой строки в null преобразует в нулл также пустые списки, что искажает факт --->
 		</cfif>
 		<!---*** не уверен в надежности конструкции во всех реализациях CF, контекст query передастся ли--->

v1/resources/svc_default.cfc

@@ -7,7 +7,6 @@
 
 	<cffunction name="get" hint="DEPRECATED. Шаблон экземпляра"><!--- *** TODO проверка принадлежности тенанту --->
 		<cfargument name="svcId" type="string" required=true hint="type:integer"/>
-		<!--- <cfargument name="usrId" type="string" /> ---><!--- arguments.usrId неявно инжектируется из Application.cfm --->
 	
 		<cftry>
 			<cfset this.helper.validateField(arguments, "svcId", "integer")/>			
@@ -23,8 +22,6 @@
 		}/>
 		
 		<cfset var out = structNew("linked")/>
-
-		<!--- <cfset var out = structCopy(svc)/> ---><!--- *** иначе, видимо, циклическая ссылка, если мы еще скопируем это внутрь структуры --->
 		
 		<cfset "out.service" = svc/>