fix(import): skip unknown organizations in integrated workbooks
This commit is contained in:
74
docs/integrated-structures-import.md
Normal file
74
docs/integrated-structures-import.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# Частичная загрузка интегрированных структур
|
||||
|
||||
`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-экспорта.
|
||||
Reference in New Issue
Block a user