bsodfather/crank
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ceb37ad0d3b228ab897e75dffd9410b34a2c3242
crank/docs/implementation-plan.md
T

12 KiB
Raw Blame History

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

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/mcpaas-core
  • crates/mcpaas-schema
  • crates/mcpaas-mapping
  • crates/mcpaas-proto
  • crates/mcpaas-registry
  • crates/mcpaas-runtime
  • crates/mcpaas-adapter-rest
  • crates/mcpaas-adapter-graphql
  • crates/mcpaas-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

Цель:

  • реализовать mcpaas-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

Цель:

  • реализовать mcpaas-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 и БД

Цель:

  • реализовать mcpaas-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 сценарий.

Фичи:

  • mcpaas-adapter-rest
  • mcpaas-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

Цель:

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

Фичи:

  • mcpaas-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.

Фичи:

  • mcpaas-proto
  • descriptor loading;
  • service/method discovery;
  • protobuf normalization;
  • mcpaas-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.

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

Reference in New Issue View Git Blame Copy Permalink