docs: add analysis handoff and project notes

2026-04-29 22:30:22 +04:00
parent 783c985d51
commit 712e6769af
4 changed files with 715 additions and 0 deletions
@@ -0,0 +1,137 @@
 # Handoff для нового чата
 Работаем с локальной копией репозитория, НЕ с mounted-папкой на VM. Предыдущая сессия шла в sshfs-монте, из-за этого были зависания git write-tree, git diff --name-only и периодическая рассинхронизация. В новой сессии нужно продолжать только в обычной локальной папке на диске.
 ## Задача
 - аккуратно очистить исходники svc-api-x по этапам
 - каждый этап фиксировать отдельным локальным коммитом
 - не пушить
 - документировать ВСЁ отдельно в папке analysis
 - не спешить, действовать консервативно
 - в конце собрать оглавление файлов и единый markdown-документ со всеми исходниками
 - после выполнения подготовить вопросы заказчику по неоднозначным местам
 ## Очень важно
 - если переносишь репу локально, нужно переносить всю репу вместе с .git, чтобы сохранить уже сделанные локальные коммиты и ветку cleanup/svc-api-package
 - если это уже новая локальная копия, сначала проверь, что история и ветка сохранились
 - не удалять файлы автоматически без высокой уверенности
 - не трогать vendor-слой Taffy на ранних этапах
 - не лезть сразу в большие рискованные файлы вроде Application.cfc и instance.cfc без отдельного аккуратного прохода
 - продолжать документирование в analysis
 ## Текущее состояние ветки и коммитов
 - рабочая ветка: cleanup/svc-api-package
 - текущий HEAD: 44daae628d24502730745a94f2f3665474f22c4a
 - ранее были созданы локальные cleanup-коммиты через git plumbing, потому что обычный git commit и часть git-команд подвисали на mounted-репе
 ### Известные cleanup-коммиты
 - f6d5c868cb54b87c1daffdeda95689a5f121ca8f
  - message: cleanup: remove legacy headers and commented alternatives
 - 7b98eee156c3251bdd37a4d22d3596ba671a447c
  - message: cleanup: remove reasoning comments and translate helper docs
 - 44daae628d24502730745a94f2f3665474f22c4a
  - message: cleanup: trim list resources and remaining helper comments
 ## Что уже сделано по коду
 - очищены и частично переведены helper-файлы
 - выполнен консервативный проход по небольшим resource list-файлам
 - ведётся внешний журнал работы в analysis
 ### Файлы, которые уже правились
 - analysis/cleanup-worklog-2026-04-29.md
 - v1/lib/TokenGenerator.cfc
 - v1/lib/field_set.cfm
 - v1/lib/order_build.cfm
 - v1/lib/rest_api_helper.cfc
 - v1/resources/svc_default.cfc
 - v1/lib/field.cfm
 - v1/lib/filter_build.cfm
 - v1/resources/catalog_service_ls.cfc
 - v1/resources/catalog_service_param_ls.cfc
 ### Что уже сделано по смыслу
 - удалены старые version-header комментарии там, где это безопасно
 - удалены закомментированные альтернативные строки и debug-хвосты
 - удалены комментарии в формате внутренних рассуждений там, где это явно безопасно
 - переведена часть английских комментариев в helper-слое
 - syntax/errors на изменённых файлах проверялись, явных ошибок на затронутых файлах не было
 ## Какие файлы сознательно НЕ трогались или почти не трогались
 - v1/Application.cfc
 - v1/resources/instance.cfc
 - крупные и неоднозначные instance/operation resource-файлы
 - весь vendor-слой v1/taffy
 - backup-каталоги v1/resources/bk и v1/etc/bk
 ## Какие аналитические файлы уже созданы
 - analysis/project-history-analysis.md
 - analysis/project-history-analysis-careful-2026-04-29.md
 - analysis/task-brief-2026-04-29.md
 - analysis/cleanup-worklog-2026-04-29.md
 ## Важно по журналу
 - продолжать писать именно в analysis/cleanup-worklog-2026-04-29.md
 - перед каждым новым заметным этапом фиксировать, что собираешься делать
 - после этапа фиксировать результат, что вошло, что сознательно не трогалось и почему
 ## Что сделать в новой сессии первым делом
 1. Проверить, что открыт именно локальный путь, а не mounted sshfs-копия.
 2. Проверить текущую ветку и HEAD.
 3. Проверить, чистое ли рабочее дерево.
 4. Открыть и прочитать analysis/cleanup-worklog-2026-04-29.md, чтобы продолжать журнал в том же стиле.
 5. После этого выбрать следующую небольшую безопасную группу файлов для зачистки.
 ## Какой следующий шаг по коду предпочтителен
 - не идти сразу в Application.cfc
 - взять ещё 1-2 компактных resource-файла с плотным, но безопасно удаляемым comment/dead-code слоем
 - кандидатами могут быть небольшие list-resource или compute/helper resource-файлы, но только после чтения
 - перед правкой обязательно посмотреть текущий файл целиком или значимую часть
 - править минимально и без рефакторинга логики
 ## Стратегия на продолжение
 - маленькие партии файлов
 - отдельный лог в analysis
 - отдельный локальный commit на каждый смысловой этап
 - сначала убирать комментированный мёртвый код и явно лишние рассуждения
 - потом переводить оставшиеся полезные английские комментарии
 - только потом переходить к более крупным и рискованным файлам
 ## Что НЕ делать
 - не удалять cfm/cfc-файлы автоматически по догадке
 - не трогать vendor Taffy без отдельного решения
 - не смешивать много разных смысловых этапов в один commit
 - не пытаться причесать всё сразу
 - не переписывать логику ради красоты
 - не пушить
 ## Отдельно учесть
 - файл analysis/task-brief-2026-04-29.md мог быть изменён пользователем после прошлой сессии, поэтому перед любыми правками его нужно перечитать и не затирать пользовательские изменения
 - если локальная копия создавалась копированием, а не переносом всей .git-истории, нужно сразу выяснить, есть ли коммиты f6d5c868cb54b87c1daffdeda95689a5f121ca8f, 7b98eee156c3251bdd37a4d22d3596ba671a447c, 44daae628d24502730745a94f2f3665474f22c4a; если их нет, надо либо перенести ветку, либо повторить уже сделанные этапы осознанно, а не вслепую
 ## Цель ближайшей итерации
 - подтвердить локальную среду
 - продолжить worklog
 - выбрать следующую безопасную группу файлов
 - сделать ещё один аккуратный cleanup-stage
 - проверить syntax/errors
 - создать следующий локальный commit
 ## Если состояние локальной копии не совпадает с ожидаемым
 Сначала нужно коротко описать расхождение и только потом продолжать правки.
@@ -0,0 +1,394 @@
 # Подробный анализ истории и устройства проекта svc-api-x
 ## Статус анализа
 Этот отчет составлен повторно и отдельно от предыдущего файла, с опорой на проверенные факты из git-объектов, структуры каталогов и ключевых исходников.
 Что удалось проверить напрямую:
 - корневой коммит
 - количество коммитов в текущей истории
 - цепочку последних 8 коммитов
 - наличие веток и отсутствие тегов
 - стартовое дерево файлов корневого коммита
 - текущую структуру каталогов
 - ключевые технические файлы: `Application.cfc`, `resources/*`, `lib/rest_api_helper.cfc`, `build/Dockerfile`, `build/Jenkinsfile`, `v1/etc/readme.txt`, `v1/taffy/package.json`
 Что важно оговорить честно:
 - обычные команды `git log` и `git show` в этом окружении часто подвисали
 - поэтому выводы ниже сделаны не по полному удобному логу, а по низкоуровневым объектам git и выборочным проверкам
 - этого достаточно для надежной общей картины, но не для полной тематической классификации всех 364 коммитов
 ## Ключевые факты
 ### Базовые метаданные репозитория
 - текущая история содержит 364 коммита
 - корневой коммит: `ab5c944862b102e27a1f04da24ffe19c1e24093c`
 - сообщение корневого коммита: `initial`
 - дата корневого коммита: `2024-10-23 12:17:42 +0400`
 - автор корневого коммита: `msyu <msyu@mail.ru>`
 Текущие ветки:
 - локальные: `dev`, `naeel`
 - удаленные: `origin/dev`, `origin/naeel`
 Тегов нет.
 Это сразу говорит о нескольких вещах:
 - проект живет в обычной веточной модели без оформленных release tags
 - история не выглядит как релизно-ориентированная
 - контроль версий, вероятнее всего, велся через рабочую ветку `dev` и прикладные коммиты, а не через формальный релизный процесс
 ## Когда и как появился репозиторий
 Самый важный вывод по старту проекта: репозиторий возник не как минимальная заготовка, а как импорт уже существующей рабочей кодовой базы.
 Основания для этого вывода:
 - самый первый коммит уже называется просто `initial`, без цепочки подготовительных bootstrap-коммитов
 - в корневом снимке сразу присутствуют прикладные файлы, инфраструктурные файлы и исторические артефакты
 - в стартовом дереве уже есть:
  - `.dockerignore`
  - `.gitignore`
  - `v1/Application.cfc`
  - `v1/index.cfm`
  - `v1/lib/*`
  - `v1/resources/*`
  - `v1/etc/bk/*`
  - `v1/etc/info/*`
  - `build/*`
 Особенно показательно наличие в самом первом коммите:
 - backup-файлов
 - каталога `bk`
 - архивированных HTML-страниц и их ассетов в `v1/etc/info`
 Если бы проект создавался в git с нуля, такой набор в первом коммите почти не встречается. Это типичный след импорта уже существовавшей рабочей директории или внутреннего проекта, который до этого жил вне аккуратной git-структуры.
 ## Что это за проект по назначению
 Наиболее точное краткое описание: это CFML REST backend для deck, работающий на Lucee и Taffy поверх PostgreSQL.
 Это не гипотеза, а прямой вывод из файла `v1/etc/readme.txt`, где сказано:
 - `deck ReST backend`
 - `Lucee+Taffy+Postgre`
 - API реализует ограниченное подмножество функций консоли
 Также в том же файле перечислены функции API:
 - список инстансов клиента с актуальными стейтами
 - детализация инстанса
 - конфигурирование инстанса через CFS-параметры
 - создание инстанса
 - запуск других операций сервиса
 - детализация операции
 - статус операции
 - сервис с параметрами
 То есть по предметной области это backend для сервисного каталога и управления экземплярами сервисов, а не просто справочный API.
 ## Технологическая архитектура
 ### Платформа выполнения
 По `build/Dockerfile` проект собирается в контейнер на базе:
 - `ortussolutions/commandbox:lucee5-alpine-3.9.2`
 Из этого следует:
 - рантайм — Lucee
 - запуск и конфигурация приложения идут через CommandBox
 - проект рассчитан на контейнерное исполнение
 В Dockerfile есть признаки production-like окружения:
 - установка сертификатов
 - настройка логирования Lucee/Runwar в stdout
 - настройка heap size
 - деплой JDBC-драйвера PostgreSQL
 - проброс access/application logs в stdout
 Это уже не локальный экспериментальный код, а сервис, который реально готовили к запуску в контейнерной среде.
 ### CI/CD
 `build/Jenkinsfile` очень короткий, но показательный:
 - pipeline работает на `node("docker")`
 - основной сценарий сборки подтягивается из отдельного репозитория `deck/universalDeckPipelines.git`
 Это значит:
 - сам репозиторий не содержит весь CI logic внутри себя
 - сборка и деплой централизованы через общую библиотеку пайплайнов
 - проект встроен во внутреннюю инженерную инфраструктуру, а не живет изолированно
 ### Приложение и framework
 `v1/Application.cfc` расширяет `taffy.core.api`, то есть проект построен поверх Taffy REST framework.
 Внутри `Application.cfc` видно:
 - маппинги на `resources`, `lib`, `taffy`
 - выбор конфигурации через `conf/prod.cfm`, `conf/stage.cfm`, `conf/dev.cfm`
 - fallback-конфиг при отсутствии файлов окружения
 - зависимость от IAM service
 - использование переменных окружения Vault
 - глобальные CORS-заголовки
 - настройку версии API
 Это говорит о том, что `Application.cfc` играет роль одновременно:
 - точки входа
 - конфигурационного слоя
 - куска security/bootstrap logic
 - адаптера к внешнему окружению
 То есть архитектура эволюционная: часть системной логики сосредоточена в одном большом файле, а не строго разделена по слоям.
 ## Taffy: внешний framework, включенный прямо в репозиторий
 Важный архитектурный факт: Taffy лежит в репозитории как вендорнутый код в каталоге `v1/taffy`.
 Это подтверждается несколькими фактами:
 - каталог `v1/taffy` содержит типичную структуру самого framework: `core`, `dashboard`, `tests`, `docs`, `examples`, `verify`
 - `v1/taffy/ReadMe.md` — это оригинальный README Taffy
 - `v1/taffy/package.json` содержит:
  - name: `cfml-taffy`
  - version: `3.8.0`
  - repository: `https://github.com/atuttle/Taffy.git`
 Вывод:
 - проект не просто использует Taffy как зависимость, а хранит его код у себя
 - это упрощает разворачивание, но размывает границу между прикладным кодом и внешним framework
 - для анализа истории это важно: часть дерева репозитория не является уникальным кодом команды, а представляет собой внешнюю библиотеку
 ## Прикладная структура проекта
 ### Верхний уровень
 Верхнеуровневая структура показывает, что прикладная часть сосредоточена в `v1`:
 - `v1/Application.cfc`
 - `v1/index.cfm`
 - `v1/lib`
 - `v1/resources`
 - `v1/etc`
 - `v1/taffy`
 Плюс рядом находятся:
 - `build/Dockerfile`
 - `build/Jenkinsfile`
 - `README.md`
 - `health.cfm`
 ### Каталог resources
 Каталог `v1/resources` содержит REST-ресурсы уровня домена:
 - `instance.cfc`
 - `instance_ls.cfc`
 - `instance_operation*.cfc`
 - `svc.cfc`
 - `svc_ls.cfc`
 - `svc_grouped_ls.cfc`
 - `svc_operation*.cfc`
 - `resource_realm*.cfc`
 - `user.cfc`
 - `notification_ls.cfc`
 - `bookmark*.cfc`
 - `vault_record.cfc`
 Это показывает, что модель данных ориентирована на:
 - сервисы и их операции
 - экземпляры сервисов и их состояния
 - параметры конфигурации
 - ресурсные realm-ы
 - пользователей и нотификации
 То есть проект работает как API к сервисному каталогу и операционному состоянию объектов.
 ### Каталог lib
 В `v1/lib` лежит технический и вспомогательный код:
 - `rest_api_helper.cfc`
 - `JsonSerializer.cfc`
 - `TokenGenerator.cfc`
 - `jwt.cfc`
 - `expression_parser.cfc`
 - `notifier.cfc`
 - `field.cfm`, `field_set.cfm`
 - `filter_build.cfm`, `order_build.cfm`
 По содержимому `rest_api_helper.cfc` видно, что helper отвечает как минимум за:
 - валидацию параметров
 - сборку записей результата
 - парсинг фильтрации
 - парсинг сортировки
 - нормализацию пустых значений
 Это важный признак: сериализация и трансформация данных в API делаются не только на уровне framework, но и значительной частью вручную.
 ## Что видно по коду ресурсов
 ### `svc.cfc`
 `v1/resources/svc.cfc` показывает типичный паттерн ресурса:
 - ресурс наследуется от `taffy.core.resource`
 - создается `lib.rest_api_helper`
 - параметры валидируются вручную
 - ответ собирается через SQL-запросы и helper layer
 - данные агрегируются в вложенные структуры
 Это не ORM-проект и не современный тонкий REST layer. Здесь API строится как ручная сборка JSON-представлений поверх SQL.
 ### `instance.cfc`
 `v1/resources/instance.cfc` еще показательнее:
 - длинные SQL-запросы с join-ами
 - извлечение состояния инстанса и операций прямо на уровне ресурса
 - бизнес-логика частично находится рядом с SQL
 - есть следы долгой эволюции: TODO, обсуждающие комментарии, оговорки про безопасность и поведение API
 Архитектурный вывод:
 - код ближе к стилю "толстый resource + SQL + helper", чем к чистому разделению controller/service/repository
 - такая структура типична для развивавшегося внутреннего backend-сервиса, который долго меняли по рабочим требованиям
 ## Что видно по внутренним заметкам разработчика
 `v1/etc/readme.txt` особенно важен, потому что это не маркетинговый README, а рабочая инженерная заметка.
 Из нее видно:
 - проект напрямую связан с `deck`
 - допускается обширное дублирование с приложением `deck`
 - есть TODO по mappings, сертификатам, сериализации JSON, автотестам, изоляции клиентов, каталогу услуг
 - некоторые строки содержат отметки дат осени 2024 года
 Это показывает, что репозиторий в ранний период был рабочим internal-проектом с незавершенными архитектурными решениями, а не продуктом, доведенным до полностью выверенной структуры.
 ## Последний наблюдаемый этап истории
 Удалось надежно восстановить цепочку последних 8 коммитов:
 1. `dd3fd1391ff9a6f305266c320f8e8320f2209569`
   - дата: `2026-04-20 15:40:44 +0400`
   - сообщение: `228 back again`
 2. `708f683188cf879f3040bb2188140e53dc320e6c`
   - дата: `2026-04-20 21:09:08 +0400`
   - сообщение: `229 is_hidden fix`
 3. `eef7a95d574b1a9f7270b8ed1e86af68fdedeeca`
   - дата: `2026-04-20 21:53:01 +0400`
   - сообщение: `229 is_disabled`
 4. `808ff75d6725f3e173420374c695cb39cdc2824c`
   - дата: `2026-04-21 12:57:53 +0400`
   - сообщение: `231 append pseudorandom`
 5. `bc45b6cb9c21319059b09421bdbeeb72b78afae6`
   - дата: `2026-04-24 10:32:58 +0400`
   - сообщение: `232 service catalog`
 6. `8a32a0d5f0dc6a112ea60ac4a1c26065b57bb3b4`
   - дата: `2026-04-27 16:41:31 +0400`
   - сообщение: `233 service catalog preview`
 7. `74c073bd7e72926b842fa28a5d0fe78515531a91`
   - дата: `2026-04-27 18:57:24 +0400`
   - сообщение: `234 attempt to fix js error Uncaught SyntaxError: Unexpected identifier 'hidden'`
 8. `f2718d4f44792c2b80b8b8f7e8e1b393c6621bac`
   - дата: `2026-04-29 18:25:11 +0400`
   - сообщение: `deprecated secret clean`
 Эта последовательность дает очень полезную картину.
 ### Что она означает
 Во-первых, в апреле 2026 проект активно меняли.
 Во-вторых, по сообщениям видно, что активная работа шла не вокруг инфраструктуры, а вокруг прикладного UI/API-сценария сервисного каталога:
 - `service catalog`
 - `service catalog preview`
 - `is_hidden fix`
 - `is_disabled`
 - исправление JS syntax error
 Это указывает, что сервис в тот момент использовался не только как чистый backend-API, но и как часть пользовательского сценария, где важны preview/hidden/disabled-состояния и совместимость с JS-фронтом.
 В-третьих, финальный коммит `deprecated secret clean` стоит особняком. Он не продолжает продуктовую тему каталога, а выглядит как санитарная или безопасностная чистка.
 ## Что можно сказать о зрелости процесса разработки
 ### Плюсы
 - проект явно реально использовался и менялся под живые требования
 - есть контейнеризация
 - есть Jenkins pipeline
 - есть внешний IAM/Vault контекст
 - структура домена уже достаточно богатая
 - история не мертвая, а живая до конца апреля 2026
 ### Минусы
 - нет тегов, то есть релизная дисциплина слабая или вынесена вне репозитория
 - в репозитории много исторического шума: backup-файлы, архивы, вспомогательные артефакты
 - framework вендорнут внутрь проекта, что затрудняет отделение своего кода от внешнего
 - `Application.cfc` перегружен и совмещает несколько ролей
 - ресурсы местами слишком толстые и держат сложные SQL-запросы внутри себя
 - комментарии в коде и `v1/etc/readme.txt` показывают, что архитектура во многом развивалась по мере необходимости
 ## Мой вывод о природе проекта
 Это не учебный репозиторий, не демо и не аккуратный greenfield. Это рабочий внутренний backend для deck-контура, выросший эволюционно вокруг Lucee + Taffy + PostgreSQL.
 Самая вероятная история его развития выглядит так:
 ### Этап 1. До-git или ранний internal-код
 Сначала существовал набор рабочего CFML-кода, возможно как часть более широкого deck-контекста или рядом с ним.
 ### Этап 2. Импорт в отдельный репозиторий
 23 октября 2024 года этот код был импортирован в git одним большим коммитом `initial`, уже вместе с историческим мусором, backup-файлами и сторонними артефактами.
 ### Этап 3. Интеграция в инфраструктуру
 Проект получил контейнерную упаковку, Jenkins pipeline, внешний конфиг по окружениям, IAM/Vault-зависимости.
 ### Этап 4. Развитие прикладного API
 Постепенно оформились ресурсы для сервисов, инстансов, операций, параметров и resource realm-ов.
 ### Этап 5. Поздняя продуктовая доработка
 В апреле 2026 шли изменения вокруг service catalog, preview, hidden/disabled-состояний и связанной JS-логики.
 ### Этап 6. Санитарная зачистка
 Последним наблюдаемым коммитом стала чистка deprecated secrets.
 ## Что это означает practically
 Если смотреть на репозиторий как на объект последующей очистки, упаковки или документирования, то нужно учитывать:
 1. В репозитории смешаны три разных слоя:
   - собственный прикладной код
   - внешний framework Taffy
   - исторические/вспомогательные артефакты
 2. Нельзя анализировать проект только по README в корне.
   Корневой `README.md` почти не несет полноценного описания. Более полезен `v1/etc/readme.txt` и сами ресурсы.
 3. Чистка проекта без потери смысла потребует сначала отделить:
   - runtime-critical файлы
   - вендорный код framework
   - архивный мусор
   - старые backup-файлы
 4. Комментарии и TODO в коде здесь несут реальную историческую информацию.
   Если цель — сделать чистый исходный комплект, их можно сокращать. Если цель — сохранить инженерный контекст, удалять их без отдельного архива рискованно.
 ## Итог
 Самый точный краткий диагноз такой:
 `svc-api-x` — это наследованный внутренний Lucee/CFML backend для deck, построенный поверх вендорнутого Taffy, импортированный в git сразу большим рабочим срезом и затем развивавшийся как сервисный API для каталога услуг, инстансов и операций, с поздними правками в UI/API-логике и последующей чисткой секретов.
 Иначе говоря, это зрелая рабочая система с признаками долгой эволюции, а не чистый новый сервис.
 ---
 Отчет сформирован GitHub Copilot GPT-5.4.
 Дата формирования: 2026-04-29 20:13:09 +0400.
@@ -0,0 +1,146 @@
 # Анализ истории и устройства проекта svc-api-x
 ## Краткий вывод
 Это не маленький новый сервис, а зрелый и уже наследованный CFML/ColdFusion API-проект, построенный вокруг Taffy REST framework. По истории видно, что репозиторий появился не как пустая заготовка, а как большой импорт уже существующего кода и сопутствующих материалов, после чего в него вносили точечные правки, в том числе связанные с безопасностью и чисткой секретов.
 На текущий момент в истории репозитория 364 коммита.
 ## Хронология
 ### 1. Старт репозитория: крупный импорт существующего проекта
 Корневой коммит:
 - hash: `ab5c944862b102e27a1f04da24ffe19c1e24093c`
 - сообщение: `initial`
 - дата: `2024-10-23 12:17:42 +0400`
 - автор: `msyu <msyu@mail.ru>`
 По содержимому корневого снимка видно, что в репозиторий сразу попал не пустой скелет, а уже насыщенное дерево файлов:
 - `v1/Application.cfc`
 - `v1/index.cfm`
 - `v1/lib/*`
 - `v1/resources/*`
 - `taffy/*`
 - `build/Dockerfile`
 - `build/Jenkinsfile`
 - `v1/etc/*`
 - архивные и справочные HTML-файлы внутри `v1/etc/info`
 Это типичный признак импортированного legacy-кода: сначала в git попала почти готовая рабочая система, а не минимальный bootstrap.
 ### 2. Последующее развитие: доработка прикладной логики и инфраструктуры
 Структура текущего кода показывает, что проект дальше развивался как полноценный API-сервис:
 - слой входа и конфигурации живет в `v1/Application.cfc`
 - бизнес-утилиты и сериализация вынесены в `v1/lib`
 - доменные сущности и REST-ресурсы находятся в `v1/resources`
 - Taffy framework лежит локально в `taffy/`, то есть проект либо завязан на вендорнутую копию, либо хранит её как часть исходников
 - сборка и деплой оформлены через `build/Dockerfile` и `build/Jenkinsfile`
 Содержимое `v1/Application.cfc` показывает несколько важных вещей:
 - приложение наследуется от `taffy.core.api`
 - маппинги явно указывают на `resources`, `taffy` и `lib`
 - конфиг тянется из разных окружений: `conf/prod.cfm`, `conf/stage.cfm`, `conf/dev.cfm`
 - есть fallback-конфигурация на случай отсутствия внешнего конфига
 - приложение завязано на IAM endpoint и Vault-переменные окружения
 - используются глобальные заголовки CORS и версия API
 Это говорит о том, что проект не просто «API», а реальный сервисный слой с окруженческой конфигурацией, аутентификацией и инфраструктурными зависимостями.
 ### 3. Современный этап: чистка и консолидация наследия
 Текущий HEAD-коммит:
 - hash: `74c073bd7e72926b842fa28a5d0fe78515531a91`
 - сообщение: `deprecated secret clean`
 - дата: `2026-04-29 18:25:11 +0400`
 - автор и committer: `unknown <smishchuk@nubes.ru>`
 Само сообщение коммита показывает, что в истории был отдельный этап чистки устаревших секретов или их следов. Это важный сигнал: репозиторий не только развивали, но и позднее приводили в более безопасное состояние.
 ## Что именно лежит в проекте
 ### Технологический профиль
 Проект выглядит как CFML/ColdFusion сервис, работающий через Taffy REST framework.
 Основные признаки:
 - `v1/Application.cfc` содержит CFML-код и расширяет `taffy.core.api`
 - `v1/index.cfm` явно служит заглушкой для Tomcat
 - в `v1/lib` находятся утилиты и сериализаторы
 - в `v1/resources` лежат REST-ресурсы и доменные модели
 - `build/Dockerfile` и `build/Jenkinsfile` указывают на контейнерную сборку и CI
 ### Доменная структура
 По именам файлов видно, что сервис работает с:
 - инстансами
 - сервисами (`svc`)
 - пользователями
 - ресурсными realm-ами
 - параметрами и subparam-ами
 - операциями и валидацией операций
 - событиями и уведомлениями
 То есть это не узкий утилитарный API, а довольно широкий метаданных/управляющий сервис.
 ### Следы наследованного кода и артефактов
 В корневом снимке и в дереве репозитория есть признаки долгой жизни проекта:
 - backup-файлы `*.bk`, `*.bak`
 - архивированные или скопированные HTML-страницы и их ассеты
 - файлы с промежуточными/сервисными именами
 - плавающие старые документы и фрагменты справочного материала
 Это обычно означает, что кодовая база росла поверх старой рабочей системы, а не создавалась заново по чистой архитектуре.
 ## История по смысловым этапам
 ### Этап A. Импорт и закрепление базовой платформы
 Вероятнее всего, на старте в git попал уже существующий CFML-проект с Taffy и прикладной логикой. Коммит `initial` не выглядит как создание с нуля минимального прототипа, потому что в нем уже много файлов, конфигураций и старых материалов.
 ### Этап B. Развитие API и доменной модели
 Дальше репозиторий, судя по структуре, развивали вокруг сущностей `instance`, `svc`, `resource realm`, `operation`, `param`, `user`. Это похоже на сервис управления конфигурациями и состоянием, а не на классический CRUD без доменной сложности.
 ### Этап C. Интеграция с инфраструктурой
 В `Application.cfc` видны:
 - выбор stand-окружения из базы
 - маршрутизация на IAM service
 - использование Vault переменных
 - настройка CORS и общих HTTP-заголовков
 Это этап, когда приложение стало частью окружения облачной инфраструктуры и перестало быть автономным кодом.
 ### Этап D. Поздняя санитарная правка
 Коммит `deprecated secret clean` показывает, что в поздней фазе проводили гигиену репозитория: убирали deprecated secret material или следы чувствительных данных.
 ## Технические риски и особенности
 1. `Application.cfc` перегружен ответственностями.
   Там одновременно живут конфигурация, безопасность, выбор окружения, IAM-логика и часть инфраструктурных решений.
 2. Есть жесткая зависимость от внешних окружений.
   Сервис ожидает `conf/prod.cfm`, `conf/stage.cfm`, `conf/dev.cfm` и env-переменные для Vault и IAM.
 3. В проекте много исторического наследия.
   Backup-файлы и архивные HTML-ассеты усложняют чтение истории и затрудняют понимание того, что реально используется сейчас.
 4. Архитектура явно эволюционная, а не чистая.
   Это видно и по структуре, и по комментариям в коде, и по смешению кода, конфигов и инфраструктурных деталей.
 ## Итог
 Если сжать всё до одной фразы: это старый, но активно живший CFML/Taffy API-сервис, который начинался как большой импорт уже существующего решения, затем обрастал инфраструктурными зависимостями, а позднее проходил чистку и локальную консолидацию.
 Для дальнейшего анализа логично идти в одном из двух направлений:
 - по коммитам разложить историю на этапы и найти ключевые тематические изменения
 - отдельно разобрать архитектуру кода: вход, auth, ресурсы, сериализация, деплой, legacy-артефакты
 ---
 Анализ выполнен моделью GitHub Copilot GPT-5.4 mini.
 Дата и время формирования отчета: 2026-04-29 20:13:09 +0400.
@@ -0,0 +1,38 @@
 # Задача для ИИ
 Источник задания:
 > Добрый день! Есть задача для ии. Ручное исполнение неинтересно, так я и сам могу. Надо выкачать исходники deck/svc-api (внутренняя gitea), очистить и скомпоновать. По каждому этапу нужен отдельный коммит. Пушить в репу не надо. Чистка такая.
 > 0. Удалить неиспользуемые файлы cfm, cfc. Оставить надо будет скрипты создания бд (sql). Наверно, это я сделаю руками. 
 > 1.Удалить закомментированные фрагменты кода. Это относится к файлам cfm, cfc
 > 2. Удалить комментарии, имеющие смысл и формат рассуждений
 > 3. Удалить комментарии  в начале файла, относящиеся к старым версиям. 
 > 4. Оставшиеся комментарии перевести на русский, если на английском.
 > Собрать оглавление (список всех файлов с путями)
 > Собрать все исходники в вордовый файл и слепить с огравлением. Можно не ворд, а MD
 > В результате должны получиться все исходники в вордовом файле, из которого теоретически можно восстановить проект
 ## Суть задачи
 - выкачать исходники `deck/svc-api` из внутренней Gitea
 - очистить проект по этапам
 - каждый этап оформить отдельным коммитом
 - не пушить результат в репозиторий
 - собрать оглавление всех файлов с путями
 - собрать исходники в один документ, пригодный для последующего восстановления проекта
 ## Ожидаемые этапы очистки
 1. удалить неиспользуемые `cfm` и `cfc`-файлы, оставив SQL-скрипты для БД
 2. удалить закомментированные фрагменты кода в `cfm` и `cfc`
 3. удалить смысловые комментарии и комментарии в стиле рассуждений
 4. удалить старые комментарии в начале файлов, относящиеся к прежним версиям
 5. перевести оставшиеся комментарии на русский язык, если они на английском
 ## Формат результата
 - отдельные коммиты по каждому этапу
 - итоговый документ в формате `md` или `docx`
 - в документе должно быть оглавление и все исходники
 - документ должен позволять теоретически восстановить проект
 cnjq