feat: import integrated structures from a ZIP archive
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

This commit is contained in:
Aleksandr Meshchryakov
2026-10-08 10:34:42 +02:00
parent 70dfc55f3d
commit 4e548fcc8e
8 changed files with 581 additions and 47 deletions

View File

@@ -1,8 +1,50 @@
# Частичная загрузка интегрированных структур
# Загрузка интегрированных структур из ZIP
`POST /api/v1/parsers/upload/integrated_structure_documents/` принимает multipart:
`workbook` (XLSX с листами `is_stages` и `is_stages_docs`) и необязательные
`attachments` (RTF). Требуются существующие права администратора загрузки.
одно файловое поле `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 сохраняется.
Пример запроса (с уже настроенной авторизацией клиента):
```text
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` заполнен).