Files
T

11 KiB
Raw Blame History

Spec Delta

Purpose

Давать приложениям общий контракт хранения бизнес-параметров и технических значений, которые должны меняться в runtime без рестарта.

ADDED Requirements

Requirement: Контракт хранения настроек

ID: CFG.AS-01

PLBA2 SHALL определять назначение полей и структуру таблицы для бизнес-параметров и технических значений, которыми приложение управляет в runtime.

Scenario: Сокращенный use case: структура настроек

Основной поток
  1. Фиксируем поля таблицы 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: Загрузка начальных настроек

Участники
  • Миграция приложения и база данных приложения.
Предусловия
  • База данных приложения доступна для применения миграции.
Основной поток
  1. Миграция создаёт нужное приложению хранилище по CFG.AS-01.FR-01.
  2. Миграция записывает начальные значения непосредственно в базу приложения и завершается с 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 и имя своей схемы.
Основной поток
  1. Запрашиваем включённые записи по ключу и, если задана, области config_key в порядке контракта по CFG.AS-03.FR-02.
  2. Декодируем значения и возвращаем их через 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