feat(savings): Add savings module with categories, transactions, recurring plans

- Categories: regular, deposits, credits, recurring, multi-user, accounts
- Transactions: deposits and withdrawals with user tracking
- Recurring plans: monthly payment obligations per user
- Stats: overdues calculation with allocation algorithm
- Excludes is_account categories from total sums
- Documentation: docs/SAVINGS.md
This commit is contained in:
Cosmo
2026-02-16 06:48:09 +00:00
parent 9e90aa6d95
commit 2a50e50771
18 changed files with 2910 additions and 162 deletions

56
docs/SAVINGS.md Normal file
View File

@@ -0,0 +1,56 @@
# Savings Module
Модуль накоплений для Pulse App. Позволяет отслеживать накопления, вклады, кредиты и регулярные платежи.
## Функционал
### Категории
- **Обычные накопления** — копилки с произвольными пополнениями
- **Депозиты (is_deposit)** — вклады с процентной ставкой и сроком
- **Кредиты (is_credit)** — отслеживание погашения кредитов
- **Регулярные (is_recurring)** — категории с ежемесячными обязательствами
- **Мультипользовательские (is_multi)** — общие категории для нескольких пользователей
- **Счета (is_account)** — транзитные счета (исключаются из общих сумм)
### Recurring Plans
Для категорий с is_recurring=true создаются планы платежей:
- effective — дата начала действия плана
- amount — сумма ежемесячного платежа
- day — день месяца для платежа (1-28)
- user_id — пользователь (для multi-категорий)
### Алгоритм расчёта просрочек
1. Определение периода: начало = MAX(category.created_at, earliest_plan.effective)
2. Построение списка месяцев от начала до текущего
3. Расчёт required для каждого месяца по активному плану
4. Allocation deposits: каждый депозит сначала покрывает свой месяц, потом предыдущие
5. Overdues: все прошлые месяцы с remaining > 0
### Расчёт сумм
- total_deposits — сумма пополнений пользователя (исключая is_account)
- total_withdrawals — сумма снятий пользователя (исключая is_account)
- total_balance — сумма балансов всех категорий пользователя
## API Endpoints
### Categories
- GET /savings/categories — список категорий
- POST /savings/categories — создать категорию
- PUT /savings/categories/:id — обновить
- DELETE /savings/categories/:id — удалить
### Transactions
- GET /savings/transactions — список транзакций
- POST /savings/transactions — создать
- PUT /savings/transactions/:id — обновить
- DELETE /savings/transactions/:id — удалить
### Stats
- GET /savings/stats — статистика (балансы, monthly_payments, overdues)
### Recurring Plans
- GET /savings/categories/:id/recurring-plans — планы
- POST /savings/categories/:id/recurring-plans — создать
- PUT /savings/recurring-plans/:planId — обновить
- DELETE /savings/recurring-plans/:planId — удалить