docs: add detailed streaming specifications
This commit is contained in:
a.tolmachev
@@ -0,0 +1,434 @@
|
||||
# Streaming UI Contract
|
||||
|
||||
## 1. Назначение документа
|
||||
|
||||
Этот документ фиксирует точный UI-контракт для настройки потоковых операций.
|
||||
|
||||
Цель:
|
||||
|
||||
- определить экраны и блоки wizard;
|
||||
- перечислить все поля;
|
||||
- перечислить валидации;
|
||||
- определить protocol-specific visibility rules;
|
||||
- зафиксировать UX states, warnings и system messages.
|
||||
|
||||
## 2. Основные экраны
|
||||
|
||||
Потоковая конфигурация живет в:
|
||||
|
||||
- `Operations Wizard`
|
||||
- `Operation Detail`
|
||||
- `Test Run`
|
||||
- `Agent Tool Preview`
|
||||
- `Logs` / `Usage` observability surfaces
|
||||
|
||||
Дополнительно админские страницы:
|
||||
|
||||
- `Stream Sessions`
|
||||
- `Async Jobs`
|
||||
|
||||
## 3. Wizard information architecture
|
||||
|
||||
## 3.1. Shared wizard structure
|
||||
|
||||
Шаги:
|
||||
|
||||
1. `Protocol`
|
||||
2. `Upstream`
|
||||
3. `Request / Subscription`
|
||||
4. `Execution Mode`
|
||||
5. `Input Schema`
|
||||
6. `Output / Aggregation`
|
||||
7. `Safety and Limits`
|
||||
8. `Tool Family`
|
||||
9. `Test Run`
|
||||
10. `Publish`
|
||||
|
||||
## 3.2. Step `Execution Mode`
|
||||
|
||||
Поля:
|
||||
|
||||
- `Mode`
|
||||
- `Unary`
|
||||
- `Window`
|
||||
- `Session`
|
||||
- `Async Job`
|
||||
- `Transport behavior`
|
||||
- `Request / response`
|
||||
- `Server stream`
|
||||
|
||||
Подсказки:
|
||||
|
||||
- `Unary` для обычных request-response integrations.
|
||||
- `Window` для bounded snapshots из stream или feed.
|
||||
- `Session` для follow-style tools с `start/poll/stop`.
|
||||
- `Async Job` для long-running operations с `status/result/cancel`.
|
||||
|
||||
Валидации:
|
||||
|
||||
- `Transport behavior=server_stream` не может использоваться с protocol, который его не поддерживает.
|
||||
- `WebSocket` не может быть `Unary`.
|
||||
- `SOAP` в первой волне не может быть `Session`.
|
||||
|
||||
## 3.3. Step `Input Schema`
|
||||
|
||||
Поля:
|
||||
|
||||
- `Input schema source`
|
||||
- manual
|
||||
- sample-derived
|
||||
- descriptor/wsdl-derived
|
||||
- `Input fields`
|
||||
- `Required fields`
|
||||
- `Defaults`
|
||||
- `Mapping preview`
|
||||
|
||||
## 3.4. Step `Output / Aggregation`
|
||||
|
||||
Поля:
|
||||
|
||||
- `Aggregation mode`
|
||||
- `Raw items`
|
||||
- `Summary only`
|
||||
- `Summary + samples`
|
||||
- `Stats`
|
||||
- `Latest state`
|
||||
- `Items path`
|
||||
- `Summary path`
|
||||
- `Cursor path`
|
||||
- `Status path`
|
||||
- `Done path`
|
||||
- `Output mapping`
|
||||
|
||||
Валидации:
|
||||
|
||||
- `Items path` обязателен для `Raw items` и `Summary + samples`.
|
||||
- `Summary path` обязателен для `Summary only`, `Summary + samples`, `Stats`, `Latest state`.
|
||||
- `Done path` обязателен для `Async Job`, если upstream status не выражается отдельным field set.
|
||||
|
||||
## 3.5. Step `Safety and Limits`
|
||||
|
||||
Поля:
|
||||
|
||||
- `Window duration`
|
||||
- `Poll interval`
|
||||
- `Upstream timeout`
|
||||
- `Idle timeout`
|
||||
- `Session lifetime`
|
||||
- `Max items`
|
||||
- `Max bytes`
|
||||
- `Max field length`
|
||||
- `Drop duplicates`
|
||||
- `Sampling rate`
|
||||
- `Redacted paths`
|
||||
|
||||
Валидации:
|
||||
|
||||
- `Window duration` обязателен для `Window`.
|
||||
- `Poll interval` обязателен для `Session`.
|
||||
- `Idle timeout` обязателен для `Session`.
|
||||
- `Session lifetime` обязателен для `Session`.
|
||||
- `Max items` > 0.
|
||||
- `Max bytes` > 0.
|
||||
- `Sampling rate` > 0 and <= 1.
|
||||
|
||||
## 3.6. Step `Tool Family`
|
||||
|
||||
Показывается только для:
|
||||
|
||||
- `Session`
|
||||
- `Async Job`
|
||||
|
||||
Для `Session`:
|
||||
|
||||
- `Start tool name`
|
||||
- `Poll tool name`
|
||||
- `Stop tool name`
|
||||
|
||||
Для `Async Job`:
|
||||
|
||||
- `Start tool name`
|
||||
- `Status tool name`
|
||||
- `Result tool name`
|
||||
- `Cancel tool name`
|
||||
|
||||
Валидации:
|
||||
|
||||
- имена обязательны;
|
||||
- имена должны быть уникальны в пределах agent;
|
||||
- имена не должны конфликтовать с already bound tools.
|
||||
|
||||
## 4. Protocol-specific UI
|
||||
|
||||
## 4.1. REST
|
||||
|
||||
Поля:
|
||||
|
||||
- `Base URL`
|
||||
- `HTTP method`
|
||||
- `Path template`
|
||||
- `Headers`
|
||||
- `Query mapping`
|
||||
- `Body mapping`
|
||||
- `SSE enabled`
|
||||
- `SSE event filter`
|
||||
|
||||
Visibility:
|
||||
|
||||
- `SSE enabled` показывается только если method/endpoint допускают stream use case;
|
||||
- `Window` и `Session` доступны, если оператор включает stream behavior.
|
||||
|
||||
## 4.2. GraphQL
|
||||
|
||||
Поля:
|
||||
|
||||
- `Endpoint`
|
||||
- `Operation type`
|
||||
- `Operation name`
|
||||
- `Query template`
|
||||
- `Variables schema`
|
||||
- `Response path`
|
||||
|
||||
Visibility:
|
||||
|
||||
- `Window`, `Session`, `Async Job` скрыты в текущей продуктовой волне;
|
||||
- `Subscription` UI не показывается.
|
||||
|
||||
## 4.3. gRPC
|
||||
|
||||
Поля:
|
||||
|
||||
- `Server address`
|
||||
- `Package`
|
||||
- `Service`
|
||||
- `Method`
|
||||
- `Descriptor source`
|
||||
- `Stream kind`
|
||||
- `Unary`
|
||||
- `Server streaming`
|
||||
|
||||
Visibility:
|
||||
|
||||
- `Window`, `Session`, `Async Job` доступны только для `Server streaming`;
|
||||
- `Client streaming` и `Bidirectional` не показываются вообще.
|
||||
|
||||
## 4.4. WebSocket
|
||||
|
||||
Поля:
|
||||
|
||||
- `WebSocket URL`
|
||||
- `Subprotocols`
|
||||
- `Connect timeout`
|
||||
- `Heartbeat interval`
|
||||
- `Subscribe message template`
|
||||
- `Unsubscribe message template`
|
||||
- `Message envelope path`
|
||||
|
||||
Visibility:
|
||||
|
||||
- `Unary` не показывается;
|
||||
- `Window`, `Session`, `Async Job` доступны всегда;
|
||||
- `Subscribe message template` обязательно для `Window` и `Session`.
|
||||
|
||||
## 4.5. SOAP
|
||||
|
||||
Поля:
|
||||
|
||||
- `WSDL source`
|
||||
- `Service`
|
||||
- `Port`
|
||||
- `Operation`
|
||||
- `SOAP version`
|
||||
- `SOAPAction`
|
||||
- `Endpoint override`
|
||||
- `Header config`
|
||||
|
||||
Visibility:
|
||||
|
||||
- `Session` скрыт;
|
||||
- `Window` скрыт по умолчанию и включается только для polling-style enterprise workflows;
|
||||
- `Unary` и `Async Job` доступны.
|
||||
|
||||
## 5. Test Run UX
|
||||
|
||||
## 5.1. Window
|
||||
|
||||
UI должен показывать:
|
||||
|
||||
- `Status`
|
||||
- `Duration`
|
||||
- `Items count`
|
||||
- `Bytes count`
|
||||
- `Window complete`
|
||||
- `Truncated`
|
||||
- `Has more`
|
||||
- `Summary`
|
||||
- `Items preview`
|
||||
- `Cursor`
|
||||
|
||||
Кнопки:
|
||||
|
||||
- `Run window test`
|
||||
- `Repeat`
|
||||
- `Save config`
|
||||
|
||||
## 5.2. Session
|
||||
|
||||
UI должен показывать:
|
||||
|
||||
- `Session id`
|
||||
- `Status`
|
||||
- `Expires at`
|
||||
- `Poll after`
|
||||
- `Summary preview`
|
||||
- `Items preview`
|
||||
|
||||
Кнопки:
|
||||
|
||||
- `Start session`
|
||||
- `Poll next chunk`
|
||||
- `Stop session`
|
||||
|
||||
## 5.3. Async Job
|
||||
|
||||
UI должен показывать:
|
||||
|
||||
- `Job id`
|
||||
- `Status`
|
||||
- `Progress`
|
||||
- `Started at`
|
||||
- `Finished at`
|
||||
- `Result preview`
|
||||
|
||||
Кнопки:
|
||||
|
||||
- `Start job`
|
||||
- `Refresh status`
|
||||
- `Get result`
|
||||
- `Cancel job`
|
||||
|
||||
## 6. Page-level states
|
||||
|
||||
Каждый streaming-aware экран обязан поддерживать:
|
||||
|
||||
- `idle`
|
||||
- `validating`
|
||||
- `saving`
|
||||
- `testing`
|
||||
- `running`
|
||||
- `completed`
|
||||
- `failed`
|
||||
- `stopped`
|
||||
- `expired`
|
||||
|
||||
## 7. Warnings and messages
|
||||
|
||||
## 7.1. Validation warnings
|
||||
|
||||
- `This mode will truncate responses above the configured byte limit.`
|
||||
- `Current protocol does not support the selected execution mode.`
|
||||
- `Session lifetime is shorter than idle timeout.`
|
||||
- `Aggregation mode summary_only hides raw items from the final tool output.`
|
||||
- `WebSocket reconnect may duplicate events if upstream does not provide cursor semantics.`
|
||||
- `SOAP async mode requires a separate status/result contract.`
|
||||
|
||||
## 7.2. Confirmations
|
||||
|
||||
- `Stop current session?`
|
||||
- `Cancel running job?`
|
||||
- `Switching execution mode will reset protocol-specific fields.`
|
||||
|
||||
## 7.3. Errors
|
||||
|
||||
- `Streaming configuration is invalid.`
|
||||
- `Test session expired.`
|
||||
- `Upstream did not return any messages within the configured window.`
|
||||
- `The collected stream payload was truncated by size limits.`
|
||||
- `This protocol does not support the selected execution mode.`
|
||||
|
||||
## 8. Stream Sessions page
|
||||
|
||||
Колонки:
|
||||
|
||||
- `Session ID`
|
||||
- `Operation`
|
||||
- `Agent`
|
||||
- `Mode`
|
||||
- `Status`
|
||||
- `Created`
|
||||
- `Last poll`
|
||||
- `Expires`
|
||||
|
||||
Actions:
|
||||
|
||||
- `Open`
|
||||
- `Stop`
|
||||
- `Delete`
|
||||
|
||||
Detail view:
|
||||
|
||||
- `Session metadata`
|
||||
- `Cursor preview`
|
||||
- `State summary`
|
||||
- `Recent events summary`
|
||||
|
||||
## 9. Async Jobs page
|
||||
|
||||
Колонки:
|
||||
|
||||
- `Job ID`
|
||||
- `Operation`
|
||||
- `Agent`
|
||||
- `Status`
|
||||
- `Progress`
|
||||
- `Created`
|
||||
- `Updated`
|
||||
- `Finished`
|
||||
|
||||
Actions:
|
||||
|
||||
- `Open`
|
||||
- `Cancel`
|
||||
- `Get result`
|
||||
|
||||
Detail view:
|
||||
|
||||
- `Job metadata`
|
||||
- `Progress payload`
|
||||
- `Result preview`
|
||||
- `Error preview`
|
||||
|
||||
## 10. Exact frontend adapters
|
||||
|
||||
Ожидаемые frontend modules:
|
||||
|
||||
- `streaming-form.js`
|
||||
- `streaming-validation.js`
|
||||
- `stream-test-run.js`
|
||||
- `stream-sessions.js`
|
||||
- `async-jobs.js`
|
||||
|
||||
Ожидаемые frontend functions:
|
||||
|
||||
- `loadProtocolCapabilities()`
|
||||
- `applyStreamingPreset()`
|
||||
- `validateStreamingConfig()`
|
||||
- `serializeStreamingConfig()`
|
||||
- `deserializeStreamingConfig()`
|
||||
- `startWindowTest()`
|
||||
- `startSessionTest()`
|
||||
- `pollSessionTest()`
|
||||
- `stopSessionTest()`
|
||||
- `startAsyncJobTest()`
|
||||
- `refreshAsyncJobStatus()`
|
||||
- `loadAsyncJobResult()`
|
||||
|
||||
## 11. Shared UI rules
|
||||
|
||||
- UI никогда не должен предлагать unsupported mode;
|
||||
- UI должен строить availability по `protocol-capabilities`, а не по hardcoded if-else;
|
||||
- UI должен явно объяснять, почему поле скрыто или disabled;
|
||||
- UI должен всегда показывать итоговую tool topology:
|
||||
- `1 tool`
|
||||
- `3 tools start/poll/stop`
|
||||
- `4 tools start/status/result/cancel`
|
||||
Reference in New Issue
Block a user