Initialize project scaffold and domain model

2026-03-25 12:20:42 +03:00
commit fb302b2a2c
51 changed files with 6815 additions and 0 deletions
@@ -0,0 +1,127 @@
+# Runtime Config
+
+## 1. Назначение документа
+
+Этот документ фиксирует конфигурацию окружения, storage и базовые operational assumptions для MVP.
+
+Его задача - убрать неявные решения, которые обычно всплывают уже в процессе написания кода.
+
+## 2. Базовые решения для MVP
+
+- каноническая БД: `PostgreSQL`
+- допустимый упрощенный режим разработки: `SQLite`
+- artifact storage: локальная файловая система
+- MCP transport: `Streamable HTTP`
+- admin API и mcp-server запускаются как отдельные приложения
+
+## 3. Artifact storage
+
+В MVP sample JSON, `.proto`, `descriptor set` и YAML import payload должны храниться в локальном файловом storage.
+
+Требования:
+
+- все файлы кладутся в контролируемый базовый каталог;
+- в БД хранится только `storage_ref`;
+- структура каталогов должна быть детерминированной;
+- storage слой должен быть абстрагирован, чтобы потом заменить его на S3-compatible backend.
+
+Рекомендуемая структура:
+
+```text
+var/mcpaas/
+  samples/
+  descriptors/
+  yaml-imports/
+```
+
+## 4. Секреты и auth profiles
+
+Для MVP:
+
+- operation хранит только `auth_profile_ref`;
+- auth profile хранит только `secret_ref`;
+- реальные секреты не должны попадать в YAML export;
+- секреты не должны логироваться.
+
+Допустимые варианты secret storage:
+
+- env-backed secret store;
+- encrypted local secret storage.
+
+Минимальный безопасный вариант для MVP:
+
+- `secret_ref` указывает на env variable alias или key в локальном secret store;
+- приложение резолвит его на runtime.
+
+## 5. Переменные окружения
+
+Минимально ожидаются:
+
+- `MCPAAS_DATABASE_URL`
+- `MCPAAS_STORAGE_ROOT`
+- `MCPAAS_ADMIN_BIND`
+- `MCPAAS_MCP_BIND`
+- `MCPAAS_LOG_LEVEL`
+- `MCPAAS_SECRET_PROVIDER`
+
+Опционально:
+
+- `MCPAAS_ADMIN_TOKEN`
+- `MCPAAS_MASTER_KEY`
+
+## 6. Логирование и трассировка
+
+Для MVP нужно использовать:
+
+- structured logging через `tracing`;
+- correlation id для test runs и runtime execution;
+- раздельные стадии ошибок: schema, mapping, adapter, external service.
+
+## 7. Таймауты и retries
+
+Рекомендуемые стартовые значения:
+
+- default timeout: `10s`
+- retry default: `1` attempt, то есть без автоматического повтора
+
+Причина:
+
+- сначала важнее детерминированность и прозрачность;
+- aggressive retries могут маскировать реальные ошибки интеграции.
+
+## 8. Режимы запуска
+
+Минимально нужны два режима:
+
+- local development
+- demo/deployment
+
+Local development:
+
+- `SQLite` допустим;
+- локальный storage;
+- упрощенная auth-модель admin-api.
+
+Demo/deployment:
+
+- `PostgreSQL`;
+- локальный или сетевой storage;
+- включенная auth-защита admin-api;
+- стабильный `Streamable HTTP` endpoint для MCP.
+
+## 9. Что важно не допустить
+
+- пути к storage, зашитые в код;
+- секреты в `.yaml` exports;
+- разные конфигурационные модели для local и production без причины;
+- смешивание runtime config и business config operation.
+
+## 10. Практический итог
+
+До старта разработки должны быть приняты как минимум такие решения:
+
+- где лежит БД;
+- где лежат artifacts;
+- как резолвятся `secret_ref`;
+- на каких bind-address запускаются `admin-api` и `mcp-server`;
+- какой transport использует MCP server.