arm-core/openspec/specs/corrections-api/spec.md

corrections-api Specification

Purpose

Предоставляет backend-контракт для просмотра, сохранения и экспорта корректировок агрегатов бухгалтерского баланса, вычисленных сервисом разнесения ОСВ.

Requirements

Requirement: Чтение таблицы корректировок

Система SHALL вызывать сервис разнесения AURORA-1751 через CorrectionAggregateSource и возвращать его агрегаты ББ с компаниями, статьями, счетами, позициями, сопоставленными парами, суммами, отклонением и сохранённой корректировкой. GET MUST NOT записывать вычисленное разнесение, пары или корректировки в БД.

Scenario: Чтение доступной версии

• WHEN пользователь с правом просмотра запрашивает таблицу доступной версии
• THEN система возвращает вычисленные агрегаты, сопоставленные пары и оставшиеся позиции в стабильном порядке
• THEN в БД не создаются назначения или корректировки

Scenario: Сопоставленная пара

• WHEN сервис AURORA-1751 возвращает элемент в matched или with_discrepancy
• THEN агрегат содержит pairs с обеими сторонами этого элемента
• THEN каждая сторона пары содержит относящиеся к ней идентификаторы строк ОСВ, счета и сумму
• THEN суммы и отклонение пары совпадают с результатом AURORA-1751 без повторного сопоставления в сервисе корректировок

Scenario: Позиция без сопоставленной стороны

• WHEN ручная или односторонняя позиция агрегата не входит ни в одну вычисленную пару
• THEN она присутствует в соответствующей стороне агрегата без искусственно созданной встречной позиции

Requirement: Расчёт отклонения и элиминации

Система SHALL считать абсолютное отклонение и процент к меньшей положительной сумме без предварительного округления. При отклонении не более 5 % справочная сумма элиминации SHALL равняться меньшей сумме; остаток SHALL относиться к большей статье.

Scenario: Отклонение не более пяти процентов

• WHEN меньшая сторона положительна и отклонение составляет ровно 5 % или меньше
• THEN сумма элиминации равна меньшей стороне
• THEN разница остаётся в большей статье

Scenario: Отклонение больше пяти процентов

• WHEN отклонение больше 5 %
• THEN агрегат помечается как требующий корректировки

Scenario: Нулевая меньшая сторона

• WHEN одна сторона равна нулю
• THEN процент отклонения равен null
• THEN агрегат считается односторонним

Requirement: Сохранение корректировки агрегата

Система SHALL атомарно заменять корневые и дочерние строки корректировки существующего агрегата. Комментарий после trim MUST быть непустым при каждом сохранении. Успешное сохранение SHALL устанавливать статус APPLIED.

Scenario: Сохранение с комментарием

• WHEN аналитик сохраняет допустимые суммы и статьи обеих сторон с непустым комментарием
• THEN система полностью заменяет набор корректировки и возвращает APPLIED
• THEN создаётся аудит CORRECTION_CREATE или CORRECTION_EDIT

Scenario: Пустой комментарий

• WHEN аналитик сохраняет корректировку с пустым или состоящим из пробелов комментарием
• THEN система возвращает COMMENT_REQUIRED
• THEN ни одна строка корректировки не изменяется

Scenario: Ошибка одной дочерней строки

• WHEN одна из сумм или статей недопустима
• THEN весь запрос отклоняется без частичной записи

Requirement: Конкурентное и статусное ограничение

Система MUST разрешать изменение только владельцу активной блокировки редактируемой версии. Клиент SHALL передавать ожидаемую редакцию существующей корректировки.

Scenario: Конфликт редакции

• WHEN ожидаемая редакция не совпадает с текущей
• THEN система возвращает CORRECTION_VERSION_CONFLICT без записи

Scenario: Верифицированная версия

• WHEN пользователь пытается сохранить корректировку после верификации версии
• THEN система отклоняет изменение

Requirement: XLSX-экспорт корректировок

Система SHALL экспортировать таблицу одним листом XLSX. Строка агрегата SHALL сопровождаться следующими за ней раскрываемыми строками детализации; колонка правила у строки детализации SHALL быть пустой. Каждая сопоставленная пара SHALL занимать одну строку с одновременно заполненными колонками обеих компаний.

Scenario: Экспорт ББ

• WHEN пользователь экспортирует таблицу корректировок
• THEN файл называется Корректировки_<название ГК>_<год>_<квартал>.xlsx
• THEN книга содержит один лист с агрегатами, детализацией и итогами в рублях
• THEN позиции сопоставленной пары не дублируются отдельными строками под той же парой
• THEN ручные и односторонние позиции выводятся отдельными строками
• THEN система создаёт событие аудита EXPORT

Requirement: Граница этапа

Система MUST NOT предоставлять в этом capability импорт XLSX, собственный алгоритм разнесения строк ОСВ, ручной перенос строк между правилами или операции изменения назначений. Вызов готового расчёта AURORA-1751 для чтения таблицы SHALL считаться интеграцией с источником, а не реализацией разнесения в capability корректировок.

Scenario: Контракт этапа

• WHEN публикуется OpenAPI этапа корректировок
• THEN в нём отсутствуют операции импорта и назначения строк правилам

Requirement: Инвалидация корректировки при ручном назначении

После успешного ASSIGN/UNASSIGN система SHALL определять затронутые пары компаний непосредственно по entry_ids в osv_entry и переводить все их APPLIED-корректировки в DRAFT. Суммы, статьи и комментарий SHALL сохраняться. Операция MUST NOT выполнять полный расчёт assignment_candidates; статус REVOKED на этом этапе не устанавливается.

Scenario: Изменено назначение строки пары компаний

• WHEN аналитик назначает строку правилу или снимает назначение
• THEN все APPLIED-корректировки этой пары компаний получают DRAFT
• THEN корректировки других пар и уже находящиеся в DRAFT не изменяются