docs: add analysis handoff and project notes

analysis/new-chat-handoff-2026-04-29.md

@@ -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
+
+## Если состояние локальной копии не совпадает с ожидаемым
+
+Сначала нужно коротко описать расхождение и только потом продолжать правки.

analysis/project-history-analysis-careful-2026-04-29.md

@@ -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.

analysis/project-history-analysis.md

@@ -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.

analysis/task-brief-2026-04-29.md

@@ -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