a.tolmachev
443 lines
9.3 KiB
Markdown
443 lines
9.3 KiB
Markdown
# 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`
|
||
|
||
Для test-run UX:
|
||
|
||
- wizard status block должен различать `unary`, `window`, `session`, `async_job`;
|
||
- `window` показывает bounded flags `window_complete`, `truncated`, `has_more`;
|
||
- `session` показывает `session_id`, `poll_after_ms` и переводит оператора к странице `Stream Sessions`;
|
||
- `async_job` показывает `job_id` и переводит оператора к странице `Async Jobs`;
|
||
- request/response preview textareas остаются общими для всех режимов.
|
||
|
||
## 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`
|