init commit

python_app/docs/runtime_data_flow.md

@@ -0,0 +1,39 @@
+# Потоки данных runtime
+
+## 1. Непрерывный acquisition pipeline
+1. `AppWindowPipelineMixin._start_run()` строит `RunConfigModel` из UI.
+2. `ConfigWriter` пишет runtime config и bundles calibration/reference.
+3. `ProcessSupervisor` запускает:
+   - `data_processor`
+   - `data_preprocessor`
+   - `sweep_orchestrator`
+4. GUI открывает `ShmRingReader` для:
+   - raw tap
+   - preprocessed tap
+   - results
+5. Таймер GUI (`QTimer`) вызывает `_poll_rings()`:
+   - чтение raw/preprocessed/results
+   - запись в history deques
+   - рендер либо trace-lines, либо B-scan heatmap.
+
+## 2. B-scan path
+- Источник: `preprocessed` history ring.
+- Кэш-сигнатура: `build_bscan_signature()` учитывает live-параметры и tail history.
+- Ребилд: `rebuild_bscan_history_from_preprocessed()` + `compute_bscan_profile()`.
+- Рендер: `ImageItem` с LUT и уровнями (`bscan_lookup_table`, `bscan_levels`).
+
+## 3. Single capture path
+- `_start_single_capture()` запускает pipeline в non-continuous режиме.
+- GUI ждет collection после стартового timestamp и валидного trace payload.
+- По завершении выполняется `_stop_run()`.
+
+## 4. Snapshot path
+- `AppWindowSnapshotMixin._save_snapshot()` предварительно дренирует ring buffers.
+- `NpzStore.save_runtime_snapshot_numpy()`:
+  - выбирает aligned histories (`select_aligned_histories`),
+  - пишет `raw/preprocessed/results` + `manifest.json`.
+
+## 5. Failure handling
+- Process crashes читаются через `ProcessSupervisor.collect_crash_reports()`.
+- Reader/parsing errors логируются в GUI runtime log.
+- Hardware/validation errors показываются через `_show_error()` и лог.