252 lines
22 KiB
Markdown
252 lines
22 KiB
Markdown
# ТЗ на доработку: оптимизация создания и обработки ЭТрН
|
||
|
||
**Дата:** 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. Поток
|
||
|
||
```text
|
||
Проведение (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 при анализе был частично недоступен.
|