Files
plba_v2/openspec/specs/configuration/application-config-file/spec.md
T
alex d517820088
PLBA package CI / Python tests (push) Failing after 2s
PLBA package CI / Package version increment (push) Skipped
PLBA2-2. Архивация спек
2026-10-10 20:55:13 +03:00

104 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Capability: Файл технической конфигурации приложения
## Purpose
Предоставлять приложению загрузчик редко меняемых технических параметров из `config.yaml` с поддержкой перезагрузки без рестарта.
## Границы
- В capability входят начальная загрузка технических параметров из корневого config.yaml и атомарное применение валидных изменений без рестарта. Бизнес-настройки и удалённо меняемые runtime-значения относятся к configuration/application-settings.
## Requirements
### Requirement: Загрузка технической конфигурации из файла
**ID:** `CFG.ACF-01`
PLBA2 SHALL загружать техническую конфигурацию приложения из `config.yaml` в корне приложения и предоставлять её в типизированном виде до запуска компонентов, которые от неё зависят.
#### Scenario: Начальная загрузка технической конфигурации
##### Участники
- Приложение, загрузчик YAML-конфигурации и файл `config.yaml`.
##### Предусловия
- В корне приложения находится `config.yaml`; приложение объявило типизированную модель своей конфигурации.
##### Основной поток
1. Загрузчик читает `config.yaml` и проверяет его по модели приложения.
2. Загрузчик предоставляет приложению типизированную конфигурацию до запуска зависимых компонентов и сообщает `APP_CONFIG_LOADED` по [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки).
##### Альтернативы и ошибки
- Файл отсутствует, содержит некорректный YAML или не соответствует модели — запуск приложения завершается с `APP_CONFIG_LOAD_FAILED` по [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки).
##### Результат
Зависимые компоненты получают техническую конфигурацию приложения из валидного файла.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APP_CONFIG_LOADED` | Файл прочитан, проверен и предоставлен приложению | [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки) |
| `APP_CONFIG_LOAD_FAILED` | Файл отсутствует или не соответствует формату либо модели приложения | [CFG.ACF-01.FR-02](#cfgacf-01fr-02-результат-загрузки) |
#### Функциональные требования
##### CFG.ACF-01.FR-01: Файл и модель технической конфигурации
Стандартный файл называется `config.yaml` и располагается в корне приложения. PLBA2 определяет общее необязательное строковое поле `application_id` и поля workers: `workers.<worker_name>.disabled` (boolean, по умолчанию `false`), `workers.<worker_name>.interval_seconds` и `workers.<worker_name>.pause_seconds`. При `disabled: true` worker не запускается; если поле не задано, worker запускается. Остальные поля YAML и типизированную модель приложения определяет само приложение. В файле находятся редко меняемые технические параметры приложения. Бизнес-параметры, feature toggles и технические значения, которые требуется менять удалённо во время работы приложения, хранятся через capability `configuration/application-settings` в таблице `settings` и не входят в `config.yaml`.
##### CFG.ACF-01.FR-02: Результат загрузки
Загрузчик разбирает YAML по типизированной модели приложения и предоставляет проверенную конфигурацию до запуска зависимых компонентов. При отсутствии файла, ошибке разбора или ошибке проверки модели возвращается `APP_CONFIG_LOAD_FAILED`, запуск приложения прекращается. Успешная загрузка завершается с `APP_CONFIG_LOADED`.
### Requirement: Перезагрузка технической конфигурации без рестарта
**ID:** `CFG.ACF-02`
PLBA2 SHALL подхватывать валидные изменения `config.yaml` во время работы приложения без перезапуска процесса.
#### Scenario: Изменение технической конфигурации во время работы
##### Участники
- Приложение, загрузчик YAML-конфигурации и файл `config.yaml`.
##### Предусловия
- Приложение работает с успешно загруженной технической конфигурацией.
##### Основной поток
1. Загрузчик обнаруживает изменение `config.yaml` и проверяет новое содержимое по модели приложения.
2. Валидная конфигурация заменяет текущую; последующие чтения получают новое значение без рестарта, операция завершается с `APP_CONFIG_RELOADED` по [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки).
##### Альтернативы и ошибки
- Новое содержимое невалидно — приложение продолжает использовать последнюю валидную конфигурацию, а загрузчик сообщает `APP_CONFIG_RELOAD_FAILED` по [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки).
##### Результат
После успешной перезагрузки новые чтения используют обновлённую конфигурацию; процесс приложения продолжает работу без рестарта.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APP_CONFIG_RELOADED` | Новая валидная конфигурация активирована без рестарта | [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки) |
| `APP_CONFIG_RELOAD_FAILED` | Изменённый файл не прошёл проверку; активна последняя валидная конфигурация | [CFG.ACF-02.FR-02](#cfgacf-02fr-02-результат-перезагрузки) |
#### Функциональные требования
##### CFG.ACF-02.FR-01: Замена активной конфигурации
Загрузчик обнаруживает изменения файла и проверяет их по модели приложения. После успешной проверки он атомарно заменяет текущую конфигурацию; все последующие чтения получают новую конфигурацию, а уже полученные снимки остаются неизменными. Перезапуск приложения не требуется.
##### CFG.ACF-02.FR-02: Результат перезагрузки
Успешная проверка и замена завершаются с `APP_CONFIG_RELOADED`. Если файл не читается, YAML не разбирается или новое содержимое не соответствует модели, загрузчик оставляет активной последнюю валидную конфигурацию, сообщает приложению ошибку и завершает попытку с `APP_CONFIG_RELOAD_FAILED`.