Добавлена возможность регистрировать прикладные апи

README.md

@@ -40,6 +40,7 @@ PLBA (`Platform Runtime for Business Applications`) - это runtime-слой д
 - `health` (`HealthRegistry`) - агрегирование здоровья воркеров и дополнительных компонентов.
 - `workflow` (`WorkflowEngine` и persistence-слой) - исполнение шагов бизнес-процесса с переходами и фиксацией состояния.
 - `control plane` (`ControlPlaneService`, `HttpControlChannel`) - внешние health/action endpoints.
+- `application HTTP` (`ApplicationHttpService`, `HttpApplicationChannel`) - пользовательские HTTP routes бизнес-приложения.
 - `queue` (`InMemoryTaskQueue`) - локальный in-memory буфер как утилита прикладного уровня.
 
 ## 3. Архитектура
@@ -89,6 +90,7 @@ classDiagram
     class HealthRegistry
     class TraceService
     class ControlPlaneService
+    class ApplicationHttpService
     class WorkflowRuntimeFactory
     class WorkflowEngine
     class WorkflowPersistence
@@ -106,6 +108,7 @@ classDiagram
     RuntimeManager --> TraceService
     RuntimeManager --> WorkerSupervisor
     RuntimeManager --> ControlPlaneService
+    RuntimeManager --> ApplicationHttpService
 
     WorkerSupervisor --> Worker
     Worker --> Routine : invokes
@@ -127,7 +130,8 @@ classDiagram
 - Реализация: контракт `app_runtime.contracts.application.ApplicationModule`, регистрация через `app_runtime.core.registration.ModuleRegistry`.
 - Как работает / API / вызовы / таблицы:
   - API: `name`, `register(registry)`.
-  - Типичные вызовы: `registry.add_worker(worker)`, `registry.add_health_contributor(contributor)`.
+- Типичные вызовы: `registry.add_worker(worker)`, `registry.add_health_contributor(contributor)`.
+- Для HTTP-модулей: `registry.add_http_routes(registrar)`.
   - `RuntimeManager.register_module()` вызывает `module.register(...)` и добавляет имя модуля в снимок runtime.
   - В БД напрямую не пишет.
 - Типовая схема использования:
@@ -314,7 +318,72 @@ with traces.open_context(alias="email:123", kind="email") as message_trace_id:
   - Producer в рутине кладет элементы через `put`.
   - Consumer-воркер извлекает через `get(timeout)` и обрабатывает.
 
-## 5. MVP бизнес-приложения
+## 5. Application HTTP
+`PLBA` поддерживает отдельный прикладной HTTP-слой для пользовательских страниц и API бизнес-приложения. Он не смешивается с `control plane` и поднимается отдельным сервисом внутри того же runtime.
+
+`Control Plane` и `Application HTTP` обслуживают разные контуры:
+- `Control Plane` используется для `/health`, `/actions/*`, `/traces/*`.
+- `Application HTTP` используется для бизнес-маршрутов приложения, например `/estimate`, `/estimate/api/tasks`, `/api/orders`.
+
+### Основные компоненты
+- `ApplicationHttpService` управляет lifecycle прикладного HTTP на уровне runtime.
+- `HttpApplicationChannel` поднимает отдельный `FastAPI` app через `uvicorn`.
+- `HttpRouteRegistrar` регистрирует пользовательские routes и получает `ServiceContainer`.
+- `HttpApplicationAppFactory` собирает `FastAPI(title="PLBA Application API")`, middleware и routes.
+
+### Минимальный пример
+```python
+from fastapi import FastAPI, File, UploadFile
+from fastapi.responses import HTMLResponse
+from plba import ApplicationModule, HttpApplicationChannel, create_runtime
+
+
+class DemoRoutes:
+    def register(self, app: FastAPI, services) -> None:
+        @app.get("/demo")
+        async def demo_page():
+            return HTMLResponse("<h1>Demo</h1>")
+
+        @app.post("/demo/api/tasks")
+        async def create_task(file: UploadFile = File(...)):
+            payload = await file.read()
+            return {"filename": file.filename, "size": len(payload)}
+
+
+class DemoModule(ApplicationModule):
+    @property
+    def name(self) -> str:
+        return "demo"
+
+    def register(self, registry) -> None:
+        registry.add_http_routes(DemoRoutes())
+
+
+runtime = create_runtime(DemoModule(), config_path="config.yml")
+runtime.application_http.register_channel(
+    HttpApplicationChannel(host="0.0.0.0", port=15000, timeout=5)
+)
+runtime.start()
+```
+
+После старта runtime приложение будет обслуживать:
+- `GET /demo`
+- `POST /demo/api/tasks`
+
+### Типовые сценарии
+- `Web UI для фоновых задач`: список задач, запуск, статус, cancel, download result.
+- `Внутренний REST API`: например `POST /jobs`, `GET /jobs/{id}`, `POST /jobs/{id}/cancel`.
+- `Файловый шлюз`: загрузка входного файла, асинхронная обработка через worker, скачивание результата.
+- `Webhook endpoint`: прием callback от внешней системы и передача события в worker pipeline.
+
+### Ограничения и рекомендации
+- Не смешивайте business routes с `control plane`.
+- Держите бизнес-логику в сервисах, а handlers используйте как тонкий HTTP-адаптер.
+- Runtime предоставляет доступ к зависимостям через `services`, поэтому handlers не должны зависеть от `RuntimeManager`.
+- В первой версии `Application HTTP` не решает auth, static files, шаблонизаторы, websocket и OpenAPI customization.
+- Для публичного доступа выносите auth, TLS и reverse proxy на внешний ingress.
+
+## 6. MVP бизнес-приложения
 Минимальная конфигурация запуска:
 1. Создать один `ApplicationModule`.
 2. В модуле собрать одну `Routine` и один `Worker` (1 worker -> 1 routine).
@@ -374,4 +443,4 @@ runtime = create_runtime(DemoModule(), config_path="config.yml")
 runtime.start()
 ```
 
-Для production-сценария после MVP обычно добавляют `tracing`, `health contributors`, `workflow` и HTTP control plane, но базовый запуск не требует этих расширений.
+Для production-сценария после MVP обычно добавляют `tracing`, `health contributors`, `workflow`, HTTP control plane и при необходимости `application HTTP`, но базовый запуск не требует этих расширений.