cursor-1c/этрн.md

ТЗ на доработку: оптимизация создания и обработки ЭТрН

Дата: 07.10.2026
Конфигурация: ВесоваяАК (ves2020)
Версия конфигурации (на момент анализа): 0.0.3.21
Область: контур электронных транспортных накладных (ЭТрН / ЭПД, API Санадор)
Тип работ: оптимизация производительности без изменения бизнес-смысла процесса

Документ сформирован по результатам анализа исходников. Правки в конфигурацию этим документом не вносятся.

---

1. Цель и критерии успеха

1.1. Цель

Сократить время и нагрузку на СУБД/сеть при регламентной обработке очереди ЭТрН и при сборке payload титулов Т1/Т3, сохранив текущую модель:

• проведение документов не обращается к внешнему API;
• создание/отправка ЭТрН выполняется роботом ак_ЭТрНРобот по очереди в регистре ак_СтатусыДокументовЭПД;
• опросы статусов остаются пакетными по организации.

1.2. Критерии приёмки

№	Критерий	Как проверить
К1	Один проход РЗ с той же порцией новых документов укладывается в бюджет времени стабильнее (меньше срабатываний «Исчерпан бюджет времени»)	Журнал регистрации события робота до/после на сопоставимой нагрузке
К2	Запросы выборки очереди (ДобавитьНовые / ДобавитьОпросы / подсчёт неудач) не сканируют лишнюю историю без необходимости	План запроса / замер времени на тестовой ИБ с наполненным регистром
К3	На одну отправку Т1 уменьшено число точечных запросов к ИБ (адреса, телефоны, КИ, ТС и т.п.)	Сравнение числа запросов на документ в отладке / технологическом журнале
К4	Повторные чтения параметров авторизации ЭПД и создание нового HTTP-соединения на каждый вызов устранены или сведены к минимуму в рамках порции	Код-ревью + замер latency порции
К5	Поиск перевозки для Т3 без uuid не выполняет отдельный HTTP-запрос на каждый документ при одинаковых ключах поиска	Код-ревью сценария «только Т3»
К6	Поведение статусов, идемпотентность перепроведения и запрет повторной отправки Т1 при наличии uuid не нарушены	Регрессионные сценарии §6

Нефункционально: изменения обратимы, без «тихих» смен контракта API Санадора.

---

2. Текущая архитектура (as-is)

2.1. Поток

Проведение (5 видов документов)
        ↓
ак_ЭТрНРобот.ЗарегистрироватьПриПроведении
        ↓
РС ак_СтатусыДокументовЭПД («К отправке» / «Не требуется»)
        ↓
РЗ ак_ОбработкаОчередиЭТрН → ак_ЭТрНРобот.ОбработатьОчередь
        ↓
ак_ЭТрНОтправка (Т1 / Т3) ← ак_ЭТрНФормированиеТитулов ← ак_ЭТрНДанные
        ↓
ак_ПолучениеДанныхЭПД (синхронный HTTPS к Санадору)

2.2. Ключевые объекты

Объект	Назначение
ОбщийМодуль.ак_ЭТрНРобот	Регистрация при проведении, очередь, регламент
ОбщийМодуль.ак_ЭТрНОтправка	Сборка + отправка Т1/Т3, запись статусов
ОбщийМодуль.ак_ЭТрНФормированиеТитулов	Payload титулов для API
ОбщийМодуль.ак_ЭТрНДанные	Запросы к ИБ, КешДанных
ОбщийМодуль.ак_ЭТрНКлиентСервер / ак_ЭТрНПовтИсп	Контекст, статусы, константы
ОбщийМодуль.ак_ПолучениеДанныхЭПД	HTTP к API ЭПД
РС.ак_СтатусыДокументовЭПД	Очередь и история статусов (период — секунда)
РС.ак_УчетныеЗаписиЭПД, ак_АбонентыЭПД	Учётные записи / абоненты
РЗ.ак_ОбработкаОчередиЭТрН	Метод: ак_ЭТрНРобот.ОбработатьОчередь
Обработка.ак_ВыбывшиеДокументыЭТрН	РМ по застрявшим документам

Документы-основания: РасходнаяНакладная, РасходПоСкладу, ПеремещениеСПоляНаЭлеватор, ПриходПоВесовой, ПриходПоСкладу.

Отдельного документа «Электронная транспортная накладная» в конфигурации нет: ЭТрН создаётся во внешнем сервисе.

2.3. Что уже сделано удачно (не ломать)

• Проведение не ходит в сеть.
• Разделение очередей «новые» / «опросы» по наличию ИдентификаторСанадор (защита от повторного Т1).
• Пакетный опрос статусов по организации (порции uuid).
• Раздельные лимиты порций новых и опросов, мягкий бюджет времени.
• КешДанных на порцию (часть идентификаторов / auth / организация по контрагенту).
• Ключ регламентного задания против параллельного запуска.

---

3. Проблемы (на основании анализа кода)

ID	Проблема	Где	Влияние
P1	Синхронный HTTP в цикле по документам порции; каждое соединение создаётся заново	ОбработатьОчередь → отправка → ак_ПолучениеДанныхЭПД.ОтправитьHTTPЗапрос	Основной риск исчерпания бюджета 300 с
P2	Auth (ак_УчетныеЗаписиЭПД) читается на каждый HTTP; кэш робота HTTP-слоем не используется	ВызватьHTTPМетод	Лишние обращения к РС на каждый вызов
P3	СрезПоследних без отбора по измерениям; итоги среза последних выключены; ВТ_Неудачи сканирует историю по регистру	ДобавитьНовые, ДобавитьОпросы, ТекстВременнойТаблицыНеудач	Рост стоимости РЗ с объёмом истории
P4	Фильтрация статусов по .Наименование (строка)	Запросы робота	Хуже для индексации/планов, хрупкость
P5	Много точечных запросов на сборку одного Т1	ак_ЭТрНДанные + ак_ЭТрНФормированиеТитулов	Нагрузка на СУБД пропорционально порции × полям
P6	Поиск Т3 без uuid: HTTP-список АРМ на каждый документ	ак_ЭТрНОтправка.ПеревозкаВСервисе	Лишние сетевые вызовы при сценарии «только Т3»
P7	Мелкие накладные: ИНН через точечные чтения; Метаданные.НайтиПоТипу в цикле РМ	ПеревозкаСторонняя, ДокументыСОшибками	Вторичный эффект

---

4. Объём доработки (to-be)

Работы разбиты на этапы. Этапы можно сдавать отдельно при сохранении критериев §1.2 для затронутой части.

Этап A — очередь и регистр статусов (P3, P4) — приоритет 1

Задачи

1. Оценить и при положительном результате включить итоги среза последних у ак_СтатусыДокументовЭПД (сейчас EnableTotalsSliceLast = false). Зафиксировать влияние на запись статусов и объём ИБ.
2. Переработать выборку кандидатов очереди:
   • не строить полный срез «всего регистра», если достаточно отбора по активным статусам / отдельной структуре очереди;
   • подсчёт неудач (ВТ_Неудачи) ограничить документами-кандидатами текущей выборки, а не всей историей ошибок.
3. По возможности заменить отбор по Статус.Наименование на отбор по ссылкам справочника ак_СтатусыЭТРН (предопределённые / кэшированные ссылки).
4. (Опционально, при росте объёма) ввести узкий регистр/механизм «активная очередь» (документ + вид очереди: новый/опрос), историю статусов оставить в текущем РС.

Ограничения

• Сохранить семантику: условие в параметрах СрезПоследних по статусу нельзя ставить так, чтобы возвращалась «последняя запись с таким статусом», а не последняя запись документа (это уже осознанно зафиксировано в комментариях модуля).
• Не менять смысл границы «новый / опрос» по ИдентификаторСанадор.

Результат этапа: ускорение ДобавитьНовые / ДобавитьОпросы / протокола ошибок на наполненном регистре.

Этап B — HTTP и авторизация в рамках порции (P1, P2) — приоритет 1

Задачи

1. Переиспользовать HTTPСоединение (и при возможности параметры авторизации) в рамках одной порции / одной организации.
2. Пробросить/использовать кэш параметров авторизации (КешДанных.ПараметрыАвторизации или аналог) в ак_ПолучениеДанныхЭПД.ВызватьHTTPМетод, чтобы не читать ак_УчетныеЗаписиЭПД на каждый вызов.
3. Настроить/зафиксировать рекомендуемые параметры РЗ: меньшая порция новых (ориентир 10–20) при отдельном/более частом запуске опросов — без изменения кода бизнес-логики титулов, если достаточно настроек расписания и параметров метода.

Ограничения

• Параллельный запуск нескольких экземпляров робота по-прежнему не допускается без отдельного архитектурного решения (ключ РЗ).
• Контракт API (URL, заголовки Bearer / counterparty-uuid, тела Т1/Т3) не менять.

Результат этапа: снижение latency порции отправки при том же числе документов.

Этап C — пакетная подготовка данных титула Т1 (P5) — приоритет 2

Задачи

1. Расширить prefetch на порцию: один или несколько пакетных запросов по массиву документов вместо серии точечных вызовов (РабочийТелефонВодителя, АдресВесовой, адреса/телефоны сторон, координаты, ДокументЗакрепленияТС, даты прибытия/убытия и т.п. — по фактическому использованию в ПараметрыОтправкиТ1).
2. Расширить КешДанных ключами по ссылкам (адреса КИ, телефоны, коды регионов, закрепления ТС), с заполнением из prefetch.
3. По возможности дополнить уже существующий ДанныеПоДокументам (UNION по видам документов) полями, которые сейчас читаются повторно при сборке payload.

Ограничения

• Состав и смысл полей JSON payload Т1/Т3 не менять (кроме явно согласованных дефектов данных).
• Ошибки заполнения полей по-прежнему фиксируются в результате формирования / статусах.

Результат этапа: меньше запросов к ИБ на документ при отправке Т1.

Этап D — батч поиска перевозки для Т3 (P6) — приоритет 2

Задачи

1. Группировать вызовы ПолучитьСписокДокументовДляАРМ по ключу (организация, водитель, номер ТС, окно дат) внутри порции.
2. Разбирать общую таблицу ответа локально для нескольких документов группы.
3. Где в данных есть uuid связанной перевозки / ранее сохранённый идентификатор — использовать его и не вызывать поиск АРМ.

Ограничения

• Правила различения нескольких перевозок «Груз в пути» (входящий номер / номер документа) сохранить.
• Состояния ожидания Т2 по-прежнему блокируют отправку Т3.

Результат этапа: меньше HTTP при сценарии документов только с Т3 без uuid.

Этап E — мелкие оптимизации (P7) — приоритет 3

Задачи

1. Пакетное/кэшируемое чтение ИНН сторон в ПеревозкаСторонняя.
2. В ДокументыСОшибками — соответствие тип → синоним вместо Метаданные.НайтиПоТипу на каждую строку.
3. Оценить необходимость двух записей статуса после успешного Т1 («Черновик…» + «Ожидается Т2…»); менять только при согласовании с пользователями РМ/отчётами по истории.

---

5. Вне объёма

• Изменение формата обмена с Санадором / новых титулов ЭПД.
• Перенос создания ЭТрН в интерактивный режим «по кнопке» вместо робота.
• Оптимизация бумажных макетов ПФ_MXL_ТранспортнаяНакладная*.
• Параллельная обработка очереди несколькими рабочими процессами (требует отдельного ТЗ по блокировкам и идемпотентности API).
• Рефакторинг модулей сндОбменДаннымиСанадор* вне контура ЭТрН.

---

6. Регрессионные сценарии

№	Сценарий	Ожидание
R1	Проведение документа со сторонней перевозкой и включённой настройкой Т1/Т3	Статус «К отправке», сеть не вызывается
R2	Проведение при внутренней перевозке / выключенных настройках	«Не требуется» или отсутствие постановки по текущим правилам
R3	Повторное проведение документа уже в процессе	Статус/очередь не дублируют отправку
R4	РЗ: новый документ → Т1	Черновик в сервисе, заполнен ИдентификаторСанадор, статус ожидания Т2
R5	РЗ: опрос при готовности к Т3	Отправка Т3, корректный статус
R6	РЗ: документ с ошибкой первой отправки, неудач < максимума	Повторная попытка как «новый»
R7	Документ с uuid и ошибкой Т3	Не уходит в очередь «новых», не создаётся второй Т1
R8	РМ «Выбывшие документы ЭТрН» → вернуть в очередь	Счётчик неудач сбрасывается логикой ВернутьВОчередь, история сохраняется
R9	Исчерпание бюджета времени	Текущий документ дорабатывается, остальные подхватываются следующим запуском

---

7. Порядок внедрения и оценка

Рекомендуемый порядок: A → B → C → D → E.

Этап	Ориентир трудозатрат	Зависимости
A	2–5 чел·дн (без нового РС); +2–4 при введении узкой очереди	Решение по итогам среза / метаданным РС
B	1–3 чел·дн	Согласование сигнатур HTTP-обёрток
C	3–6 чел·дн	Этап B желателен, не обязателен
D	1–3 чел·дн	—
E	0,5–1,5 чел·дн	—

Оценки ориентировочные; уточняются после замера текущего времени ДобавитьНовые/ДобавитьОпросы и средней длительности HTTP на тестовой/боевой статистике.

---

8. Риски

Риск	Митигация
Включение итогов среза увеличит стоимость каждой записи статуса	Замер записи до/после; при неприемлемости — узкая очередь без итогов
Кэш auth устареет при смене токена в середине порции	Инвалидация кэша по организации при 401/ошибке авторизации и один повтор
Prefetch полей титула разъедется с ветвлениями по видам документов	Покрыть R4–R5 на всех 5 видах документов
Батч поиска Т3 склеит чужие перевозки	Сохранить текущие правила уточнения по номерам; не укрупнять ключ сверх (орг+водитель+ТС+даты)

---

9. Поставка

1. Описание изменений по модулям/метаданным.
2. Результаты замеров до/после (хотя бы время порции РЗ и число запросов/HTTP на документ).
3. Протокол прохождения сценариев §6.
4. При изменении метаданных РС — инструкция обновления ИБ и оценка времени пересчёта итогов (если применимо).

---

10. Источники анализа

• ves2020/CommonModules/ак_ЭТрНРобот/Ext/Module.bsl
• ves2020/CommonModules/ак_ЭТрНОтправка/Ext/Module.bsl
• ves2020/CommonModules/ак_ЭТрНФормированиеТитулов/Ext/Module.bsl
• ves2020/CommonModules/ак_ЭТрНДанные/Ext/Module.bsl
• ves2020/CommonModules/ак_ПолучениеДанныхЭПД/Ext/Module.bsl
• ves2020/InformationRegisters/ак_СтатусыДокументовЭПД.xml
• ves2020/ScheduledJobs/ак_ОбработкаОчередиЭТрН.xml

Memory: локальный memory.md (постоянных записей по ЭТрН нет).
Template: проверка шаблонов MCP в сессии недоступна — «no fitting template».
Docs / Metadata tooling: разбор по исходникам выгрузки; live MCP user-1c при анализе был частично недоступен.