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
117 lines
8.2 KiB
Markdown
117 lines
8.2 KiB
Markdown
# Загрузка интегрированных структур из 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-экспорта.
|