---

[I128-2831] Mapping внешних интеграций и реестр ExternalId в модуле API

---

НАЧАЛО >> Оглавление >> Общее описание >> История изменений >> Что нового в проекте I128 >> Версия 2026.3 >> [I128-2831] Mapping внешних интеграций и реестр ExternalId в модуле API📄 Скачать в DOCX

---

Тип	Версия	Статус	Приоритет	Исполнитель
⚙️ Новые возможности	2026.3	🔘 Завершено	Средний	Ilya Mikhaylenko

Компоненты: ИРБИС 128. Модуль API - API ИРБИС 64/128

Завершено: 07.09.2026 08:58

1. Цель

Нужно расширить существующий модуль API так, чтобы он стал владельцем декларативного mapping contract и реестра ExternalId для внешних интеграций ИРБИС 128.

Внешний потребитель или integration adapter должен уметь однозначно сопоставить внешний объект с внутренней записью, проверить mapping payload без изменения данных, получить понятную диагностику конфликтов и использовать единый реестр внешних идентификаторов вместо хранения внешних ключей в частных полях доменных модулей.

1. Контекст

В модуле API должен существовать базовый реестр APIContract и IntegrationAdapterProfile. Этот срез развивает их следующим слоем: для опубликованного adapter profile нужно описать, какие внешние object types соответствуют внутренним object types, какие external ids связаны с конкретными внутренними объектами и как внешние поля, статусы, переходы и участники преобразуются в внутренние значения ИРБИС 128.

Mapping и external ids должны быть общесистемным integration contract модуля API. Доменные модули продолжают владеть своими записями, бизнес-правилами, сохранением изменений и прикладной валидацией. API не должен знать физическую структуру записей Tasks, VirtualRef, RQST, Users, EC или других предметных модулей сверх опубликованных field keys, workflow keys и resolver contracts.

1. Что Нужно Сделать

Нужно реализовать реестр ExternalId в модуле API. Запись ExternalId должна связывать внешний идентификатор с external system, IntegrationAdapterProfile, object type, внутренним record key или record reference, external object type, направлением использования, статусом связи, датами создания и последнего подтверждения, источником регистрации и диагностическими признаками.

Один внутренний объект может иметь несколько external ids в разных adapter profiles или external systems. Поиск внутреннего объекта по external id должен учитывать как минимум adapter profile, external system и object type. Неоднозначный поиск должен возвращать безопасную ошибку, а не случайно выбранную запись.

Нужно описать правила уникальности external ids. По умолчанию одна активная связка external system + adapter profile + object type + external id должна указывать только на один внутренний объект. Если профиль допускает alias или историю смены внешнего идентификатора, это должно быть явно описано policy и не должно ломать основной однозначный lookup.

Нужно реализовать управление жизненным циклом ExternalId: регистрация, подтверждение при повторном обмене, деактивация, пометка конфликтной связи, безопасное удаление или архивирование по policy. Изменение external id должно оставлять audit/diagnostic trail, достаточный для разбора интеграционного инцидента.

Нужно реализовать mapping profile, связанный с IntegrationAdapterProfile, APIContract version, direction и object type. Mapping profile должен описывать преобразование внешнего payload во внутреннюю нормализованную модель API и обратное представление, если направление профиля это допускает.

Mapping полей должен ссылаться на стабильные field keys из FieldConfiguration, а не на физические номера полей, подполей или частные имена переменных доменного модуля. Для поля должны быть описаны внешний ключ, внутренний field key, направление, обязательность, null/default policy, тип значения, простые правила нормализации, правила ошибки при неизвестном значении и диагностическое сообщение.

Mapping workflow-состояний должен ссылаться на ключи WorkflowProject, WorkflowStatus и WorkflowTransition там, где внутренний объект участвует в workflow. API не должен хранить собственный список статусов или переходов; он должен проверять, что указанные ключи существуют и применимы к выбранному object type и project context.

Mapping пользователей, организаций и участников должен выполняться через resolver contracts модулей Users и Organisations. В mapping profile нужно указать, какие внешние признаки используются для поиска участника: login, email, подтвержденный контакт, внешний subject id, организация, роль или delegation context. Неоднозначный или неподтвержденный участник должен попадать в диагностируемую ошибку.

Если mapping ссылается на файлы или вложения, он должен работать только со ссылками на FT/TemporaryFiles contracts и не должен передавать физические пути или внутренние storage identifiers наружу. Полная реализация file transfer или storage pipeline не входит в этот срез.

Нужно реализовать where-used для ExternalId и mapping profile. Администратор и диагностический API должны показывать, какие adapter profiles, API methods, object types, fields, statuses, transitions, user resolvers и внутренние записи используют конкретный external id или mapping rule.

Нужно реализовать dryrun mapping. По входному payload, adapter profile, object type и operation API должен построить нормализованный результат: найденный или предполагаемый внутренний объект, matched external id, список преобразованных полей, предполагаемые workflowссылки, найденных участников, ошибки, предупреждения, возможный diff и required permissions. Dryrun не должен сохранять запись, создавать ExternalId, выполнять workflowпереходы, запускать post-functions, отправлять события или ставить задания в Queue.

Нужно добавить диагностику дублей и конфликтов external ids: несколько внутренних объектов для одного external id, несколько активных external ids там, где policy запрещает множественность, устаревший mapping profile, неизвестный field key, неизвестный status/transition key, неразрешенный пользователь, недоступное поле, отказ Security, скрытый объект, неподдерживаемый object type и несовместимая версия APIContract.

Нужно добавить API/admin операции для просмотра и управления mapping profiles и ExternalId: список, чтение карточки, поиск по external id, поиск external ids внутреннего объекта, создание или деактивация связи по правам, dryrun mapping, whereused и export безопасной конфигурации. Изменяющие операции должны проходить через Security и idempotency policy профиля.

Нужно добавить HealthCheck provider для API mapping/external ids. Проверки должны находить несуществующие field keys, workflow statuses/transitions, broken user resolver bindings, дубли external ids, битые adapter profile references, несовместимые версии APIContract, отсутствующие TestA datasets и правила mapping, которые ссылаются на скрытые или недоступные поля.

Нужно подготовить TestAсценарии для регистрации ExternalId, поиска внутреннего объекта по external id, запрета дублей, dryrun mapping без изменения записи, field mapping через FieldConfiguration, status/transition mapping через Workflow*, user mapping через Users/Organisations resolver, отказов Security, безопасной диагностики и HealthCheck provider checks.

Нужно обновить Help модуля API: назначение ExternalId, настройка mapping profile, правила уникальности, whereused, dryrun, типовые ошибки диагностики, границы ответственности API и порядок подключения доменного модуля к общему integration contract.

1. Границы Ответственности

API владеет реестром ExternalId, mapping profile, правилами уникальности external ids, lookup contract, whereused, dryrun mapping, APIlevel diagnostics и безопасным export mappingконфигурации.

FieldConfiguration владеет field keys, типами полей, отображением, вводом, поиском, экспортом и API-семантикой полей. API только ссылается на field keys и проверяет их доступность через опубликованный контракт.

Workflow* владеет WorkflowProject, WorkflowStatus, WorkflowTransition, доступностью переходов, workflowсостоянием записи и применением workflowдействий. API только ссылается на workflow keys в mapping profile и не реализует собственный workflow engine.

Security владеет правами, masking, grants/denies, field security, view security, service accounts и безопасными отказами доступа. API обязан использовать Security для операций с mapping/external ids и не должен создавать параллельный механизм прав.

Users и Organisations владеют пользователями, организациями, подтвержденными контактами, внешними участниками, делегированием и resolver-ами участников. API использует resolver contract и не хранит частную копию пользовательской модели.

Доменные модули владеют своими бизнесоперациями, сохранением изменений, прикладной валидацией и преобразованием нормализованного APIresult в реальные изменения записи. API dryrun может построить proposed change plan, но фактическое применение изменений должно делегироваться модулювладельцу объекта.

EventBus и Queue не получают новую ответственность в этом срезе. Полноценный bidirectional sync, доставка событий, retry, dead-letter, schedule и execution runtime должны реализовываться отдельными задачами поверх готового mapping/external id contract.

JSONRPC и REST остаются transportслоями. Они могут передавать запросы к APIоперациям mapping/external ids, но не владеют mapping profile, ExternalId registry, where-used или diagnostics.

В этот срез не входит реализация конкретного Jira adapter, внешней ticketsystem интеграции, почтового adapter, webhook adapter, полноценного bidirectional sync runtime, сложного fieldlevel merge и ручного conflict resolution UI. Эти задачи должны заводиться отдельно после выбора первого реального внешнего потребителя.

1. Критерии Приемки

В модуле API есть реестр ExternalId, который связывает external system, adapter profile, object type, external id и внутренний record key или record reference.

По external id можно найти внутренний объект только с учетом adapter profile, external system и object type; неоднозначность возвращает безопасную диагностическую ошибку.

Один внутренний объект может иметь несколько external ids в разных profiles/external systems без записи внешних ключей в частные поля доменного модуля.

Правила уникальности external ids предотвращают дубли там, где policy не допускает неоднозначность.

Mapping profile описывает mapping полей, workflowстатусов, workflowпереходов и участников через контракты FieldConfiguration, Workflow*, Users и Organisations.

Mapping profile не использует физические номера полей, подполей или внутренние структуры записей доменных модулей.

Dry-run mapping показывает normalized result, matched external id, proposed changes, warnings, errors, required permissions и диагностические details без сохранения записи и без внешних побочных эффектов.

Where-used показывает использование external ids и mapping rules в adapter profiles, object types, API methods, fields, statuses, transitions, user resolver bindings и внутренних записях.

HealthCheck находит дубли external ids, broken references, неизвестные field/status/transition keys, проблемы resolver-ов, несовместимые версии APIContract и отсутствие TestA coverage.

Security проверяет права на просмотр, создание, изменение, деактивацию, export и dry-run mapping/external ids; ошибки не раскрывают скрытые записи, поля, пользователей, файлы или external ids.

TraceContext доступен в diagnostics mapping/external id операций; diagnostic details не содержат secret values и лишних персональных данных.

TestA покрывает позитивные и негативные сценарии ExternalId lookup, duplicate detection, dryrun mapping, field/status/transition/user mapping, Security denial, HealthCheck provider checks и отсутствие изменений данных при dryrun.

Help содержит руководство администратора и разработчика по ExternalId, mapping profile, whereused, dryrun, диагностике конфликтов и границам с FieldConfiguration, Workflow*, Security, Users/Organisations и доменными модулями.

-

Реализован первый срез I128-2830 для существующего модуля API.

Что сделано:

• добавлен реестр APIContract с системным legacy JSONRPC контрактом api.legacyjsonrpc.v1;
• описаны metadata текущих JSON-RPC методов без изменения их поведения;
• добавлены схемы IntegrationAdapterProfile, idempotency policy и diagnostics;
• добавлены чтение recordbacked APIконтрактов/профилей, валидаторы и API/CheckHealth;
• включен административный список APIзаписей и briefформат;
• обновлены Help-разделы;
• добавлены saferead TestAпроверки.

Не входит в этот PR:

• runtime mapping/external ids (I128-2831);
• bidirectional sync/conflict resolution (I128-2832);
• конкретные внешние adapters.

Проверка:

• php -l по modules/API;
• git diff --check;
• TestA: API saferead + structural, 17/17 passed, runid 2026090506172266d96956.

-

Реализован второй APIсрез I1282831 поверх I128-2830.

Что сделано:

• добавлены отдельные API-записи kind=mappingProfile и kind=externalId;
• добавлены схемы MappingProfile и ExternalId;
• добавлены функции чтения реестров, lookup ExternalId, whereused, dryrun mapping;
• добавлены управляемые операции RegisterExternalId и DeactivateExternalId с проверкой прав на запись модуля API;
• расширены editor variables и индексы 1288 для mapping/external ids;
• расширены ExportContractRegistry, CheckHealth и diagnostics schema;
• обновлены Help-разделы API;
• добавлены saferead TestAпроверки mapping/external ids.

Границы:

• API владеет mapping/external id contract, lookup, whereused, dryrun и diagnostics;
• FieldConfiguration, Workflow*, Security, Users/Organisations, FT и доменные модули остаются владельцами своих контрактов;
• полноценный bidirectional sync/conflict resolution не входит в этот PR и остается в I128-2832.

Проверки:

• php -l для файлов modules/API;
• git diff --check;
• TestA API safe-read structural: 30/30 passed.

База PR: feature/I1282830apicontractregistry, потому что I1282831 зависит от открытого PR #1329 / I1282830.

1. Связанные задачи

1.1. 🔗 blocks: I128-2832

1.2. 🔗 blocks: I128-2790

1.3. 🔗 blocks: I128-2793

1.4. 🔗 blocks: I128-2797

1.5. 🔗 blocks: I128-2798

1.6. 🔗 blocks: I128-2799

1.7. 🔗 blocks: I128-2813

1.8. 🔗 blocks: I128-2818

1.9. 🔗 blocks: I128-2825

1.10. 🔗 blocks: I128-2830