rmser/API_DOCS.md

API Documentation: RMSER Backend

1. Общая информация

• Base URL: http://localhost:8080/api
• Формат данных: JSON.
• CORS: Разрешены запросы с localhost:5173 (и любых других источников в режиме dev).
• Auth: На данный момент эндпоинты открыты. В будущем предполагается передача токена в заголовке Authorization: Bearer <token>.

Обработка ошибок

В случае ошибки сервер возвращает HTTP код 4xx/5xx и JSON:

{
  "error": "Описание ошибки"
}

---

2. TypeScript Интерфейсы (Models)

Используйте эти интерфейсы для типизации данных на клиенте.

// --- Общие типы ---

// UUID (строка)
type UUID = string;

// Decimal (деньги/вес приходят строкой, чтобы избежать потери точность в JS)
type Decimal = string; 

// --- Каталог и OCR ---

// Товар для выпадающего списка (Autosuggest)
export interface CatalogItem {
  id: UUID;
  name: string;
  code: string; // Артикул или код быстрого набора
}

// Связь "Текст из чека" -> "Товар iiko"
export interface ProductMatch {
  raw_name: string;      // Текст из OCR (ключ)
  product_id: UUID;
  product?: CatalogItem; // Вложенный объект (при чтении)
  updated_at: string;    // ISO Date
}

// --- Рекомендации (Аналитика) ---

export interface Recommendation {
  ID: UUID;
  Type: string;         // Код проблемы (UNUSED_IN_RECIPES, NO_INCOMING, etc.)
  ProductID: UUID;
  ProductName: string;
  Reason: string;       // Человекочитаемое описание проблемы
  CreatedAt: string;
}

// --- Накладные ---

export interface InvoiceItemRequest {
  product_id: UUID;
  amount: number; // или string, если нужна высокая точность
  price: number;
}

export interface CreateInvoiceRequest {
  document_number: string;
  date_incoming: string; // Format: "YYYY-MM-DD"
  supplier_id: UUID;
  store_id: UUID;
  items: InvoiceItemRequest[];
}

---

3. Эндпоинты

📊 Аналитика (Рекомендации)

Получить список рекомендаций

Возвращает список выявленных проблем в учете (товары без техкарт, ингредиенты без закупок и т.д.). Данные обновляются фоновым процессом на бэкенде.

• URL: /recommendations
• Method: GET
• Response: 200 OK

[
  {
    "ID": "uuid...",
    "Type": "UNUSED_IN_RECIPES",
    "ProductID": "uuid...",
    "ProductName": "Петрушка с/м",
    "Reason": "Товар не используется ни в одной техкарте",
    "CreatedAt": "2023-10-27T10:00:00Z"
  }
]

---

👁 OCR и Обучение (Matching)

1. Получить справочник товаров (для селекта)

Используется для построения локального индекса поиска (autocomplete) на фронтенде, чтобы привязывать позиции. Возвращает только активные товары (GOODS).

• URL: /ocr/catalog
• Method: GET
• Response: 200 OK

[
  {
    "id": "607a1e96-f539-45d2-8709-3919f94bdc3e",
    "name": "Молоко Домик в Деревне 3.2%",
    "code": "00123"
  },
  ...
]

2. Получить таблицу обучения (Matches)

Возвращает список уже созданных связей "Грязное название из чека" -> "Чистый товар iiko".

• URL: /ocr/matches
• Method: GET
• Response: 200 OK

[
  {
    "raw_name": "молоко двд 3,2",
    "product_id": "607a1e96-f539-45d2-8709-3919f94bdc3e",
    "product": {
       "ID": "607a1e96-f539-45d2-8709-3919f94bdc3e",
       "Name": "Молоко Домик в Деревне 3.2%",
       ...
    },
    "updated_at": "..."
  }
]

3. Создать/Обновить привязку

Сохраняет правило: "Если в чеке встретишь этот текст, считай это вот этим товаром".

• URL: /ocr/match
• Method: POST
• Body:

{
  "raw_name": "молоко двд 3,2", 
  "product_id": "607a1e96-f539-45d2-8709-3919f94bdc3e"
}

• Response: 200 OK -> {"status": "saved"}

---

📄 Накладные (Invoices)

Отправить накладную в iikoRMS

Создает черновик приходной накладной в системе iiko.

• URL: /invoices/send
• Method: POST
• Body:

{
  "document_number": "INV-12345",
  "date_incoming": "2023-10-27",
  "supplier_id": "uuid-supplier...",
  "store_id": "uuid-store...",
  "items": [
    {
      "product_id": "uuid-product...",
      "amount": 10.5,
      "price": 150.00
    }
  ]
}

• Response: 200 OK

{
  "status": "ok",
  "created_number": "000123" // Номер документа, присвоенный iiko
}

---

⚙️ System

Healthcheck

Проверка доступности API.

• URL: http://localhost:8080/health
• Method: GET
• Response:

{
  "status": "ok",
  "time": "2023-10-27T12:34:56+03:00"
}

---

4. Сценарии использования (Frontend Workflow)

Сценарий А: "Обучение" (раздел Settings / OCR Learning)

1. При загрузке страницы вызвать GET /api/ocr/matches и отобразить таблицу.
2. Вызвать GET /api/ocr/catalog и сохранить в памяти для быстрого поиска (Combobox/Select).
3. Пользователь может добавить новую связь вручную:
   • Вводит текст (например, "Хлеб Бородинский").
   • Выбирает товар из выпадающего списка.
   • Нажимает "Save" -> вызывается POST /api/ocr/match.
   • Таблица обновляется.

Сценарий Б: "Дашборд аналитика"

1. При загрузке главной страницы вызвать GET /api/recommendations.
2. Сгруппировать массив по полю Type или Reason.
3. Отобразить карточки: "Товары без техкарт (5 шт)", "Ингредиенты без закупок (12 шт)".

Сценарий В: "Создание накладной" (Пока ручное)

Пока нет загрузки фото через Web, предполагается ручной ввод или редактирование данных, полученных иным путем.

1. Форма ввода номера, даты.
2. Таблица товаров (добавление строк через поиск по каталогу).
3. Кнопка "Отправить в iiko" -> POST /api/invoices/send.