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.