# Spec Delta ## Purpose Давать приложениям общий контракт хранения бизнес-параметров и технических значений, которые должны меняться в runtime без рестарта. ## ADDED Requirements ### Requirement: Контракт хранения настроек **ID:** `CFG.AS-01` PLBA2 SHALL определять назначение полей и структуру таблицы для бизнес-параметров и технических значений, которыми приложение управляет в runtime. #### Scenario: Сокращенный use case: структура настроек ##### Основной поток 1. Фиксируем поля таблицы `settings`, их назначение и ограничения по [CFG.AS-01.FR-01](#cfgas-01fr-01-db-таблица-хранения-settings). #### Функциональные требования ##### CFG.AS-01.FR-01 [DB]: Таблица хранения settings Таблица `settings` создаётся в схеме приложения и содержит: | Поле | Тип | Ограничения и значение по умолчанию | Назначение | | --- | --- | --- | --- | | `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки | | `config_key` | `VARCHAR(128)` | NULL | Область или сущность приложения | | `setting_key` | `VARCHAR(128)` | NOT NULL | Имя настройки | | `setting_value` | `TEXT` | NOT NULL | Текстовое значение настройки | | `sort_order` | `INT` | NOT NULL, DEFAULT 0 | Порядок повторяющихся ключей | | `is_enabled` | `BOOLEAN` | NOT NULL, DEFAULT TRUE | Признак участия записи в чтении | | `description` | `TEXT` | NULL | Пояснение к настройке | Индексы поддерживают выборку по `setting_key`, `config_key`, `is_enabled` и порядок `sort_order`, `id`. Ограничение уникальности на `setting_key` не устанавливается. Приложение владеет DDL, данными и связями `config_key` со своими сущностями. В `settings` хранятся бизнес-параметры, feature toggles и технические значения, которые нужно менять удалённо во время работы приложения. Feature toggle хранится в `setting_value`; `is_enabled` только включает или исключает строку из чтения. Редко меняемые технические параметры задаются отдельным файлом `config.yaml`. ### Requirement: Загрузка настроек **ID:** `CFG.AS-02` Приложение SHALL загружать начальные настройки в собственную базу данных миграцией при установке или первой раскатке. #### Scenario: Загрузка начальных настроек ##### Участники - Миграция приложения и база данных приложения. ##### Предусловия - База данных приложения доступна для применения миграции. ##### Основной поток 1. Миграция создаёт нужное приложению хранилище по [CFG.AS-01.FR-01](#cfgas-01fr-01-db-таблица-хранения-settings). 2. Миграция записывает начальные значения непосредственно в базу приложения и завершается с `SETTINGS_LOADED` по [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки). ##### Альтернативы и ошибки - Миграция не может создать хранилище или записать значения — загрузка завершается с `SETTINGS_LOAD_FAILED` по [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки). ##### Результат Настройки приложения доступны в его базе до запуска использующего их кода. ##### Коды завершения | Код | Смысл | Связанные FR | | --- | --- | --- | | `SETTINGS_LOADED` | Миграция записала настройки в базу приложения | [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки) | | `SETTINGS_LOAD_FAILED` | Миграция не создала хранилище или не записала настройки | [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки) | #### Функциональные требования ##### CFG.AS-02.FR-01: Загрузка миграцией Приложение создаёт таблицу `settings` и загружает начальные значения собственными миграциями при первой раскатке. Последующие значения бизнес-параметров и технических параметров, меняемых удалённо, могут обновляться в БД без рестарта приложения. PLBA2 не запускает миграции, не управляет изменением строк и не переносит YAML-конфигурацию в `settings`; конфигурация из `config.yaml` является отдельным слоем. ##### CFG.AS-02.FR-02: Результат загрузки | Код | Текст сообщения | Дальнейшее поведение | | --- | --- | --- | | `SETTINGS_LOADED` | Сообщение отсутствует | Приложение может запускать компоненты, которым нужны загруженные настройки | | `SETTINGS_LOAD_FAILED` | Исходная ошибка миграции доступна инструменту установки | Раскатка не считается успешной; приложение исправляет причину и повторно применяет миграцию по правилам своего инструмента | ### Requirement: Чтение настроек **ID:** `CFG.AS-03` PLBA2 SHALL предоставлять типизированный контракт чтения настроек и PostgreSQL-адаптер, читающий данные из схемы приложения. #### Scenario: Чтение настроек приложения ##### Участники - Бизнес-модуль, SettingsReader, PostgreSQL-адаптер и база данных приложения. ##### Предусловия - Приложение объявило типизированный ключ с decoder и передало адаптеру пул PostgreSQL и имя своей схемы. ##### Основной поток 1. Запрашиваем включённые записи по ключу и, если задана, области `config_key` в порядке контракта по [CFG.AS-03.FR-02](#cfgas-03fr-02-postgresql-адаптер). 2. Декодируем значения и возвращаем их через SettingsReader с кодом `SETTING_READ` по [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения). ##### Альтернативы и ошибки - Нет обязательного значения — возвращаем `SETTING_NOT_FOUND`; decoder отклонил значение — `SETTING_INVALID`; PostgreSQL недоступен — `SETTINGS_DATABASE_UNAVAILABLE`, согласно [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения). ##### Результат Бизнес-код использует типизированный контракт независимо от конкретного адаптера хранения. ##### Коды завершения | Код | Смысл | Связанные FR | | --- | --- | --- | | `SETTING_READ` | Значения прочитаны и декодированы в исходном порядке | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) | | `SETTING_NOT_FOUND` | Отсутствует обязательная настройка | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) | | `SETTING_INVALID` | Значение не прошло decoder приложения | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) | | `SETTINGS_DATABASE_UNAVAILABLE` | Запрос к базе приложения завершился ошибкой | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) | #### Функциональные требования ##### CFG.AS-03.FR-01: Контракт SettingsReader SettingsReader принимает типизированный ключ настройки и необязательный `config_key`, возвращает упорядоченный список значений типа ключа. Для ключа приложение задаёт decoder и обязательность или default. Каждый вызов использует актуальное значение источника настроек; удалённое изменение применяется при следующем чтении без рестарта приложения. Бизнес-код зависит от контракта, а не от SQL или драйвера БД. ##### CFG.AS-03.FR-02: PostgreSQL-адаптер Адаптер читает `settings` схемы приложения через переданный приложением пул. Он фильтрует по `setting_key`, заданному `config_key` и `is_enabled = TRUE`, сохраняя порядок `sort_order`, затем `id`. Значения запроса параметризуются; имя схемы валидируется и безопасно экранируется. Адаптер не создаёт таблицу, не запускает миграции и не владеет настройками. ##### CFG.AS-03.FR-03: Результат чтения | Код | Текст сообщения | Дальнейшее поведение | | --- | --- | --- | | `SETTING_READ` | Сообщение отсутствует | Декодированные значения передаются приложению в порядке контракта | | `SETTING_NOT_FOUND` | Сообщение отсутствует | Для обязательного ключа возвращается типизированная ошибка; default применяется только по настройке ключа | | `SETTING_INVALID` | Сообщение отсутствует; исходная ошибка decoder доступна приложению | Значение не выдаётся как успешно прочитанное | | `SETTINGS_DATABASE_UNAVAILABLE` | Сообщение отсутствует; исходная ошибка драйвера передаётся приложению | PLBA2 не подменяет ошибку default-значением и не выполняет скрытый retry |