crank/docs/implementation-plan.md

# План реализации

## 1. Назначение документа

Этот документ фиксирует порядок реализации модулей и фич. Он нужен затем, чтобы разработка шла последовательно, а не параллельно во все стороны сразу.

Принцип:

- сначала фундамент;
- потом минимальный end-to-end сценарий;
- потом расширение протоколов;
- потом polish и demo readiness.

## 2. Этап 0. Scaffold проекта

Цель:

- создать `cargo workspace`;
- создать приложения и crates;
- подключить базовый CI/test workflow;
- зафиксировать структуру каталогов.

Состав:

- `apps/admin-api`
- `apps/mcp-server`
- `apps/ui`
- `crates/crank-core`
- `crates/crank-schema`
- `crates/crank-mapping`
- `crates/crank-proto`
- `crates/crank-registry`
- `crates/crank-runtime`
- `crates/crank-adapter-rest`
- `crates/crank-adapter-graphql`
- `crates/crank-adapter-grpc`

Результат:

- проект собирается;
- тестовый pipeline запускается;
- есть пустые crate boundaries.

DoD:

- создан `cargo workspace`;
- все crates и apps объявлены в workspace;
- проект собирается без бизнес-логики;
- базовые test targets запускаются;
- сделан атомарный commit со scaffold.

## 3. Этап 1. Базовая доменная модель

Цель:

- реализовать типы из `data-model`.

Фичи:

- `Operation`
- `Target`
- `Schema`
- `MappingSet`
- `ExecutionConfig`
- `ToolDescription`
- `AuthProfile`

Параллельно:

- unit tests на доменные типы;
- базовая сериализация `JSON`/`YAML`.

Результат:

- модель данных существует как код;
- нет инфраструктурных зависимостей внутри домена.

DoD:

- типы из `data-model` реализованы;
- базовая сериализация `JSON` и `YAML` проходит тесты;
- доменные `impl` не содержат инфраструктурной логики;
- unit tests на ключевые типы проходят;
- изменения зафиксированы через один или несколько `RGR + commit`.

## 4. Этап 2. Schema engine

Цель:

- реализовать `crank-schema`.

Фичи:

- model полей и типов;
- schema validation;
- field traversal;
- нормализация JSON samples;
- protobuf -> schema bridge contracts.

Результат:

- можно описывать и валидировать вход/выход.

DoD:

- реализована схема полей и типов;
- работает schema validation;
- JSON sample normalization покрыт тестами;
- контракты protobuf -> schema зафиксированы;
- нет смешивания schema logic с adapter logic.

## 5. Этап 3. Mapping engine

Цель:

- реализовать `crank-mapping`.

Фичи:

- `JSONPath` parsing и validation;
- input mapping;
- output mapping;
- transforms;
- generation draft mapping из samples.

Результат:

- можно преобразовывать MCP input в request model и response в output model.

DoD:

- `JSONPath` parsing и validation работают;
- input/output mapping проходят unit tests;
- generation draft mapping покрыта фикстурами;
- transforms ограничены и задокументированы;
- mapping engine не знает о конкретных protocol adapters.

## 6. Этап 4. Registry и БД

Цель:

- реализовать `crank-registry` и миграции.

Фичи:

- таблицы из `database-schema`;
- version snapshots;
- published operations;
- auth profiles;
- sample metadata;
- descriptor metadata;
- YAML import job log.

Результат:

- конфигурации можно хранить и версионировать.

DoD:

- миграции создают таблицы из `database-schema`;
- version snapshots работают корректно;
- publish linkage реализован;
- auth profiles и artifact metadata сохраняются;
- integration tests на registry проходят на реальной БД.

## 7. Этап 5. REST vertical slice

Цель:

- получить первый рабочий end-to-end сценарий.

Фичи:

- `crank-adapter-rest`
- `crank-runtime` для REST
- REST test run
- создание REST operation
- publish REST operation
- вызов published REST tool из MCP слоя

Результат:

- MVP работает хотя бы для REST.

DoD:

- REST operation можно создать, протестировать и опубликовать;
- runtime исполняет REST operation end-to-end;
- published REST tool вызывается через MCP слой;
- negative tests на mapping и external errors существуют;
- есть демонстрационный REST сценарий.

## 8. Этап 6. Admin API v1

Цель:

- дать UI полный backend-контракт для базового сценария.

Фичи:

- CRUD operations;
- create version;
- publish;
- upload input/output JSON samples;
- generate draft;
- test run;
- auth profiles CRUD;
- YAML import/export.

Результат:

- UI может полностью управлять REST operation без ручных правок кода.

DoD:

- доступны CRUD, versioning, publish, samples, draft generation, test runs;
- доступны auth profiles и YAML import/export;
- API контракты соответствуют документации;
- integration tests на ключевые endpoints проходят;
- нет скрытой бизнес-логики в handlers.

## 9. Этап 7. UI v1

Цель:

- собрать рабочую административную консоль.

Фичи:

- список операций;
- мастер создания операции;
- sample upload;
- schema viewer;
- mapping editor;
- test run screen;
- publish flow;
- YAML import/export screen.

Результат:

- есть демонстрируемый пользовательский интерфейс.

DoD:

- UI покрывает основной сценарий от создания operation до publish;
- sample upload и mapping editor работают;
- YAML import/export доступен из UI;
- нет блокирующих заглушек на критическом пути демо;
- основные пользовательские сценарии проверены вручную или integration tests.

## 10. Этап 8. MCP server

Цель:

- публиковать published operations как MCP tools.

Фичи:

- `Streamable HTTP`;
- list tools;
- call tool;
- reload published tools;
- error mapping MCP layer.

Результат:

- REST operation доступна как полноценный MCP tool.

DoD:

- `Streamable HTTP` transport работает;
- list tools и call tool реализованы;
- reload published tools работает без перезапуска;
- ошибки runtime корректно транслируются в MCP слой;
- есть end-to-end test или demo flow вызова published REST tool.

## 11. Этап 9. GraphQL support

Цель:

- добавить второй протокол без разрушения архитектуры.

Фичи:

- `crank-adapter-graphql`
- GraphQL target support;
- variables mapping;
- `response_path`;
- GraphQL test runs;
- publish и вызов через MCP.

Результат:

- второй end-to-end сценарий.

DoD:

- GraphQL operation можно создать, протестировать и опубликовать;
- variables mapping и `response_path` работают;
- GraphQL `errors` корректно обрабатываются;
- published GraphQL tool вызывается через MCP слой;
- есть demo fixture или integration scenario.

## 12. Этап 10. gRPC support

Цель:

- добавить unary gRPC.

Фичи:

- `crank-proto`
- descriptor loading;
- service/method discovery;
- protobuf normalization;
- `crank-adapter-grpc`
- unary test runs;
- publish и вызов через MCP.

Результат:

- третий end-to-end сценарий.

DoD:

- `.proto` или descriptor set можно загрузить;
- unary method discovery работает;
- JSON <-> protobuf conversion покрыта тестами;
- gRPC operation можно протестировать и опубликовать;
- published gRPC tool вызывается через MCP слой.

## 13. Этап 11. Harden и demo readiness

Цель:

- довести проект до стабильного demo state.

Фичи:

- логирование и tracing;
- улучшение ошибок;
- фикстуры и demo scenarios;
- polish UI;
- документация по запуску;
- проверка YAML roundtrip;
- проверка publish/reload flow.

DoD:

- демонстрационные сценарии воспроизводимы;
- логирование и ошибки читаемы;
- YAML roundtrip проверен;
- publish/reload flow стабилен;
- документация по запуску достаточна для повторения демо.

## 14. Этап 12. Deployment и CD

Цель:

- сделать повторяемый production-like запуск проекта.

Фичи:

- `Dockerfile` для приложений;
- `docker-compose.yml`;
- `.env.example`;
- reverse proxy examples;
- health endpoints;
- CD workflow для `main`.

Результат:

- проект можно развернуть на Linux-хосте без ручной сборки бинарей и без ad-hoc shell-скриптов.

DoD:

- backend приложения собираются в контейнеры;
- есть production-like compose конфигурация;
- reverse proxy examples задокументированы;
- CI и CD разделены;
- deployment проверяется healthchecks.

## 15. Приоритеты по реализации

Если времени не хватает, сохраняется такой приоритет:

1. REST end-to-end
2. Registry + versioning
3. YAML import/export
4. MCP server
5. GraphQL
6. gRPC

Причина:

- диплом должен показать работающую платформу;
- лучше один полный вертикальный сценарий, чем три недоделанных адаптера.

## 16. Разбиение по фичам

Каждый этап желательно бить на маленькие фичи:

- `schema-field-model`
- `schema-validator`
- `jsonpath-parser`
- `input-mapping-engine`
- `output-mapping-engine`
- `registry-create-version`
- `registry-publish`
- `rest-adapter-post-json`
- `yaml-export-portable`
- `mcp-list-tools`

Для каждой такой фичи локальный `DoD` должен быть записан до начала реализации хотя бы в рабочем описании задачи или ветки.

## 17. Практический итог

Правильная последовательность для проекта:

- сначала домен и фундамент;
- потом registry;
- потом один полный REST vertical slice;
- потом admin-ui и MCP слой;
- только после этого расширение на GraphQL и gRPC.

Такой порядок минимизирует архитектурный риск и дает ранний рабочий результат.