From 570acfaa5643161c769ec9ceb684b4d27ea4f56c Mon Sep 17 00:00:00 2001 From: tsygankoviva Date: Mon, 26 Oct 2026 09:24:23 +0300 Subject: [PATCH] =?UTF-8?q?AURORA-1677:=20arm=5Fstatements=20=D1=82=D0=B5?= =?UTF-8?q?=D0=BF=D0=B5=D1=80=D1=8C=20=D0=B1=D0=B8=D0=B1=D0=BB=D0=B8=D0=BE?= =?UTF-8?q?=D1=82=D0=B5=D0=BA=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- context/03-architecture.md | 3 ++ context/07-open-questions.md | 3 ++ context/09-delivery-plan.md | 3 ++ contracts/recognition-result.schema.json | 4 +-- .../.openspec.yaml | 3 ++ .../design.md | 25 ++++++++++++++++ .../proposal.md | 29 +++++++++++++++++++ .../tasks.md | 10 +++++++ 8 files changed, 78 insertions(+), 2 deletions(-) create mode 100644 openspec/changes/document-statements-library-contract/.openspec.yaml create mode 100644 openspec/changes/document-statements-library-contract/design.md create mode 100644 openspec/changes/document-statements-library-contract/proposal.md create mode 100644 openspec/changes/document-statements-library-contract/tasks.md diff --git a/context/03-architecture.md b/context/03-architecture.md index fa900f0..ed4b50a 100644 --- a/context/03-architecture.md +++ b/context/03-architecture.md @@ -1,5 +1,8 @@ # 03. Архитектура (целевая, по решениям DECISION-1…5 и ARCH-* в DBML v5.22) +> Актуализация 23.10.2026: arm-core подключает `arm_statements` как устанавливаемую библиотеку `pylib-ai-arm-statements`; локальная установка — `make venv`, переустановка — `make install`. Версия — непустой VERSION, иначе метаданные дистрибутива. Ниже описана также прежняя схема копирования для сервисов; завершение их перехода здесь не утверждается. Change: `document-statements-library-contract`, дочерний arm-core `use-installed-statements-library`. + + ## Компоненты (= репозитории, см. `00-workspace-layout.md`) ``` diff --git a/context/07-open-questions.md b/context/07-open-questions.md index ad2ad90..e7e3cfc 100644 --- a/context/07-open-questions.md +++ b/context/07-open-questions.md @@ -1,5 +1,8 @@ # 07. Открытые вопросы (реестр) +> Примечание 23.10.2026: change `document-statements-library-contract` актуализирует только описания библиотеки в JSON-контракте. Согласование идентификаторов версий библиотеки между сервисами остаётся отдельной работой; новые решения и номера OQ этим обновлением не вводятся. + + Правило: агент **не закрывает** вопросы сам. Если решение нужно для текущего среза — делает явное допущение, помечает его в коде `# ASSUMPTION(OQ-nn)` и в OpenSpec-change, и переносит вопрос в статус «допущение принято». Пользователь закрывает вопросы с аналитиками/методологами и обновляет этот файл. diff --git a/context/09-delivery-plan.md b/context/09-delivery-plan.md index 45d1f81..fa638bb 100644 --- a/context/09-delivery-plan.md +++ b/context/09-delivery-plan.md @@ -1,5 +1,8 @@ # 09. План работ вертикальными срезами +> Сопровождение среза 3b, 23.10.2026: `document-statements-library-contract` согласует описания общей схемы с переходом arm-core на библиотеку (дочерний change `use-installed-statements-library`). Формат остаётся 2.0; статус поставки других сервисов этим обновлением не меняется. + + Принцип: каждый срез — рабочий end-to-end кусок (миграции + API + минимальный UI + тесты на реальных фикстурах), который можно показать аналитику. Порядок выбран так, чтобы самое рискованное (парсер ОСВ, матчинг ВГО) проверялось на реальных данных как можно раньше, а внешние зависимости (ИС Сканирование, РАИСА, NATS платформы) не блокировали. diff --git a/contracts/recognition-result.schema.json b/contracts/recognition-result.schema.json index 19531dd..7590744 100644 --- a/contracts/recognition-result.schema.json +++ b/contracts/recognition-result.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "arm-ka/recognition-result/v2", "title": "Результат распознавания файла (tabular-parser / scan-gateway), контракт v2.0", - "description": "Один файл (stored_file) → один job → N документов. Сервисы не знают БД: только структура файла. Формы ББ/ОФР нормализуются общим кодом arm_statements (05-domain-rules.md §11): статусы строк, needs_review, проверки §7, статус документа и структурные предупреждения приходят готовыми; ядро хранит их как пришли и пересчитывает тем же кодом только после правок аналитика. Нормализация счетов ОСВ, резолв контрагентов, сверка ИНН и периода — в arm-core.", + "description": "Один файл (stored_file) → один job → N документов. Сервисы не знают БД: только структура файла. Формы ББ/ОФР нормализуются библиотекой arm_statements (05-domain-rules.md §11): статусы строк, needs_review, проверки §7, статус документа и структурные предупреждения приходят готовыми; ядро хранит их как пришли и пересчитывает тем же кодом только после правок аналитика. Нормализация счетов ОСВ, резолв контрагентов, сверка ИНН и периода — в arm-core.", "$comment": "Версионирование: schema_version = MAJOR.MINOR. MINOR (2.1, 2.2, …) — необязательные поля и новые значения enum; MAJOR (3.0) — удаление/переименование полей, смена типов или семантики. Потребитель принимает известный MAJOR и любой MINOR. Новый MINOR раскатывается сначала на потребителей (ядро и сервисы обновляют копии схем раньше, чем производитель начнёт слать новый MINOR), потому что закрытые enum отвергают незнакомые значения. Новый MAJOR — порядок «сначала ядро»: ядро на время перехода принимает и прежний, и новый MAJOR (два маппера), сервисы переходят после выкладки ядра. Changelog: 1.0 — исходный контракт; 1.1 — osvDocument.rows[].extra; 1.2 — DISCLOSURE, statementDocument.checks, границы периода ОСВ; 2.0 (RSHB/arm-ka-docs#116, change unified-statement-normalization) — line_code nullable и line_status (ok | unreadable | missing | detail), row_index, ref, parent_ref, line_code_text, needs_review у значения и строки, values[].text, header.<поле>_text и <поле>_confidence у всех полей шапки, header.needs_review_fields, columns[].period_kind и label_confidence, document.status и document.warnings у всех документов (включая ОСВ), statementDocument.form_variant, metrics.warnings и warnings — структуры с уровнем и привязкой, checks обязателен у BALANCE/INCOME со строками, нарушения с codes, удалён checks.duplicate_line_codes, service.statements_version, header.okei (+ _text, _confidence), смысл is_recognized у OCR отвязан от confidence, statementDocument.form_variant обязателен, OTHER удалён из statementDocument.document_type. Схема 1.2 на окне перехода лежит рядом — recognition-result.v1.schema.json (примеры — examples/v1/); удаляется вместе с маппером 1.x ядра после перехода обоих сервисов.", "type": "object", "required": ["schema_version", "job_id", "file_id", "service", "status", "documents"], @@ -16,7 +16,7 @@ "properties": { "name": { "enum": ["tabular-parser", "scan-gateway"] }, "version": { "type": "string" }, - "statements_version": { "type": "string", "minLength": 1, "description": "коммит репозитория arm-statements, из которого разложена копия общего кода; обязателен, если в documents есть statementDocument" } + "statements_version": { "type": "string", "minLength": 1, "description": "маркер VERSION библиотеки arm_statements, если он есть, иначе версия установленного дистрибутива pylib-ai-arm-statements; обязателен, если в documents есть statementDocument" } } }, "status": { "enum": ["done", "needs_check", "error"], "description": "done ⇔ все документы done и нет предупреждений файла уровня error; error — документов нет" }, diff --git a/openspec/changes/document-statements-library-contract/.openspec.yaml b/openspec/changes/document-statements-library-contract/.openspec.yaml new file mode 100644 index 0000000..433743a --- /dev/null +++ b/openspec/changes/document-statements-library-contract/.openspec.yaml @@ -0,0 +1,3 @@ +schema: spec-driven +created: 2026-10-23 +skip_specs: true diff --git a/openspec/changes/document-statements-library-contract/design.md b/openspec/changes/document-statements-library-contract/design.md new file mode 100644 index 0000000..9dbe077 --- /dev/null +++ b/openspec/changes/document-statements-library-contract/design.md @@ -0,0 +1,25 @@ +# Design + +## Context + +Связанный change arm-core — `use-installed-statements-library`; обновление аннотаций общей схемы одобрено пользователем 23.10.2026. Файл схемы в docs — источник истины для побайтовых копий сервисов. + +## Goals / Non-Goals + +**Goals:** согласовать descriptions и явно подтвердить отсутствие изменений валидируемой структуры. + +**Non-Goals:** изменение версии/ограничений контракта, правка docs/source, запуск миграций, обновление runtime других сервисов. + +## Decisions + +Обновить только корневой description и description поля service.statements_version по согласованному тексту arm-core. Проверить глубокое равенство JSON до/после без этих двух аннотаций и точное совпадение файлов docs/arm-core. Использовать существующий валидатор примеров и тест сверки копий. Отдельные дельты требований не нужны (`skip_specs: true`), поскольку нормативный формат не меняется. + +Контекст получает короткие заметки о переходе arm-core; они не объявляют переход остальных сервисов завершённым. + +## Decisions made without discussion + +23.10.2026: сохранить schema_version 2.0 при изменении только descriptions. Обоснование — множество валидных входов и структура результата неизменны. Цена ошибки — неверная маркировка релиза; проверяется сравнением JSON без двух изменённых аннотаций. Обновление общей схемы вместо отката локальной копии выбрано пользователем. + +## Risks / Trade-offs + +[Другие копии схем ещё содержат прежний текст] → перечислить производителей и потребителя в proposal; их копии могут быть синхронизированы отдельными изменениями. [Контекст по другим сервисам не проверялся] → заметки ограничены arm-core. diff --git a/openspec/changes/document-statements-library-contract/proposal.md b/openspec/changes/document-statements-library-contract/proposal.md new file mode 100644 index 0000000..0dc48c9 --- /dev/null +++ b/openspec/changes/document-statements-library-contract/proposal.md @@ -0,0 +1,29 @@ +# Proposal + +## Why + +Описание общей нормализации и `service.statements_version` ещё говорит о копировании исходников. После перехода arm-core на устанавливаемую библиотеку локальные описания актуализированы, но перестали побайтово совпадать с источником в docs. + +## What Changes + +- В `contracts/recognition-result.schema.json` актуализируются только два `description`: нормализация библиотекой `arm_statements` и источник версии (непустой VERSION, иначе метаданные дистрибутива `pylib-ai-arm-statements`). +- Текст синхронизируется с `../arm-core/api/contracts/recognition-result.schema.json`; структура, обязательность полей и ограничения JSON Schema сохраняются. +- `schema_version` остаётся 2.0: меняются только аннотации документации, а не формат, проверка данных или семантика обработки результата. Правило повышения версии контракта применяется к изменениям поведения/формата, которых здесь нет. + +## Capabilities + +### New Capabilities + +Нет. + +### Modified Capabilities + +Нет изменений нормативных требований: documentation-only, `skip_specs: true`. + +## Impact + +Сопровождение среза 3b. Связанный дочерний change: `../arm-core/openspec/changes/use-installed-statements-library`. Читатель результата — arm-core, производители — tabular-parser и scan-gateway; runtime-код этих сервисов не меняется. Их обновление текстовых копий схем можно выполнять отдельно; этот change подтверждает совпадение docs и arm-core. + +## Non-goals + +Новые поля, типы, enum, изменение MAJOR/MINOR, изменение алгоритмов §7/§11, миграции БД, массовое редактирование исходников сервисов и закрытие вопросов общего выпуска библиотеки. Контекстные документы получают только точечную заметку о статусе arm-core, без объявления миграции других сервисов завершённой. diff --git a/openspec/changes/document-statements-library-contract/tasks.md b/openspec/changes/document-statements-library-contract/tasks.md new file mode 100644 index 0000000..179921a --- /dev/null +++ b/openspec/changes/document-statements-library-contract/tasks.md @@ -0,0 +1,10 @@ +# Tasks + +## 1. Аннотации контракта + +- [x] 1.1 docs, contracts/recognition-result.schema.json: обновить два description по согласованной копии arm-core; проверить, что остальные JSON-значения не изменены, и выполнить scripts/validate_contracts.py. +- [x] 1.2 arm-core, api/contracts и tests/test_contract.py: подтвердить побайтовое совпадение общей и локальной схемы существующим тестом идентичности. + +## 2. Контекст + +- [x] 2.1 docs, context/03-architecture.md, 07-open-questions.md, 09-delivery-plan.md: добавить точечные заметки о библиотеке arm-core и связанном change, не менять статус других сервисов и не вводить новые доменные решения; проверить diff и openspec validate.