docs: extend protocol platform architecture

2026-04-06 01:57:26 +03:00
parent 04ed704e94
commit 7f15b2db9e
12 changed files with 475 additions and 34 deletions
@@ -0,0 +1,126 @@
+# SOAP
+
+## 1. Роль протокола в проекте
+
+SOAP поддерживается как enterprise-oriented upstream protocol для интеграций с системами, где REST уже не является стандартом де-факто.
+
+Типичные домены:
+
+- ERP;
+- banking;
+- insurance;
+- government and B2B gateways;
+- legacy enterprise systems;
+- ESB-oriented internal APIs.
+
+## 2. Что поддерживается в целевом продукте
+
+- SOAP 1.1 и SOAP 1.2;
+- WSDL upload/import;
+- выбор `service`, `port` и `operation`;
+- document/literal first;
+- XML schema extraction из WSDL/XSD;
+- input/output schema generation;
+- mapping `MCP JSON -> SOAP body`;
+- mapping `SOAP response -> normalized JSON`;
+- SOAP headers config;
+- basic auth, bearer auth и auth profiles;
+- test run;
+- publish as MCP tool.
+
+## 3. Что не входит в текущий продуктовый scope
+
+- полный стек WS-* расширений;
+- MTOM attachments;
+- arbitrary XML transformation engine;
+- full schema authoring inside UI;
+- server-side SOAP hosting.
+
+## 4. Ключевое архитектурное ограничение
+
+SOAP не является просто HTTP POST с XML body.
+
+Для платформы SOAP operation определяется:
+
+- WSDL model;
+- service/port/operation binding;
+- envelope structure;
+- namespaces;
+- optional SOAPAction;
+- fault model;
+- XML schema contract.
+
+Поэтому SOAP должен иметь отдельный adapter и отдельную конфигурационную модель.
+
+## 5. Типовые use cases
+
+- enterprise CRM/ERP operations;
+- payment and settlement integrations;
+- policy and claims systems;
+- regulated B2B data exchange;
+- legacy internal service contracts.
+
+## 6. Внутренняя модель SOAP operation
+
+SOAP operation должна включать:
+
+- `wsdl_ref`
+- `service_name`
+- `port_name`
+- `operation_name`
+- `endpoint_override`
+- `soap_version`
+- `soap_action`
+- `input_schema`
+- `output_schema`
+- `input_mapping`
+- `output_mapping`
+- `header_config`
+- `execution_config`
+- `tool_description`
+
+## 7. Как оператор настраивает SOAP operation
+
+1. Загружает WSDL.
+2. Система извлекает services, ports, operations и XSD schemas.
+3. Оператор выбирает service, port и operation.
+4. UI показывает input/output schema в JSON-oriented виде.
+5. Оператор настраивает mapping `MCP input -> SOAP body`.
+6. При необходимости задает SOAP headers и auth profile.
+7. Настраивает output mapping и fault handling.
+8. Выполняет test run.
+9. Публикует operation как MCP tool.
+
+## 8. Поведение runtime
+
+При выполнении SOAP operation runtime должен:
+
+1. Валидировать MCP input.
+2. Построить XML envelope.
+3. Подставить namespaces и headers.
+4. Выполнить HTTP request.
+5. Разобрать SOAP response и SOAP Fault.
+6. Нормализовать XML result в JSON.
+7. Применить output mapping.
+8. Вернуть итоговый результат.
+
+## 9. Критические нюансы
+
+- WSDL import должен быть отделен от runtime call;
+- XML namespaces должны быть first-class частью конфигурации;
+- SOAP Fault нельзя сводить только к HTTP error;
+- input/output schema должны отображаться в UI как нормализованные поля, а не как raw XML;
+- auth и headers должны настраиваться отдельно от body mapping.
+
+## 10. Почему SOAP должен входить в product scope
+
+Если Crank позиционируется как enterprise integration platform, отсутствие SOAP оставляет большую часть legacy и regulated environments вне продукта.
+
+Поэтому SOAP должен быть частью общей protocol strategy наравне с:
+
+- REST
+- GraphQL
+- gRPC
+- WebSocket
+
+Но при этом он должен оставаться request-response oriented adapter, а не ломать общую execution model.