Метод GET /api/v1/fridge/drafts

Домен: INVENTORY | Сервис: backend-api (Gateway) | Получение списка черновиков для модерации

Ограничение публичной документации

В открытом доступе представлена демонстрационная версия метода. В настоящей публичной документации отображены не все шаги, технические сценарии и приватные эндпоинты для системы цифровых симуляторов бизнес-процессов.

Полная спецификация метода: Будет доступна только во внутреннем контуре разработки (Confluence / Swagger Enterprise).

Функциональное назначение

The GET /api/v1/fridge/drafts method is a synchronous REST API entry point used by the mobile client. It retrieves a list of ambiguous text entries (drafts) for a specific user or home group that failed automatic AI censorship due to a low neural network confidence level (confidence < 0.85) and require manual reconciliation.

After editing the text on the frontend, the mobile application reuses the existing POST /api/v1/fridge/items/upload-text method, forwarding the original draft ID within the X-Request-ID header. This ensures the end-to-end history of the censorship process is preserved and the violation counter is properly tracked.

Interaction Protocol (HTTP Contract)

Method: GET
Route: /api/v1/fridge/drafts
Data Format: application/json

Headers Specification (HTTP Headers)

Header	Required	Description	Example Value
`Authorization`	Yes	Access Token. The gateway extracts `user_id` and `home_group_id` from this token.	`Bearer eyJhbGciOiJIUzI1Ni...`

Response Body Specification (HTTP Response Body)

200 OK (Successful List Retrieval)

Returns an array of active drafts awaiting moderation.

{
  "success": true,
  "drafts": [
    {
      "draft_id": "uuid-draft-555",
      "trace_id": "req-manual-text-99aa",
      "raw_text_input": "Молоко Юрта в ауле сомнительныйконтекст 3.2%",
      "app_lang": "ru",
      "created_at": "2026-08-07T10:23:00Z"
    }
  ]
}

Метод GET /api/v1/fridge/drafts является синхронной входной точкой (HTTP REST API) для мобильного клиента. Он возвращает список сомнительных текстовых записей (черновиков) конкретного пользователя или домашней группы, которые не прошли автоматическую ИИ-цензуру из-за низкого уровня уверенности нейросети (confidence < 0.85) и требуют ручной корректировки.

После редактирования текста на фронтенде, мобильное приложение повторно использует метод POST /api/v1/fridge/items/upload-text, пробрасывая в заголовке X-Request-ID оригинальный ID этого черновика для сохранения сквозной истории цензуры.

Протокол взаимодействия (HTTP Контракт)

Метод: GET
Маршрут: /api/v1/fridge/drafts
Формат данных: application/json

Спецификация заголовков (HTTP Headers)

Заголовок	Обязательный	Описание	Пример значения
`Authorization`	Да	Токен доступа (`Access Token`). Шлюз извлекает `user_id` и `home_group_id`.	`Bearer eyJhbGciOiJIUzI1Ni...`

Спецификация ответа (HTTP Response Body)

200 OK (Успешное получение списка)

Возвращает массив активных черновиков, ожидающих модерации.

{
  "success": true,
  "drafts": [
    {
      "draft_id": "uuid-draft-555",
      "trace_id": "req-manual-text-99aa",
      "raw_text_input": "Молоко Юрта в ауле сомнительныйконтекст 3.2%",
      "app_lang": "ru",
      "created_at": "2026-08-07T10:23:00Z"
    }
  ]
}

Диаграмма последовательности (Mermaid)

sequenceDiagram
    autonumber
    actor User as Mobile Client (App)
    participant App as Moderation Tab
    participant GW as FastAPI Gateway
    participant DB as DB / Read Model
    participant K as Apache Kafka Cluster

    %% STEP 1-4: FETCH DRAFTS
    App->>GW: GET /api/v1/fridge/drafts
    GW->>DB: Fetch group drafts (confidence < 0.85)
    DB-->>GW: Array of drafts from DB
    GW-->>App: HTTP 200 OK (Array with draft_id and trace_id)
    Note over App: Local card rendering on screen

    %% STEP 5-7: REUSE MANUAL INPUT
    User->>App: Fixes text manually and taps "Save"
    Note over App: Existing manual entry method is reused!<br/>The draft trace_id is forwarded in the X-Request-ID header.
    App->>GW: POST /api/v1/fridge/items/upload-text
    Note over GW: Step 6: String length validation via Pydantic model
    GW->>K: Push to topic: bpds.inventory.in.receipt.upload
    GW-->>App: HTTP 202 Accepted

sequenceDiagram
    autonumber
    actor User as Пользователь (App)
    participant App as Вкладка модерации
    participant GW as FastAPI Gateway
    participant DB as DB / Read Model

    %% ШАГ 6: ПОЛУЧЕНИЕ ЧЕРНОВИКОВ
    App->>GW: GET /api/v1/fridge/drafts
    GW->>DB: Выборка черновиков группы с confidence < 0.85
    DB-->>GW: Массив черновиков
    GW-->>App: HTTP 200 OK (Массив с draft_id и trace_id)
    Note over App: Рендеринг карточки на экране

    %% ШАГ 7: ПЕРЕИСПОЛЬЗОВАНИЕ РУЧНОГО ВВОДА
    User->>App: Исправляет текст руками и жмет "Сохранить"
    Note over App: Переиспользование существующего метода!<br/>В заголовок X-Request-ID передается trace_id черновика.
    App->>GW: POST /api/v1/fridge/items/upload-text
    Note over GW: Валидация длины строки (Шаг 1 общей таблицы)<br/>и пуш в Kafka под старым trace_id
    GW-->>App: HTTP 202 Accepted

Расшифровка шагов метода

Step	Action	Parameters / Requests / DTO	Errors (Exceptions / Statuses)
1 (`App -> GW`)	The user opens the moderation tab. The app sends a request to retrieve all ambiguous entries associated with the user’s home group.	`HTTP GET /api/v1/fridge/drafts` Headers: `Authorization: Bearer <Access_JWT>`	`HTTP 401 Unauthorized` (access token is modified, forged, expired, or missing; code `IAD-AUTH-401`)
2 (`GW -> DB`)	The API Gateway extracts the `home_group_id` from the token payload and queries the moderation drafts database replica.	SQL Query: `SELECT draft_id, trace_id, raw_text_input, app_lang FROM moderation_drafts WHERE home_group_id = 'group_abc123' AND confidence < 0.85;`	No business errors
3 (`DB -> GW`)	The database returns the up-to-date array of draft objects that match the filtering criteria.	Database response: Array of rows or an empty set `[]` if no ambiguous entries exist.	No business errors
4 (`GW -> App`)	The gateway formats the final JSON response, delivering the draft list to the mobile app for rendering and local state management.	HTTP Status: `200 OK` Response Body: The structured JSON array of drafts specified above.	No business errors
5 (`App -> GW`)	Tapping a card opens the text locally. The user edits it and hits “Save”. The app calls the standard manual entry method, passing the draft’s `trace_id` into the `X-Request-ID` header.	`HTTP POST /api/v1/fridge/items/upload-text` Headers: `X-Request-ID: "req-manual-text-99aa"`, `Authorization` Payload (`UploadTextRequestDTO`): `{ "raw_text_input": "Молоко Юрта 3.2% 1.5 л", "app_lang": "ru" }`	No business errors
6 (`GW -> GW`)	Internal Validation: The backend gateway validates the modified string against the Pydantic model, checking the critical length restriction.	Internal check: `len(payload.raw_text_input) <= 120`	`HTTP 422 Unprocessable Entity` (edited text is empty or exceeds the 120-character limit; code `IAD-VAL-422`)
7 (`GW -> K`)	The gateway publishes the event to the message broker for repeated censorship. Reusing the old `trace_id` ensures the worker tracks the limit history.	Kafka Message (Topic: `bpds.inventory.in.receipt.upload`): `Key: "usr_9876"` `Payload: { "trace_id": "req-manual-text-99aa", "source_type": "USER_EDIT", "raw_text_input": "Молоко Юрта..." }`	No business errors
7 Continuation (`GW -> App`)	The gateway immediately terminates the synchronous connection with the client, confirming the task has been queued in the asynchronous processing pipeline.	HTTP Output Status: `202 Accepted` Response Body: `{ "success": true, "message": "Request accepted for processing", "trace_id": "req-manual-text-99aa" }`	No business errors

Шаг	Действие	Параметры / Запросы / DTO	Ошибки (Исключения / Статусы)
1 (`App -> GW`)	Пользователь открывает вкладку модерации. Приложение отправляет запрос для получения всех сомнительных записей домашней группы пользователя.	`HTTP GET /api/v1/fridge/drafts` Headers: `Authorization: Bearer <Access_JWT>`	`HTTP 401 Unauthorized` (токен доступа изменен, просрочен или отсутствует, код `IAD-AUTH-401`)
2 (`GW -> DB`)	API-шлюз извлекает `home_group_id` из полезной нагрузки токена и выполняет запрос к реплике базы данных черновиков.	SQL-запрос: `SELECT draft_id, trace_id, raw_text_input, app_lang FROM moderation_drafts WHERE home_group_id = 'group_abc123' AND confidence < 0.85;`	Бизнес-ошибки отсутствуют
3 (`DB -> GW`)	База данных возвращает актуальный массив объектов черновиков, соответствующих критериям фильтрации.	Ответ СУБД: Массив строк или пустой сет `[]`, если сомнительные записи отсутствуют.	Бизнес-ошибки отсутствуют
4 (`GW -> App`)	Шлюз формирует финальный JSON-ответ, возвращая список черновиков мобильному приложению для рендеринга и локального сохранения в стейт.	HTTP Статус: `200 OK` Response Body: Специфицированный выше JSON с массивом `drafts`.	Бизнес-ошибки отсутствуют
5 (`App -> GW`)	По клику на карточку текст открывается локально. Пользователь правит его и жмет «Сохранить». Приложение вызывает стандартный метод добавления, подставляя `trace_id` черновика в заголовок `X-Request-ID`.	`HTTP POST /api/v1/fridge/items/upload-text` Headers: `X-Request-ID: "req-manual-text-99aa"`, `Authorization` Payload (`UploadTextRequestDTO`): `{ "raw_text_input": "Молоко Юрта 3.2% 1.5 л", "app_lang": "ru" }`	Бизнес-ошибки отсутствуют
6 (`GW -> GW`)	Внутренняя валидация: Бэкенд-шлюз пропускает измененную строку через Pydantic-модель, проверяя критическое ограничение длины.	Внутренняя проверка: `len(payload.raw_text_input) <= 120`	`HTTP 422 Unprocessable Entity` (отредактированный текст пустой или превысил лимит, код `IAD-VAL-422`)
7 (`GW -> K`)	Шлюз публикует событие в брокер сообщений для повторной цензуры. Использование старого `trace_id` гарантирует, что воркер сохранит историю лимитов.	Kafka Message (Topic: `bpds.inventory.in.receipt.upload`): `Key: "usr_9876"` `Payload: { "trace_id": "req-manual-text-99aa", "source_type": "USER_EDIT", "raw_text_input": "Молоко Юрта..." }`	Бизнес-ошибки отсутствуют
7 Продолжение (`GW -> App`)	Шлюз возвращает клиенту статус 202, подтверждая успешную постановку задачи в асинхронную очередь обработки.	HTTP Статус на выходе: `202 Accepted` Response Body: `{ "success": true, "message": "Request accepted for processing", "trace_id": "req-manual-text-99aa" }`	Бизнес-ошибки отсутствуют