docs: add analysis handoff and project notes
This commit is contained in:
“Naeel”
@@ -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.
|
||||
Reference in New Issue
Block a user