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