bulid 63

broadcast_settings/README.md

@@ -0,0 +1,80 @@
+# broadcast_settings
+
+Отдельная переносимая библиотека для проектов ТВ-графики/vMix.
+
+Она отвечает за:
+
+- загрузку и сохранение `settings/settings.json`;
+- загрузку и сохранение `settings/vmix_json.json`;
+- загрузку справочника функций `settings/vmix_functions.json`;
+- сохранение выбранного соревнования/раунда или другой активной сущности;
+- backup настроек перед импортом;
+- универсальный импорт настроек из `.json`/`.zip` другого проекта;
+- миграцию старого формата лёгкой атлетики `vmixColumns`, `vmixTransforms`, `vmixRows`;
+- поиск и выдачу нужного vMix JSON-пресета.
+
+## Подключение в другом проекте
+
+Скопируй папку `broadcast_settings` в корень проекта.
+
+```python
+from pathlib import Path
+from broadcast_settings import settings as settings_lib
+
+PROJECT_DIR = Path(__file__).resolve().parent.parent
+APP_DIR = Path(__file__).resolve().parent
+
+settings_lib.configure(
+    project_dir=PROJECT_DIR,
+    app_dir=APP_DIR,
+)
+
+settings = settings_lib.read_settings()
+vmix_json = settings_lib.read_vmix_json()
+functions = settings_lib.read_vmix_functions()
+```
+
+Можно передать свои дефолтные настройки:
+
+```python
+settings_lib.configure(
+    project_dir=PROJECT_DIR,
+    app_dir=APP_DIR,
+    default_settings=MY_DEFAULT_SETTINGS,
+    default_vmix_json=MY_DEFAULT_VMIX_JSON,
+    default_vmix_functions=MY_DEFAULT_VMIX_FUNCTIONS,
+)
+```
+
+## Главные функции
+
+```python
+read_settings()
+write_settings(data)
+read_vmix_json()
+write_vmix_json(data)
+read_vmix_functions()
+write_vmix_functions(data)
+read_selection()
+write_selection(selection)
+get_vmix_config(key)
+settings_meta()
+make_settings_backup(reason)
+preview_settings_import(data, file_name)
+apply_settings_import(preview, ...)
+```
+
+В golf-проекте файл `app/settings_manager.py` теперь является только тонким адаптером,
+а вся логика находится здесь.
+
+## Portable joins / merge sources
+
+The reusable file `broadcast_settings/joins.py` provides a generic JSON join engine:
+
+```python
+from broadcast_settings.joins import apply_join_rules
+
+rows = apply_join_rules(base_rows, joins_config, source_resolver)
+```
+
+A project only needs to provide `source_resolver(join)`, which returns JSON/list rows for the requested source. The join config itself is portable and can be stored inside each vMix JSON config under the `joins` key.