svc-api-x/analysis/project-history-analysis-careful-2026-04-29.md

Подробный анализ истории и устройства проекта 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.