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

75 lines
5.1 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.
# Частичная загрузка интегрированных структур
`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` возвращаются:
```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-экспорта.