diff --git a/docs/implementation/contract-drafts.md b/docs/implementation/contract-drafts.md new file mode 100644 index 0000000..cbe490f --- /dev/null +++ b/docs/implementation/contract-drafts.md @@ -0,0 +1,100 @@ +# Контрактные черновики (Pass 1 draft) + +## Конвенции ответов upload (F-2..F-6) + +### Success (queued/async) +```json +{ + "upload_id": "uuid", + "form": "f2", + "report_year": 2026, + "report_quarter": 1, + "report_period_display": "I квартал 2026", + "status": "queued", + "job_id": "uuid", + "created_at": "2026-04-14T10:22:00+03:00" +} +``` + +### Success (sync, может быть без job_id) +```json +{ + "upload_id": "uuid", + "form": "f2", + "report_year": 2026, + "report_quarter": 1, + "report_period_display": "I квартал 2026", + "status": "done", + "created_at": "2026-04-14T10:22:00+03:00", + "result": { + "batch_id": 123, + "loaded_count": 10, + "skipped_count": 2, + "errors": [] + } +} +``` + +### Error (валидация multipart) +```json +{ + "error_code": "validation_error", + "error_message": "Validation failed", + "details": [ + { + "field": "report_year", + "code": "invalid", + "message": "report_year is required" + }, + { + "field": "file", + "code": "invalid_file_type", + "message": "Unsupported file extension" + } + ] +} +``` + +## users/me contract (ожидаемый) +```json +{ + "id": 1, + "username": "admin", + "email": "admin@example.com", + "phone": "+79990000000", + "is_active": true, + "role": "admin", + "role_label": "Администратор системы", + "capabilities": { + "can_access_admin_page": false + }, + "profile": { + "first_name": "Администратор", + "middle_name": "", + "last_name": "", + "full_name": "Администратор" + } +} +``` + +## Organizations list contract (expected fields) +```json +{ + "id": "uuid", + "short_name": "АО «Альфа»", + "full_name": "Акционерное общество Альфа", + "corporation_scope": ["rosatom"], + "corporation_scope_label": ["Госкорпорация «Росатом»"], + "organization_type": "ao", + "organization_type_label": "Акционерное общество", + "inn": "7405000428", + "ogrn": "1027400661650", + "kpp": "745001001", + "okpo": "07624755", + "active_registry_names": ["Реестр госкорпорации Росатом"] +} +``` + +## Отдельный note по неясностям +- Для F-3/F-5/F-6 endpoint период нужно согласовать в рамках Pass 1 после проверки форматов файлов и старых контрактов. +- Статусы для upload: если sync выполняется мгновенно, статус `done`, если в очередь — `queued` и `job_id` обязателен.