svc-api-x/analysis/cleanup-worklog-2026-04-29.md

Рабочий журнал по задаче очистки и компоновки 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. Дочистка явных хвостов

Сделать:

• удалить закомментированный onRequest и старые Taffy-заготовки из v1/Application.cfc
• убрать остатки debug-комментариев и лишних пояснений из v1/resources/instance_operation_run.cfc
• перепроверить, что логика не изменилась

Ожидаемый результат:

• source-файлы без явного мусора и без затронутого runtime

Этап E. Сводный документ

Сделать:

• собрать оглавление всех файлов с путями
• собрать все итоговые исходники в единый md
• сохранить структуру так, чтобы проект можно было теоретически восстановить

Ожидаемый результат:

• единый комплект исходников в одном документе

Этап F. Коммиты и вопросы заказчику

Сделать:

• оформить поэтапные локальные коммиты
• подготовить список вопросов по неоднозначным местам
• отдельно указать, какие решения были приняты по умолчанию без уточнения заказчика

Этап G. Дочистка remaining source-файлов

Сделать:

• убрать декоративные и старые комментарии из оставшихся прикладных v1/* файлов
• отдельно дочистить v1/Application.cfc от закомментированного кода и явного мусора
• проверить, что git diff --check остаётся чистым

Ожидаемый результат:

• текущий набор source-файлов без явных comment-hash остатков и без сломанной логики

Результат:

• большая часть remaining source-файлов очищена от декоративных комментариев
• v1/Application.cfc очищен от закомментированного кода и старых debug-хвостов
• git diff --check после правок остаётся чистым

Принятые допущения на текущий момент

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 как специальный случай

Обновление: второй проход по комментариям-рассуждениям

Дата фиксации: 2026-04-29 20:45:13 +0400.

Что сделано

Во втором проходе очищались не version-header блоки, а именно комментарии в стиле внутренних сомнений, оценок и рассуждений автора.

Обработаны файлы:

• v1/lib/field_set.cfm
• v1/lib/order_build.cfm
• v1/resources/svc_default.cfc
• v1/lib/rest_api_helper.cfc

Удалялись в первую очередь такие типы комментариев:

• сомнения автора в корректности подхода
• эмоциональные оценки вроде "некрасиво"
• внутренние заметки вида "не уверен", "не нравится", "странно"
• краткие следы от отладочных/временных рассуждений

Что не удалялось

• технические комментарии, поясняющие назначение параметров и смысл структуры данных
• комментарии, нужные для понимания формата вызова или ограничений API
• комментарии, которые пока относятся к будущему этапу перевода, а не удаления

Проверка

После второго прохода измененные файлы проверены на ошибки. Результат:

• синтаксических ошибок не обнаружено

Промежуточный вывод

Эта стратегия работает лучше, чем агрессивная массовая чистка: можно постепенно отделять лишние авторские рассуждения от реально полезных технических пояснений.

Следующий шаг

• перевести оставшиеся английские комментарии в уже обработанных небольших файлах
• отдельно обработать v1/lib/TokenGenerator.cfc, где комментарии почти полностью англоязычные
• затем перейти к следующей группе прикладных файлов

Обновление: дополнительные commented-out блоки и перевод комментариев

Дата фиксации: 2026-04-29 20:48:58 +0400.

Что сделано перед переводом

Перед этапом перевода был выполнен еще один безопасный шаг:

• удалены крупные закомментированные legacy-блоки в v1/lib/rest_api_helper.cfc
• удален закомментированный альтернативный блок base64url-преобразования в v1/lib/TokenGenerator.cfc

Причина:

• переводить комментарии вокруг уже неиспользуемого мертвого кода не имеет смысла
• сначала убирается то, что точно не участвует в runtime

Что переведено на русский

Перевод выполнен в следующих файлах:

• v1/lib/TokenGenerator.cfc
• v1/lib/field.cfm
• v1/lib/order_build.cfm
• v1/lib/filter_build.cfm
• v1/lib/rest_api_helper.cfc

Переводились:

• hint-описания функций и компонентов
• английские технические комментарии
• внутренние пояснения о поведении генератора токенов и helper-логики

Что сознательно не переводилось:

• runtime-сообщения ошибок и исключений
• публичные текстовые значения, которые могут участвовать в API-контракте

Проверка

После удаления закомментированных блоков и после перевода комментариев проверены измененные файлы. Результат:

• синтаксических ошибок не обнаружено

Промежуточный вывод

На этом этапе уже очищен и приведен к более однородному виду значимый кусок вспомогательного слоя v1/lib. Это хорошая база перед переходом к более рискованным файлам уровня Application.cfc и крупных resources/*.cfc.

Следующий шаг

• посмотреть текущее 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

Обновление: выбран следующий безопасный мини-этап

Дата фиксации: 2026-04-29.

Что планируется сделать

На следующем проходе берется очень маленькая и контролируемая группа resource-файлов:

• v1/resources/resource_realm_type_ls.cfc
• v1/resources/bookmark.cfc

Цель прохода:

• убрать только очевидный закомментированный мертвый код и debug-хвосты
• убрать комментарии в формате внутренних рассуждений, если они не нужны текущей логике
• не менять SQL-логику, контракт ресурса и структуру аргументов

Почему выбраны именно они

• оба файла компактнее крупных instance* и operation* ресурсов
• в них уже видны локальные и низкорисковые cleanup-кандидаты
• правки можно сделать без захода в архитектурно спорные области

Что сознательно не входит в этот этап

• v1/Application.cfc
• крупные instance* и svc_operation* ресурсы
• vendor-слой v1/taffy
• автоматическое удаление файлов

Результат этапа

Выполнен точечный cleanup в двух компактных resource-файлах:

• v1/resources/resource_realm_type_ls.cfc
• v1/resources/bookmark.cfc

Что именно убрано:

• закомментированные debug-возвраты и cfdump-хвосты
• закомментированные неиспользуемые строки вроде старого request.locateIamService()
• комментарии в формате внутренних рассуждений рядом с helper-инициализацией
• неиспользуемые закомментированные SQL/field-фрагменты
• закомментированный legacy-блок с проверкой qSave.cnt

Что сознательно оставлено:

• действующая SQL-логика ресурсов
• текущая структура аргументов и hint
• комментарии, которые еще можно отдельно разобрать на этапе перевода или дальнейшей локальной чистки

Проверка

Измененные файлы проверены на ошибки. Результат:

• синтаксических ошибок в v1/resources/resource_realm_type_ls.cfc не обнаружено
• синтаксических ошибок в v1/resources/bookmark.cfc не обнаружено

Вывод

Подтверждается, что после helper-слоя можно безопасно продолжать малыми проходами по компактным resources/*.cfc, если ограничиваться только явным dead-code и debug-comment слоем.

Следующий шаг

• посмотреть рабочее дерево после этого мини-этапа
• при необходимости взять еще 1-2 похожих компактных resource-файла
• затем собрать следующий локальный cleanup-коммит без смешения с рискованными файлами

Обновление: зафиксирован локальный коммит по компактным resource-файлам

Дата фиксации: 2026-04-29.

Коммит

Создан локальный коммит:

• 81b8fee
• сообщение: cleanup: trim small resource debug comments

В него вошли:

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

Обновление: убран следующий слой dead-code и debug-комментариев в operation-ресурсах

Дата фиксации: 2026-04-29.

Что планируется сделать

Следующий проход выполняется по двум прикладным ресурсам среднего риска:

• v1/resources/instance_operation.cfc
• v1/resources/svc_operation_cfs_param_compute.cfc

Цель этапа:

• убрать закомментированные SQL-поля и старые альтернативные ветки
• убрать debug-хвосты с cfdump/cfabort
• убрать длинные комментарии-рассуждения и sample-блоки, не влияющие на runtime
• не менять контракт ресурсов и действующую вычислительную логику

Результат этапа

Выполнено:

• в instance_operation.cfc убраны закомментированные поля, join/where-хвосты, комментарии-размышления и отладочный abort при ошибке десериализации состояния
• в instance_operation.cfc сохранена рабочая логика, а при сбое десериализации оставлен безопасный пустой currentState
• в svc_operation_cfs_param_compute.cfc удалены длинные вводные рассуждения, мертвые альтернативные ветки, устаревшие sample URL и служебные комментарии

Проверка

После правок оба файла нужно проверить на синтаксические ошибки и затем зафиксировать отдельным локальным коммитом.

Результат проверки:

• синтаксических ошибок в v1/resources/instance_operation.cfc не обнаружено
• синтаксических ошибок в v1/resources/svc_operation_cfs_param_compute.cfc не обнаружено

Обновление: cleanup helper-парсера и API helper

Дата фиксации: 2026-04-29.

Что планируется сделать

Следующий этап переносится на helper-слой:

• v1/lib/rest_api_helper.cfc
• v1/lib/expression_parser.cfc

Цель:

• убрать длинные блоки рассуждений и временные пояснения разработки
• удалить мёртвые закомментированные фрагменты и служебные следы отладки
• оставить только рабочую логику и короткие runtime-описания через hint, не меняя поведение методов

Результат этапа

Выполнено:

• в v1/lib/rest_api_helper.cfc убраны служебные и устаревшие комментарии внутри helper-методов
• в v1/lib/expression_parser.cfc удалены длинные блоки рассуждений о контексте, временные заметки и закомментированные debug-хвосты

Проверка

Результат проверки:

• синтаксических ошибок в v1/lib/rest_api_helper.cfc не обнаружено
• синтаксических ошибок в v1/lib/expression_parser.cfc не обнаружено

Обновление: начат консервативный проход по неиспользуемым CFML-файлам

Дата фиксации: 2026-04-29.

Что проверено

• состав каталогов v1/resources/bk и v1/etc/bk
• наличие явных backup-сериализаторов в v1/resources/bk
• отсутствие необходимости затрагивать vendor-слой v1/taffy

Решение по этому этапу

Сразу удаляется только узкий набор файлов с высокой уверенностью, которые являются backup-артефактами и не участвуют в текущем runtime:

• v1/resources/bk/JSONUtil.cfc
• v1/resources/bk/JsonBNSerializer.cfc
• v1/resources/bk/JsonSerializer.cfc
• v1/resources/bk/JsonUtilSerializer.cfc

Каталог v1/etc/bk на этом этапе не затрагивается, потому что для его файлов нужна отдельная проверка по назначению и ссылкам.

Обновление: минимальный cleanup-проход по Application.cfc

Дата фиксации: 2026-04-29.

Границы этапа

В этом проходе затрагивается только безопасный comment/debug-слой:

• верхние исторические и объяснительные блоки
• закомментированные настройки и альтернативы, не влияющие на текущий runtime
• служебные комментарии вокруг bootstrap и locateIamService

Что сознательно не трогается:

• основной control flow onTaffyRequest
• override-логика Taffy в onRequest
• тексты ошибок и поведение авторизации

Проверка

Результат проверки:

• синтаксических ошибок в v1/Application.cfc не обнаружено

Обновление: собраны итоговые markdown-артефакты

Дата фиксации: 2026-04-29.

Что собрано

Сначала были созданы два итоговых файла в analysis, затем они вынесены в отдельную корневую папку results:

• results/source-toc-2026-04-29.md
• results/source-bundle-2026-04-29.md

Принятый состав bundle

В единый markdown включен только прикладной слой проекта:

• health.cfm
• v1/Application.cfc
• v1/index.cfm
• v1/lib/*
• v1/resources/* без v1/resources/bk/*

Что сознательно исключено:

• v1/taffy/* как vendor framework, его примеры и тесты
• удаленные backup-сериализаторы из v1/resources/bk/*
• оставшийся v1/etc/bk/*, который пока выделен как backup-слой вне основного bundle

Результат

• оглавление собрано отдельным компактным файлом
• единый markdown-бандл собран по актуальному прикладному CFML-слою после cleanup

Обновление: дочищен backup-слой etc/bk

Дата фиксации: 2026-04-29.

Что сделано

После сборки итоговых артефактов удалены еще два backup-CFC из v1/etc/bk:

• v1/etc/bk/login.cfc
• v1/etc/bk/user.cfc

Основание:

• каталог bk используется как backup-слой
• файлы не входят в основной прикладной bundle
• удаление не затрагивает текущий runtime-маршрут и основной слой v1/resources/*

Следующий мини-этап

Для следующего такого же безопасного прохода выбраны:

• v1/resources/param_value_list.cfc
• v1/resources/resource_realm_ls.cfc

План по этапу:

• убрать закомментированные debug-строки и мертвые фрагменты
• убрать комментарии-рассуждения рядом с helper-инициализацией
• не менять запросы, условия доступа и runtime-поведение

Результат этапа

Выполнен еще один точечный cleanup-проход по двум ресурсам:

• v1/resources/param_value_list.cfc
• v1/resources/resource_realm_ls.cfc

Что убрано:

• комментарии-рассуждения рядом с созданием helper-компонента
• закомментированные debug-возвраты и старые временные строки
• неиспользуемые закомментированные фрагменты, не влияющие на runtime

Что не менялось:

• текст запросов
• проверка входных параметров по существующей логике
• условия доступа и структура ответа

Проверка

Измененные файлы проверены на ошибки. Результат:

• синтаксических ошибок в v1/resources/param_value_list.cfc не обнаружено
• синтаксических ошибок в v1/resources/resource_realm_ls.cfc не обнаружено

Вывод

Паттерн повторяется: в небольших list-resource можно безопасно удалять слой исторических и отладочных комментариев отдельными локальными коммитами без вмешательства в бизнес-логику.

Обновление: выбран следующий mini-cleanup проход

Дата фиксации: 2026-04-29.

Выбранные файлы

• v1/resources/available_resource_realms.cfc
• v1/resources/bookmark_ls.cfc

Что планируется убрать

• закомментированные debug-возвраты и cfdump-хвосты
• старые временные комментарии рядом с cftry и helper-инициализацией
• закомментированные неиспользуемые строки и хвосты в cfscript

Что в этот этап не входит

• изменение SQL-логики
• пересмотр бизнес-ограничений по contragent_id
• правка спорных комментариев, которые еще могут нести смысл бизнес-правил

Результат этапа

Выполнен cleanup-проход по двум следующим ресурсам:

• v1/resources/available_resource_realms.cfc
• v1/resources/bookmark_ls.cfc

Что убрано:

• комментарии-рассуждения рядом с helper-инициализацией
• закомментированные debug-возвраты и cfdump-хвосты
• закомментированные неиспользуемые строки и временные следы в cfscript
• старые закомментированные альтернативы сортировки и выборки полей

Что оставлено специально:

• рабочая SQL-логика
• комментарий про общую букмарку, так как он still поясняет текущее бизнес-правило
• структура ответа и набор аргументов

Проверка

Измененные файлы проверены на ошибки. Результат:

• синтаксических ошибок в v1/resources/available_resource_realms.cfc не обнаружено
• синтаксических ошибок в v1/resources/bookmark_ls.cfc не обнаружено

Вывод

Даже в чуть более длинных list-resource по-прежнему удается безопасно снимать debug/comment слой малыми независимыми коммитами, если не заходить в спорные бизнес-комментарии и не трогать логику запросов.

Обновление: выбран следующий cleanup-проход

Дата фиксации: 2026-04-29.

Выбранные файлы

• v1/resources/catalog_service_ls.cfc
• v1/resources/resource_realm.cfc

Границы этапа

• убрать только debug-комментарии, временные следы и комментарии-рассуждения
• не менять SQL-запросы и фильтрацию
• не превращать этап в bugfix или рефакторинг

Результат этапа

Выполнен еще один узкий cleanup-проход:

• v1/resources/catalog_service_ls.cfc
• v1/resources/resource_realm.cfc

Что убрано:

• нерелевантный комментарий-копипаста в catalog_service_ls.cfc
• TODO/рассуждение и закомментированный cfdump в resource_realm.cfc

Что не менялось:

• SQL-запросы
• состав полей ответа
• поведение ошибок и фильтрация

Проверка

Измененные файлы проверены на ошибки. Результат:

• синтаксических ошибок в v1/resources/catalog_service_ls.cfc не обнаружено
• синтаксических ошибок в v1/resources/resource_realm.cfc не обнаружено

Обновление: выбран cleanup-проход по compute/list слою

Дата фиксации: 2026-04-29.

Выбранные файлы

• v1/resources/svc_operation_cfs_subparam_compute.cfc
• v1/resources/instance_operation_ls.cfc

Ограничения этапа

• убирать только закомментированные debug-хвосты и комментарии-рассуждения
• не менять активную обработку ошибок и не исправлять живые runtime-аномалии
• не заходить глубоко в post и крупные блоки бизнес-логики

Результат этапа

Выполнен cleanup-проход по compute/list слою:

• v1/resources/svc_operation_cfs_subparam_compute.cfc
• v1/resources/instance_operation_ls.cfc

Что убрано:

• комментарии-рассуждения рядом с helper-инициализацией
• закомментированные cfdump/cfabort хвосты
• старые закомментированные debug-строки валидации и SQL-вывода

Что сознательно не трогалось:

• активные cfcatch и текущее поведение ошибок
• крупные блоки post
• спорные бизнес-комментарии вне явного debug-слоя

Проверка

Измененные файлы проверены на ошибки. Результат:

• синтаксических ошибок в v1/resources/svc_operation_cfs_subparam_compute.cfc не обнаружено
• синтаксических ошибок в v1/resources/instance_operation_ls.cfc не обнаружено

Обновление: выбран cleanup-проход по default-ресурсам

Дата фиксации: 2026-04-29.

Выбранные файлы

• v1/resources/instance_default.cfc
• v1/resources/svc_default.cfc
• v1/resources/instance_operation_default.cfc

Ограничения этапа

• убирать только закомментированные аргументы, TODO-заметки, явные debug-хвосты и комментарии-рассуждения
• не править живые участки, где cleanup уже превращается в bugfix
• не менять формирование value_list, default_value и остальную логику шаблонов

Результат этапа

Выполнен cleanup-проход по default-ресурсам:

• v1/resources/instance_default.cfc
• v1/resources/svc_default.cfc
• v1/resources/instance_operation_default.cfc

Что убрано:

• старые TODO/рассуждения в заголовках методов
• закомментированные неиспользуемые аргументы и debug-хвосты
• часть локальных закомментированных альтернатив, не влияющих на текущий runtime

Что сознательно не трогалось:

• живой cfdump/cfabort в обработке ошибки instance_operation_default.cfc
• логика генерации value_list, nested_ref_data и default_value

Проверка

Измененные файлы проверены на ошибки. Результат:

• синтаксических ошибок в v1/resources/instance_default.cfc не обнаружено
• синтаксических ошибок в v1/resources/svc_default.cfc не обнаружено
• синтаксических ошибок в v1/resources/instance_operation_default.cfc не обнаружено

Обновление: выбран bugfix-adjacent этап по debug-артефактам

Дата фиксации: 2026-04-29.

Выбранные файлы

• v1/resources/notification_ls.cfc
• v1/resources/instance_operation_default.cfc

Цель этапа

• убрать живые debug-артефакты, которые сейчас влияют на поведение ресурса
• сохранить общий контракт ответов и не трогать остальную бизнес-логику
• оформить это отдельным коммитом, а не смешивать с чисто косметическим cleanup

Обновление: правило по спорным смысловым комментариям

Дата фиксации: 2026-04-29.

Уточнена трактовка исходного задания.

Решение на дальнейшую работу:

• явный закомментированный код, debug-хвосты и комментарии-рассуждения удалять
• спорные смысловые комментарии, где неочевидно, имелась ли в виду их обязательная зачистка, пока оставлять в коде
• не добавлять в исходники новые пометки вида TODO удалить потом, чтобы не создавать новый мусор
• вести отдельный внешний список кандидатов на удаление в analysis/comment-removal-candidates-2026-04-29.md

Это позволяет не терять спорные места и при этом не засорять исходники новыми временными комментариями.

Результат bugfix-adjacent этапа

Изменены файлы:

• v1/resources/notification_ls.cfc
• v1/resources/instance_operation_default.cfc

Что сделано:

• удален живой тестовый возврат Проверка связи 3 из ветки invalidParamValue в notification_ls.cfc
• убран сопутствующий закомментированный debug-слой вокруг этого ресурса
• в instance_operation_default.cfc удален cfdump/cfabort при ошибке десериализации стейта
• вместо аварийного останова оставлен безопасный fallback на пустые структуры

Дополнительно:

• создан внешний список спорных смысловых комментариев: analysis/comment-removal-candidates-2026-04-29.md

Проверка

Измененные файлы проверены на ошибки. Результат:

• синтаксических ошибок в v1/resources/notification_ls.cfc не обнаружено
• синтаксических ошибок в v1/resources/instance_operation_default.cfc не обнаружено

Обновление: выбран cleanup-проход по instance_operation_cfs_param_ls.cfc

Дата фиксации: 2026-04-29.

Цель этапа

• снять с большого файла верхний слой явных рассуждений и закомментированного кода
• не вычищать насильно все технические пояснения за один проход
• спорные смысловые комментарии при необходимости оставлять и учитывать через внешний список кандидатов

Результат этапа

В v1/resources/instance_operation_cfs_param_ls.cfc удалены:

• большой верхний блок авторских рассуждений про URI и контекст
• закомментированные альтернативные поля и отладочные хвосты
• часть комментариев-оценок вокруг helper-вызовов, уникальности и временных веток
• закомментированные catch/debug-блоки, не участвующие в runtime

Что оставлено:

• технические комментарии, которые все еще объясняют ограничения валидации и semantics параметров
• спорные пояснения, которые могут быть полезны при дальнейшей разборке файла

Проверка

Измененный файл проверен на ошибки. Результат:

• синтаксических ошибок в 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 не обнаружено