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