Refactored transaction input handling and removed unused receipt-related definitions in Swagger.

docs/finance_module_specification.md

@@ -7,9 +7,10 @@
 - расходов
 - категорий
 
-Поддерживает два способа ввода расходов:
+Поддерживает три способа ввода расходов:
 1. Ручной ввод
-2. Сканирование чека (QR-код)
+2. Ввод номера и даты чека
+3. Загрузка фото чека
 
 ---
 
@@ -155,13 +156,27 @@ categories (
 
 ---
 
-### 4.3 Сканирование чека
+### 4.3 Добавление расхода по номеру и дате чека
 
 #### Поток:
-1. Пользователь отправляет QR-код
+1. Пользователь вводит номер и дату чека
 2. Backend получает данные чека через внешний сервис
 3. Создаётся запись в `receipts`
-4. Для каждой позиции создаётся запись в `positions`
+4. Создаётся связанная транзакция в `transactions`
+5. Для каждой позиции создаётся запись в `positions`
+
+---
+
+### 4.4 Добавление расхода по фото чека
+
+#### Поток:
+1. Пользователь загружает фото чека
+2. Backend извлекает текст через OCR
+3. Backend извлекает из текста номер и дату чека
+4. Backend получает данные чека через внешний сервис
+5. Создаётся запись в `receipts`
+6. Создаётся связанная транзакция в `transactions`
+7. Для каждой позиции создаётся запись в `positions`
 
 ---
 
@@ -169,54 +184,92 @@ categories (
 
 ### Ручной ввод
 
-```
-User → API → positions
+```text
+User → API POST /transactions → transactions
 ```
 
 ### Доход
 
+```text
+User → API POST /transactions → transactions
 ```
-User → API → positions
+
+### Чек по номеру и дате
+
+```text
+User → API POST /transactions → receipt provider → receipts + positions + transactions
+```
+
+### Чек по фото
+
+```text
+User → API POST /transactions multipart/form-data → OCR → receipt provider → receipts + positions + transactions
 ```
 
 ---
 
 ## 6. API (черновик)
 
-### Создание позиции
+### Создание транзакции вручную
 
-```
-POST /positions
+```http
+POST /api/v1/transactions
+Content-Type: application/json
 ```
 
 ```json
 {
+  "family_id": 1,
+  "created_by": 2,
+  "type": "expense",
+  "category": "groceries",
   "amount": 1000,
-  "category_id": 1,
-  "description": "Продукты"
+  "description": "Продукты",
+  "datetime": "2026-01-21T10:11:12Z"
 }
 ```
 
 ---
 
-### Сканирование чека
+### Создание транзакции по номеру и дате чека
 
-```
-POST /receipts/scan
+```http
+POST /api/v1/transactions
+Content-Type: application/json
 ```
 
 ```json
 {
-  "qr_data": "string"
+  "family_id": 1,
+  "created_by": 2,
+  "receipt_number": "0123456789ABCDEFGHIJKLMN",
+  "receipt_date": "21.01.2026"
 }
 ```
 
 ---
 
-### Получение позиций
+### Создание транзакции по фото чека
 
+```http
+POST /api/v1/transactions
+Content-Type: multipart/form-data
 ```
-GET /positions
+
+Поля формы:
+- `photo` — файл изображения чека, обязательно
+- `family_id` — ID семьи, обязательно
+- `created_by` — ID пользователя, обязательно
+- `type` — тип транзакции, опционально, по умолчанию `expense`
+- `category` — категория, опционально, по умолчанию `receipt`
+- `description` — описание транзакции, опционально
+
+---
+
+### Получение транзакций
+
+```http
+GET /api/v1/transactions
 ```
 
 Фильтры:
@@ -227,6 +280,21 @@ GET /positions
 
 ---
 
+### Правила для `POST /api/v1/transactions`
+
+Используется ровно один сценарий создания:
+
+1. Ручная транзакция:
+   обязательны `family_id`, `created_by`, `type`, `category`, `amount`, `datetime`
+2. Транзакция по чеку:
+   обязательны `family_id`, `created_by`, `receipt_number`, `receipt_date`
+3. Транзакция по фото:
+   обязательны `photo`, `family_id`, `created_by`
+
+Нельзя смешивать ручные поля транзакции (`amount`, `datetime`, `receipt_id`) с полями чека (`receipt_number`, `receipt_date`) в одном JSON-запросе.
+
+---
+
 ## 7. Задачи для разработки
 
 ### Этап 1 — База
@@ -242,10 +310,10 @@ GET /positions
 
 ---
 
-### Этап 3 — Позиции
+### Этап 3 — Транзакции
 
-- [ ] Endpoint создания позиции
-- [ ] Endpoint получения списка
+- [x] Endpoint создания транзакции
+- [x] Endpoint получения списка
 - [ ] Фильтрация
 
 ---
@@ -259,9 +327,11 @@ GET /positions
 
 ### Этап 5 — Чеки
 
-- [ ] Endpoint загрузки QR
+- [x] Endpoint загрузки фото чека через `POST /transactions`
 - [ ] Интеграция с сервисом чеков
-- [ ] Создание receipts
+- [x] Создание receipts
+- [x] Создание транзакции по номеру и дате чека
+- [x] Создание транзакции по фото чека
 - [ ] Создание positions
 
 ---
@@ -295,5 +365,5 @@ GET /positions
 - [ ] Нужна ли мультивалютность?
 - [ ] Можно ли редактировать чек?
 - [ ] Как обрабатывать ошибки OCR?
+- [ ] Нужен ли отдельный endpoint для повторной привязки чека к существующей транзакции?
 - [ ] Нужны ли роли внутри семьи?
-