Files
mostovik-backend/docs/integrated-structures-import.md
2026-09-28 11:27:46 +02:00

5.1 KiB
Raw Blame History

Частичная загрузка интегрированных структур

POST /api/v1/parsers/upload/integrated_structure_documents/ принимает multipart: workbook (XLSX с листами is_stages и is_stages_docs) и необязательные attachments (RTF). Требуются существующие права администратора загрузки.

Backend сначала проверяет весь файл и вложения. ОКПО сопоставляются только с организациями канонического справочника (directory_imported_at заполнен). Неизвестные ОКПО пропускаются; организации автоматически не создаются.

При наличии и известных, и неизвестных организаций HTTP-ответ остаётся 200, success=true, errors=null. В data возвращаются:

{
  "status": "partial",
  "records_count": 48,
  "imported_organizations_count": 48,
  "skipped_organizations_count": 2,
  "skipped_organizations": [
    {
      "okpo": "02742757",
      "code": "unknown_canonical_okpo",
      "message": "Организация не загружена: ОКПО отсутствует в каноническом реестре."
    },
    {
      "okpo": "10386058",
      "code": "unknown_canonical_okpo",
      "message": "Организация не загружена: ОКПО отсутствует в каноническом реестре."
    }
  ],
  "warnings": [
    {
      "code": "unknown_canonical_okpo",
      "message": "Часть организаций не загружена: ОКПО отсутствуют в каноническом реестре.",
      "meta": {"okpos": ["02742757", "10386058"]}
    }
  ]
}

Это фрагмент ответа: также возвращаются существующие artifact_id, task_id, batch_id и статистика workbook. Тот же результат доступен в BackgroundJob. Фронтенду следует показать количество загруженных организаций и все пропуски из skipped_organizations, а не трактовать success=true как отсутствие предупреждений.

  • Все ОКПО известны: status=published, список пропусков и warnings пусты.
  • Все ОКПО неизвестны: HTTP 200, status=skipped, reason=no_known_organizations, records_count=0, artifact_id=null, без batch_id; текущий snapshot не меняется.
  • Идентичный последний опубликованный batch при неизменном сопоставлении с реестром: status=skipped, reason=identical_batch; возвращается прежняя статистика batch и его предупреждения, дублей нет.
  • После пополнения канонического реестра тот же workbook можно загрузить повторно: ранее пропущенные организации будут учтены.
  • Два канонических совпадения одного ОКПО, повреждённый XLSX/RTF и нарушенные связи остаются ошибками 422; известная часть при этих ошибках не публикуется.

structures_count, event_rows_count, document_link_rows_count, unique_documents_count, events_without_documents_count описывают исходный workbook. records_count/imported_organizations_count описывают загруженную часть batch. snapshot_records_count описывает весь текущий snapshot, включая сохранённые старые записи. imported_documents_count, attachments_count и missing_attachments_count относятся к загруженным организациям; submitted_attachments_count — ко всем переданным и проверенным вложениям. Полностью пропущенный файл возвращает только счётчики организаций и предупреждения.

Частичная публикация атомарна и меняет данные только известных организаций из файла. Прежние записи других организаций сохраняются. Документы и RTF, связанные только с пропущенными организациями, не публикуются. Документ, связанный также с известной организацией, включается в её данные. Полная загрузка сохраняет прежнюю семантику замены snapshot.

Хотфикс относится к Mostovik dev. Он не добавляет этот источник на main и не меняет другие источники или форматы JSON-экспорта.