# Рабочий журнал по задаче очистки и компоновки 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` как специальный случай