PLBA2-1. Спецификация
This commit is contained in:
@@ -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-ожидание-и-статус-остановки) |
|
||||
+99
@@ -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`.
|
||||
+145
@@ -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 |
|
||||
+86
@@ -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; приложение выбирает политику ошибки |
|
||||
+40
@@ -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; доставку и просмотр обеспечивает платформа.
|
||||
+48
@@ -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`.
|
||||
+106
@@ -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.
|
||||
@@ -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 и кодами завершения, если задача затрагивает эти результаты.
|
||||
@@ -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).
|
||||
Binary file not shown.
@@ -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())
|
||||
Reference in New Issue
Block a user