@processengine/nominal-beneficiaries-rules

v2.0.10

Published

12 days ago

Пакет правил проверок бенефициаров номинальных счетов для jsonspecs

0High
0Medium
0Low

nominal-beneficiaries-rules

Пакет правил проверки бенефициаров номинальных счетов для @jsonspecs/rules 4.0.1 и спецификации jsonspecs/spec 1.0.0-rc.7.

Версия пакета: 2.0.10.

Состав пакета

13 экспортируемых сценариев для регистрации, обновления и отвязки бенефициара;
533 исполняемых артефакта в полном замыкании exports;
справочники и переиспользуемые условия;
семь доменных операторов с закрытыми схемами и эталонными тестами;
169 исполняемых примеров с полным покрытием 242 кодов ошибок;
воспроизводимый snapshot.json формата fv2.

Быстрый старт

Требуется Node.js 20 или новее.

npm ci
npm test

Канонические команды проекта предоставляет jsonspecs-cli 4:

jsonspecs validate --fail-on-warning
jsonspecs test
jsonspecs build --fail-on-warning
jsonspecs sandbox

npm test последовательно запускает эти проверки, эталонные векторы операторов, собирает dist/ и проверяет согласованность готового пакета.

Экспортируемые сценарии

| pipelineId | Сценарий | | --- | --- | | entrypoints.fl_resident.full_validation | ФЛ-резидент | | entrypoints.fl_nonresident.full_validation | ФЛ-нерезидент | | entrypoints.ip_resident.full_validation | ИП-резидент | | entrypoints.ip_nonresident.full_validation | ИП-нерезидент | | entrypoints.ul_resident.full_validation | ЮЛ-резидент | | entrypoints.ul_nonresident.full_validation | ЮЛ-нерезидент | | entrypoints.beneficiary.unbind.type_supported | допустимость типа при отвязке | | entrypoints.beneficiary.unbind.field_validation | поля заявки на отвязку | | entrypoints.fl_resident.update_validation | частичное обновление ФЛ-резидента | | entrypoints.fl_nonresident.update_validation | частичное обновление ФЛ-нерезидента | | entrypoints.ip_resident.update_validation | частичное обновление ИП-резидента | | entrypoints.ul_resident.update_validation | частичное обновление ЮЛ-резидента | | entrypoints.ul_nonresident.update_validation | частичное обновление ЮЛ-нерезидента |

Все сценарии *.full_validation и *.update_validation требуют context.currentDate. Отсутствие даты возвращает структурированную ошибку бизнес-проверки уровня EXCEPTION с кодом CONTEXT.CURRENT_DATE.REQUIRED.

Сценарии *.update_validation проверяют только присланные на обновление поля. Для FL_NONRESIDENT адрес регистрации всегда считается российским: countryCode не требуется и не влияет на результат, fullAddress необязателен, а структурные поля российского адреса обязательны. Один countryCode не считается переданным адресом. Для FL_RESIDENT код страны при передаче адреса должен быть RU, а для IP_RESIDENT сохраняется прежнее значение в контракте. Полную строку российского адреса собирает процессор после нормализации. Для этих типов также проверяются оба варианта телефона: российский phone и международный foreignPhone. Для UL_NONRESIDENT частично проверяются переданные сведения об организации, регистрации и иностранном налоговом резидентстве.

Гражданство и регистрационный адрес FL_NONRESIDENT

С версии 2.0.4 полная регистрационная проверка FL_NONRESIDENT отклоняет citizenshipCode = RU: тип резидента/нерезидента определяется гражданством. US остаётся отдельным регуляторным отказом, допустимый иностранный код принимается. Та же проверка гражданства применяется, если поле передано в частичном update.

При регистрации код страны адреса обязателен. RU требует российскую ФИАС-структуру, разрешённая иностранная страна — непустой fullAddress, а US даёт регуляторный отказ. Свободный текст адреса не используется для определения страны. Совместимый адресный контракт частичного update в этой версии не меняется.

Регистрационный адрес FL_RESIDENT

С версии 2.0.5 полная и частичная проверка адреса FL_RESIDENT допускает только beneficiary.address.registration.countryCode = RU. Российский адрес передаётся структурированно для последующей проверки по ФИАС. Корректный иностранный код возвращает обычную ошибку данных BEN.ADDR.REG.COUNTRY.MUST_BE_RU, а US сохраняет отдельный регуляторный отказ. Строковый иностранный регистрационный адрес относится только к FL_NONRESIDENT.

Дополнительный документ FL_NONRESIDENT

С версии 2.0.6 при передаче любого поля beneficiary.addDoc требуется технический typeCode: 005 для ВНЖ, 006 для РВП и 007 для миграционной карты. При регистрации у дополнительного документа обязательны номер и дата начала действия. Для ВНЖ и РВП серия передаётся при наличии, а дата окончания требуется только когда она предусмотрена самим документом.

Номер миграционной карты принимается в одной из трёх форм: 7 цифр без серии, 11 цифр без серии либо отдельная серия из 4 цифр и номер из 7 цифр. Прочая длина, нецифровые символы и сочетание отдельной серии с 11-значным номером отклоняются. Для миграционной карты при регистрации дата окончания остаётся обязательной.

В entrypoints.fl_nonresident.update_validation сохраняется частичный контракт: отсутствующие поля не становятся обязательными, однако при изменении addDoc необходимо повторить typeCode, а переданные номер, серия и даты проверяются по своему формату.

Налоговые признаки ФЛ и ИП

Полные проверки ФЛ и ИП требуют три логических поля: beneficiary.tax.foreignTaxResident, beneficiary.tax.usTaxResident и beneficiary.tax.usResident. Отсутствие поля, null и пустая строка дают ошибку .REQUIRED; значение другого типа даёт ошибку .BOOL. Логическое значение false считается заполненным.

В частичных проверках обновления отсутствие поддерживаемого налогового поля по-прежнему означает «не изменять». Если поле передано, null и значение другого типа отклоняются. Проверки конкретных значений признаков сохраняют прежнюю семантику для резидентов и нерезидентов.

Источники признаков США для ФЛ и ИП

Если передан beneficiary.contacts.postalAddress, вместе с ним требуется beneficiary.contacts.postalAddressCountryCode в формате ISO 3166-1 alpha-2. Значение US возвращает регуляторный отказ BEN.CONTACTS.POSTAL.NOT_US. Страна определяется по отдельному коду; слова в свободном тексте postalAddress не участвуют в этой проверке.

Тот же принцип действует для адресов и налоговых данных ФЛ и ИП. Код гражданства проверяется по beneficiary.fl.citizenshipCode, страна иностранного налогового резидентства — по beneficiary.tax.foreignTaxResidency.countryCode, а американские налоговые и резидентские признаки — по логическим полям налогового блока. Для регистрации FL_NONRESIDENT также проверяется beneficiary.address.registration.countryCode. Свободные строки почтового и иностранного налогового адреса не используются для определения страны.

Для beneficiary.fl.birthPlace действует отдельное ограничение регистрации: явные обозначения США распознаются по закрытому словарю целых Unicode-токенов и точечных аббревиатур. Проверка отклоняет США, USA, U.S., U.S.A., United States, United States of America, Соединенные Штаты и Соединенные Штаты Америки, включая варианты регистра и ё. Подстроки внутри других слов не совпадают: RUSSIA, AUSTRALIA, AUSTIN и United Statesville принимаются. Название города без явного обозначения страны, например Нью-Йорк, само по себе не классифицируется как США. Частичное обновление карточки этим регистрационным решением не изменено.

При регистрации FL_NONRESIDENT и IP_NONRESIDENT иностранный налоговый адрес и почтовый адрес необязательны и могут отсутствовать одновременно. При этом страна иностранного налогового резидентства, иностранный ИНН или причина его отсутствия остаются обязательными, а структурированный код US по-прежнему возвращает регуляторный отказ.

Контакты FL_NONRESIDENT

С версии 2.0.9 общий минимум контактов FL_NONRESIDENT снова требует российский beneficiary.contacts.phone или beneficiary.contacts.email. foreignPhone не может быть единственным контактом: процессор не передаёт его в телефонное поле карточки, поскольку ЦФТ принимает там только российский формат номера. Поле остаётся условно обязательным при применимом иностранном блоке и отсутствии российского телефона; при наличии оно всегда проверяется по международному формату. Контактные правила FL_RESIDENT и ИП этим изменением не затрагиваются.

Юридический адрес при регистрации UL_RESIDENT

С версии 2.0.0 entrypoints.ul_resident.full_validation требует в beneficiary.address.legal код страны RU, regionCode, postalCode, city или locality, streetType, street, house. fullAddress необязателен; одной строки недостаточно. Значения составных полей должны быть строками с непробельными символами. Адреса без улицы не входят в этот контракт. Идентификаторы ФИАС от мерчанта не требуются.

Проверки расположены в internal.ul_resident.address.* и вызываются только регистрационным блоком ЮЛ-резидента. Общая библиотека адресов, обновление ЮЛ-резидента и остальные 12 экспортов не меняются. Обновление ЮЛ по-прежнему требует полную строку при передаче адресного блока.

Отсутствующие поля дают UL.ADDRESS.LEGAL.FIAS.<PART>.REQUIRED уровня ERROR. Нестрочные значения и строки из пробелов дают .FORMAT. У общей ошибки CITY_OR_LOCALITY.REQUIRED поле field равно null; сервис может опускать его в мерчантском ответе. Эта проверка полноты не заменяет проверку адреса ЦФТ.

Это несовместимое изменение: ранее принятая заявка только с countryCode и fullAddress теперь отклоняется. Потребитель должен явно обновить точную версию зависимости и согласовать переход для незавершённых заявок.

Использование в сервисе

const { createEngine } = require("@jsonspecs/rules");
const snapshot = require("@processengine/nominal-beneficiaries-rules/dist/snapshot.json");
const operators = require("@processengine/nominal-beneficiaries-rules/operators/node");

const engine = createEngine({ operators });
const prepared = engine.compileSnapshot(snapshot);

const result = engine.runPipeline(prepared, {
  pipelineId: "entrypoints.fl_resident.full_validation",
  payload,
  context: { currentDate: "2026-07-22" },
});

Сервис компилирует snapshot один раз при старте. pipelineId всегда передаётся явно на верхнем уровне. Ограничение транспортного размера, аутентификация, авторизация и доставка одобренной версии пакета остаются обязанностью сервиса.

Авторская модель

manifest.json          версия спеки, exports, пути и единый UI-каталог
rules/                 один JSON-артефакт на файл
operators/node/        доменные операторы Rules v4
tests/                 эталонные векторы операторов
samples/               входы и ожидаемые бизнес-результаты
scripts/               проверки пакета и релизного состояния
dist/                  результат jsonspecs build, не источник истины

manifest.catalog является единственным источником редакторских метаданных. Исполняемые артефакты не содержат description, а отдельные контракты полей, привязанные к конкретному обработчику, в пакете не поддерживаются.

Правила, создающие ошибки, содержат issue.meta со ссылками на разделы и пункты бизнес-требований, справочной страницей и SHA-256 исходного DOCX. Этот блок входит в sourceHash и возвращается Rules v4 вместе с ошибкой.

У правила нет роли check|predicate: оператор возвращает PASS, FAIL или SKIP. Объект issue определяет последствия FAIL в исполняемом шаге и игнорируется при использовании правила внутри when.

Доменные операторы

valid_inn проверяет контрольные разряды ИНН ФЛ и ЮЛ;
inn_not_repeated запрещает 12-значный ИНН из одной повторяющейся цифры;
is_iso_date проверяет существующую календарную дату в формате YYYY-MM-DD;
migration_card_number_format проверяет формы номера миграционной карты 7, 11 и 4+7 цифр;
not_contains_normalized_phrases проверяет отсутствие заданных целых фраз, регистрозависимых токенов и точечных аббревиатур после Unicode-нормализации;
passport_rf_issued_at_or_after_age проверяет минимальный возраст выдачи;
passport_rf_valid_after_replacement_age проверяет возраст замены и льготный период.

Операторы экспортируются напрямую как карта {schema, evaluate}. Ядро разрешает пути из field и inputs; оператор получает только значения и постоянные params, не видит payload, context или текущий pipeline.

Документация

История миграции с прежнего движка остаётся в Git. Начиная с версии 1.0.0 регрессионным контрактом являются актуальные правила, примеры и эталонные векторы.