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. Сводный документ

Сделать:

• собрать оглавление всех файлов с путями
• собрать все итоговые исходники в единый 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 как специальный случай