92 lines
10 KiB
Markdown
92 lines
10 KiB
Markdown
## ADDED Requirements
|
||
|
||
### Requirement: Библиотека общего кода `arm_statements`
|
||
Общий код нормализации ББ/ОФР SHALL жить в репозитории `RSHB/pylib_ai_arm_statements` Python-библиотекой: дистрибутив
|
||
`pylib-ai-arm-statements`, импорт — `arm_statements`, свои тесты, конфиг линтеров и `make check`. Библиотека SHALL
|
||
содержать: типы шага 1 (`FormCandidate`, `Cell`; сериализуемые в json dataclass-ы), шаги 2–8, общие разборы текста
|
||
(двойники, даты, суммы, коды), словари — проверок §7 `statement_checks.yaml` (полный и упрощённый наборы), периодов
|
||
`statement_periods.yaml`, заголовков форм и ОКУД, подписей колонок («Код», «Наименование», исключения), букв-двойников,
|
||
единиц измерения `statement_units.yaml` (написания и коды ОКЕИ), упорядоченные перечни кодов форм по редакциям (`66n`,
|
||
`fsbu4`) и вариантам (`full`, `simplified`) без наименований — байтовая копия `docs/contracts/statement-code-orders.yaml`
|
||
как `arm_statements/rules/statement_code_orders.yaml`, диапазоны кодов — и загрузчик словарей. Словари SHALL входить в
|
||
дистрибутив данными пакета (wheel и sdist), установленная библиотека читает их без исходного репозитория. Словаря
|
||
«код → наименование» в библиотеке MUST NOT быть (Р-3). Библиотека SHALL владеть своими типами входа и выхода;
|
||
конвертацию выхода в модель контракта делает потребитель. Golden-тесты — внутри библиотеки на синтетических и
|
||
обезличенных данных; тесты на реальных фикстурах остаются в сервисах и соседние репозитории не читают. Зависимости
|
||
библиотеки — только те, что есть в зеркале банка (сейчас PyYAML), Python — 3.11 (версия платформы).
|
||
|
||
В tabular-parser, scan-gateway и arm-core библиотека SHALL подключаться зависимостью и импортироваться по имени
|
||
`arm_statements`; поставку, версию и порядок её подъёма задаёт требование «Поставка библиотеки потребителям».
|
||
|
||
#### Scenario: Наименований в библиотеке нет
|
||
- **WHEN** ревьюер ищет в библиотеке соответствие «код → наименование»
|
||
- **THEN** его нет: в перечне кодов только коды, наименования строк — словарь ядра
|
||
|
||
#### Scenario: Словари в установленном пакете
|
||
- **WHEN** wheel библиотеки установлен в чистое окружение без исходного репозитория
|
||
- **THEN** `import arm_statements` и загрузка стандартных правил работают, все YAML-словари на месте
|
||
|
||
### Requirement: Поставка библиотеки потребителям
|
||
Версия библиотеки SHALL быть семантической (`MAJOR.MINOR.PATCH`), записываться в файл `VERSION` корня репозитория
|
||
библиотеки и помечаться тегом `v<версия>` на коммите выпуска; опубликованная версия MUST NOT пересобираться с другим
|
||
содержимым. Публикацию в Nexus выполняет платформа (CI в Gitea нет).
|
||
|
||
Потребители (`arm-core`, `tabular-parser`, `scan-gateway`) SHALL держать в `api/requirements.txt` строку
|
||
`pylib_ai_arm_statements==<версия>`; копии исходников библиотеки в потребителях MUST NOT быть. На платформе библиотека
|
||
ставится из Nexus по этой строке. Вне банка `make venv` SHALL пропускать строки `pylib_ai*` (как `raisa_*`) и ставить
|
||
библиотеку из локального checkout `STATEMENTS_DIR` (по умолчанию `../pylib_ai_arm_statements`); `make install`
|
||
переустанавливает её без пересоздания окружения. Обе цели SHALL сначала сверять checkout (цель `statements-version`):
|
||
`VERSION` checkout не равен версии из `requirements.txt` или checkout нет — ошибка; checkout не на теге `v<версия>` —
|
||
предупреждение (правка библиотеки до выпуска). `STATEMENTS_TAG` по умолчанию — `v<версия>` из `requirements.txt`.
|
||
`make docker-build` SHALL передавать checkout библиотеки контекстом сборки `statements` и отказывать, если `HEAD`
|
||
checkout не совпадает с тегом `STATEMENTS_TAG`.
|
||
`ruff` и `mypy` потребителя библиотеку не проверяют (она проверяется своим `make check`), `arm_statements` в конфиге
|
||
`ruff` потребителя — сторонний пакет.
|
||
|
||
Маркер версии в результате (`service.statements_version`) и версия ядра для `STATEMENTS_VERSION_MISMATCH` SHALL
|
||
браться из метаданных установленного дистрибутива (`importlib.metadata`). У заданий, посчитанных до перехода, в
|
||
`recognition_job.statements_version` остаётся хэш коммита копии; расхождение с версией ядра даёт
|
||
`STATEMENTS_VERSION_MISMATCH` (`info`) — это ожидаемо и не исправляется (решение владельца 26.10.2026).
|
||
|
||
Порядок правки перечня кодов: PR в docs (`contracts/statement-code-orders.yaml`) → PR в библиотеку (байтовая копия
|
||
yaml) и новая версия → подъём версии в потребителях «сначала ядро». Пока цепочка не дошла до библиотеки,
|
||
`statements-orders-check` в docs предупреждает, но не краснеет. Подъём версии в потребителях выкладывается одной
|
||
поставкой ядра и обоих сервисов.
|
||
|
||
#### Scenario: Версия общего кода в результате
|
||
- **WHEN** сервис собирает результат с установленной библиотекой версии `0.1.1`
|
||
- **THEN** в результате `service.statements_version = "0.1.1"`
|
||
|
||
#### Scenario: Сборка образа не с того коммита
|
||
- **WHEN** в `../pylib_ai_arm_statements` checkout стоит на коммите после тега `v0.1.1`, а `STATEMENTS_TAG = v0.1.1`
|
||
- **THEN** `make docker-build` завершается ошибкой «HEAD библиотеки не совпадает с v0.1.1», образ не собирается
|
||
|
||
#### Scenario: Checkout библиотеки другой версии
|
||
- **WHEN** в `api/requirements.txt` сервиса `pylib_ai_arm_statements==0.1.2`, а в `../pylib_ai_arm_statements` `VERSION` = `0.1.1`
|
||
- **THEN** `make venv` и `make install` завершаются ошибкой с обеими версиями, библиотека не ставится
|
||
|
||
#### Scenario: Задание до перехода
|
||
- **WHEN** аналитик правит форму, посчитанную сервисом с копией (`statements_version` — хэш коммита), а у ядра
|
||
установлена библиотека `0.1.1`
|
||
- **THEN** пересчёт пишет `STATEMENTS_VERSION_MISMATCH` (`info`), на статус и подтверждение это не влияет
|
||
|
||
#### Scenario: Перечень кодов в docs новее библиотеки
|
||
- **WHEN** в docs в `statement-code-orders.yaml` добавлен код, а библиотека ещё не выпущена с ним
|
||
- **THEN** `make -C docs check` печатает предупреждение `statements-orders-check` и называет файл, код возврата 0
|
||
|
||
## REMOVED Requirements
|
||
|
||
### Requirement: Пакет общего кода `arm_statements` и его копии
|
||
**Reason**: копии пакета в сервисах заменены установленной библиотекой (AURORA-1677), репозиторий `arm-statements`
|
||
архивирован, код перенесён в `RSHB/pylib_ai_arm_statements`.
|
||
**Migration**: требования «Библиотека общего кода `arm_statements`» и «Поставка библиотеки потребителям».
|
||
|
||
### Requirement: `sync-statements` — копии пакета в потребителях
|
||
**Reason**: копии `api/arm_statements/` в сервисах заменены установленной библиотекой (AURORA-1677); раскладывать и
|
||
сверять нечего, скрипт `docs/scripts/sync-statements.sh` и цели `sync-statements`, `statements-check`,
|
||
`test-sync-statements` удалены.
|
||
**Migration**: поставка и версия — требование «Поставка библиотеки потребителям»; сверка перечня кодов docs с
|
||
библиотекой — цель `statements-orders-check` в `make -C docs check`; сверка словаря имён ядра с перечнем —
|
||
тест ядра `test_name_dictionary_codes_in_code_orders`.
|
||
|