FamilyHUB/docs/finance_module_specification.md

📘 Финансовый модуль

1. Общее описание

Финансовый модуль предназначен для учёта:

• доходов
• расходов
• категорий

Поддерживает два способа ввода расходов:

1. Ручной ввод
2. Сканирование чека (QR-код)

---

2. Глоссарий

Доход (Income)
Денежное поступление (зарплата, перевод, подарок и т.д.)

Расход (Expense)
Факт траты денег

Категория (Category)
Классификация доходов и расходов (например: еда, транспорт, зарплата)

Чек (Receipt)
Документ, содержащий информацию о покупке (дата, позиции, сумма)

Позиция (Position)
Отдельная строка в чеке (товар или услуга)

---

3. Доменная модель

3.1 Positions

positions (
    id,
    receipt_number,
    operation_date,
    gtin_code,
    product_name,
    product_count,
    amount,
    discount,
    name_spd,
    category_id,
    family_id,
    family_member_id,
    created_at,
    updated_at
)

Описание полей:

• receipt_number — номер чека (nullable для ручного ввода)
• operation_date — дата операции
• gtin_code — код товара
• product_name — название товара
• product_count — количество
• amount — сумма позиции
• discount — скидка
• name_spd — продавец
• category_id — категория
• family_id — семья
• family_member_id — участник

---

3.2 Receipts

receipts (
    id,
    receipt_number,
    ui,
    status,
    issued_at,
    total_amount,
    payment_amount,
    cash_amount,
    another_amount,
    clearing_amount,
    margin,
    currency,
    payment_type,
    cashbox_number,
    cashier,
    name_spd,
    name_to,
    name_np,
    type_np,
    street_to,
    house_to,
    kod_soato,
    oblast_soato,
    rayon_soato,
    selsovet_soato,
    doc_num,
    skno_number,
    unp,
    success,
    family_id,
    family_member_id,
    created_at
)

Описание:

• хранит агрегированную информацию о чеке
• используется при сканировании QR
• связывается с positions через receipt_number

---

3.3 Categories

categories (
    id,
    name,
    type,
    family_id,
    family_member_id,
    created_at
)

Описание полей:

• type — income | expense
• категория принадлежит семье

---

4. Бизнес-логика

4.1 Добавление расхода вручную

• пользователь вводит:
  • сумму
  • описание
  • категорию
• создаётся запись в positions
• receipt_number = NULL

---

4.2 Добавление дохода

• аналогично расходу
• используется категория типа income

---

4.3 Сканирование чека

Поток:

1. Пользователь отправляет QR-код
2. Backend получает данные чека через внешний сервис
3. Создаётся запись в receipts
4. Для каждой позиции создаётся запись в positions

---

5. Потоки

Ручной ввод

User → API → positions

Доход

User → API → positions

---

6. API (черновик)

Создание позиции

POST /positions

{
  "amount": 1000,
  "category_id": 1,
  "description": "Продукты"
}

---

Сканирование чека

POST /receipts/scan

{
  "qr_data": "string"
}

---

Получение позиций

GET /positions

Фильтры:

• дата
• категория
• тип
• family_id

---

7. Задачи для разработки

Этап 1 — База

• Переписать SQL-миграции (positions, receipts, categories)

---

Этап 2 — Категории

• CRUD категорий
• Валидация типа (income/expense)

---

Этап 3 — Позиции

• Endpoint создания позиции
• Endpoint получения списка
• Фильтрация

---

Этап 4 — Доходы/расходы

• Определение типа через категорию
• Валидация соответствия

---

Этап 5 — Чеки

• Endpoint загрузки QR
• Интеграция с сервисом чеков
• Создание receipts
• Создание positions

---

Этап 6 — Telegram интеграция

• Команды добавления дохода/расхода
• Обработка QR

---

Этап 7 — Дополнительно

• Автокатегоризация
• Статистика
• Лимиты

---

8. Архитектурные решения

• Transaction — основная сущность финансов
• Receipt — дополняет транзакцию
• Position - позиции из чека
• Категории определяют тип операции
• Поддержка multi-tenant через family_id

---

9. Открытые вопросы

• Нужна ли мультивалютность?
• Можно ли редактировать чек?
• Как обрабатывать ошибки OCR?
• Нужны ли роли внутри семьи?