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` обязателен.