PLBA2-2. Архивация спек
This commit is contained in:
@@ -0,0 +1,149 @@
|
||||
# Capability: Хранение и чтение настроек приложения
|
||||
|
||||
## Purpose
|
||||
|
||||
Давать приложениям общий контракт хранения бизнес-параметров и технических значений, которые должны меняться в runtime без рестарта.
|
||||
|
||||
## Границы
|
||||
|
||||
- В capability входят контракт таблицы settings, начальная загрузка миграцией приложения и типизированное чтение через PostgreSQL adapter. Таблицы и данные принадлежат приложению.
|
||||
|
||||
## 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 |
|
||||
Reference in New Issue
Block a user