PLBA2-1. Спецификация

This commit is contained in:
2026-10-10 18:19:37 +03:00
commit c540f591b9
37 changed files with 3921 additions and 0 deletions
View File
@@ -0,0 +1,2 @@
schema: function-driven
created: 2026-10-09
@@ -0,0 +1,97 @@
# Design
## Context
PLBA2 — Python-библиотека компонентов и runtime. Приложение владеет entrypoint, composition root, бизнес-логикой, рабочими сообщениями, схемой БД и HTTP host. PLBA2 предоставляет десять capabilities из [proposal.md](proposal.md). Реализации PLBA v1 служат ориентиром для worker, health, workflow и бизнес trace контрактов.
## Goals / Non-Goals
**Goals:**
- Запускать несколько независимо выполняемых workers с уникальными именами; управлять ими только через lifecycle всего приложения.
- Дать приложению единые contracts для lifecycle, health, workflow, HTTP API, identity, двух слоёв конфигурации и business trace.
- Разделить персистентную бизнес-историю и технический вывод в stdout.
- Поддержать замену PostgreSQL settings adapter без изменения кода, использующего SettingsReader.
**Non-Goals:**
- Не создавать entrypoint, composition root, HTTP server, сервис настроек или API business history.
- Не предоставлять общую очередь, RabbitMQ consumer/producer для рабочих заданий, outbox или retry framework.
- Не управлять миграциями приложения, доставкой stdout логов или бизнес-правилами workflow.
## Decisions
### Runtime и workers
- Capability `runtime/worker` отвечает за имена, независимый lifecycle, расписание, внутреннюю остановку и health отдельных workers.
- Capability `runtime/application-lifecycle` управляет запуском и остановкой приложения; при запуске стартуют все workers без `disabled: true`. Отдельного API для запуска или остановки worker нет. Runtime не завершает принадлежащий приложению OS process или HTTP host.
- При обычной остановке каждый worker завершает текущий цикл и не начинает следующий; `force=true` прерывает активную обработку. Приложение становится `stopped` после остановки всех workers.
- `timeout_seconds` ограничивает только ожидание HTTP-вызова. При его истечении возвращается `stopping`, а остановка продолжается; отсутствие timeout означает неограниченное ожидание.
- Worker читает признак запуска из `workers.<worker_name>.disabled` и расписание из `workers.<worker_name>.interval_seconds` или `pause_seconds` в `config.yaml`. Отсутствующий `disabled` эквивалентен `false`; изменение признака во время работы вступает в силу при следующем запуске приложения.
- Интервал задаёт период между началами циклов, пауза — стабильное ожидание после каждого цикла; активные изменения расписания применяются при планировании следующего цикла.
- Исключение цикла не завершает worker. Runtime выставляет автоматический health status; прикладная health-логика добавляет собственные условия, а `critical` ограничивает влияние worker по правилам health aggregation.
### Health
- Сохраняется v1 модель worker health и агрегация `ok`, `degraded`, `unhealthy`.
- Health report содержит application_id, runtime state и health-состояния запущенных workers; contributors вычисляют собственное состояние. Некритичный компонент может ухудшить aggregate до `degraded`, но не до `unhealthy` по HL.AG-01.FR-01.
- Worker с `disabled: true` исключается из набора ожидаемых компонентов.
- Если runtime lifecycle приложения `stopped`, aggregate health возвращает `stopped`.
### Единый HTTP API
- PLBA2 предоставляет один router для health и lifecycle всего приложения; общий adapter описан в [API.HTTP.CA-01](specs/api/http/control-api/spec.md), отдельные endpoints — в своих Requirements.
- Приложение подключает router к одному HTTP host и listener. Все routes используют один порт; capabilities не запускают собственные серверы.
- HTTP слой делегирует расчёт health capability HL.AG-01 и управление приложением — RT.AL-01–RT.AL-02. Отдельных worker routes нет; состояния запущенных workers доступны в агрегированном health-отчёте.
### Workflow
- Сохраняется object-based API PLBA v1: WorkflowDefinition, WorkflowNode, WorkflowStep, WorkflowContext и StepResult.
- Engine применяет только объявленные переходы, сохраняет ход выполнения через WorkflowPersistence и передаёт исключения вызывающему приложению.
- Рабочие сообщения, retries и предметные решения остаются у приложения.
### Идентификатор приложения
- Необязательное `application_id` задаётся в корневом `config.yaml`. Если оно отсутствует или пустое, runtime берёт `[project].name` из `pyproject.toml`, а при недоступности метаданных генерирует UUIDv4.
- Идентификатор разрешается до старта зависимых компонентов, предоставляется runtime-контексту и не меняется в течение процесса. Health и логирование используют его согласно требованиям своих capabilities.
### Настройки
- CFG.AS-01 описывает таблицу `settings` для бизнес-параметров, feature toggles и технических значений, которые требуется менять удалённо в runtime.
- По CFG.AS-02 приложение создаёт таблицу и загружает начальные значения собственными миграциями. Дальнейшие обновления строк выполняются владельцем приложения; PLBA2 не запускает миграции и не предоставляет сервис изменения конфигурации.
- По CFG.AS-03 типизированный SettingsReader читает актуальные значения. Изменения в БД становятся доступны при следующем чтении без рестарта приложения; PostgreSQL adapter фильтрует строки и сортирует их по `sort_order`, `id`.
### Техническая конфигурация из файла
- CFG.ACF-01 читает `config.yaml` из корня приложения. PLBA2 задаёт общее необязательное поле `application_id`, `workers.<worker_name>.disabled` (по умолчанию `false`) и поля расписания `workers.<worker_name>.interval_seconds` / `workers.<worker_name>.pause_seconds`; остальные поля и типизированную модель файла определяет приложение.
- Локальный file provider заменяет текущую модель удалённых configuration snapshots; отдельный configuration-service и сетевой client не входят в PLBA2.
- Файл хранит редко меняемые технические параметры. Бизнес-параметры, feature toggles и технические значения для удалённых runtime-изменений находятся в таблице `settings`.
- CFG.ACF-02 обнаруживает изменения файла и атомарно заменяет активную конфигурацию после проверки. Последующие чтения получают новый снимок; уже полученные снимки не мутируют.
- Ошибка начальной загрузки блокирует запуск зависимых компонентов. При невалидном runtime-изменении сохраняется последний валидный снимок и приложению сообщается ошибка.
- Реализация требует YAML parser; механизм обнаружения изменения файла остаётся деталью адаптера и не входит в публичный контракт.
### Business trace и технические логи
- Business trace adapter пишет контексты и сообщения в `trace_contexts` и `trace_messages` схемы приложения; `application_id` входит в `attrs_json` контекста и каждого сообщения, без добавления колонок; migration приложения создаёт обе таблицы.
- В публичном контракте используется `business_trace_id`, в совместимой схеме таблиц — поле `trace_id`.
- Бизнес-события не публикуются через RabbitMQ. Чтение истории и API истории не входят в эту capability.
- Technical logger формирует JSON с фиксированными полями и пишет в stdout; platform agent отвечает за доставку и просмотр.
## Risks / Trade-offs
- Отсутствие индивидуального worker API упрощает управление приложением; уникальные имена нужны для конфигурации, регистрации и health.
- Повторяющиеся setting keys требуют упорядоченного списка значений; adapter не сводит их к одной строке.
- Приложению нужно подключить один route bundle и включить миграции до запуска адаптеров.
- Изменение публичных контрактов текущего скелета требует отдельной версии PLBA2 и осознанной миграции потребителей.
## Migration Plan
1. Реализовать core contracts для application identity, worker runtime, health, workflow, двух слоёв конфигурации и business trace.
2. Добавить YAML loader dependency и PostgreSQL adapters; не добавлять RabbitMQ extra.
3. Включить создание `settings`, `trace_contexts` и `trace_messages` в первые миграции каждого приложения.
4. Перевести приложения на named workers, единый route bundle, SettingsReader, business trace adapter и JSON stdout formatter.
5. Выпустить новую major-версию; при откате вернуть предыдущую версию пакета, не удаляя данные приложений.
## Open Questions
Нет. HTTP host и единственный listener остаются у приложения; PLBA2 отдаёт подключаемый router.
@@ -0,0 +1,29 @@
# Proposal
## Summary
Подготовить PLBA2 — библиотеку Python-компонентов и runtime для приложений. Каждое приложение сохраняет собственный entrypoint, composition root, бизнес-логику и интеграции.
## Scope
- Добавить runtime для lifecycle всего приложения и независимого исполнения именованных workers. API управляет приложением целиком; выборочные операции запуска и остановки worker не предоставляются.
- Задавать расписание и признак запуска worker в техническом `config.yaml`; если `disabled` отсутствует, worker запускается.
- Сохранить contracts workers, health, workflow, application identity, DB-backed settings, business trace и технического JSON logging.
- Предоставить единый подключаемый HTTP router для health и управления приложением.
## Capabilities
- `runtime/application-lifecycle`: запуск и остановка приложения, включая таймаут ожидания и принудительную остановку.
- `runtime/worker`: независимое циклическое выполнение именованных workers, расписание, health и контролируемая остановка в составе приложения.
- `health/aggregation`: единый health-отчёт приложения и его активных компонентов.
- `api/http/control-api`: единый HTTP API health и lifecycle приложения на host приложения.
- `runtime/application-identity`: стабильный идентификатор приложения.
- `configuration/application-config-file`: загрузка и перезагрузка технических настроек из корневого `config.yaml`.
- `configuration/application-settings`: чтение бизнес-настроек и runtime-параметров из таблицы `settings` схемы приложения.
- `workflow/orchestration`: orchestration workflow по contracts PLBA v1.
- `observability/business-tracing`: запись бизнес-истории в таблицы схемы приложения.
- `observability/technical-logging`: структурированные технические JSON-логи в stdout.
## Out of scope
PLBA2 не становится приложением или развёртываемым сервисом, не владеет entrypoint, HTTP host, рабочими RabbitMQ messages, миграциями приложения, configuration-service, API бизнес-истории или доставкой технических логов.
@@ -0,0 +1,280 @@
# Spec Delta
## Purpose
Объединить health и управление lifecycle приложения в одном HTTP API, подключаемом к host приложения.
## ADDED Requirements
### Requirement: Единый HTTP adapter
**ID:** `API.HTTP.CA-01`
PLBA2 SHALL предоставлять один route adapter для всех HTTP endpoints управления приложением; adapter подключается к host приложения и использует его единственный listener.
#### Scenario: Сокращенный use case: подключение control API
##### Основной поток
1. Приложение подключает route adapter к своему host по [API.HTTP.CA-01.FR-01](#apihttpca-01fr-01-подключение-к-host-приложения).
#### Функциональные требования
##### API.HTTP.CA-01.FR-01: Подключение к host приложения
Приложение подключает route adapter к собственному HTTP host. Все endpoints control API используют его listener и порт. PLBA2 не запускает HTTP server и не открывает отдельный порт; adapter делегирует обработку соответствующим capabilities.
### Requirement: Health через GET /health
**ID:** `API.HTTP.CA-02`
PLBA2 SHALL возвращать агрегированный health report приложения через GET /health.
#### Scenario: Получение health-отчёта через GET /health
##### Участники
- HTTP-клиент, route adapter PLBA2 и health aggregator.
##### Предусловия
- Control API подключён к host приложения.
- Health aggregator получает состояния зарегистрированных workers и contributors.
##### Основной поток
1. Клиент вызывает GET /health; adapter получает запрос.
2. Adapter запрашивает агрегированный health report по [HL.AG-01.FR-01](../../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов).
3. Adapter сериализует report по [API.HTTP.CA-02.FR-01](#apihttpca-02fr-01-сериализация-health-отчёта) и завершает с HEALTH_RESPONSE_RETURNED.
##### Альтернативы и ошибки
- Aggregator отклоняет некорректное состояние компонента — adapter передаёт ошибку с кодом HEALTH_INPUT_INVALID по [API.HTTP.CA-02.FR-02](#apihttpca-02fr-02-ошибка-источника-health).
##### Результат
Клиент получает текущий агрегированный health status, lifecycle и состояния компонентов приложения.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `HEALTH_RESPONSE_RETURNED` | Агрегированный health report сериализован и возвращён клиенту | [API.HTTP.CA-02.FR-01](#apihttpca-02fr-01-сериализация-health-отчёта) |
| `HEALTH_INPUT_INVALID` | Aggregator отклонил некорректное состояние компонента | [API.HTTP.CA-02.FR-02](#apihttpca-02fr-02-ошибка-источника-health) |
#### Функциональные требования
##### API.HTTP.CA-02.FR-01: Сериализация health-отчёта
Adapter возвращает без пересчёта агрегированный health report, включая application_id, lifecycle, итоговый status и состояния компонентов; при успешной сериализации завершает с HEALTH_RESPONSE_RETURNED. Правила агрегирования и состав report задаёт [HL.AG-01](../../../health/aggregation/spec.md).
##### API.HTTP.CA-02.FR-02: Ошибка источника health
Если health aggregator отклоняет входное состояние, adapter передаёт ошибку HEALTH_INPUT_INVALID и не подменяет причину или повторно не рассчитывает статусы.
#### CONTRACT
##### Request
Метод: `GET`; путь: `/health`. Тело запроса и query-параметры отсутствуют.
##### Response
HTTP status: 200 при успешной сериализации health report.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `application_id` | `string` | Обязательное | null запрещён | Идентификатор приложения | Берётся из runtime context по [RT.AI-01.FR-01](../../../runtime/application-identity/spec.md#rtai-01fr-01-разрешение-идентификатора) |
| `lifecycle` | `string` | Обязательное | new, starting, running, stopping, stopped или failed; null запрещён | Lifecycle приложения | Копируется из runtime state по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки) |
| `status` | `string` | Обязательное | ok, degraded, unhealthy или stopped; null запрещён | Итоговый health status приложения | Рассчитывается aggregator согласно [HL.AG-01.FR-01](../../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов) и [HL.AG-01.FR-02](../../../health/aggregation/spec.md#hlag-01fr-02-результат-агрегации) |
| `components` | `array<object>` | Обязательное | null запрещён; пустой массив допустим | Health-состояния workers и contributors | Содержит состояния, переданные aggregator; workers с disabled: true исключены |
| `components[].name` | `string` | Обязательное | null запрещён | Имя worker или health contributor | Копируется из имени, с которым компонент зарегистрирован в приложении |
| `components[].status` | `string` | Обязательное | ok, degraded или unhealthy; null запрещён | Health status компонента | Копируется из переданного компонентом health-состояния |
| `components[].critical` | `boolean` | Обязательное | null запрещён | Влияние компонента на общий health | Копируется из признака critical, переданного при регистрации или health-отчёте |
| `components[].detail` | `string or null` | Обязательное | null допустим | Краткое пояснение состояния | Копируется из detail health-состояния; при отсутствии передаётся null |
| `components[].meta` | `object` | Обязательное | null запрещён | Дополнительные структурированные данные | Копируется из meta health-состояния; при отсутствии передаётся пустой объект |
### Requirement: Запуск приложения через POST /runtime/start
**ID:** `API.HTTP.CA-03`
PLBA2 SHALL запускать приложение по запросу POST /runtime/start и возвращать итоговый lifecycle status.
#### Scenario: Запуск приложения через POST /runtime/start
##### Участники
- HTTP-клиент, route adapter PLBA2, runtime и workers приложения.
##### Предусловия
- Control API подключён, workers зарегистрированы, конфигурация приложения загружена.
##### Основной поток
1. Клиент вызывает POST /runtime/start без тела запроса.
2. Adapter запускает приложение по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения).
3. Adapter возвращает итоговый lifecycle status по [API.HTTP.CA-03.FR-01](#apihttpca-03fr-01-результат-запуска) и завершает с APPLICATION_STARTED.
##### Альтернативы и ошибки
- Не удалось запустить один или несколько workers — runtime получает status failed, adapter возвращает его с кодом APPLICATION_START_FAILED по [API.HTTP.CA-03.FR-02](#apihttpca-03fr-02-ошибка-запуска).
##### Результат
Клиент получает lifecycle status после попытки запуска приложения.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STARTED` | Приложение перешло в lifecycle status running | [API.HTTP.CA-03.FR-01](#apihttpca-03fr-01-результат-запуска) |
| `APPLICATION_START_FAILED` | Запуск приложения завершился ошибкой; lifecycle status равен failed | [API.HTTP.CA-03.FR-02](#apihttpca-03fr-02-ошибка-запуска) |
#### Функциональные требования
##### API.HTTP.CA-03.FR-01: Результат запуска
Adapter делегирует запуск runtime по [RT.AL-01](../../../runtime/application-lifecycle/spec.md), возвращает APPLICATION_STARTED после успешного запуска и lifecycle status running.
##### API.HTTP.CA-03.FR-02: Ошибка запуска
Если запуск одного или нескольких workers завершается ошибкой, runtime устанавливает status failed; adapter возвращает APPLICATION_START_FAILED и status failed.
#### CONTRACT
##### Request
Метод: `POST`; путь: `/runtime/start`. Тело запроса отсутствует.
##### Response
HTTP status: 200 после обработки запроса запуска; результат запуска передаётся в поле status.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `status` | `string` | Обязательное | running или failed; null запрещён | Итоговый lifecycle status после запуска | running после APPLICATION_STARTED; failed после APPLICATION_START_FAILED |
### Requirement: Остановка приложения через POST /runtime/stop
**ID:** `API.HTTP.CA-04`
PLBA2 SHALL останавливать приложение через POST /runtime/stop и возвращать его актуальный lifecycle status.
#### Scenario: Остановка приложения через POST /runtime/stop
##### Участники
- HTTP-клиент, route adapter PLBA2, runtime, supervisor и workers приложения.
##### Предусловия
- Control API подключён, приложение запущено, workers зарегистрированы.
##### Основной поток
1. Клиент передаёт параметры остановки в теле POST /runtime/stop.
2. Adapter валидирует запрос и делегирует остановку по [RT.AL-02.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-02fr-01-режимы-остановки-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки).
3. Adapter возвращает stopped или stopping по [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) с кодом APPLICATION_STOPPED или APPLICATION_STOPPING.
##### Альтернативы и ошибки
- Таймаут ожидания истёк — остановка продолжается, adapter возвращает HTTP 202 и APPLICATION_STOPPING.
- Тело или значение timeout невалидно — adapter возвращает HTTP 400 с кодом HTTP_CONTROL_REJECTED по [API.HTTP.CA-04.FR-01](#apihttpca-04fr-01-валидация-запроса-остановки).
##### Результат
Клиент получает status stopped после завершения workers либо stopping, пока приложение завершает их работу.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STOPPED` | Все workers остановлены; ответ содержит stopped | [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) |
| `APPLICATION_STOPPING` | Остановка продолжается после истечения времени ожидания API | [API.HTTP.CA-04.FR-02](#apihttpca-04fr-02-результат-остановки) |
| `HTTP_CONTROL_REJECTED` | Параметры stop-запроса отклонены | [API.HTTP.CA-04.FR-01](#apihttpca-04fr-01-валидация-запроса-остановки) |
#### Функциональные требования
##### API.HTTP.CA-04.FR-01: Валидация запроса остановки
Adapter принимает объект запроса по контракту ниже; невалидное тело или значение timeout_seconds отклоняется с HTTP 400 и кодом HTTP_CONTROL_REJECTED. Правила остановки определяет [RT.AL-02](../../../runtime/application-lifecycle/spec.md).
##### API.HTTP.CA-04.FR-02: Результат остановки
Без timeout_seconds adapter ожидает завершения всех workers без ограничения времени. force=true прерывает активную обработку; timeout ограничивает ожидание ответа и не включает force. Если workers завершились, adapter возвращает HTTP 200, status stopped и APPLICATION_STOPPED. При истечении timeout он возвращает HTTP 202, status stopping и APPLICATION_STOPPING; остановка продолжается.
#### CONTRACT
##### Request
Метод: `POST`; путь: `/runtime/stop`. Тело запроса — JSON object.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- | --- |
| `force` | `boolean` | Опциональное | null запрещён; по умолчанию false | Принудительно прервать активную обработку workers |
| `timeout_seconds` | `number` | Опциональное | Положительное число секунд; null запрещён; отсутствие означает неограниченное ожидание | Ограничить время ожидания завершения workers |
##### Response
HTTP status: 200, если остановка завершена; 202, если она продолжается после истечения timeout; 400 для отклонённого запроса.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `status` | `string` | Обязательное | Для HTTP 200 — stopped; для HTTP 202 — stopping; null запрещён | Текущий lifecycle status приложения | Берётся из runtime: stopped после остановки всех workers; stopping, пока их остановка продолжается |
### Requirement: Lifecycle status через GET /runtime/status
**ID:** `API.HTTP.CA-05`
PLBA2 SHALL возвращать текущее lifecycle status приложения через GET /runtime/status.
#### Scenario: Чтение lifecycle status через GET /runtime/status
##### Участники
- HTTP-клиент, route adapter PLBA2 и runtime приложения.
##### Предусловия
- Control API подключён к host приложения.
##### Основной поток
1. Клиент вызывает GET /runtime/status.
2. Adapter читает lifecycle status без запуска или остановки компонентов по [API.HTTP.CA-05.FR-01](#apihttpca-05fr-01-чтение-lifecycle-status).
3. Adapter возвращает status с кодом APPLICATION_STATUS_RETURNED.
##### Альтернативы и ошибки
- Приложение ещё не запускалось или уже остановлено — endpoint возвращает соответственно new или stopped.
##### Результат
Клиент получает текущее lifecycle status приложения без изменения его состояния.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STATUS_RETURNED` | Текущее lifecycle status сериализовано и возвращено клиенту | [API.HTTP.CA-05.FR-01](#apihttpca-05fr-01-чтение-lifecycle-status) |
#### Функциональные требования
##### API.HTTP.CA-05.FR-01: Чтение lifecycle status
Adapter читает status без побочных действий и завершает с APPLICATION_STATUS_RETURNED по [RT.AL-01](../../../runtime/application-lifecycle/spec.md) и [RT.AL-02](../../../runtime/application-lifecycle/spec.md).
#### CONTRACT
##### Request
Метод: `GET`; путь: `/runtime/status`. Тело запроса и query-параметры отсутствуют.
##### Response
HTTP status: 200 при успешном чтении lifecycle status.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `status` | `string` | Обязательное | new, starting, running, stopping, stopped или failed; null запрещён | Текущее lifecycle status приложения | Копируется без пересчёта из runtime state по [RT.AL-01.FR-01](../../../runtime/application-lifecycle/spec.md#rtal-01fr-01-запуск-и-состояния-приложения) и [RT.AL-02.FR-02](../../../runtime/application-lifecycle/spec.md#rtal-02fr-02-ожидание-и-статус-остановки) |
@@ -0,0 +1,99 @@
# Spec Delta
## Purpose
Предоставлять приложению загрузчик редко меняемых технических параметров из `config.yaml` с поддержкой перезагрузки без рестарта.
## ADDED 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`.
@@ -0,0 +1,145 @@
# 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 |
@@ -0,0 +1,58 @@
# Spec Delta
## Purpose
Агрегировать текущий health приложения из runtime, workers и health contributors.
## ADDED Requirements
### Requirement: Агрегация health-состояния
**ID:** `HL.AG-01`
Health aggregator SHALL формировать единый отчёт по lifecycle приложения и текущему состоянию компонентов.
#### Scenario: Получение health-отчёта
##### Участники
- Приложение, runtime, workers и health contributors.
##### Предусловия
- Каждый worker и contributor предоставляет состояние по health-контракту.
##### Основной поток
1. Собираем состояния runtime и компонентов — aggregator формирует отчёт по [HL.AG-01.FR-01](#hlag-01fr-01-состав-и-приоритет-статусов).
2. Рассчитываем общий статус и завершаем с `HEALTH_REPORT_CREATED` по [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации).
##### Альтернативы и ошибки
- Входной статус не соответствует контракту — возвращаем `HEALTH_INPUT_INVALID` по [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации).
##### Результат
Приложение получает единый статус и детализацию состояния каждого запущенного worker.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `HEALTH_REPORT_CREATED` | Отчёт сформирован из валидных состояний | [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации) |
| `HEALTH_INPUT_INVALID` | Состояние не соответствует health-контракту | [HL.AG-01.FR-02](#hlag-01fr-02-результат-агрегации) |
#### Функциональные требования
##### HL.AG-01.FR-01: Состав и приоритет статусов
Worker сообщает status, critical, detail и meta через health-контракт. Отчёт содержит application_id, lifecycle приложения и состояния каждого запущенного worker/contributor. Worker с `disabled: true` исключён из набора ожидаемых компонентов и не ухудшает health. Статусы упорядочены как `ok < degraded < unhealthy`; применяется худший итоговый статус. Для критичного компонента учитывается переданный status. Для некритичного компонента `unhealthy` ограничивается до `degraded`; отсутствие некритичного worker также даёт не ниже `degraded`. Отсутствующий критичный worker даёт `unhealthy`. Lifecycle `new` и `failed` даёт `unhealthy`, `starting` и `stopping` — не ниже `degraded`. Когда lifecycle приложения `stopped`, общий health status — `stopped` независимо от прежних статусов компонентов.
##### HL.AG-01.FR-02: Результат агрегации
Health-статус является данными. Валидные агрегированные `ok`, `degraded`, `unhealthy` и `stopped` возвращаются в отчёте; `stopped` обозначает lifecycle приложения, а статусы запущенных worker/contributor остаются `ok`, `degraded` или `unhealthy`. Ошибка появляется только при нарушении контракта входного состояния.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `HEALTH_REPORT_CREATED` | Сообщение отсутствует | Отчёт возвращается вызывающему коду для представления клиенту |
| `HEALTH_INPUT_INVALID` | Сообщение отсутствует; ошибка контракта передаётся вызывающему коду | Отчёт не формируется; приложение исправляет contributor |
@@ -0,0 +1,86 @@
# Spec Delta
## Purpose
Сохранять ход бизнес-операций в trace_contexts и trace_messages схемы приложения.
## ADDED Requirements
### Requirement: Персистентная бизнес-история
**ID:** `OBS.BT-01`
PLBA2 SHALL предоставлять приложению контракт и PostgreSQL-адаптер для записи бизнес-контекстов и сообщений в БД приложения.
#### Scenario: Запись сообщения бизнес-операции
##### Участники
- Прикладной workflow, business trace adapter и схема БД приложения.
##### Предусловия
- Приложение установило business trace context и передало адаптеру пул PostgreSQL и схему приложения.
##### Основной поток
1. Создаём контекст — адаптер сохраняет его в `trace_contexts` по [OBS.BT-01.FR-01](#obsbt-01fr-01-db-таблица-хранения-tracecontexts).
2. Записываем шаг операции — адаптер сохраняет сообщение в `trace_messages` по [OBS.BT-01.FR-02](#obsbt-01fr-02-db-таблица-хранения-tracemessages) и завершает с `BUSINESS_TRACE_WRITTEN` по [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи).
##### Альтернативы и ошибки
- PostgreSQL недоступен или запись не выполнена — исходная ошибка передаётся приложению с `BUSINESS_TRACE_WRITE_FAILED` по [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи).
##### Результат
Бизнес-события сохранены отдельно от технических JSON-логов.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `BUSINESS_TRACE_WRITTEN` | Контекст или сообщение сохранены | [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи) |
| `BUSINESS_TRACE_WRITE_FAILED` | Запись в бизнес trace хранилище завершилась ошибкой | [OBS.BT-01.FR-03](#obsbt-01fr-03-результат-записи) |
#### Функциональные требования
##### OBS.BT-01.FR-01 [DB]: Таблица хранения trace_contexts
Таблица `trace_contexts` создаётся в схеме приложения и содержит:
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `trace_id` | `UUID` | NOT NULL, primary key | Публичный `business_trace_id` контекста |
| `parent_id` | `UUID` | NULL | `trace_id` родительского контекста |
| `alias` | `TEXT` | NOT NULL | Короткое имя контекста |
| `trace_type` | `TEXT` | NOT NULL | Тип бизнес-операции |
| `event_time` | `TIMESTAMPTZ` | NOT NULL | Время создания контекста |
| `attrs_json` | `JSONB` | NOT NULL | JSON-атрибуты контекста, включая `application_id` по RT.AI-01.FR-01 |
Создаются индексы по `parent_id` и `event_time`. Таблица принадлежит приложению.
##### OBS.BT-01.FR-02 [DB]: Таблица хранения trace_messages
Таблица `trace_messages` создаётся в схеме приложения и содержит:
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор сообщения |
| `trace_id` | `UUID` | NOT NULL | `trace_id` контекста |
| `event_time` | `TIMESTAMPTZ` | NOT NULL | Время сообщения |
| `step` | `TEXT` | NOT NULL | Имя шага бизнес-операции |
| `status` | `TEXT` | NOT NULL | Результат шага |
| `level` | `TEXT` | NOT NULL | Уровень бизнес-сообщения |
| `message` | `TEXT` | NOT NULL | Текст бизнес-сообщения |
| `attrs_json` | `JSONB` | NOT NULL | JSON-атрибуты сообщения, включая `application_id` по [RT.AI-01.FR-01](../../runtime/application-identity/spec.md#rtai-01fr-01-разрешение-идентификатора) |
Поле `trace_id` ссылается на `trace_contexts.trace_id` с каскадным удалением. Создаются индексы по `trace_id`, `event_time` и `status`. Таблица принадлежит приложению.
##### OBS.BT-01.FR-03: Результат записи
Приложение передаёт адаптеру пул PostgreSQL и имя своей схемы. Адаптер записывает контексты и сообщения по [OBS.BT-01.FR-01](#obsbt-01fr-01-db-таблица-хранения-tracecontexts) и [OBS.BT-01.FR-02](#obsbt-01fr-02-db-таблица-хранения-tracemessages), добавляя `application_id` в `attrs_json` обоих типов записей. Приложение создаёт таблицы своей миграцией; PLBA2 не запускает миграции, не владеет данными, не публикует события в RabbitMQ и не реализует API истории.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `BUSINESS_TRACE_WRITTEN` | Сообщение отсутствует | Выполнение бизнес-сценария продолжается по решению приложения |
| `BUSINESS_TRACE_WRITE_FAILED` | Сообщение отсутствует; исходная ошибка БД передаётся приложению | PLBA2 не выполняет скрытый retry; приложение выбирает политику ошибки |
@@ -0,0 +1,40 @@
# Spec Delta
## Purpose
Формировать единые технические JSON-логи в stdout с application_id и business_trace_id.
## ADDED Requirements
### Requirement: Структурированные технические логи
**ID:** `OBS.TL-01`
PLBA2 SHALL задавать контракт технической JSON-записи и передавать её в stdout.
#### Scenario: Сокращенный use case: техническая запись
##### Основной поток
1. Описываем поля отправляемой записи по [OBS.TL-01.FR-01](#obstl-01fr-01-api-контракт-сообщения-технической-записи).
2. Фиксируем контекст и вывод записи в stdout по [OBS.TL-01.FR-02](#obstl-01fr-02-контекст-и-передача-в-stdout).
#### Функциональные требования
##### OBS.TL-01.FR-01 [API]: Контракт сообщения технической записи
Тип контракта: request
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- | --- |
| `timestamp` | `string` | Обязательное | UTC timestamp; null запрещён | Время формирования записи |
| `level` | `string` | Обязательное | Null запрещён | Уровень технической записи |
| `logger` | `string` | Обязательное | Null запрещён | Имя logger |
| `message` | `string` | Обязательное | Null запрещён | Текст записи |
| `application_id` | `string` | Обязательное | Null запрещён | Идентификатор приложения |
| `attributes` | `object` | Опциональное | Значения должны быть JSON-safe | Структурированные поля записи |
| `business_trace_id` | `string` | Опциональное | Передаётся при установленном business trace context | Связь технической записи с бизнес-историей |
##### OBS.TL-01.FR-02: Контекст и передача в stdout
При установленном контексте formatter добавляет `business_trace_id`; контекст поддерживает async-задачи и использует то же значение, что business trace adapter. JSON кодируется стандартным сериализатором. Приложение направляет formatter в stdlib StreamHandler для stdout. PLBA2 не отправляет технические логи в БД, RabbitMQ, Loki или Grafana; доставку и просмотр обеспечивает платформа.
@@ -0,0 +1,48 @@
# Spec Delta
## Purpose
Определять `application_id` приложения и предоставлять разрешённое значение runtime-контексту.
## ADDED Requirements
### Requirement: Разрешение идентификатора приложения
**ID:** `RT.AI-01`
PLBA2 SHALL разрешать `application_id` до запуска зависящих от него компонентов и предоставлять значение runtime.
#### Scenario: Определение идентификатора приложения
##### Участники
- Файл `config.yaml`, метаданные проекта, загрузчик конфигурации и runtime приложения.
##### Предусловия
- Файл `config.yaml` успешно загружен; поле `application_id` и метаданные проекта могут отсутствовать.
##### Основной поток
1. Разрешаем `application_id` по приоритету источников согласно [RT.AI-01.FR-01](#rtai-01fr-01-разрешение-идентификатора).
2. Предоставляем значение runtime-контексту; операция завершается с `APPLICATION_ID_RESOLVED` по [RT.AI-01.FR-01](#rtai-01fr-01-разрешение-идентификатора).
##### Альтернативы и ошибки
- `application_id` не задан, а `pyproject.toml` или `[project].name` отсутствует — генерируем UUIDv4; результат тот же.
##### Результат
Runtime-контекст содержит один `application_id`, неизменный в течение работы процесса.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_ID_RESOLVED` | Идентификатор выбран и предоставлен runtime | [RT.AI-01.FR-01](#rtai-01fr-01-разрешение-идентификатора) |
#### Функциональные требования
##### RT.AI-01.FR-01: Разрешение идентификатора
В корневом `config.yaml` приложение может задать необязательное строковое поле `application_id`. Непустое значение используется без изменений. Если значение отсутствует или пустое, PLBA2 использует имя проекта из `[project].name` в `pyproject.toml`. Если файл, секция или имя проекта недоступны, PLBA2 генерирует случайный UUIDv4. Идентификатор разрешается один раз до запуска зависящих компонентов, предоставляется runtime-контексту и остаётся неизменным в течение работы процесса; UUIDv4 при новом запуске генерируется заново. Успешное разрешение завершается с `APPLICATION_ID_RESOLVED`.
@@ -0,0 +1,106 @@
# Spec Delta
## Purpose
Управлять lifecycle всего приложения через runtime-контракт, сохраняя entrypoint и HTTP host в приложении.
## ADDED Requirements
### Requirement: Запуск приложения
**ID:** `RT.AL-01`
Runtime SHALL запускать все зарегистрированные и не отключённые workers и предоставлять состояние запуска приложения.
#### Scenario: Запуск приложения
##### Участники
- Приложение, runtime PLBA2 и зарегистрированные workers.
##### Предусловия
- Workers зарегистрированы с уникальными именами.
- Приложение подключило runtime control API.
##### Основной поток
1. Запрашиваем запуск приложения — runtime запускает workers, не отключённых в конфигурации, по [RT.WK-01.FR-01](../worker/spec.md#rtwk-01fr-01-имя-состояния-и-управление-worker).
2. После запуска workers возвращаем `APPLICATION_STARTED` по [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения).
##### Альтернативы и ошибки
- Запуск одного или нескольких workers завершился ошибкой — возвращаем `APPLICATION_START_FAILED`; состояние приложения становится `failed`.
##### Результат
Lifecycle приложения и результат запуска workers доступны приложению.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STARTED` | Все зарегистрированные и включённые workers запущены | [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения) |
| `APPLICATION_START_FAILED` | Не удалось запустить один или несколько workers | [RT.AL-01.FR-01](#rtal-01fr-01-запуск-и-состояния-приложения) |
#### Функциональные требования
##### RT.AL-01.FR-01: Запуск и состояния приложения
При запуске runtime переводит приложение в `starting`, запускает зарегистрированные workers, у которых `workers.<worker_name>.disabled` отсутствует или равно `false`, по их контракту и переводит приложение в `running` после их успешного старта. Ошибка запуска переводит lifecycle в `failed`. Состояния приложения: `new`, `starting`, `running`, `stopping`, `stopped` и `failed`.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `APPLICATION_STARTED` | Сообщение отсутствует | Приложение доступно для control operations |
| `APPLICATION_START_FAILED` | Сообщение отсутствует; исходная ошибка доступна приложению | Lifecycle приложения остаётся `failed` |
### Requirement: Остановка приложения
**ID:** `RT.AL-02`
Runtime SHALL останавливать все workers приложения в graceful или принудительном режиме и предоставлять актуальный lifecycle status.
#### Scenario: Остановка приложения
##### Участники
- Клиент control API, runtime PLBA2, supervisor и зарегистрированные workers.
##### Предусловия
- Приложение запущено и его workers зарегистрированы.
##### Основной поток
1. Запрашиваем остановку приложения с выбранным режимом — runtime останавливает workers по [RT.AL-02.FR-01](#rtal-02fr-01-режимы-остановки-приложения).
2. Дожидаемся завершения workers и возвращаем `APPLICATION_STOPPED` по [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки).
##### Альтернативы и ошибки
- Истёк заданный timeout ожидания — возвращаем status `stopping` и `APPLICATION_STOPPING`; runtime продолжает остановку по [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки).
##### Результат
Lifecycle становится `stopped` только после остановки всех workers.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `APPLICATION_STOPPED` | Все workers приложения остановлены | [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки) |
| `APPLICATION_STOPPING` | Остановка продолжается после завершения ожидания API | [RT.AL-02.FR-02](#rtal-02fr-02-ожидание-и-статус-остановки) |
#### Функциональные требования
##### RT.AL-02.FR-01: Режимы остановки приложения
По умолчанию runtime запрашивает graceful stop у всех workers: каждый worker завершает активный цикл и не начинает следующий. При `force=true` runtime принудительно прерывает активную обработку workers. После любого режима новые циклы не запускаются.
##### RT.AL-02.FR-02: Ожидание и статус остановки
Положительный необязательный `timeout_seconds` ограничивает только ожидание ответа на запрос остановки. Если timeout отсутствует, runtime ждёт завершения всех workers без ограничения по времени. По истечении timeout runtime возвращает status `stopping`, продолжая остановку в фоне; timeout не включает принудительный режим. Lifecycle становится `stopped`, когда supervisor подтвердил остановку всех workers по [RT.WK-02.FR-02](../worker/spec.md#rtwk-02fr-02-результат-остановки-группы). Health aggregator возвращает `stopped` по [HL.AG-01.FR-01](../../health/aggregation/spec.md#hlag-01fr-01-состав-и-приоритет-статусов). Runtime не завершает принадлежащий приложению OS process или HTTP host; их остановка остаётся решением приложения.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `APPLICATION_STOPPED` | Сообщение отсутствует | Runtime фиксирует lifecycle `stopped` |
| `APPLICATION_STOPPING` | Сообщение отсутствует; lifecycle доступен в status | Runtime продолжает остановку workers |
@@ -0,0 +1,205 @@
## Purpose
Запускать именованные workers независимо друг от друга, выполнять их процессы по расписанию и формировать их health-состояния.
## ADDED Requirements
### Requirement: Независимые workers
**ID:** `RT.WK-01`
Runtime SHALL выполнять каждый зарегистрированный worker независимо от остальных по его стабильному уникальному имени.
#### Scenario: Работа worker в составе приложения
##### Участники
- Приложение, runtime PLBA2, supervisor и зарегистрированный worker.
##### Предусловия
- Composition root зарегистрировал workers с уникальными именами.
- Приложение запускает workers через lifecycle приложения.
##### Основной поток
1. При запуске приложения supervisor запускает worker, если `workers.<worker_name>.disabled` отсутствует или равно `false`, с результатом `WORKER_STARTED` по [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker).
2. Runtime хранит lifecycle и health каждого запущенного worker отдельно по [RT.WK-01.FR-02](#rtwk-01fr-02-независимость-работы-и-состояния).
##### Альтернативы и ошибки
- Для worker задано `disabled: true` — supervisor пропускает его запуск.
- Worker не удалось запустить — runtime сообщает `WORKER_START_FAILED` по [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker), остальные workers сохраняют собственное состояние.
##### Результат
Каждый включённый worker выполняется независимо и имеет отдельные имя, lifecycle и health-состояние.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `WORKER_STARTED` | Включённый worker запущен при запуске приложения | [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker) |
| `WORKER_START_FAILED` | Worker не удалось запустить | [RT.WK-01.FR-01](#rtwk-01fr-01-имя-состояния-и-управление-worker) |
#### Функциональные требования
##### RT.WK-01.FR-01: Имя, состояния и управление worker
Каждый worker регистрируется с уникальным стабильным именем. Runtime управляет его внутренним lifecycle через supervisor: запускает worker при запуске приложения, если `workers.<worker_name>.disabled` отсутствует или равно `false`, и останавливает его при остановке приложения. При `disabled: true` worker не запускается. Значение `disabled` применяется при запуске приложения; изменение этого значения во время работы не запускает и не останавливает worker до следующего запуска приложения. Отдельные операции API для запуска или остановки worker не предоставляются. Lifecycle и health запущенных workers доступны в общем health-отчёте. Неудачный внутренний запуск worker фиксируется с `WORKER_START_FAILED`; успешный — с `WORKER_STARTED`.
##### RT.WK-01.FR-02: Независимость работы и состояния
Runtime хранит lifecycle и health каждого worker отдельно. Исключение в процессе или состояние одного worker не меняет lifecycle и состояние остальных workers; операции управления приложением применяются ко всем включённым workers. Контракт health определён в [RT.WK-04.FR-01](#rtwk-04fr-01-контракт-и-прикладные-условия-health).
### Requirement: Контролируемая остановка workers
**ID:** `RT.WK-02`
Supervisor SHALL запрашивать остановку всех запущенных workers приложения и сообщать, когда каждый из них завершил текущую работу.
#### Scenario: Остановка группы workers
##### Участники
- Runtime PLBA2, supervisor и зарегистрированные workers.
##### Предусловия
- Workers запущены и доступны supervisor.
##### Основной поток
1. Передаём всем запущенным workers приложения режим остановки по [RT.WK-02.FR-01](#rtwk-02fr-01-режимы-остановки-worker).
2. Сообщаем о результате группы по [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы); после завершения возвращаем `WORKERS_STOPPED`.
##### Альтернативы и ошибки
- Часть workers ещё выполняет работу — сообщаем `WORKERS_STOPPING` и их имена по [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы).
##### Результат
Для каждого запущенного worker известно, завершена ли его работа.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `WORKERS_STOPPED` | Все запущенные workers приложения остановлены | [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы) |
| `WORKERS_STOPPING` | Не все запущенные workers приложения завершили работу | [RT.WK-02.FR-02](#rtwk-02fr-02-результат-остановки-группы) |
#### Функциональные требования
##### RT.WK-02.FR-01: Режимы остановки worker
При graceful stop worker завершает текущий цикл и не начинает следующий. При принудительной остановке runtime прерывает активную обработку worker. Supervisor отправляет запрос остановки всем запущенным workers приложения; остановка одного не задерживает отправку запросов остальным.
##### RT.WK-02.FR-02: Результат остановки группы
Supervisor возвращает `WORKERS_STOPPED` только после остановки всех запущенных workers приложения. Пока хотя бы один worker работает, результат — `WORKERS_STOPPING` со списком таких workers. Ожидание и таймаут ответа API определяет capability `runtime/application-lifecycle`.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `WORKERS_STOPPED` | Сообщение отсутствует | Supervisor подтверждает завершение группы |
| `WORKERS_STOPPING` | Результат содержит имена ещё работающих workers | Supervisor продолжает остановку |
### Requirement: Периодическое выполнение worker
**ID:** `RT.WK-03`
Runtime SHALL выполнять прикладной процесс worker циклами по расписанию, заданному для этого worker в `config.yaml`.
#### Scenario: Циклическое выполнение процесса
##### Участники
- Runtime PLBA2, зарегистрированный worker и конфигурация приложения.
##### Предусловия
- Приложение зарегистрировало worker с уникальным именем и предоставило его прикладной процесс.
- Для каждого включённого worker задан ровно один допустимый режим расписания.
##### Основной поток
1. Запускаем процесс worker без начальной задержки — runtime принимает расписание с `WORKER_SCHEDULE_STARTED` по [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания) и начинает цикл по [RT.WK-03.FR-01](#rtwk-03fr-01-режимы-и-настройки-расписания).
2. После завершения цикла планируем следующий запуск по текущей конфигурации и продолжаем последовательное исполнение по [RT.WK-03.FR-01](#rtwk-03fr-01-режимы-и-настройки-расписания).
##### Альтернативы и ошибки
- Настройки расписания отсутствуют, заданы вместе или имеют недопустимое значение — worker не запускается с `WORKER_CONFIG_INVALID` по [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания).
##### Результат
Worker выполняет прикладной процесс последовательно и повторяет его согласно выбранному режиму расписания.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `WORKER_SCHEDULE_STARTED` | Расписание принято, worker начал циклическое исполнение | [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания) |
| `WORKER_CONFIG_INVALID` | Расписание отсутствует или некорректно | [RT.WK-03.FR-02](#rtwk-03fr-02-валидация-расписания) |
#### Функциональные требования
##### RT.WK-03.FR-01: Режимы и настройки расписания
Настройки каждого worker находятся в корневом `config.yaml` по пути `workers.<worker_name>`. Для включённого worker нужно задать ровно одну положительную длительность в секундах: `interval_seconds` или `pause_seconds`. Worker с `disabled: true` не запускается и не требует настроек расписания. Первый цикл начинается сразу после старта worker; циклы одного worker не выполняются параллельно. При `interval_seconds` задан период между началами циклов: после обработки runtime ждёт остаток периода, а если обработка заняла дольше интервала — запускает следующий цикл сразу. При `pause_seconds` runtime ждёт указанную паузу после завершения каждого цикла. При планировании следующего цикла используются активные настройки; валидные изменения файла применяются без рестарта по capability `configuration/application-config-file`.
##### RT.WK-03.FR-02: Валидация расписания
Для включённого worker runtime принимает расписание только если задан ровно один ключ — `interval_seconds` или `pause_seconds` — со значением больше нуля. Если оба ключа отсутствуют, заданы вместе или значение некорректно, запуск приложения завершается ошибкой `WORKER_CONFIG_INVALID`; детали доступны приложению. Для worker с `disabled: true` проверка расписания не выполняется. Валидное расписание завершается с `WORKER_SCHEDULE_STARTED`.
### Requirement: Health worker
**ID:** `RT.WK-04`
Runtime SHALL формировать health-состояние каждого worker, продолжая циклическую работу после исключения в прикладном процессе.
#### Scenario: Обновление health worker
##### Участники
- Runtime PLBA2, worker, прикладная health-логика и health aggregator.
##### Предусловия
- Worker запущен и зарегистрирован в health aggregator.
##### Основной поток
1. Определяем состояние worker по результату цикла и прикладным условиям по [RT.WK-04.FR-01](#rtwk-04fr-01-контракт-и-прикладные-условия-health).
2. Передаём status и critical aggregator по [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления); обновление завершается с `WORKER_HEALTH_UPDATED`.
##### Альтернативы и ошибки
- Процесс цикла выбрасывает исключение — фиксируем `unhealthy`, возвращаем `WORKER_PROCESS_FAILED`, сохраняем worker запущенным и планируем следующий цикл по [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления).
##### Результат
Health-состояние worker доступно aggregator; исключение одного цикла не прекращает последующие циклы.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `WORKER_HEALTH_UPDATED` | Новое health-состояние worker передано aggregator | [RT.WK-04.FR-01](#rtwk-04fr-01-контракт-и-прикладные-условия-health), [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления) |
| `WORKER_PROCESS_FAILED` | Цикл завершился исключением, worker продолжит работу по расписанию | [RT.WK-04.FR-02](#rtwk-04fr-02-правила-статуса-и-восстановления) |
#### Функциональные требования
##### RT.WK-04.FR-01: Контракт и прикладные условия health
Health worker содержит `status` (`ok`, `degraded` или `unhealthy`), `critical`, `detail` и `meta` по контракту capability `health/aggregation`. Приложение задаёт `critical` при регистрации worker и может предоставить прикладную health-логику, возвращающую один из этих статусов по условиям своей задачи.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `WORKER_HEALTH_UPDATED` | Сообщение отсутствует | Новое состояние worker передаётся health aggregator |
##### RT.WK-04.FR-02: Правила статуса и восстановления
Исключение прикладного процесса переводит автоматическое состояние worker в `unhealthy`, но runtime перехватывает исключение и планирует следующий цикл. В режиме `interval_seconds` превышение длительностью цикла заданного интервала переводит автоматическое состояние в `degraded`; в режиме `pause_seconds` этот статус не возникает из-за расписания. Успешный следующий цикл сбрасывает автоматическое состояние в `ok`. Итоговый status — худший по порядку `ok < degraded < unhealthy` из автоматического состояния и результата прикладной health-логики; прикладная логика не маскирует ошибку цикла.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `WORKER_PROCESS_FAILED` | Сообщение отсутствует; исходное исключение доступно приложению | Worker сохраняет работу и запускает следующий цикл по расписанию |
@@ -0,0 +1,59 @@
# Spec Delta
## Purpose
Выполнять workflow из шагов приложения по явным переходам и сохранять состояние выполнения.
## ADDED Requirements
### Requirement: Workflow engine
**ID:** `WF.OR-01`
Workflow engine SHALL выполнять определение из именованных шагов, применять их переходы и сохранять ход запуска через persistence-контракт.
#### Scenario: Выполнение workflow
##### Участники
- Приложение, workflow engine, шаги приложения и persistence adapter.
##### Предусловия
- Приложение передало определение workflow, начальный шаг, контекст и адаптер сохранения.
##### Основной поток
1. Запускаем workflow — engine сохраняет начало запуска и вызывает объект текущего шага по [WF.OR-01.FR-01](#wfor-01fr-01-определение-и-выполнение).
2. Применяем результат шага — engine выбирает только объявленный переход и сохраняет checkpoint по [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки).
3. Достигаем конечного шага и завершаем с `WORKFLOW_COMPLETED`.
##### Альтернативы и ошибки
- Шаг выбрасывает исключение — engine сохраняет ошибку запуска, прекращает дальнейшие шаги и передаёт исходное исключение с `WORKFLOW_STEP_FAILED` по [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки).
##### Результат
Приложение получает результат запуска и актуальный контекст workflow.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `WORKFLOW_COMPLETED` | Workflow достиг конечного шага | [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки) |
| `WORKFLOW_STEP_FAILED` | Шаг завершился исключением | [WF.OR-01.FR-02](#wfor-01fr-02-сохранение-и-ошибки) |
#### Функциональные требования
##### WF.OR-01.FR-01: Определение и выполнение
Приложение задаёт WorkflowDefinition с именем, начальным шагом и именованными узлами. Узел содержит WorkflowStep и карту переходов; шаг получает WorkflowContext и возвращает StepResult с переходом, обновлениями состояния и статусом. Engine исполняет только объявленные переходы и не содержит бизнес-правил приложения.
##### WF.OR-01.FR-02: Сохранение и ошибки
Engine сохраняет начало и итог workflow, старт и завершение каждого шага, snapshot контекста и ошибки через переданный WorkflowPersistence. Ошибка шага сохраняется и передаётся вызывающему коду; скрытые повторы и выполнение следующих шагов не допускаются. Подключение к БД для сохранения задаёт приложение.
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `WORKFLOW_COMPLETED` | Сообщение отсутствует | Engine возвращает итоговый context и run id |
| `WORKFLOW_STEP_FAILED` | Сообщение отсутствует; исходное исключение передаётся вызывающему коду | Engine сохраняет ошибку, прекращает workflow и не повторяет шаг |
@@ -0,0 +1,42 @@
# Tasks
## 1. Runtime и идентичность приложения
- [ ] 1.1 Разрешать application_id из `config.yaml`, `pyproject.toml` или UUIDv4 и предоставлять его runtime-контексту по RT.AI-01.FR-01.
- [ ] 1.2 Поддержать уникальные имена, независимое выполнение и состояния workers; запускать только workers без `disabled: true` по RT.WK-01.FR-01–RT.WK-01.FR-02.
- [ ] 1.3 Реализовать запуск приложения и всех включённых workers по RT.AL-01.FR-01; при ошибке фиксировать состояние `failed`.
- [ ] 1.4 Реализовать graceful/force stop workers и групповой результат по RT.WK-02.FR-01–RT.WK-02.FR-02.
- [ ] 1.5 Реализовать остановку приложения с необязательным таймаутом ожидания и status `stopping` по RT.AL-02.FR-01–RT.AL-02.FR-02.
- [ ] 1.6 Реализовать цикл worker, проверку расписания и применение активной конфигурации по RT.WK-03.FR-01–RT.WK-03.FR-02.
- [ ] 1.7 Формировать автоматический health worker, сохранять цикл после исключения, принимать прикладные health-условия и передавать critical по RT.WK-04.FR-01–RT.WK-04.FR-02.
## 2. Health и workflow
- [ ] 2.1 Собирать статусы runtime и запущенных workers по HL.AG-01.FR-01–HL.AG-01.FR-02; исключать отключённые workers из health-агрегации и возвращать `stopped` после остановки приложения.
- [ ] 2.2 Сохранить object-based workflow API PLBA v1, явные переходы, snapshots, persistence и передачу ошибок по WF.OR-01.FR-01–WF.OR-01.FR-02.
## 3. Единый HTTP API
- [ ] 3.1 Добавить общий route adapter и отдельные endpoint Requirements с CONTRACT для GET /health, POST /runtime/start, POST /runtime/stop и GET /runtime/status по API.HTTP.CA-01–API.HTTP.CA-05; worker-specific routes не добавлять.
- [ ] 3.2 Подключать все routes к одному host и listener приложения; проверить, что capabilities не создают отдельные порты.
- [ ] 3.3 Делегировать health и lifecycle решения соответствующим contracts; HTTP слой отвечает за маршрутизацию и сериализацию.
## 4. Конфигурация приложения
- [ ] 4.1 Описать структуру и назначение полей таблицы `settings` по CFG.AS-01.FR-01; сверить её с запросом PostgreSQL-адаптера.
- [ ] 4.2 Зафиксировать создание таблицы и загрузку начальных значений миграциями по CFG.AS-02.FR-01–CFG.AS-02.FR-02; определить обновление runtime-значений владельцем приложения без рестарта.
- [ ] 4.3 Реализовать SettingsReader и PostgreSQL read adapter по CFG.AS-03.FR-01–CFG.AS-03.FR-03; проверить фильтрацию ключа, config_key и is_enabled, порядок sort_order/id и видимость изменения БД при следующем чтении.
- [ ] 4.4 Заменить удалённый ConfigurationSnapshotManager на typed YAML provider для `config.yaml` в корне приложения с общими полями `application_id`, `workers.<worker_name>.disabled` (по умолчанию `false`) и настройками расписания workers по CFG.ACF-01.FR-01–CFG.ACF-01.FR-02; проверить успешную загрузку и блокировку запуска при ошибочном исходном файле.
- [ ] 4.5 Подхватывать изменения `config.yaml` без рестарта по CFG.ACF-02; проверять атомарную замену, сохранение последнего валидного снимка и передачу ошибки при некорректном изменении.
## 5. Business trace и технические логи
- [ ] 5.1 Реализовать business trace contract и PostgreSQL adapter для `trace_contexts`/`trace_messages`, включая `application_id` в `attrs_json` контекстов и сообщений, по OBS.BT-01.FR-01–OBS.BT-01.FR-03.
- [ ] 5.2 Добавить пример первой миграции приложения для `trace_contexts`/`trace_messages` по OBS.BT-01.FR-01–OBS.BT-01.FR-02 и проверить ключи, индексы и каскадную связь сообщений с контекстом.
- [ ] 5.3 Реализовать JSON formatter для stdout с application_id и business_trace_id по OBS.TL-01.FR-01–OBS.TL-01.FR-02; оставить доставку платформе.
## 6. Интеграция и документация
- [ ] 6.1 Удалить configuration-service и RabbitMQ business-event API из публичных exports и документации; сохранить границу RabbitMQ рабочих сообщений внутри приложений.
- [ ] 6.2 Обновить package metadata, YAML parser dependency, optional PostgreSQL extra, README и examples для десяти capabilities.
- [ ] 6.3 Добавить contract/unit/integration проверки для AL, WK, AI, HA, HTTP, WO, AS, ACF, BT и OBS.TL; проверить core-only и PostgreSQL extra imports.
+33
View File
@@ -0,0 +1,33 @@
schema: function-driven
context: |
Актуальные спецификации проекта находятся в openspec/specs/.
Старые документы spec/specs/ устарели и не подтверждают текущее поведение.
Capability имеет отдельную бизнес-функцию или понятный результат и живёт
в иерархии доменов, например orders/snapshot-sync.
Requirement описывает одну завершённую техническую функцию.
Формат требований определяется локальной схемой function-driven.
Включай только сведения, влияющие на наблюдаемое поведение, устойчивый
контракт или обязательное техническое ограничение; не добавляй повторы и
пояснительный текст без такого влияния.
Пиши спецификации по-русски; имена API, SQL-полей и кодов сохраняй.
rules:
specs:
- Каждый Requirement содержит ровно один Use case. Автор выбирает полный или сокращенный формат независимо от типа FR и предмета описания.
- Обычный FR без метки описывает логику, правила или последовательность шагов; специальные типы помечай в заголовке FR как [DB], [API] или [UI].
- FR [DB] с таблицей БД оформляй по openspec/schemas/function-driven/patterns/database-table.md.
- Каждый HTTP endpoint описывай отдельным Requirement с полным Use case; сложные шаги выноси в FR и связывай со сценарием.
- Контракт endpoint помещай после FR в завершающий CONTRACT с подразделами Request и Response; не создавай для request/response отдельные FR.
- Таблицы тела запроса и ответа в CONTRACT оформляй по openspec/schemas/function-driven/patterns/message-contract.md; для каждого поля Response указывай источник или правило формирования значения.
- Сериализуемые контракты сообщений и технических логов описывай в FR [API] по openspec/schemas/function-driven/patterns/message-contract.md; один FR описывает одно направление.
- Детали находятся в локально нумерованных FR за пределами Scenario; шаги ссылаются на FR.
- Коды завершения сами передают смысл результата и связаны с FR о текстах и дальнейшем поведении.
- Для master spec используй templates/main-spec.md выбранной схемы; для delta используй templates/spec.md.
- Проверяй формат командой python3 openspec/schemas/function-driven/validate_format.py <spec-path>.
proposal:
- Сохраняй полные иерархические пути capabilities.
design:
- Ссылайся на Requirement ID и локальные FR; описывай решения реализации без копирования требований.
tasks:
- Связывай задачи с Requirement ID, FR и кодами завершения, если задача затрагивает эти результаты.
+166
View File
@@ -0,0 +1,166 @@
# Схема function-driven
Проект использует `function-driven` из `openspec/config.yaml`. Схема основана на
`spec-driven` и сохраняет workflow `proposal → specs / design → tasks`.
Новый формат требований задан в `schema.yaml` и шаблонах. Существующие changes
с явно указанной `schema: spec-driven` продолжают использовать свою схему;
их миграция не является частью изменения формата master spec.
## Уровни спецификации
- Capability — отдельная бизнес-функция или понятный результат в иерархии доменов.
- Requirement — одна завершённая техническая функция, стабильный ID и ровно один Scenario.
- Scenario — один из двух форматов Use case: полный или сокращенный. Автор выбирает формат независимо от того, описываются ли БД, API, логика, UI или другая часть системы.
- FR — подробные правила и контракты сообщений за пределами Scenario;
контракт HTTP endpoint размещается в завершающем CONTRACT.
В спецификацию включаются только сведения, влияющие на наблюдаемое поведение,
устойчивый контракт или обязательное техническое ограничение. Повторы и
пояснения без такого влияния удаляются.
Для каждой capability зарегистрируй стабильный уникальный префикс в
[`capability-codes.md`](capability-codes.md). Его сегменты отражают путь
capability: например, `configuration/application-settings` получает `CFG.AS`.
ID Requirement имеет вид `CFG.AS-01`; его номер уникален внутри capability.
В сочетании с уникальным префиксом это даёт уникальный ID в проекте.
ID FR включает ID Requirement и локальный номер: `CFG.AS-01.FR-01`,
`CFG.AS-01.FR-02`. Нумерация FR начинается с `FR-01` в каждом Requirement.
В новых и изменяемых Requirements используй составные ID. Неизменённые legacy
specs могут сохранять прежние ID до отдельного рефакторинга.
## Формат Requirement
Markdown-рендерер автоматически создаёт якоря из заголовков Requirement и FR.
Не добавляй HTML `<a id="..."></a>`. Ссылки используй на slug заголовка; при
переименовании заголовка обновляй все ссылки на него. Семантический ID Requirement
остаётся в строке `**ID:**`; полный ID FR входит в заголовок и подпись ссылки.
```text
### Requirement: Завершённая техническая функция
**ID:** AREA.CAP-01
Система SHALL ...
#### Scenario: Завершённый процесс
##### Участники
##### Предусловия
##### Основной поток
##### Альтернативы и ошибки
##### Результат
##### Коды завершения
#### Функциональные требования
##### AREA.CAP-01.FR-01: Правило обработки
##### AREA.CAP-01.FR-02 [DB]: Структура таблицы
##### AREA.CAP-01.FR-03 [API]: Контракт сообщения
##### AREA.CAP-01.FR-04 [UI]: Требования к интерфейсу
```
В Scenario «Назначение» опционально и добавляется только при наличии сведений,
которых нет в заголовке. «Контекст» в Scenario отсутствует. Основной поток —
нумерованные короткие шаги «Что делаем — как делаем», например:
«Получаем клиентов — вызываем GET /cp/users по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение)».
## Форматы Use case
Полный Use case содержит Участников, Предусловия, Основной поток, Альтернативы и ошибки, Результат и Коды завершения. Сокращенный Use case содержит только Основной поток; каждый шаг ссылается на FR. Автор выбирает формат для конкретного описания независимо от типа FR и предмета описания.
Для каждого HTTP endpoint используй отдельный Requirement и полный Use case.
```text
#### Scenario: Сокращенный use case: описание функции
##### Основной поток
1. Описываем первый аспект по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
2. Уточняем второй аспект по [AREA.CAP-01.FR-02](#areacap-01fr-02-дополнительное-правило).
```
Сокращенный Use case не содержит участников, предусловий, альтернатив и ошибок,
результата и кодов завершения.
Шаг, альтернатива или абзац Scenario содержит не более 240 знаков текста
без URL Markdown-ссылок. Сценарий не содержит Gherkin, блоков кода, таблиц
полей и подробных алгоритмов. Технические детали, тексты сообщений и логика находятся в FR; контракт HTTP
endpoint — в завершающем CONTRACT. Единственная таблица
Scenario — `Код | Смысл | Связанные FR`.
Ссылки ведут на автоматически сгенерированные slugs заголовков FR, например
`[AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки-контракт-api-структура-бд-форма-ui)`.
Полный ID используется внутри Requirement и при ссылке на другую capability.
Адрес фрагмента соответствует заголовку FR назначения. Каждый код ссылается
хотя бы на один FR, в котором он описан. Смысл кода понятен без `stage` или текста исключения.
FR задаёт тексты, дальнейшие действия и связи с другими требованиями.
Одинаковая обработка нескольких диагностических причин допускает один код.
Промежуточные события trace не включаются в коды завершения.
## Форматы FR
Обычный FR не имеет метки типа и описывает логику, правила или последовательность шагов. Специальный формат указывается после ID в заголовке: `[DB]`, `[API]` или `[UI]`. Метка не входит в ID FR и не меняет ссылки на него.
- [DB] описывает структуру базы данных по паттерну таблицы БД.
- FR [API] описывает контракт асинхронного сообщения или сериализуемой записи, включая технический лог. HTTP endpoint описывается в CONTRACT.
- [UI] зарезервирован для требований к интерфейсу; детальный паттерн будет добавлен отдельно.
## HTTP-контракт в Requirement
Каждый endpoint оформляется отдельным Requirement. Сценарий использует полный
Use case; сложные правила шагов выносятся в FR. После всех FR, в конце
Requirement, размещается раздел CONTRACT с подразделами Request и Response.
В Request указываются один HTTP-метод и путь, тело и query-параметры. В
Response указываются HTTP status и таблица сериализуемого ответа. Не создавай
отдельные FR для частей HTTP-контракта.
Таблица тела Request содержит пять колонок по
patterns/message-contract.md. Таблица Response содержит те же колонки и
последнюю колонку «Формирование значения», описывающую источник или правило
формирования каждого поля. Для отсутствующего тела запроса укажи это явно и не
добавляй пустую таблицу.
## Паттерны FR
FR, описывающий таблицу БД, оформляется по
[`patterns/database-table.md`](patterns/database-table.md): таблица содержит поля,
типы, ограничения/default и назначение. Паттерн не требует писать SQL DDL.
Контракт сообщения или технического лога в FR оформляется по
[`patterns/message-contract.md`](patterns/message-contract.md): таблица задаёт направление,
поля, wire-типы, обязательность и ограничения. Один FR описывает одно направление.
В response-таблице также указывается источник или правило формирования каждого поля.
Другие паттерны добавляются отдельными файлами по мере появления потребности.
## Шаблоны и delta specs
- `templates/main-spec.md` — постоянная спецификация capability.
- `templates/spec.md` — delta для change, предоставляемая `openspec instructions specs`.
- `templates/proposal.md`, `design.md`, `tasks.md` — остальные артефакты workflow.
ADDED и MODIFIED используют весь блок Requirement. REMOVED содержит Reason/Migration,
RENAMED — FROM/TO. Они являются операциями над требованиями, поэтому отдельный
Scenario в таких операциях не создаётся. В delta сохраняются ID Requirements и
заголовки FR master spec, на которые ведут автоматически созданные slugs. Для
ссылок на неизменённые требования при проверке передай `--base <master-spec>`.
Если смысловые коды или сообщения ещё не выдаются приложением, это явно
фиксируется в FR вместе с соответствием текущим outcome, trace-статусам и exit codes.
Форматирование спецификации само по себе не реализует этот контракт в приложении.
## Проверки
```sh
openspec schema validate function-driven
openspec validate orders/snapshot-sync --type spec --strict --no-interactive
python3 openspec/schemas/function-driven/validate_format.py --require-qualified-ids openspec/specs/orders/snapshot-sync/spec.md
```
Без аргументов `validate_format.py` проверяет master specs в `openspec/specs/`.
Можно передать несколько файлов или каталогов; проверка не изменяет их.
Стандартный `openspec schema validate` проверяет workflow, зависимости и наличие
шаблонов. `openspec validate` проверяет стандартную структуру спецификации.
Отдельная `validate_format.py --require-qualified-ids <spec-path>` проверяет
составные ID новых и изменённых Requirements; без флага валидатор также принимает
неизменённые legacy specs. Проверка охватывает один Scenario,
обычную структуру use case или формат сокращенного use case, ссылки шагов на FR,
форматы таблиц БД и контрактов по паттернам, краткость, отсутствие Gherkin и технических блоков
в Scenario, ID из реестра capabilities, локальную нумерацию FR, отсутствие HTML-якорей, ссылки на заголовки,
таблицу кодов и её связь с FR.
Семантическую завершённость функции и понятность кода оценивает автор/reviewer.
Схема требует от автора запускать обе проверки; автоматического hook в CLI нет.
Механизм схем и шаблонов: [официальная документация OpenSpec](https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md).
@@ -0,0 +1,19 @@
# Коды capabilities
Каждому пути capability соответствует один стабильный короткий префикс. Полные
префиксы должны быть уникальны в проекте; при переименовании capability код не
переиспользуется для другой capability.
| Путь capability | Префикс Requirement |
| --- | --- |
| `configuration/application-settings` | `CFG.AS` |
| `configuration/application-config-file` | `CFG.ACF` |
| `health/aggregation` | `HL.AG` |
| `api/http/control-api` | `API.HTTP.CA` |
| `runtime/application-lifecycle` | `RT.AL` |
| `runtime/application-identity` | `RT.AI` |
| `runtime/worker` | `RT.WK` |
| `workflow/orchestration` | `WF.OR` |
| `observability/business-tracing` | `OBS.BT` |
| `observability/technical-logging` | `OBS.TL` |
@@ -0,0 +1,37 @@
# Паттерн FR: таблица базы данных
Применяй паттерн, когда FR описывает структуру таблицы БД, а не SQL-команду её создания.
## Формат
Используй заголовок вида `<requirement-id>.FR-NN [DB]: Таблица хранения <имя>` и назови таблицу и схему приложения перед таблицей полей.
Таблицу полей оформляй с колонками в этом порядке:
| Поле | Тип | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- |
| `field_name` | `TYPE` | NULL или NOT NULL; при наличии DEFAULT укажи значение | Короткое назначение поля |
Одна строка описывает одно поле. Указывай точный тип, nullability, default и ограничения, которые влияют на хранение или чтение данных. Называй назначение каждого поля. Не используй `—` или пустые ячейки вместо явного `NULL`, `NOT NULL` или отсутствия default.
После таблицы перечисляй только ограничения таблицы, которых нет в строках: первичный и внешние ключи, уникальность, индексы, порядок выборки и владение данными. Не дублируй значения по умолчанию или назначение полей. Пиши DDL только если конкретный контракт невозможно выразить этой таблицей.
## Пример
```markdown
##### 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` не устанавливается.
```
@@ -0,0 +1,57 @@
# Паттерн сериализуемого контракта
Используй паттерн для полей сериализуемых request/response-контрактов.
Для HTTP endpoint таблицы находятся в разделах Request и Response блока
CONTRACT. Для асинхронного сообщения или технического лога контракт остаётся
в типизированном FR [API].
## HTTP endpoint
Каждый endpoint описывается отдельным Requirement с полным Use case. Сложные
правила обработки указываются в FR, а контракт помещается в самом конце
Requirement:
```markdown
#### CONTRACT
##### Request
Метод: `POST`; путь: `/resource`. Для endpoint без тела явно укажи отсутствие тела.
##### Response
HTTP status: `200` при успешном выполнении.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `field_name` | `JSON type` | Обязательное | Формат и допустимые значения | Короткое назначение поля | Источник или правило вычисления значения |
```
Тело запроса при наличии описывай таблицей с пятью колонками:
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение |
| --- | --- | --- | --- | --- |
| `field_name` | `JSON type` | Обязательное или опциональное | Формат, допустимые значения, nullable/default или явное отсутствие дополнительных ограничений и значений по умолчанию | Короткое назначение поля |
Для response используй эти же колонки и добавь последней «Формирование
значения», чтобы для каждого поля указать источник значения или правило его
вычисления.
Одна строка описывает одно поле. Указывай JSON-тип, а не тип языка реализации.
Для вложенных полей используй путь из имён полей; для массивов указывай тип
элемента. Обязательность задаёт наличие поля, а ограничения — nullability,
формат, допустимые значения и default. Условие присутствия опционального поля
укажи в ограничениях. Если дополнительных ограничений или значения по
умолчанию нет, укажи это явно. Не оставляй ячейки пустыми и не используй тире.
Не создавай отдельные FR для HTTP request/response-контрактов. Не добавляй
таблицу для отсутствующего тела запроса.
## Сообщение или технический лог в FR [API]
Заголовок FR: `<requirement-id>.FR-NN [API]: Контракт сообщения <имя>` либо
Контракт запроса / Контракт ответа. Сразу после заголовка укажи
`Тип контракта: request` для отправляемых данных или
`Тип контракта: response` для возвращаемых данных. Для отправляемого сообщения
используй request. Один FR описывает одно направление и содержит одну таблицу
по формату выше.
@@ -0,0 +1,266 @@
name: function-driven
version: 1
description: Иерархические capabilities, завершённые технические функции и краткие use cases с локальными FR
artifacts:
- id: proposal
generates: proposal.md
description: Initial proposal document outlining the change
template: proposal.md
instruction: |
Create the proposal document that establishes WHY this change is needed.
Sections:
- **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
- **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
- **Capabilities**: Identify which specs will be created or modified:
- **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
- **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
- **Impact**: Affected code, APIs, dependencies, or systems.
IMPORTANT: The Capabilities section is critical. It creates the contract between
proposal and specs phases. Research existing specs before filling this in:
run `openspec list --specs` for the project's capability inventory, then
`openspec show "<spec-id>" --type spec --json --no-scenarios` for any that
look related - that returns a capability's purpose and requirement texts
without pulling whole spec files into context. Append `--store "<id>"` to
both commands only for a registered standalone store, and keep `--type
spec`: a change and a spec sharing a name is otherwise an ambiguous-item
error. `openspec list` without `--specs` lists in-flight changes, not
specs - it never shows what the project already covers. Reuse an existing
capability's exact path instead of introducing a near-duplicate name.
The filtered read is only an overview. Before deciding what is already
covered or what should change, read each relevant spec in full, including
scenarios, with `openspec show "<spec-id>" --type spec` (same `--store` rule).
Each capability listed here will need a corresponding spec file.
Every change must either declare at least one capability (new or
modified) or explicitly opt out of specs: `openspec validate` rejects a
change with zero deltas unless the change's `.openspec.yaml` sets
`skip_specs: true`. Use `skip_specs: true` only when no spec-level
behavior changes (pure refactor, tooling, docs) - specs describe
behavior, so if behavior does not change, no spec should change either.
Do not invent a requirement just to satisfy validation.
Keep it concise (1-2 pages). Focus on the "why" not the "how" -
implementation details belong in design.md.
This is the foundation - specs, design, and tasks all build on this.
requires: []
- id: specs
generates: "specs/**/*.md"
description: Detailed specifications for the change
template: spec.md
instruction: |
Создай спецификации наблюдаемого поведения и устойчивых контрактов.
Правила ниже применяются к master specs и к полным блокам ADDED/MODIFIED
в delta specs. Это пользовательский формат без Gherkin.
Иерархия и границы:
- Capability имеет отдельную бизнес-функцию или понятный результат.
- Сохраняй полный иерархический путь, например orders/snapshot-sync.
- Один Requirement описывает одну завершённую техническую функцию.
- Не дроби один процесс на Requirements для чтения, валидации и записи.
- Каждый Requirement имеет стабильный ID вида CFG.AS-01 и ровно один Scenario.
- Префикс Requirement уникален для пути capability и регистрируется в
capability-codes.md: configuration/application-settings получает CFG.AS.
Номер Requirement уникален внутри capability, что делает полный ID
уникальным в проекте. Существующие, ещё не рефакторенные Requirements
могут сохранять старый ID.
- Заголовки OpenSpec: ### Requirement: и #### Scenario:.
- Описание Requirement содержит SHALL/MUST и наблюдаемый результат.
- Включай только сведения, меняющие наблюдаемое поведение, устойчивый
контракт или обязательное техническое ограничение. Удаляй повторы,
пояснения и формулировки, которые не меняют поведение и не снимают
неоднозначность контракта.
Scenario:
- Поддерживаются два формата Use case: полный и сокращенный. Автор
выбирает формат по ситуации, независимо от типа FR и того, что
описывается: runtime-процесс, БД, API, UI или другая часть системы.
- Полный Use case содержит разделы Участники, Предусловия,
Основной поток, Альтернативы и ошибки, Результат, Коды завершения —
в таком порядке.
- Сокращенный Use case содержит только раздел `##### Основной поток`;
каждый шаг кратко описывает аспект и ссылается на FR. Он не содержит
участников, предусловий, альтернатив и ошибок, результата или кодов
завершения и не задаёт отдельные runtime-развилки.
- В обычном сценарии Назначение опционально; добавляй только если оно
сообщает сведения, которых нет в заголовке. Контекст отсутствует.
- Основной поток — нумерованные короткие шаги «Что делаем — как делаем».
- Шаг runtime-сценария может назвать действие, endpoint или способ записи
и сослаться на FR.
- Каждый HTTP endpoint описывай в отдельном Requirement с полным Use case.
Сложные правила шага выноси в FR и связывай со сценарием ссылками.
- Основной поток и альтернативы обычного сценария включают коды
завершения, если они определены для этой функции.
- Таблицы полей, алгоритмы, SQL, JSON-примеры, параметры запросов, тексты
сообщений и дальнейшая логика располагаются за пределами Scenario.
- Единственная таблица Scenario — Коды завершения с колонками
Код, Смысл, Связанные FR. Код имеет формат UPPER_SNAKE_CASE.
- Код сам сообщает смысл итога; дополнительный stage или свободный текст
не должен требоваться для понимания кода. События промежуточных шагов
не являются кодами завершения. Не создавай код для каждой диагностики.
- Каждая запись кода ссылается на локальные FR, определяющие дальнейшую
логику, текст или применимые правила результата.
- Каждый шаг, альтернатива и абзац сценария — не более 240 знаков
содержательного текста без адресов Markdown-ссылок.
- Не используй Gherkin GIVEN/WHEN/THEN/AND/BUT.
Функциональные требования:
- После Scenario, на уровне ####, идёт раздел Функциональные требования.
- Внутри: ##### CFG.AS-01.FR-01: <название>, ##### CFG.AS-01.FR-02 [DB]: <название>, ##### CFG.AS-01.FR-03 [API]: <название> и так далее.
- ID FR содержит ID Requirement и локальный номер: <requirement-id>.FR-NN.
Номер начинается с FR-01 в каждом Requirement.
- FR содержит отдельное понятное правило или связанный контракт; не дроби
связную логику на множество атомарных FR.
- Обычный FR без метки описывает логику, правила или последовательность
шагов. Типизированный FR помечай сразу после ID меткой [DB], [API]
или [UI]; метка не входит в ID и не меняет slug ссылки.
- [DB] описывает структуру БД по паттерну таблицы. FR [API] описывает
контракт сообщения или технического лога. Контракт HTTP endpoint
размещается в отдельном разделе CONTRACT. [UI] описывает требования к
UI; детальный паттерн будет добавлен отдельно.
- Для FR [DB] с таблицей БД следуй паттерну
`openspec/schemas/function-driven/patterns/database-table.md`.
- Для сериализуемого контракта сообщения в FR [API] следуй паттерну
`openspec/schemas/function-driven/patterns/message-contract.md`.
- Контракт HTTP endpoint не оформляй отдельными FR. После раздела
Функциональные требования добавляй завершающий раздел CONTRACT с
подразделами Request и Response в таком порядке. В Request указывай
один HTTP-метод и путь; для отсутствующего тела явно отмечай это.
Таблицы тела запроса и ответа оформляй по паттерну message-contract.md.
- В таблице Response раздела CONTRACT укажи для каждого поля источник
значения или правило его формирования в последней колонке.
- В таблице response-контракта FR [API] укажи для каждого поля источник
значения или правило его формирования в колонке «Формирование значения».
- Не добавляй HTML-якоря вида <a id="..."></a>. Markdown генерирует
якоря из заголовков Requirement и FR.
- Ссылайся на FR по полному ID и slug его заголовка, например
[CFG.AS-01.FR-01](#cfgas-01fr-01-правило-обработки). Полный ID
используется и для ссылки внутри Requirement, и для ссылки на другой
Requirement.
- Сохраняй заголовки FR стабильными; при переименовании обновляй ссылки.
- Сохраняй существующие ID. При изменении FR сохраняй его номер;
новые FR добавляй в конец. Порядок первого документа последовательный.
- Для кодов укажи в FR тексты сообщений и поведение, включая отсутствие
сообщения/действия, если это часть контракта. Параметры сообщений
являются данными, а не скрытым значением кода.
- Если смысловой код спецификации отличается от действующего runtime,
явно опиши соответствие и статус реализации в FR. Не утверждай,
что новый код или текст уже возвращается приложением.
Работа с OpenSpec:
- Создай specs/<capability-path>/spec.md для каждой capability из proposal.
- Master spec использует шаблон templates/main-spec.md этой схемы.
- Delta spec использует templates/spec.md и разделы ## ADDED Requirements,
## MODIFIED Requirements, ## REMOVED Requirements, ## RENAMED Requirements.
- Для новой capability delta начинается с ## Purpose (50+ знаков).
Для существующей capability Purpose в delta не добавляй.
- MODIFIED содержит полный Requirement: ID, один Scenario и все FR.
Его заголовок должен совпадать с заголовком master spec.
- REMOVED содержит Reason и Migration; RENAMED использует FROM/TO.
Это операции над требованиями, не сценарии технических функций.
- При копировании блоков в delta сохраняй ID Requirements, номера и
заголовки FR, на которые ссылаются по slug. Если ссылка ведёт в
неизменённый Requirement master spec, проверяй delta с --base <master-spec>.
- Не создавай delta для чистого форматирования, tooling или рефакторинга.
Для change без изменения поведения используй skip_specs: true.
- Проверь schema через openspec schema validate function-driven.
- Проверь spec через openspec validate и отдельно через
python3 openspec/schemas/function-driven/validate_format.py
--require-qualified-ids <spec-path>. Для неизменённых legacy specs
этот флаг не нужен.
Стандартный валидатор OpenSpec не проверяет все правила этого формата.
requires:
- proposal
- id: design
generates: design.md
description: Technical design document with implementation details
template: design.md
instruction: |
Create the design document that explains HOW to implement the change.
When to include design.md (create only if any apply):
- Cross-cutting change (multiple services/modules) or new architectural pattern
- New external dependency or significant data model changes
- Security, performance, or migration complexity
- Ambiguity that benefits from technical decisions before coding
Sections:
- **Context**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why").
- **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries.
- **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
- **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
- **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
- **Open Questions**: Unknowns that can safely be answered later without
changing the specs, the approach, or the task breakdown. Omit if none.
Open questions are for genuinely deferrable unknowns, not decisions you
skipped. If a question would change the specs, the chosen approach, or
the task breakdown, resolve it now - ask the user instead of guessing.
Focus on architecture and approach, not line-by-line implementation.
The proposal covers why and what; design covers how. Reference the
proposal for motivation and, once written, the specs for requirements -
if a section would only restate them, point to them instead.
Good design docs explain the "why" behind technical decisions.
requires:
- proposal
- id: tasks
generates: tasks.md
description: Implementation checklist with trackable tasks
template: tasks.md
instruction: |
Create the task list that breaks down the implementation work.
Before writing tasks, check design.md for Open Questions. If any of them
would change what gets built, resolve them with the user first - do not
bake an unstated assumption into the task list.
**IMPORTANT: Follow the template below exactly.** The apply phase parses
checkbox format to track progress. A box holding only `x` counts as done,
upper or lower case and with any spacing, so `- [ x]` is done too. Every
other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as
unfinished. A line with no checkbox is not tracked at all.
Guidelines:
- Group related tasks under ## numbered headings
- Each task MUST be a checkbox: `- [ ] X.Y Task description`
- Tasks should be small enough to complete in one session
- Order tasks by dependency (what must be done first?)
- Each task MUST state how to verify completion (a test, command,
observable behavior, or delivered artifact). Put the verification in
that task's checkbox description. Use a separate verification task only
when it checks broader integration or system behavior that spans
multiple implementation tasks.
Example:
```
# Tasks
## 1. Setup
- [ ] 1.1 Create new module structure and verify expected files are present
- [ ] 1.2 Add dependencies to package.json and verify package installation succeeds
## 2. Core Implementation
- [ ] 2.1 Implement data export function and verify the export test passes
- [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters
```
Reference specs for what needs to be built, design for how to build it.
requires:
- specs
- design
apply:
requires: [ tasks ]
tracks: tasks.md
instruction: |
Read context files, work through pending tasks, mark complete as you go.
Pause if you hit blockers or need clarification.
@@ -0,0 +1,21 @@
# Design
## Context
<!-- Current state and constraints that shape the approach. See proposal.md for motivation - don't restate it -->
## Goals / Non-Goals
**Goals:**
<!-- What this design aims to achieve -->
**Non-Goals:**
<!-- What is explicitly out of scope -->
## Decisions
<!-- Key design decisions with rationale and alternatives considered -->
## Risks / Trade-offs
<!-- Known risks and trade-offs -->
@@ -0,0 +1,106 @@
# Capability: <название>
## Purpose
<Бизнес-функция capability и понятный результат, не менее 50 знаков.>
<!-- Включай только сведения, меняющие поведение, контракт или обязательное
ограничение. Удаляй повторы и пояснения без такого влияния. -->
## Границы
- <область ответственности capability>.
## Requirements
### Requirement: <название завершённой технической функции>
**ID:** `AREA.CAP-01`
Система SHALL <наблюдаемый результат завершённой функции>.
#### Scenario: <название завершённого процесса>
##### Участники
- <участники процесса>.
##### Предусловия
- <условия начала процесса>.
##### Основной поток
1. <Что делаем — как делаем> по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки-или-устойчивый-контракт).
2. Завершаем с `FUNCTION_COMPLETED` — фиксируем результат по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение).
##### Альтернативы и ошибки
- <условие ошибки> — завершаем с `FUNCTION_FAILED` по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение).
##### Результат
<Наблюдаемое состояние после завершения>.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `FUNCTION_COMPLETED` | <самодостаточный смысл успешного завершения> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) |
| `FUNCTION_FAILED` | <самодостаточный смысл ошибки> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) |
#### Функциональные требования
##### AREA.CAP-01.FR-01: Правило обработки
<Обычный FR описывает логику, правило или последовательность шагов. Для
специального формата добавь метку после ID: [DB], [API] или [UI]. Структуру
таблицы БД и контракт сообщения оформи по соответствующему паттерну. Контракт
HTTP endpoint располагай в завершающем разделе CONTRACT.>
##### AREA.CAP-01.FR-02: Коды завершения, тексты и дальнейшее поведение
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `FUNCTION_COMPLETED` | <текст или явное отсутствие сообщения> | <следующие действия> |
| `FUNCTION_FAILED` | <текст ошибки> | <обработка ошибки, повтор, действие оператора> |
<При необходимости — параметры сообщений, связанные требования и соответствие
действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.>
<!-- HTTP endpoint описывай в отдельном Requirement с полным Use case.
Контракт размещай в конце Requirement, не разбивая request/response на FR:
#### CONTRACT
##### Request
Метод: `POST`; путь: `/resource`. <Тело запроса или явное отсутствие тела.>
##### Response
HTTP status: <код и условие возврата>.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `field_name` | `JSON type` | <Обязательное или опциональное> | <Ограничения> | <Назначение> | <Источник или правило формирования> |
-->
<!-- Автор выбирает полный или сокращенный Use case по ситуации, независимо от
типа FR и предмета описания. Для сокращенного Use case используй только основной
поток и ссылки на FR:
#### Scenario: Сокращенный use case: <предмет описания>
##### Основной поток
1. <Кратко опиши первый аспект> по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
2. <Кратко опиши следующий аспект> по [AREA.CAP-01.FR-02](#areacap-01fr-02-правило-или-контракт).
-->
<!-- Типы FR: без метки — логика и правила; [DB] — структура БД;
[API] — контракт сообщения или технического лога; [UI] — требования к UI.
[DB] с таблицей оформляй по openspec/schemas/function-driven/patterns/database-table.md.
Сериализуемый контракт FR [API] оформляй по
openspec/schemas/function-driven/patterns/message-contract.md. В response-таблице
добавь колонку «Формирование значения» для каждого поля. -->
@@ -0,0 +1,31 @@
# Proposal
## Why
<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
## What Changes
<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
## Capabilities
### New Capabilities
<!-- Capabilities being introduced. Use kebab-case for path segments you introduce
(e.g., user-auth or identity/user-auth) that follow the project's existing
spec organization. Each creates specs/<capability-path>/spec.md. -->
- `<capability-path>`: <brief description of what this capability covers>
### Modified Capabilities
<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
Only list here if spec-level behavior changes. Each needs a delta spec file.
Use the exact existing path under openspec/specs/. Leave empty if no requirement
changes. A change with no capabilities at all (pure refactor, tooling, docs)
must set `skip_specs: true` in its .openspec.yaml - openspec validate rejects
a zero-delta change without that marker. Do not invent a requirement just to
satisfy validation. -->
- `<existing-capability-path>`: <what requirement is changing>
## Impact
<!-- Affected code, APIs, dependencies, systems -->
@@ -0,0 +1,107 @@
# Spec Delta
## Purpose
<!-- Только для новой capability: 1–2 предложения, не менее 50 знаков.
Для существующей capability удали этот раздел. -->
<!-- Включай только сведения, меняющие поведение, контракт или обязательное
ограничение. Удаляй повторы и пояснения без такого влияния. -->
## ADDED Requirements
<!-- Для изменения существующего Requirement используй MODIFIED Requirements
и полный блок из master spec: ID, единственный Scenario и все FR.
Сохраняй заголовок, ID, номера FR и заголовки FR, на которые ссылаются по slug. -->
### Requirement: <название завершённой технической функции>
**ID:** `AREA.CAP-01`
Система SHALL <наблюдаемый результат завершённой функции>.
#### Scenario: <название завершённого процесса>
##### Участники
- <участники процесса>.
##### Предусловия
- <условия начала процесса>.
##### Основной поток
1. <Что делаем — как делаем> по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки-или-устойчивый-контракт).
2. Завершаем с `FUNCTION_COMPLETED` — фиксируем результат по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение).
##### Альтернативы и ошибки
- <условие ошибки> — завершаем с `FUNCTION_FAILED` по [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение).
##### Результат
<Наблюдаемое состояние после завершения>.
##### Коды завершения
| Код | Смысл | Связанные FR |
| --- | --- | --- |
| `FUNCTION_COMPLETED` | <самодостаточный смысл успешного завершения> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) |
| `FUNCTION_FAILED` | <самодостаточный смысл ошибки> | [AREA.CAP-01.FR-02](#areacap-01fr-02-коды-завершения-тексты-и-дальнейшее-поведение) |
#### Функциональные требования
##### AREA.CAP-01.FR-01: Правило обработки
<Обычный FR описывает логику, правило или последовательность шагов. Для
специального формата добавь метку после ID: [DB], [API] или [UI]. Структуру
таблицы БД и контракт сообщения оформи по соответствующему паттерну. Контракт
HTTP endpoint располагай в завершающем разделе CONTRACT.>
##### AREA.CAP-01.FR-02: Коды завершения, тексты и дальнейшее поведение
| Код | Текст сообщения | Дальнейшее поведение |
| --- | --- | --- |
| `FUNCTION_COMPLETED` | <текст или явное отсутствие сообщения> | <следующие действия> |
| `FUNCTION_FAILED` | <текст ошибки> | <обработка ошибки, повтор, действие оператора> |
<При необходимости — параметры сообщений, связанные требования и соответствие
действующему runtime. Явно отметь коды и тексты, которые ещё не реализованы.>
<!-- HTTP endpoint описывай в отдельном Requirement с полным Use case.
Контракт размещай в конце Requirement, не разбивая request/response на FR:
#### CONTRACT
##### Request
Метод: `POST`; путь: `/resource`. <Тело запроса или явное отсутствие тела.>
##### Response
HTTP status: <код и условие возврата>.
| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `field_name` | `JSON type` | <Обязательное или опциональное> | <Ограничения> | <Назначение> | <Источник или правило формирования> |
-->
<!-- Автор выбирает полный или сокращенный Use case по ситуации, независимо от
типа FR и предмета описания. Для сокращенного Use case используй только основной
поток и ссылки на FR:
#### Scenario: Сокращенный use case: <предмет описания>
##### Основной поток
1. <Кратко опиши первый аспект> по [AREA.CAP-01.FR-01](#areacap-01fr-01-правило-обработки).
2. <Кратко опиши следующий аспект> по [AREA.CAP-01.FR-02](#areacap-01fr-02-правило-или-контракт).
-->
<!-- Типы FR: без метки — логика и правила; [DB] — структура БД;
[API] — контракт сообщения или технического лога; [UI] — требования к UI.
[DB] с таблицей оформляй по openspec/schemas/function-driven/patterns/database-table.md.
Сериализуемый контракт FR [API] оформляй по
openspec/schemas/function-driven/patterns/message-contract.md. В response-таблице
добавь колонку «Формирование значения» для каждого поля. -->
@@ -0,0 +1,11 @@
# Tasks
## 1. <!-- Task Group Name -->
- [ ] 1.1 <!-- Task description -->
- [ ] 1.2 <!-- Task description -->
## 2. <!-- Task Group Name -->
- [ ] 2.1 <!-- Task description -->
- [ ] 2.2 <!-- Task description -->
@@ -0,0 +1,494 @@
"""Read-only checks of function-driven Markdown conventions; no dependencies."""
from __future__ import annotations
import argparse
import re
import unicodedata
from pathlib import Path
from urllib.parse import unquote
SECTIONS = (
"Участники", "Предусловия", "Основной поток", "Альтернативы и ошибки",
"Результат", "Коды завершения",
)
CODE = re.compile(r"\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+\b")
LINK = re.compile(r"\[([^\]]+)\]\(#([^)]+)\)")
HEADING = re.compile(r"^(#{1,6})\s+(.+?)\s*#*\s*$")
LEGACY_REQUIREMENT_ID_PATTERN = r"[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)+"
QUALIFIED_REQUIREMENT_ID_PATTERN = r"[A-Z][A-Z0-9]*(?:\.[A-Z][A-Z0-9]*)+-\d{2,}"
REQUIREMENT_ID_PATTERN = rf"(?:{QUALIFIED_REQUIREMENT_ID_PATTERN}|{LEGACY_REQUIREMENT_ID_PATTERN})"
REQUIREMENT_ID = re.compile(rf"^\*\*ID:\*\* `({REQUIREMENT_ID_PATTERN})`$", re.MULTILINE)
FR_ID_PATTERN = rf"(?:{QUALIFIED_REQUIREMENT_ID_PATTERN}\.)?FR-\d{{2,}}"
FR_ID = re.compile(rf"^(?:(?P<requirement>{QUALIFIED_REQUIREMENT_ID_PATTERN})\.)?(?P<number>FR-\d{{2,}})$")
FR_HEADING = re.compile(rf"^##### ({FR_ID_PATTERN})(?: \[(DB|API|UI)\])?: (.+)$", re.MULTILINE)
HTML_ANCHOR = re.compile(r"<a\b[^>]*\bid\s*=", re.IGNORECASE)
DB_TABLE_COLUMNS = ("Поле", "Тип", "Ограничения и значение по умолчанию", "Назначение")
CONTRACT_COLUMNS = ("Поле", "Тип", "Обязательность", "Ограничения и значение по умолчанию", "Назначение")
RESPONSE_CONTRACT_COLUMNS = (*CONTRACT_COLUMNS, "Формирование значения")
CAPABILITY_CODES_PATH = Path(__file__).with_name("capability-codes.md")
CAPABILITY_CODE_ROW = re.compile(r"^\|\s*`([^`]+)`\s*\|\s*`([^`]+)`\s*\|$")
def plain_text(value: str) -> str:
value = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", value)
return re.sub(r"^[\d.\-\s]+|[`*_]", "", value).strip()
def heading_slug(title: str) -> str:
"""Build the heading fragment used by GitHub-style Markdown renderers."""
title = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", title)
title = re.sub(r"[`*_~]", "", title).lower()
slug: list[str] = []
for char in title:
category = unicodedata.category(char)[0]
if char.isspace():
if slug and slug[-1] != "-":
slug.append("-")
elif char in {"-", "_"} or category in {"L", "M", "N"}:
slug.append(char)
return "".join(slug).strip("-")
def parse_fr_reference(label: str) -> tuple[str | None, str] | None:
"""Return an optional requirement ID and the local FR number from a link label."""
label = label.strip()
match = FR_ID.fullmatch(label)
if match:
return match.group("requirement"), match.group("number")
match = re.fullmatch(
rf"({LEGACY_REQUIREMENT_ID_PATTERN})\s*/\s*(FR-\d{{2,}})", label
)
if match:
return match.group(1), match.group(2)
return None
def load_capability_codes() -> tuple[dict[str, str], list[str]]:
codes: dict[str, str] = {}
errors: list[str] = []
try:
lines = CAPABILITY_CODES_PATH.read_text(encoding="utf-8").splitlines()
except OSError as error:
return {}, [f"не удалось прочитать реестр capability codes: {error}"]
prefixes: dict[str, str] = {}
for line in lines:
match = CAPABILITY_CODE_ROW.match(line)
if not match:
continue
capability_path, prefix = match.groups()
if capability_path in codes:
errors.append(f"путь capability повторяется в реестре: {capability_path}")
if prefix in prefixes:
errors.append(f"префикс {prefix} повторяется для {prefixes[prefix]} и {capability_path}")
codes[capability_path] = prefix
prefixes[prefix] = capability_path
return codes, errors
def spec_capability_path(path: Path) -> str | None:
parts = path.parts
indexes = [index for index, part in enumerate(parts) if part == "specs"]
if not indexes:
return None
capability_parts = parts[indexes[-1] + 1:-1]
return "/".join(capability_parts) if capability_parts else None
def heading_targets(text: str) -> tuple[set[str], dict[str, tuple[str, str]]]:
"""Return generated heading fragments and fragments that target FR headings."""
targets: set[str] = set()
fr_targets: dict[str, tuple[str, str]] = {}
duplicates: dict[str, int] = {}
requirement_id = ""
for line in text.splitlines():
if line.startswith("### Requirement:"):
requirement_id = ""
id_match = REQUIREMENT_ID.match(line)
if id_match:
requirement_id = id_match.group(1)
match = HEADING.match(line)
if not match:
continue
slug = heading_slug(match.group(2))
if not slug:
continue
duplicate_index = duplicates.get(slug, 0)
duplicates[slug] = duplicate_index + 1
target = slug if duplicate_index == 0 else f"{slug}-{duplicate_index}"
targets.add(target)
fr_match = FR_HEADING.match(line)
if fr_match and requirement_id:
fr_id = FR_ID.fullmatch(fr_match.group(1))
if fr_id:
fr_targets[target] = (requirement_id, fr_id.group("number"))
return targets, fr_targets
def requirement_blocks(text: str):
heading = re.compile(r"^## .*|^### Requirement: (.+)$", re.MULTILINE)
headings = list(heading.finditer(text))
operation = ""
for index, match in enumerate(headings):
if not match.group(1):
operation = match.group().removeprefix("## ")
continue
if operation in {"REMOVED Requirements", "RENAMED Requirements"}:
continue
end = headings[index + 1].start() if index + 1 < len(headings) else len(text)
yield match.group(1), text[match.end():end]
def check_database_table_pattern(content: str) -> list[str]:
errors: list[str] = []
tables: list[list[str]] = []
current: list[str] = []
for line in content.splitlines():
if line.strip().startswith("|"):
current.append(line.strip())
elif current:
tables.append(current)
current = []
if current:
tables.append(current)
if len(tables) != 1:
return ["паттерн таблицы БД требует ровно одну Markdown-таблицу"]
rows = [[cell.strip() for cell in row.strip("|").split("|")] for row in tables[0]]
if len(rows) < 3 or tuple(rows[0]) != DB_TABLE_COLUMNS:
return ["таблица БД должна иметь заголовки Поле, Тип, Ограничения и значение по умолчанию, Назначение"]
if len(rows[1]) != len(DB_TABLE_COLUMNS) or any(not re.fullmatch(r":?-{3,}:?", cell) for cell in rows[1]):
errors.append("в таблице БД некорректная строка разделителя")
field_names: set[str] = set()
for row in rows[2:]:
if len(row) != len(DB_TABLE_COLUMNS) or any(not cell for cell in row):
errors.append("каждая строка таблицы БД должна содержать четыре непустые ячейки")
continue
field_name = row[0].strip("`")
if field_name in field_names:
errors.append(f"поле `{field_name}` повторяется в таблице БД")
field_names.add(field_name)
return errors
def check_message_contract_pattern(content: str, direction: str | None = None) -> list[str]:
errors: list[str] = []
contract_type_match = re.search(r"(?m)^Тип контракта: (request|response)$", content)
if direction is None and not contract_type_match:
errors.append("контракт должен явно указывать Тип контракта: request или response")
selected_direction = direction or (contract_type_match.group(1) if contract_type_match else "")
columns = (
RESPONSE_CONTRACT_COLUMNS
if selected_direction == "response"
else CONTRACT_COLUMNS
)
tables: list[list[str]] = []
current: list[str] = []
for line in content.splitlines():
if line.strip().startswith("|"):
current.append(line.strip())
elif current:
tables.append(current)
current = []
if current:
tables.append(current)
if len(tables) != 1:
return errors + ["паттерн контракта требует ровно одну Markdown-таблицу"]
rows = [[cell.strip() for cell in row.strip("|").split("|")] for row in tables[0]]
if len(rows) < 3 or tuple(rows[0]) != columns:
required_columns = ", ".join(columns)
return errors + [f"таблица контракта должна содержать колонки: {required_columns}"]
if len(rows[1]) != len(columns) or any(not re.fullmatch(r":?-{3,}:?", cell) for cell in rows[1]):
errors.append("в таблице контракта некорректная строка разделителя")
field_names: set[str] = set()
for row in rows[2:]:
if len(row) != len(columns) or any(not cell for cell in row):
errors.append("каждая строка таблицы контракта должна содержать нужное число непустых ячеек")
continue
field_name = row[0].strip(chr(96))
if field_name in field_names:
errors.append(f"поле контракта {field_name} повторяется")
field_names.add(field_name)
if row[2] not in {"Обязательное", "Опциональное"}:
errors.append(f"поле контракта {field_name} должно явно задавать обязательность")
return errors
def check_http_endpoint_contract(content: str) -> list[str]:
errors: list[str] = []
headings = re.findall(r"^##### (.+)$", content, re.MULTILINE)
if headings != ["Request", "Response"]:
return ["CONTRACT должен содержать только подразделы Request и Response в этом порядке"]
request, response = re.split(r"^##### (?:Request|Response)\s*$", content, maxsplit=2, flags=re.MULTILINE)[1:]
if len(re.findall(r"(?m)^Метод: \x60?(?:GET|POST|PUT|PATCH|DELETE)\x60?; путь: \x60?/\S+", request)) != 1:
errors.append("в Request укажи один HTTP-метод и путь endpoint")
request_tables = sum(line.strip().startswith("|") for line in request.splitlines())
if request_tables:
errors.extend(check_message_contract_pattern(request, "request"))
elif not re.search(r"Тело запроса(?: и query-параметры)? отсутств(?:ует|уют)", request):
errors.append("в Request укажи таблицу тела запроса или явно отметь его отсутствие")
if not re.search(r"(?m)^HTTP status:", response):
errors.append("в Response укажи HTTP status")
errors.extend(check_message_contract_pattern(response, "response"))
return errors
def check_requirement(
name: str,
block: str,
targets: set[str],
fr_targets: dict[str, tuple[str, str]],
require_qualified_ids: bool = False,
) -> list[str]:
errors: list[str] = []
ids = REQUIREMENT_ID.findall(block)
if len(ids) != 1:
return [f"{name}: нужен один стабильный **ID:** с префиксом capability и номером Requirement"]
requirement_id = ids[0]
is_qualified = "." in requirement_id
if require_qualified_ids and not is_qualified:
errors.append("новый или изменённый Requirement должен иметь составной ID capability, например CFG.AS-01")
level_four = re.findall(r"^#### (.+)$", block, re.MULTILINE)
has_contract = len(level_four) == 3 and level_four[2] == "CONTRACT"
expected_level_four = ["Функциональные требования", "CONTRACT"] if has_contract else ["Функциональные требования"]
if (
len(level_four) != len(expected_level_four) + 1
or not level_four[0].startswith("Scenario: ")
or level_four[1:] != expected_level_four
):
return [f"{name}: нужны один Scenario, Функциональные требования и опциональный завершающий CONTRACT"]
scenario_heading = level_four[0].removeprefix("Scenario: ")
is_short_use_case = scenario_heading.startswith("Сокращенный use case:")
scenario, details = block.split("#### Функциональные требования", 1)
scenario = scenario.split("#### Scenario:", 1)[1].split("\n", 1)[1]
if has_contract:
if is_short_use_case:
errors.append("Requirement с HTTP CONTRACT должен использовать полный Use case")
details, contract_content = details.split("#### CONTRACT", 1)
errors.extend(check_http_endpoint_contract(contract_content))
sections = re.findall(r"^##### (.+)$", scenario, re.MULTILINE)
narrative = ""
outcomes = ""
short_use_case_flow_lines: list[str] = []
if is_short_use_case:
if sections != ["Основной поток"]:
errors.append("сокращенный use case должен содержать только Основной поток")
before_flow, separator, flow = scenario.partition("##### Основной поток")
if not separator or before_flow.strip():
errors.append("сокращенный use case содержит только раздел Основной поток")
short_use_case_flow_lines = [line.strip() for line in flow.splitlines() if line.strip()]
if any(not re.match(r"^\d+\. .+", line) for line in short_use_case_flow_lines):
errors.append("основной поток сокращенного use case содержит только нумерованные шаги")
if any(len(plain_text(line)) > 240 for line in short_use_case_flow_lines):
errors.append("шаг сокращенного use case длиннее 240 знаков; детали должны быть в FR")
else:
required = [section for section in sections if section != "Назначение"]
if required != list(SECTIONS) or sections.count("Назначение") > 1:
errors.append("разделы Scenario не соответствуют шаблону")
if "Назначение" in sections and sections[0] != "Назначение":
errors.append("опциональное Назначение должно предшествовать Участники")
for section in sections:
content = re.split(r"^##### ", scenario.split(f"##### {section}\n", 1)[1], maxsplit=1, flags=re.MULTILINE)[0]
if not content.strip():
errors.append(f"пустой раздел Scenario: {section}")
narrative, separator, outcomes = scenario.partition("##### Коды завершения")
if not separator:
errors.append("нет списка кодов завершения")
if re.search(r"^\s*\|", narrative, re.MULTILINE):
errors.append("техническая таблица должна находиться в FR")
for paragraph in re.split(r"\n\s*\n", narrative):
lines = [line for line in paragraph.splitlines() if line.strip() and not line.startswith("#")]
chunks = lines if all(re.match(r"^(?:\d+\.|-) ", line) for line in lines) else [" ".join(lines)]
if any(len(plain_text(chunk)) > 240 for chunk in chunks):
errors.append("абзац или шаг Scenario длиннее 240 знаков; перенеси детали в FR")
if re.search(r"(?im)^\s*(?:[-*]\s*)?(?:\*\*)?(?:GIVEN|WHEN|THEN|AND|BUT)\b", scenario):
errors.append("Scenario содержит Gherkin")
if "```" in scenario or "~~~" in scenario:
errors.append("блок кода должен находиться в FR")
flow = scenario.partition("##### Основной поток")[2]
if not is_short_use_case:
flow = flow.partition("##### Альтернативы и ошибки")[0]
steps = [int(number) for number in re.findall(r"^(\d+)\. ", flow, re.MULTILINE)]
if not steps or steps != list(range(1, len(steps) + 1)):
errors.append("основной поток должен содержать последовательные нумерованные шаги")
raw_definitions = list(FR_HEADING.finditer(details))
if len(raw_definitions) != len(re.findall(r"^##### ", details, re.MULTILINE)):
errors.append("подразделы Функциональных требований должны иметь заголовки с ID вида <requirement-id>.FR-NN")
definitions: list[tuple[re.Match[str], re.Match[str]]] = []
for match in raw_definitions:
fr_id_match = FR_ID.fullmatch(match.group(1))
if not fr_id_match:
errors.append(f"некорректный ID FR в заголовке: {match.group(1)}")
continue
definitions.append((match, fr_id_match))
numbers = [int(fr_id_match.group("number").removeprefix("FR-")) for _, fr_id_match in definitions]
if not numbers or numbers[0] != 1 or numbers != sorted(set(numbers)):
errors.append("FR должны начинаться с FR-01 и иметь уникальные возрастающие номера")
fr_contents: dict[str, str] = {}
for index, (match, fr_id_match) in enumerate(definitions):
fr_id = fr_id_match.group("number")
expected_fr_id = f"{requirement_id}.{fr_id}" if is_qualified else fr_id
if match.group(1) != expected_fr_id:
errors.append(f"заголовок FR должен использовать полный ID {expected_fr_id}")
target = heading_slug(match.group(0).removeprefix("##### "))
if fr_targets.get(target) != (requirement_id, fr_id):
errors.append(f"заголовок {match.group(1)} не создаёт ожидаемый Markdown-якорь")
next_definition = definitions[index + 1][0] if index + 1 < len(definitions) else None
end = next_definition.start() if next_definition else len(details)
fr_contents[fr_id] = details[match.end():end]
format_type = match.group(2)
title = match.group(3)
if format_type == "DB" or title.lower().startswith("таблица хранения "):
errors.extend(check_database_table_pattern(fr_contents[fr_id]))
if format_type == "API" and re.match(r"контракт (?:сообщения|запроса|ответа)\b", title, re.IGNORECASE):
errors.extend(check_message_contract_pattern(fr_contents[fr_id]))
if has_contract and format_type == "API":
errors.append("HTTP request/response-контракт описывается в CONTRACT, не в FR [API]")
for label, raw_target in LINK.findall(block):
target = unquote(raw_target)
if target not in targets:
errors.append(f"ссылка {label} ведёт на отсутствующий Markdown-заголовок #{target}")
continue
linked_fr = parse_fr_reference(label)
if "FR-" in label and not linked_fr:
errors.append(f"ссылка {label} должна содержать полный ID FR")
if linked_fr:
target_fr = fr_targets.get(target)
linked_requirement, linked_number = linked_fr
if target_fr is None or target_fr[1] != linked_number:
errors.append(f"ссылка {label} должна вести на заголовок соответствующего FR")
if linked_requirement and target_fr and target_fr[0] != linked_requirement:
errors.append(f"ссылка {label} ведёт на FR другого Requirement")
if target_fr and "." in target_fr[0] and label != f"{target_fr[0]}.{target_fr[1]}":
errors.append(f"ссылка {label} должна использовать полный ID {target_fr[0]}.{target_fr[1]}")
if is_short_use_case:
for step in short_use_case_flow_lines:
has_local_fr = False
for label, raw_target in LINK.findall(step):
linked_fr = parse_fr_reference(label)
target_fr = fr_targets.get(unquote(raw_target))
expected_label = f"{requirement_id}.FR-{linked_fr[1].removeprefix('FR-')}" if linked_fr and is_qualified else (linked_fr[1] if linked_fr else "")
if linked_fr and target_fr == (requirement_id, linked_fr[1]) and label == expected_label:
has_local_fr = True
break
if not has_local_fr:
errors.append("каждый шаг сокращенного use case должен ссылаться на локальный FR")
else:
rows = [line for line in outcomes.splitlines() if line.startswith("|")]
if not rows or rows[0] != "| Код | Смысл | Связанные FR |":
errors.append("таблица завершения должна иметь колонки Код, Смысл, Связанные FR")
codes = []
for row in rows[2:]:
cells = [cell.strip() for cell in row.strip("|").split("|")]
if len(cells) != 3 or not re.fullmatch(r"`[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+`", cells[0]):
errors.append("некорректная строка таблицы кодов завершения")
continue
code = cells[0].strip("`")
codes.append(code)
references = [
fr_targets[target][1]
for _, raw_target in LINK.findall(cells[2])
if (target := unquote(raw_target)) in fr_targets
and fr_targets[target][0] == requirement_id
]
if not cells[1] or not references or not any(code in fr_contents[fr_id] for fr_id in references if fr_id in fr_contents):
errors.append(f"{code}: нужны смысл и ссылка на локальный FR, описывающий этот код")
if not codes or len(codes) != len(set(codes)):
errors.append("список кодов завершения пуст или содержит дубликаты")
if set(CODE.findall(narrative)) != set(codes):
errors.append("коды в потоке/альтернативах должны совпадать со списком завершения")
return [f"{requirement_id}: {error}" for error in errors]
def validate(
path: Path,
base: Path | None = None,
require_qualified_ids: bool = False,
capability_codes: dict[str, str] | None = None,
) -> list[str]:
text = path.read_text(encoding="utf-8")
if HTML_ANCHOR.search(text):
return ["HTML-якоря запрещены; используйте автоматически сгенерированные Markdown-якоря заголовков"]
targets, fr_targets = heading_targets(text)
if base:
base_targets, base_fr_targets = heading_targets(base.read_text(encoding="utf-8"))
targets.update(base_targets)
fr_targets.update(base_fr_targets)
errors = []
if capability_codes is None:
capability_codes, registry_errors = load_capability_codes()
errors.extend(registry_errors)
blocks = list(requirement_blocks(text))
ids = REQUIREMENT_ID.findall(text)
if len(ids) != len(set(ids)):
errors.append("повторяющиеся ID Requirements")
capability_path = spec_capability_path(path)
for requirement_id in ids:
if "." not in requirement_id:
continue
prefix = capability_codes.get(capability_path or "")
if not prefix:
errors.append(f"для capability {capability_path or '<не определена>'} нет префикса в capability-codes.md")
elif not re.fullmatch(rf"{re.escape(prefix)}-\d{{2,}}", requirement_id):
errors.append(f"ID {requirement_id} не соответствует префиксу {prefix} для {capability_path}")
if not blocks and not re.search(r"^## (REMOVED|RENAMED) Requirements$", text, re.MULTILINE):
errors.append("нет Requirements")
for name, block in blocks:
errors.extend(check_requirement(name, block, targets, fr_targets, require_qualified_ids))
return errors
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("paths", nargs="*", type=Path, default=[Path("openspec/specs")])
parser.add_argument("--base", type=Path, help="master spec referenced from a delta")
parser.add_argument(
"--require-qualified-ids",
action="store_true",
help="требовать составные ID у Requirements в новых или изменённых specs",
)
args = parser.parse_args()
paths = sorted({file for path in args.paths for file in (path.rglob("spec.md") if path.is_dir() else [path])})
if not paths:
parser.error("не найдены spec.md")
capability_codes, registry_errors = load_capability_codes()
failed = False
for error in registry_errors:
print(f"ERROR {CAPABILITY_CODES_PATH}: {error}")
failed = True
for path in paths:
try:
errors = validate(path, args.base, args.require_qualified_ids, capability_codes)
except OSError as error:
errors = [str(error)]
for error in errors:
print(f"ERROR {path}: {error}")
if not errors:
print(f"OK {path}")
failed |= bool(errors)
return int(failed)
if __name__ == "__main__":
raise SystemExit(main())
View File