Files
mostovik-backend/docs/integrated-structures-import.md
Aleksandr Meshchryakov 4e548fcc8e
Some checks failed
Mostovik Backend CI/CD / Tests and lint (push) Failing after 3m15s
Mostovik Backend CI/CD / Build linux/amd64 release images (push) Has been skipped
Mostovik Backend CI/CD / Deploy dev (push) Has been skipped
Mostovik Backend CI/CD / Deploy and verify internal main (push) Has been skipped
feat: import integrated structures from a ZIP archive
2026-10-08 10:34:42 +02:00

8.2 KiB
Raw Permalink Blame History

Загрузка интегрированных структур из ZIP

POST /api/v1/parsers/upload/integrated_structure_documents/ принимает multipart: одно файловое поле archive с ZIP. Требуются существующие права администратора загрузки. Прежние поля workbook и attachments больше не принимаются; frontend и backend следует обновлять согласованно. В nginx frontend для этого endpoint установлен предел 126 МиБ с запасом для multipart-заголовков; размер самого ZIP проверяет backend (125 МиБ).

Внутри архива должен быть ровно один XLSX с листами is_stages и is_stages_docs; RTF необязательны. Допускаются подпапки. Имя каждого RTF должно быть числовым doc_id из Excel (например, 000093.rtf для doc_id=93). Имена файлов должны быть уникальны без учёта регистра, даже в разных подпапках. Служебные .DS_Store и файлы внутри __MACOSX/ игнорируются.

Ограничения:

  • ZIP: до 125 МиБ; до 1024 записей, включая директории и служебные файлы.
  • XLSX: до 20 МиБ.
  • RTF: до 500 файлов, до 5 МиБ каждый и до 100 МиБ суммарно.
  • Всё распакованное содержимое: до 120 МиБ, включая служебные файлы.
  • Допустимы ZIP без сжатия или с Deflate; шифрование, символические ссылки, абсолютные пути, .., обратные слеши и посторонние файлы запрещены.

Backend читает архив в ограниченные временные потоки без извлечения по путям из ZIP. После проверки архива запускается прежний синхронный XLSX/RTF-импортёр; временные потоки закрываются и при ошибках. Hash/idempotency, атомарная публикация и статистика импорта сохраняются. Артефактом остаётся исходный XLSX. Передача одного ZIP устраняет ограничение Django на количество файлов multipart; лимит самого импортёра на 500 RTF сохраняется.

Пример запроса (с уже настроенной авторизацией клиента):

POST /api/v1/parsers/upload/integrated_structure_documents/
Content-Type: multipart/form-data; boundary=...

archive: structures.zip

Отсутствующий ZIP, лишние файлы multipart или старый формат запроса возвращают 422 archive_required. ZIP больше 125 МиБ возвращает 413 archive_too_large. Некорректный ZIP, опасные пути, нарушения лимитов содержимого и ошибки XLSX/RTF возвращают 422 с кодом причины; данные при этом не публикуются. В успешном ответе остаются HTTP 200 и прежние поля data, artifact_id и task_id.

Частичная загрузка

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-экспорта.