12 KiB
Capability: Хранение и чтение настроек приложения
Purpose
Давать приложениям общий контракт хранения бизнес-параметров и технических значений, которые должны меняться в runtime без рестарта.
Границы
- В capability входят контракт таблицы settings, начальная загрузка миграцией приложения и типизированное чтение через PostgreSQL adapter. Таблицы и данные принадлежат приложению.
Requirements
Requirement: Контракт хранения настроек
ID: CFG.AS-01
PLBA2 SHALL определять назначение полей и структуру таблицы для бизнес-параметров и технических значений, которыми приложение управляет в runtime.
Scenario: Сокращенный use case: структура настроек
Основной поток
- Фиксируем поля таблицы
settings, их назначение и ограничения по CFG.AS-01.FR-01.
Функциональные требования
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: Загрузка начальных настроек
Участники
- Миграция приложения и база данных приложения.
Предусловия
- База данных приложения доступна для применения миграции.
Основной поток
- Миграция создаёт нужное приложению хранилище по CFG.AS-01.FR-01.
- Миграция записывает начальные значения непосредственно в базу приложения и завершается с
SETTINGS_LOADEDпо CFG.AS-02.FR-02.
Альтернативы и ошибки
- Миграция не может создать хранилище или записать значения — загрузка завершается с
SETTINGS_LOAD_FAILEDпо CFG.AS-02.FR-02.
Результат
Настройки приложения доступны в его базе до запуска использующего их кода.
Коды завершения
| Код | Смысл | Связанные FR |
|---|---|---|
SETTINGS_LOADED |
Миграция записала настройки в базу приложения | CFG.AS-02.FR-02 |
SETTINGS_LOAD_FAILED |
Миграция не создала хранилище или не записала настройки | CFG.AS-02.FR-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 и имя своей схемы.
Основной поток
- Запрашиваем включённые записи по ключу и, если задана, области
config_keyв порядке контракта по CFG.AS-03.FR-02. - Декодируем значения и возвращаем их через SettingsReader с кодом
SETTING_READпо CFG.AS-03.FR-03.
Альтернативы и ошибки
- Нет обязательного значения — возвращаем
SETTING_NOT_FOUND; decoder отклонил значение —SETTING_INVALID; PostgreSQL недоступен —SETTINGS_DATABASE_UNAVAILABLE, согласно CFG.AS-03.FR-03.
Результат
Бизнес-код использует типизированный контракт независимо от конкретного адаптера хранения.
Коды завершения
| Код | Смысл | Связанные FR |
|---|---|---|
SETTING_READ |
Значения прочитаны и декодированы в исходном порядке | CFG.AS-03.FR-03 |
SETTING_NOT_FOUND |
Отсутствует обязательная настройка | CFG.AS-03.FR-03 |
SETTING_INVALID |
Значение не прошло decoder приложения | CFG.AS-03.FR-03 |
SETTINGS_DATABASE_UNAVAILABLE |
Запрос к базе приложения завершился ошибкой | CFG.AS-03.FR-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 |