Небольшие доработки по трейсу

README.md

@@ -1,5 +1,29 @@
 # PLBA
 
+## Установка
+
+Установка пакета напрямую из Git-репозитория через `pip`:
+
+```bash
+export GIT_PLBA_TOKEN="<ваш_токен>"
+pip install "git+https://oauth2:${GIT_PLBA_TOKEN}@git.lesha.spb.ru/alex/plba.git"
+```
+
+Если нужен конкретный тег, ветка или commit, добавьте ref после `.git`:
+
+```bash
+pip install "git+https://oauth2:${GIT_PLBA_TOKEN}@git.lesha.spb.ru/alex/plba.git@main"
+```
+
+### Доступ через `GIT_PLBA_TOKEN`
+
+Для установки по HTTPS используется переменная окружения `GIT_PLBA_TOKEN`. В нее нужно положить персональный Git-токен с правом чтения репозитория `alex/plba`. Токен передается в URL установки и позволяет `pip` скачать исходники без SSH-доступа.
+
+Рекомендуется:
+- экспортировать токен только в текущую shell-сессию;
+- не хардкодить токен в `requirements.txt`, `pyproject.toml` или исходниках;
+- использовать отдельный read-only токен, если Git-сервер это поддерживает.
+
 ## 1. Назначение платформы
 PLBA (`Platform Runtime for Business Applications`) - это runtime-слой для бизнес-приложений, который забирает на себя инфраструктурную часть исполнения. Платформа стандартизирует запуск и остановку рабочих процессов, контроль состояния приложения и эксплуатационные сервисы вокруг них. За счет этого прикладной код концентрируется на бизнес-логике, а не на lifecycle, диагностике и служебных механизмах. Базовая модель использования строится вокруг `ApplicationModule`, `Worker` и прикладной `Routine`, где каждый уровень отвечает за свою часть ответственности. В результате приложение получается предсказуемым в эксплуатации, проще в сопровождении и масштабировании.
 
@@ -189,6 +213,11 @@ classDiagram
   - Для чего нужен: позволяет собрать дерево исполнения и связать все сообщения конкретной бизнес-операции.
   - Атрибуты контекста (`TraceContextRecord`): `trace_id`, `alias`, `parent_id`, `type`, `event_time`, `attrs`.
   - Иерархия: `parent_id` указывает на родительский контекст; так строится цепочка root -> child.
+  - Стандартная модель для бизнес-приложений:
+    - root-context создается на внешний триггер верхнего уровня, например входящее письмо, webhook, команду оператора или batch-запуск;
+    - child-context создается на каждую производную единицу работы, например вложение письма, отдельную задачу, заказ или документ;
+    - child-context должен создаваться через `parent_id=<trace_id root-context>` и передаваться дальше через `trace_context` / runtime metadata как активный trace конкретной бизнес-операции;
+    - если одно входящее сообщение порождает несколько задач, у них должен быть общий parent root-context и разные child trace contexts.
   - Таблица: `trace_contexts`.
   - Как объявляется в коде:
 ```python
@@ -199,6 +228,22 @@ with traces.open_context(alias="orders-worker", kind="worker", attrs={"routine":
 root = traces.new_root("orders.sync")
 child = traces.child_of(root, "orders.process_batch")
 ```
+```python
+with traces.open_context(alias="email:123", kind="email") as message_trace_id:
+    ...
+    with traces.open_context(
+        alias="attachment:invoice.xlsx",
+        parent_id=message_trace_id,
+        kind="task",
+        attrs={"attachment_index": 0},
+    ) as task_trace_id:
+        runtime["trace_id"] = task_trace_id
+        runtime["message_trace_id"] = message_trace_id
+        ...
+```
+  - Стандарт для workflow persistence:
+    - если workflow представляет отдельную бизнес-задачу, в `state.runtime.trace_id` должен лежать активный trace этой задачи;
+    - дополнительные идентификаторы родительских контекстов (`message_trace_id`, `email_trace_id` и т.д.) могут храниться рядом в runtime для логов и связности, но `workflow_runs.trace_id` должен ссылаться именно на активный trace текущей задачи.
 - Trace Message:
   - Что это: событие внутри активного context (статус шага, предупреждение, ошибка, служебная информация).
   - Роль `step`: текущая стадия операции (`parse`, `validate`, `persist` и т.д.), которую выставляют через `traces.step("...")`.
@@ -245,6 +290,19 @@ child = traces.child_of(root, "orders.process_batch")
   - При создании runtime включить `enable_http_control=True`.
   - Использовать `/health` для readiness/liveness и `/actions/*` для операционного контроля.
 
+#### Простой Web UI через nginx (порт 15000)
+- Статические файлы UI: `web/control-ui/` (`index.html`, `app.js`, `styles.css`).
+- UI использует polling (`/api/health` раз в 2 секунды) и кнопки `Start/Stop` (`POST /api/actions/start|stop`).
+- Для вызовов API UI передает заголовок `X-Client-Source: web-ui`.
+- Пример server-конфига nginx: `deploy/nginx/plba-control-ui.conf`.
+  - Слушает `15000`.
+  - Отдает UI из `/usr/share/nginx/html`.
+  - Проксирует `/api/*` на control API `http://app:8080/*` (sidecar в docker network).
+- Пример запуска в составе бизнес-приложения: `deploy/docker-compose.control-ui.yml`.
+  - Публикуется только один внешний порт: `15000`.
+  - Внутренний control API остается в сети compose и доступен nginx по имени сервиса `app`.
+  - В `app` нужно поднять control channel на `0.0.0.0:8080`.
+
 #### Queue
 - Назначение: простой in-memory буфер задач/сообщений внутри приложения.
 - Реализация: `InMemoryTaskQueue[T]`.