887 lines
47 KiB
Markdown
887 lines
47 KiB
Markdown
# Рабочий журнал по задаче очистки и компоновки 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` как специальный случай
|
||
|
||
## Обновление: второй проход по комментариям-рассуждениям
|
||
|
||
Дата фиксации: 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` не обнаружено
|
||
|
||
### Следующий мини-этап
|
||
|
||
Для следующего такого же безопасного прохода выбраны:
|
||
- `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` не обнаружено
|