docs: add analysis handoff and project notes

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.