a.tolmachev
106 lines
3.5 KiB
Markdown
106 lines
3.5 KiB
Markdown
# Demo Runbook
|
||
|
||
## 1. Цель документа
|
||
|
||
Этот документ фиксирует минимальный воспроизводимый сценарий запуска и демонстрации Crank без знания внутренней структуры кода.
|
||
|
||
## 2. Предусловия
|
||
|
||
- доступен `PostgreSQL`;
|
||
- задан `CRANK_DATABASE_URL`;
|
||
- задан `CRANK_STORAGE_ROOT`;
|
||
- доступны `CRANK_ADMIN_BIND` и `CRANK_MCP_BIND`;
|
||
- для UI установлен `Node.js`;
|
||
- для Rust-части установлен toolchain из `rust-toolchain.toml`.
|
||
|
||
## 3. Быстрый локальный запуск
|
||
|
||
### Backend
|
||
|
||
```bash
|
||
cargo run -p admin-api
|
||
```
|
||
|
||
Во втором терминале:
|
||
|
||
```bash
|
||
cargo run -p mcp-server
|
||
```
|
||
|
||
### UI
|
||
|
||
```bash
|
||
cd apps/ui
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
## 4. Контрольные health endpoints
|
||
|
||
```bash
|
||
curl http://127.0.0.1:3001/health
|
||
curl http://127.0.0.1:3002/health
|
||
```
|
||
|
||
Ожидаемо:
|
||
|
||
- `admin-api` возвращает `{"service":"admin-api","status":"ok"}`
|
||
- `mcp-server` возвращает `{"service":"mcp-server","status":"ok"}`
|
||
|
||
## 5. Demo flow
|
||
|
||
### REST
|
||
|
||
1. Создать REST operation через UI или `admin-api`.
|
||
2. Выполнить `test-run`.
|
||
3. Опубликовать operation.
|
||
4. Проверить появление tool в MCP через `tools/list`.
|
||
5. Выполнить `tools/call`.
|
||
|
||
### GraphQL
|
||
|
||
1. Создать GraphQL operation с фиксированным `query` или `mutation`.
|
||
2. Выполнить `test-run`.
|
||
3. Экспортировать YAML.
|
||
4. Импортировать YAML в режиме `upsert`.
|
||
5. Опубликовать operation и вызвать ее через MCP.
|
||
|
||
### gRPC
|
||
|
||
1. Создать gRPC operation.
|
||
2. Загрузить `descriptor set`.
|
||
3. Проверить `grpc/services` discovery summary.
|
||
4. Выполнить `test-run`.
|
||
5. Экспортировать YAML.
|
||
6. Импортировать YAML в режиме `upsert`.
|
||
7. Опубликовать operation и вызвать ее через MCP.
|
||
|
||
## 6. Проверка publish/reload flow
|
||
|
||
После публикации новой операции `mcp-server` не требует restart.
|
||
|
||
Проверка:
|
||
|
||
1. Открыть MCP session.
|
||
2. Вызвать `tools/list`.
|
||
3. Опубликовать новую operation через `admin-api`.
|
||
4. Повторно вызвать `tools/list`.
|
||
5. Убедиться, что новый tool появился после refresh interval.
|
||
|
||
## 7. Проверка YAML roundtrip
|
||
|
||
YAML roundtrip считается успешным, если:
|
||
|
||
1. operation экспортируется через `/api/admin/operations/{operation_id}/export`;
|
||
2. экспортированный YAML импортируется через `/api/admin/operations/import?mode=upsert`;
|
||
3. создается новая версия operation;
|
||
4. `test-run` новой версии проходит успешно.
|
||
|
||
## 8. Что считать готовым demo state
|
||
|
||
- все три протокола проходят сценарий `create -> test-run -> publish -> MCP call`;
|
||
- YAML export/import проходит хотя бы для `REST`, `GraphQL` и `gRPC`;
|
||
- `mcp-server` подхватывает published changes без restart;
|
||
- ошибки `admin-api` и runtime возвращаются в читаемом виде;
|
||
- логи позволяют понять, какая операция создавалась, тестировалась, публиковалась или импортировалась.
|