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

117 lines
8.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Загрузка интегрированных структур из 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 сохраняется.
Пример запроса (с уже настроенной авторизацией клиента):
```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` заполнен).
Неизвестные ОКПО пропускаются; организации автоматически не создаются.
При наличии и известных, и неизвестных организаций HTTP-ответ остаётся 200,
`success=true`, `errors=null`. В `data` возвращаются:
```json
{
"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-экспорта.