diff --git a/analysis/cleanup-worklog-2026-04-29.md b/analysis/cleanup-worklog-2026-04-29.md new file mode 100644 index 0000000..c19b9ee --- /dev/null +++ b/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` как специальный случай diff --git a/v1/lib/field.cfm b/v1/lib/field.cfm index b999548..c170012 100644 --- a/v1/lib/field.cfm +++ b/v1/lib/field.cfm @@ -1,11 +1,4 @@  - - - - - - - - - - - - - - @@ -59,11 +52,6 @@ - - diff --git a/v1/lib/filter_build.cfm b/v1/lib/filter_build.cfm index f2cb4ab..1756315 100644 --- a/v1/lib/filter_build.cfm +++ b/v1/lib/filter_build.cfm @@ -1,15 +1,8 @@ - - - - - - - diff --git a/v1/lib/order_build.cfm b/v1/lib/order_build.cfm index b3efd8b..7d95daa 100644 --- a/v1/lib/order_build.cfm +++ b/v1/lib/order_build.cfm @@ -1,9 +1,5 @@ - - - - diff --git a/v1/lib/rest_api_helper.cfc b/v1/lib/rest_api_helper.cfc index 517f713..d9f2446 100644 --- a/v1/lib/rest_api_helper.cfc +++ b/v1/lib/rest_api_helper.cfc @@ -2,13 +2,6 @@ displayname="ReST API helper" output="true" hint="Static helper methods for ReST API"> - - - - - - - - - - - - - - + diff --git a/v1/resources/svc_default.cfc b/v1/resources/svc_default.cfc index 5952d0c..1845324 100644 --- a/v1/resources/svc_default.cfc +++ b/v1/resources/svc_default.cfc @@ -7,7 +7,6 @@ - @@ -23,8 +22,6 @@ }/> - -