From d51782008866b3f6000be1bc08ac86197ab8cb38 Mon Sep 17 00:00:00 2001 From: zosimovaa Date: Sat, 10 Oct 2026 20:55:13 +0300 Subject: [PATCH] =?UTF-8?q?PLBA2-2.=20=D0=90=D1=80=D1=85=D0=B8=D0=B2=D0=B0?= =?UTF-8?q?=D1=86=D0=B8=D1=8F=20=D1=81=D0=BF=D0=B5=D0=BA?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../.openspec.yaml | 3 + .../2026-10-10-add-plba-python-ci/design.md | 42 +++ .../2026-10-10-add-plba-python-ci/proposal.md | 30 ++ .../2026-10-10-add-plba-python-ci/tasks.md | 18 ++ .../.openspec.yaml | 0 .../design.md | 0 .../proposal.md | 0 .../specs/api/http/control-api/spec.md | 0 .../application-config-file/spec.md | 0 .../application-settings/spec.md | 0 .../specs/health/aggregation/spec.md | 0 .../observability/business-tracing/spec.md | 0 .../observability/technical-logging/spec.md | 0 .../runtime/application-identity/spec.md | 0 .../runtime/application-lifecycle/spec.md | 0 .../specs/runtime/worker/spec.md | 0 .../specs/workflow/orchestration/spec.md | 0 .../tasks.md | 0 openspec/config.yaml | 12 +- openspec/schemas/function-driven/schema.yaml | 15 + .../function-driven/templates/design.md | 10 +- .../function-driven/templates/proposal.md | 24 +- .../function-driven/templates/tasks.md | 16 +- openspec/specs/api/http/control-api/spec.md | 284 ++++++++++++++++++ .../application-config-file/spec.md | 103 +++++++ .../application-settings/spec.md | 149 +++++++++ openspec/specs/health/aggregation/spec.md | 62 ++++ .../observability/business-tracing/spec.md | 90 ++++++ .../observability/technical-logging/spec.md | 44 +++ .../runtime/application-identity/spec.md | 52 ++++ .../runtime/application-lifecycle/spec.md | 110 +++++++ openspec/specs/runtime/worker/spec.md | 211 +++++++++++++ openspec/specs/workflow/orchestration/spec.md | 63 ++++ 33 files changed, 1313 insertions(+), 25 deletions(-) create mode 100644 openspec/changes/archive/2026-10-10-add-plba-python-ci/.openspec.yaml create mode 100644 openspec/changes/archive/2026-10-10-add-plba-python-ci/design.md create mode 100644 openspec/changes/archive/2026-10-10-add-plba-python-ci/proposal.md create mode 100644 openspec/changes/archive/2026-10-10-add-plba-python-ci/tasks.md rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/.openspec.yaml (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/design.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/proposal.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/specs/api/http/control-api/spec.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/specs/configuration/application-config-file/spec.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/specs/configuration/application-settings/spec.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/specs/health/aggregation/spec.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/specs/observability/business-tracing/spec.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/specs/observability/technical-logging/spec.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/specs/runtime/application-identity/spec.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/specs/runtime/application-lifecycle/spec.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/specs/runtime/worker/spec.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/specs/workflow/orchestration/spec.md (100%) rename openspec/changes/{plba2-runtime-and-adapters => archive/2026-10-10-plba2-runtime-and-adapters}/tasks.md (100%) create mode 100644 openspec/specs/api/http/control-api/spec.md create mode 100644 openspec/specs/configuration/application-config-file/spec.md create mode 100644 openspec/specs/configuration/application-settings/spec.md create mode 100644 openspec/specs/health/aggregation/spec.md create mode 100644 openspec/specs/observability/business-tracing/spec.md create mode 100644 openspec/specs/observability/technical-logging/spec.md create mode 100644 openspec/specs/runtime/application-identity/spec.md create mode 100644 openspec/specs/runtime/application-lifecycle/spec.md create mode 100644 openspec/specs/runtime/worker/spec.md create mode 100644 openspec/specs/workflow/orchestration/spec.md diff --git a/openspec/changes/archive/2026-10-10-add-plba-python-ci/.openspec.yaml b/openspec/changes/archive/2026-10-10-add-plba-python-ci/.openspec.yaml new file mode 100644 index 0000000..1c1817d --- /dev/null +++ b/openspec/changes/archive/2026-10-10-add-plba-python-ci/.openspec.yaml @@ -0,0 +1,3 @@ +schema: function-driven +created: 2026-10-10 +skip_specs: true diff --git a/openspec/changes/archive/2026-10-10-add-plba-python-ci/design.md b/openspec/changes/archive/2026-10-10-add-plba-python-ci/design.md new file mode 100644 index 0000000..1bebd2a --- /dev/null +++ b/openspec/changes/archive/2026-10-10-add-plba-python-ci/design.md @@ -0,0 +1,42 @@ +# Design + +## Context + +Пакету требуется Python 3.11 или новее; он использует setuptools с исходниками в `src/`, объявляет pytest в extra `test` и хранит тесты в `tests/`. Infra v2 поднимает общий Python CI runner на `cloud`; workflow Gitea выбирают его по метке `cloud-build`. + +Существующая проверка версии читает базовую версию командой `git show :pyproject.toml`, поэтому целевая ветка pull request должна присутствовать в локальной истории Git. Мотивация и общий scope приведены в `proposal.md`. + +## Goals / Non-Goals + +**Goals:** + +- Запускать тесты пакета для pull request и push в `main` на build runner infra v2. +- Требовать один допустимый шаг SemVer для каждого pull request. +- Выполнять CI пакета без прав и секретов деплоя приложений. + +**Non-Goals:** + +- Автоматически публиковать wheel, container image или релиз приложения. +- Деплоить сам PLBA через `infra_v2`. + +## Decisions + +- Использовать единый `.gitea/workflows/ci.yml` для тестов пакета и проверки версии pull request. Проверки остаются отдельными jobs одного workflow. +- Запускать тесты для pull request и push в `main`. Проверять версию только для pull request, используя `github.base_ref` как целевую ветку. +- Выбирать метку `cloud-build`, соответствующую host runner, зарегистрированному как `cloud-build:host`. +- Использовать Python, установленный для runner; завершать job с понятной ошибкой, если версия ниже 3.11. Устанавливать пакет и test-зависимости через `python -m pip install -e ".[test]"`, затем запускать `python -m pytest`. +- Загружать полную историю Git для job проверки версии и вызывать существующий checker со ссылкой `origin/${{ github.base_ref }}`. Checker использует только стандартную библиотеку Python. +- До `1.0.0` использовать PATCH для исправлений, рефакторинга и документации; MINOR — для новых возможностей и любых изменений публичного контракта, включая несовместимые. Версия `1.0.0` обозначает начало стабильного контракта. Начиная с `1.0.0`, использовать PATCH для совместимых исправлений, MINOR — для совместимых возможностей, MAJOR — для несовместимых изменений публичного контракта. +- Проверка принимает только один допустимый шаг SemVer относительно base pull request. Она не определяет, соответствует ли выбранный компонент типу изменения; это проверяют OpenSpec-планирование и code review. +- Не настраивать доступ к registry или токен деплоя. PLBA является Python-пакетом; публикацией образа и деплоем занимаются репозитории приложений. + +## Risks / Trade-offs + +- На build runner может оказаться Python ниже 3.11 → проверять версию интерпретатора до установки и выводить обнаруженную версию при ошибке. +- Для установки extra `test` нужен доступ к package index → устанавливать только объявленные зависимости и сохранять ошибки установки в job log. +- Контекст pull request в Gitea должен предоставлять `github.base_ref`, а checkout action — получать целевую ветку → загружать полную историю и использовать тот же контекст, что и текущая проверка версии. +- Внешние структурные заголовки OpenSpec остаются на английском, чтобы инструменты схемы распознавали артефакты; весь пояснительный текст, включая заголовки групп задач и сценариев, оформляется на русском. + +## Migration Plan + +Заменить version-only workflow объединённым CI workflow. Первый pull request запускает тесты и проверяет версию относительно целевой ветки; последующие push в `main` запускают тестовую job. Production-деплой и миграция данных не затрагиваются. diff --git a/openspec/changes/archive/2026-10-10-add-plba-python-ci/proposal.md b/openspec/changes/archive/2026-10-10-add-plba-python-ci/proposal.md new file mode 100644 index 0000000..bdc33c5 --- /dev/null +++ b/openspec/changes/archive/2026-10-10-add-plba-python-ci/proposal.md @@ -0,0 +1,30 @@ +# Proposal + +## Why + +PLBA v2 нужен единый порядок версионирования пакета и автоматические проверки на Gitea runner для Python-проектов. Кроме того, артефакты OpenSpec change должны создаваться на русском языке, а CI должен запускать тесты при push в `main`. + +## What Changes + +- Требовать от каждого реализованного OpenSpec change отдельную финальную задачу на увеличение версии пакета по правилам SemVer для версий до и после `1.0.0`. +- Проверять версию pull request относительно целевой ветки и запускать Python-тесты для pull request и push в `main` на общем build runner. +- Требовать русский язык для пояснительного текста всех артефактов change: `proposal.md`, `design.md`, `specs/**/*.md` и `tasks.md`. +- Ограничить CI проверками Python-пакета: не публиковать container image и не запускать деплой приложения. +- Увеличить версию пакета ровно один раз: с `0.1.0` до `0.1.1`. + +## Capabilities + +### New Capabilities + +Нет. Изменение добавляет правила разработки и CI-инструменты репозитория, не меняя runtime-поведение PLBA. + +### Modified Capabilities + +Нет. В `.openspec.yaml` указано `skip_specs: true`, поскольку продуктовые возможности и контракты не меняются. + +## Impact + +- Обновляет `openspec/config.yaml`, инструкции и шаблоны схемы `function-driven`. +- Добавляет `scripts/check_package_version.py` и workflow Gitea Actions. +- Использует дополнительную зависимость `test`, уже объявленную в `pyproject.toml`. +- Требует Gitea runner `cloud-build` с Python 3.11 или новее; секреты registry и деплоя не нужны. diff --git a/openspec/changes/archive/2026-10-10-add-plba-python-ci/tasks.md b/openspec/changes/archive/2026-10-10-add-plba-python-ci/tasks.md new file mode 100644 index 0000000..f1c700f --- /dev/null +++ b/openspec/changes/archive/2026-10-10-add-plba-python-ci/tasks.md @@ -0,0 +1,18 @@ +# Tasks + +## 1. Политика версии пакета + +- [x] 1.1 Добавить в `openspec/config.yaml` правила SemVer для версий до и после `1.0.0`; проверить, что правила задач требуют финальную задачу версии для каждого реализуемого изменения. +- [x] 1.2 Добавить финальную задачу версии в шаблон `function-driven` и реализовать `scripts/check_package_version.py`; проверить отклонение неизменённой, ошибочной, пропущенной и пониженной версии. + +## 2. CI Python-пакета PLBA + +- [x] 2.1 Добавить `.gitea/workflows/ci.yml` для pull request и push в `main` с runner `cloud-build`; проверить события и метку runner в workflow. +- [x] 2.2 Добавить job тестов Python, которая проверяет версию Python 3.11+, устанавливает `.[test]` и запускает `python -m pytest`; сверить команды с `pyproject.toml`. +- [x] 2.3 Добавить job проверки версии для pull request, получать целевую ветку и вызывать `scripts/check_package_version.py`; удалить прежний version-only workflow и проверить ref, передаваемый checker. +- [x] 2.4 Задать русский язык для пояснительного текста каждого изменения в `openspec/config.yaml` и инструкциях `function-driven`; проверить, что правило охватывает proposal, design, specs и tasks. +- [x] 2.5 Перевести пояснительный текст артефактов этого изменения на русский; проверить сохранение обязательных заголовков OpenSpec и технических идентификаторов. + +## 3. Версия этого change + +- [x] 3.1 Последней задачей увеличить версию в `pyproject.toml` с `0.1.0` до `0.1.1` на один PATCH и проверить её скриптом `scripts/check_package_version.py` относительно базового коммита. diff --git a/openspec/changes/plba2-runtime-and-adapters/.openspec.yaml b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/.openspec.yaml similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/.openspec.yaml rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/.openspec.yaml diff --git a/openspec/changes/plba2-runtime-and-adapters/design.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/design.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/design.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/design.md diff --git a/openspec/changes/plba2-runtime-and-adapters/proposal.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/proposal.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/proposal.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/proposal.md diff --git a/openspec/changes/plba2-runtime-and-adapters/specs/api/http/control-api/spec.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/api/http/control-api/spec.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/specs/api/http/control-api/spec.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/api/http/control-api/spec.md diff --git a/openspec/changes/plba2-runtime-and-adapters/specs/configuration/application-config-file/spec.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/configuration/application-config-file/spec.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/specs/configuration/application-config-file/spec.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/configuration/application-config-file/spec.md diff --git a/openspec/changes/plba2-runtime-and-adapters/specs/configuration/application-settings/spec.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/configuration/application-settings/spec.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/specs/configuration/application-settings/spec.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/configuration/application-settings/spec.md diff --git a/openspec/changes/plba2-runtime-and-adapters/specs/health/aggregation/spec.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/health/aggregation/spec.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/specs/health/aggregation/spec.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/health/aggregation/spec.md diff --git a/openspec/changes/plba2-runtime-and-adapters/specs/observability/business-tracing/spec.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/observability/business-tracing/spec.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/specs/observability/business-tracing/spec.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/observability/business-tracing/spec.md diff --git a/openspec/changes/plba2-runtime-and-adapters/specs/observability/technical-logging/spec.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/observability/technical-logging/spec.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/specs/observability/technical-logging/spec.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/observability/technical-logging/spec.md diff --git a/openspec/changes/plba2-runtime-and-adapters/specs/runtime/application-identity/spec.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/runtime/application-identity/spec.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/specs/runtime/application-identity/spec.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/runtime/application-identity/spec.md diff --git a/openspec/changes/plba2-runtime-and-adapters/specs/runtime/application-lifecycle/spec.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/runtime/application-lifecycle/spec.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/specs/runtime/application-lifecycle/spec.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/runtime/application-lifecycle/spec.md diff --git a/openspec/changes/plba2-runtime-and-adapters/specs/runtime/worker/spec.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/runtime/worker/spec.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/specs/runtime/worker/spec.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/runtime/worker/spec.md diff --git a/openspec/changes/plba2-runtime-and-adapters/specs/workflow/orchestration/spec.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/workflow/orchestration/spec.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/specs/workflow/orchestration/spec.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/specs/workflow/orchestration/spec.md diff --git a/openspec/changes/plba2-runtime-and-adapters/tasks.md b/openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/tasks.md similarity index 100% rename from openspec/changes/plba2-runtime-and-adapters/tasks.md rename to openspec/changes/archive/2026-10-10-plba2-runtime-and-adapters/tasks.md diff --git a/openspec/config.yaml b/openspec/config.yaml index 856a4bc..95d1b50 100644 --- a/openspec/config.yaml +++ b/openspec/config.yaml @@ -10,10 +10,14 @@ context: | Включай только сведения, влияющие на наблюдаемое поведение, устойчивый контракт или обязательное техническое ограничение; не добавляй повторы и пояснительный текст без такого влияния. - Пиши спецификации по-русски; имена API, SQL-полей и кодов сохраняй. + Пиши по-русски весь пояснительный текст каждого изменения OpenSpec: + в proposal.md, design.md, specs/**/*.md и tasks.md. Сохраняй обязательные + заголовки и синтаксис OpenSpec, имена API, SQL-полей, кодов, файлов, + инструментов, команд и идентификаторы без перевода. rules: specs: + - Пиши пояснительный текст спецификаций по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы. - Каждый Requirement содержит ровно один Use case. Автор выбирает полный или сокращенный формат независимо от типа FR и предмета описания. - Обычный FR без метки описывает логику, правила или последовательность шагов; специальные типы помечай в заголовке FR как [DB], [API] или [UI]. - FR [DB] с таблицей БД оформляй по openspec/schemas/function-driven/patterns/database-table.md. @@ -27,7 +31,13 @@ rules: - Проверяй формат командой python3 openspec/schemas/function-driven/validate_format.py . proposal: - Сохраняй полные иерархические пути capabilities. + - Пиши пояснительный текст proposal по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы. design: - Ссылайся на Requirement ID и локальные FR; описывай решения реализации без копирования требований. + - Пиши пояснительный текст design по-русски; сохраняй обязательные заголовки OpenSpec и технические идентификаторы. tasks: - Связывай задачи с Requirement ID, FR и кодами завершения, если задача затрагивает эти результаты. + - Пиши названия групп и формулировки задач по-русски; сохраняй команды, пути, API, коды и идентификаторы без перевода. + - Каждый реализуемый change заканчивай отдельной последней задачей на увеличение версии пакета в pyproject.toml. Выполняй её после реализации и проверок; один change повышает версию ровно один раз. + - До версии 1.0.0 используй PATCH для исправлений, рефакторинга и документации; MINOR для новых возможностей и любых изменений публичного контракта, включая несовместимые. Переход на 1.0.0 означает начало стабильного публичного контракта. + - Начиная с 1.0.0 используй PATCH для исправлений, рефакторинга и документации, MINOR для обратно совместимых возможностей и MAJOR для несовместимых изменений публичного контракта. diff --git a/openspec/schemas/function-driven/schema.yaml b/openspec/schemas/function-driven/schema.yaml index b3cb764..b5c88d5 100644 --- a/openspec/schemas/function-driven/schema.yaml +++ b/openspec/schemas/function-driven/schema.yaml @@ -7,6 +7,10 @@ artifacts: description: Initial proposal document outlining the change template: proposal.md instruction: | + Пиши весь пояснительный текст артефакта изменения по-русски. Сохраняй + обязательные заголовки OpenSpec и технические идентификаторы, названия + API, файлов, инструментов, команд и коды без перевода. + Create the proposal document that establishes WHY this change is needed. Sections: @@ -52,6 +56,10 @@ artifacts: description: Detailed specifications for the change template: spec.md instruction: | + Пиши весь пояснительный текст спецификаций по-русски. Сохраняй + обязательные заголовки OpenSpec, идентификаторы, названия API и коды + без перевода. + Создай спецификации наблюдаемого поведения и устойчивых контрактов. Правила ниже применяются к master specs и к полным блокам ADDED/MODIFIED в delta specs. Это пользовательский формат без Gherkin. @@ -180,6 +188,10 @@ artifacts: description: Technical design document with implementation details template: design.md instruction: | + Пиши весь пояснительный текст design по-русски. Сохраняй обязательные + заголовки OpenSpec и технические идентификаторы, названия файлов, + инструментов и команд без перевода. + Create the design document that explains HOW to implement the change. When to include design.md (create only if any apply): @@ -215,6 +227,9 @@ artifacts: description: Implementation checklist with trackable tasks template: tasks.md instruction: | + Пиши названия групп и формулировки задач по-русски. Сохраняй обязательные + идентификаторы, пути файлов, названия API, коды и команды без перевода. + Create the task list that breaks down the implementation work. Before writing tasks, check design.md for Open Questions. If any of them diff --git a/openspec/schemas/function-driven/templates/design.md b/openspec/schemas/function-driven/templates/design.md index dc6ca73..f3225e1 100644 --- a/openspec/schemas/function-driven/templates/design.md +++ b/openspec/schemas/function-driven/templates/design.md @@ -2,20 +2,20 @@ ## Context - + ## Goals / Non-Goals **Goals:** - + **Non-Goals:** - + ## Decisions - + ## Risks / Trade-offs - + diff --git a/openspec/schemas/function-driven/templates/proposal.md b/openspec/schemas/function-driven/templates/proposal.md index b075f32..febb3fc 100644 --- a/openspec/schemas/function-driven/templates/proposal.md +++ b/openspec/schemas/function-driven/templates/proposal.md @@ -2,30 +2,28 @@ ## Why - + ## What Changes - + ## Capabilities ### New Capabilities - + - ``: ### Modified Capabilities - + - ``: ## Impact - + diff --git a/openspec/schemas/function-driven/templates/tasks.md b/openspec/schemas/function-driven/templates/tasks.md index 148874e..427379c 100644 --- a/openspec/schemas/function-driven/templates/tasks.md +++ b/openspec/schemas/function-driven/templates/tasks.md @@ -1,11 +1,15 @@ # Tasks -## 1. +## 1. -- [ ] 1.1 -- [ ] 1.2 +- [ ] 1.1 +- [ ] 1.2 -## 2. +## 2. -- [ ] 2.1 -- [ ] 2.2 +- [ ] 2.1 +- [ ] 2.2 + +## 3. Обновление версии + +- [ ] 3.1 Последней задачей увеличь версию пакета в `pyproject.toml` по правилам `openspec/config.yaml` и проверь изменение скриптом `scripts/check_package_version.py`. diff --git a/openspec/specs/api/http/control-api/spec.md b/openspec/specs/api/http/control-api/spec.md new file mode 100644 index 0000000..f5dcfd6 --- /dev/null +++ b/openspec/specs/api/http/control-api/spec.md @@ -0,0 +1,284 @@ +# Capability: HTTP API управления приложением + +## Purpose + +Объединить health и управление lifecycle приложения в одном HTTP API, подключаемом к host приложения. + +## Границы + +- В capability входят маршруты /health, /runtime/start, /runtime/stop и /runtime/status, подключаемые к HTTP host приложения. + +## 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` | Обязательное | 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-ожидание-и-статус-остановки) | diff --git a/openspec/specs/configuration/application-config-file/spec.md b/openspec/specs/configuration/application-config-file/spec.md new file mode 100644 index 0000000..4951bea --- /dev/null +++ b/openspec/specs/configuration/application-config-file/spec.md @@ -0,0 +1,103 @@ +# Capability: Файл технической конфигурации приложения + +## Purpose + +Предоставлять приложению загрузчик редко меняемых технических параметров из `config.yaml` с поддержкой перезагрузки без рестарта. + +## Границы + +- В capability входят начальная загрузка технических параметров из корневого config.yaml и атомарное применение валидных изменений без рестарта. Бизнес-настройки и удалённо меняемые runtime-значения относятся к configuration/application-settings. + +## 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..disabled` (boolean, по умолчанию `false`), `workers..interval_seconds` и `workers..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`. diff --git a/openspec/specs/configuration/application-settings/spec.md b/openspec/specs/configuration/application-settings/spec.md new file mode 100644 index 0000000..6728b60 --- /dev/null +++ b/openspec/specs/configuration/application-settings/spec.md @@ -0,0 +1,149 @@ +# Capability: Хранение и чтение настроек приложения + +## Purpose + +Давать приложениям общий контракт хранения бизнес-параметров и технических значений, которые должны меняться в runtime без рестарта. + +## Границы + +- В capability входят контракт таблицы settings, начальная загрузка миграцией приложения и типизированное чтение через PostgreSQL adapter. Таблицы и данные принадлежат приложению. + +## Requirements + +### Requirement: Контракт хранения настроек + +**ID:** `CFG.AS-01` + +PLBA2 SHALL определять назначение полей и структуру таблицы для бизнес-параметров и технических значений, которыми приложение управляет в runtime. + +#### Scenario: Сокращенный use case: структура настроек + +##### Основной поток + +1. Фиксируем поля таблицы `settings`, их назначение и ограничения по [CFG.AS-01.FR-01](#cfgas-01fr-01-db-таблица-хранения-settings). + +#### Функциональные требования + +##### CFG.AS-01.FR-01 [DB]: Таблица хранения settings + +Таблица `settings` создаётся в схеме приложения и содержит: + +| Поле | Тип | Ограничения и значение по умолчанию | Назначение | +| --- | --- | --- | --- | +| `id` | `BIGINT` | identity, primary key, NOT NULL | Идентификатор строки | +| `config_key` | `VARCHAR(128)` | NULL | Область или сущность приложения | +| `setting_key` | `VARCHAR(128)` | NOT NULL | Имя настройки | +| `setting_value` | `TEXT` | NOT NULL | Текстовое значение настройки | +| `sort_order` | `INT` | NOT NULL, DEFAULT 0 | Порядок повторяющихся ключей | +| `is_enabled` | `BOOLEAN` | NOT NULL, DEFAULT TRUE | Признак участия записи в чтении | +| `description` | `TEXT` | NULL | Пояснение к настройке | + +Индексы поддерживают выборку по `setting_key`, `config_key`, `is_enabled` и порядок `sort_order`, `id`. Ограничение уникальности на `setting_key` не устанавливается. Приложение владеет DDL, данными и связями `config_key` со своими сущностями. + +В `settings` хранятся бизнес-параметры, feature toggles и технические значения, которые нужно менять удалённо во время работы приложения. Feature toggle хранится в `setting_value`; `is_enabled` только включает или исключает строку из чтения. Редко меняемые технические параметры задаются отдельным файлом `config.yaml`. + +### Requirement: Загрузка настроек + +**ID:** `CFG.AS-02` + +Приложение SHALL загружать начальные настройки в собственную базу данных миграцией при установке или первой раскатке. + +#### Scenario: Загрузка начальных настроек + +##### Участники + +- Миграция приложения и база данных приложения. + +##### Предусловия + +- База данных приложения доступна для применения миграции. + +##### Основной поток + +1. Миграция создаёт нужное приложению хранилище по [CFG.AS-01.FR-01](#cfgas-01fr-01-db-таблица-хранения-settings). +2. Миграция записывает начальные значения непосредственно в базу приложения и завершается с `SETTINGS_LOADED` по [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки). + +##### Альтернативы и ошибки + +- Миграция не может создать хранилище или записать значения — загрузка завершается с `SETTINGS_LOAD_FAILED` по [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки). + +##### Результат + +Настройки приложения доступны в его базе до запуска использующего их кода. + +##### Коды завершения + +| Код | Смысл | Связанные FR | +| --- | --- | --- | +| `SETTINGS_LOADED` | Миграция записала настройки в базу приложения | [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки) | +| `SETTINGS_LOAD_FAILED` | Миграция не создала хранилище или не записала настройки | [CFG.AS-02.FR-02](#cfgas-02fr-02-результат-загрузки) | + +#### Функциональные требования + +##### CFG.AS-02.FR-01: Загрузка миграцией + +Приложение создаёт таблицу `settings` и загружает начальные значения собственными миграциями при первой раскатке. Последующие значения бизнес-параметров и технических параметров, меняемых удалённо, могут обновляться в БД без рестарта приложения. PLBA2 не запускает миграции, не управляет изменением строк и не переносит YAML-конфигурацию в `settings`; конфигурация из `config.yaml` является отдельным слоем. + +##### CFG.AS-02.FR-02: Результат загрузки + +| Код | Текст сообщения | Дальнейшее поведение | +| --- | --- | --- | +| `SETTINGS_LOADED` | Сообщение отсутствует | Приложение может запускать компоненты, которым нужны загруженные настройки | +| `SETTINGS_LOAD_FAILED` | Исходная ошибка миграции доступна инструменту установки | Раскатка не считается успешной; приложение исправляет причину и повторно применяет миграцию по правилам своего инструмента | + +### Requirement: Чтение настроек + +**ID:** `CFG.AS-03` + +PLBA2 SHALL предоставлять типизированный контракт чтения настроек и PostgreSQL-адаптер, читающий данные из схемы приложения. + +#### Scenario: Чтение настроек приложения + +##### Участники + +- Бизнес-модуль, SettingsReader, PostgreSQL-адаптер и база данных приложения. + +##### Предусловия + +- Приложение объявило типизированный ключ с decoder и передало адаптеру пул PostgreSQL и имя своей схемы. + +##### Основной поток + +1. Запрашиваем включённые записи по ключу и, если задана, области `config_key` в порядке контракта по [CFG.AS-03.FR-02](#cfgas-03fr-02-postgresql-адаптер). +2. Декодируем значения и возвращаем их через SettingsReader с кодом `SETTING_READ` по [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения). + +##### Альтернативы и ошибки + +- Нет обязательного значения — возвращаем `SETTING_NOT_FOUND`; decoder отклонил значение — `SETTING_INVALID`; PostgreSQL недоступен — `SETTINGS_DATABASE_UNAVAILABLE`, согласно [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения). + +##### Результат + +Бизнес-код использует типизированный контракт независимо от конкретного адаптера хранения. + +##### Коды завершения + +| Код | Смысл | Связанные FR | +| --- | --- | --- | +| `SETTING_READ` | Значения прочитаны и декодированы в исходном порядке | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) | +| `SETTING_NOT_FOUND` | Отсутствует обязательная настройка | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) | +| `SETTING_INVALID` | Значение не прошло decoder приложения | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) | +| `SETTINGS_DATABASE_UNAVAILABLE` | Запрос к базе приложения завершился ошибкой | [CFG.AS-03.FR-03](#cfgas-03fr-03-результат-чтения) | + +#### Функциональные требования + +##### CFG.AS-03.FR-01: Контракт SettingsReader + +SettingsReader принимает типизированный ключ настройки и необязательный `config_key`, возвращает упорядоченный список значений типа ключа. Для ключа приложение задаёт decoder и обязательность или default. Каждый вызов использует актуальное значение источника настроек; удалённое изменение применяется при следующем чтении без рестарта приложения. Бизнес-код зависит от контракта, а не от SQL или драйвера БД. + +##### CFG.AS-03.FR-02: PostgreSQL-адаптер + +Адаптер читает `settings` схемы приложения через переданный приложением пул. Он фильтрует по `setting_key`, заданному `config_key` и `is_enabled = TRUE`, сохраняя порядок `sort_order`, затем `id`. Значения запроса параметризуются; имя схемы валидируется и безопасно экранируется. Адаптер не создаёт таблицу, не запускает миграции и не владеет настройками. + +##### CFG.AS-03.FR-03: Результат чтения + +| Код | Текст сообщения | Дальнейшее поведение | +| --- | --- | --- | +| `SETTING_READ` | Сообщение отсутствует | Декодированные значения передаются приложению в порядке контракта | +| `SETTING_NOT_FOUND` | Сообщение отсутствует | Для обязательного ключа возвращается типизированная ошибка; default применяется только по настройке ключа | +| `SETTING_INVALID` | Сообщение отсутствует; исходная ошибка decoder доступна приложению | Значение не выдаётся как успешно прочитанное | +| `SETTINGS_DATABASE_UNAVAILABLE` | Сообщение отсутствует; исходная ошибка драйвера передаётся приложению | PLBA2 не подменяет ошибку default-значением и не выполняет скрытый retry | diff --git a/openspec/specs/health/aggregation/spec.md b/openspec/specs/health/aggregation/spec.md new file mode 100644 index 0000000..0c26a79 --- /dev/null +++ b/openspec/specs/health/aggregation/spec.md @@ -0,0 +1,62 @@ +# Capability: Агрегация health-состояния приложения + +## Purpose + +Агрегировать текущий health приложения из runtime, workers и health contributors. + +## Границы + +- В capability входят агрегация lifecycle приложения, состояний workers и health contributors, расчёт общего статуса и формирование отчёта. + +## 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 | diff --git a/openspec/specs/observability/business-tracing/spec.md b/openspec/specs/observability/business-tracing/spec.md new file mode 100644 index 0000000..e71f8c1 --- /dev/null +++ b/openspec/specs/observability/business-tracing/spec.md @@ -0,0 +1,90 @@ +# Capability: Бизнес-история приложения + +## Purpose + +Сохранять ход бизнес-операций в trace_contexts и trace_messages схемы приложения. + +## Границы + +- В capability входят контракты trace_contexts и trace_messages и PostgreSQL adapter для записи в схему приложения. Таблицы и миграции принадлежат приложению; API просмотра истории не входит в capability. + +## 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; приложение выбирает политику ошибки | diff --git a/openspec/specs/observability/technical-logging/spec.md b/openspec/specs/observability/technical-logging/spec.md new file mode 100644 index 0000000..a6f2189 --- /dev/null +++ b/openspec/specs/observability/technical-logging/spec.md @@ -0,0 +1,44 @@ +# Capability: Техническое логирование + +## Purpose + +Формировать единые технические JSON-логи в stdout с application_id и business_trace_id. + +## Границы + +- В capability входят контракт JSON-записи технического лога и её вывод через stdlib StreamHandler в stdout. Хранение и доставка логов находятся за пределами capability. + +## 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; доставку и просмотр обеспечивает платформа. diff --git a/openspec/specs/runtime/application-identity/spec.md b/openspec/specs/runtime/application-identity/spec.md new file mode 100644 index 0000000..8e3bfd9 --- /dev/null +++ b/openspec/specs/runtime/application-identity/spec.md @@ -0,0 +1,52 @@ +# Capability: Идентификатор приложения + +## Purpose + +Определять `application_id` приложения и предоставлять разрешённое значение runtime-контексту. + +## Границы + +- В capability входит однократное разрешение application_id из config.yaml, метаданных проекта или UUIDv4 и предоставление значения runtime до запуска зависимых компонентов. + +## 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`. diff --git a/openspec/specs/runtime/application-lifecycle/spec.md b/openspec/specs/runtime/application-lifecycle/spec.md new file mode 100644 index 0000000..e692545 --- /dev/null +++ b/openspec/specs/runtime/application-lifecycle/spec.md @@ -0,0 +1,110 @@ +# Capability: Жизненный цикл приложения + +## Purpose + +Управлять lifecycle всего приложения через runtime-контракт, сохраняя entrypoint и HTTP host в приложении. + +## Границы + +- В capability входят запуск и остановка приложения, переходы lifecycle status и результаты graceful или принудительной остановки workers. Завершение OS-процесса и принадлежащего приложению HTTP host остаётся ответственностью приложения. + +## 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..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 | diff --git a/openspec/specs/runtime/worker/spec.md b/openspec/specs/runtime/worker/spec.md new file mode 100644 index 0000000..79a8d5b --- /dev/null +++ b/openspec/specs/runtime/worker/spec.md @@ -0,0 +1,211 @@ +# Capability: Workers приложения + +## Purpose + +Запускать именованные workers независимо друг от друга, выполнять их процессы по расписанию и формировать их health-состояния. + +## Границы + +- В capability входят регистрация workers, независимые lifecycle и health, последовательное выполнение циклов по расписанию и контролируемая остановка. + +## 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..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..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 нужно задать ровно одну положительную длительность в секундах: `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 сохраняет работу и запускает следующий цикл по расписанию | diff --git a/openspec/specs/workflow/orchestration/spec.md b/openspec/specs/workflow/orchestration/spec.md new file mode 100644 index 0000000..df093be --- /dev/null +++ b/openspec/specs/workflow/orchestration/spec.md @@ -0,0 +1,63 @@ +# Capability: Оркестрация workflow + +## Purpose + +Выполнять workflow из шагов приложения по явным переходам и сохранять состояние выполнения. + +## Границы + +- В capability входят именованные шаги приложения, явные допустимые переходы и сохранение состояния запуска через переданный persistence-контракт. Бизнес-правила и подключение к БД задаёт приложение. + +## 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 и не повторяет шаг |