docs/domains/cards/overview.md

Ручной учёт банковских карт

Банковская карта — самостоятельный ручной учёт дебетовой карты в рублях. Пользователь задаёт название, дату начала и начальный остаток; банк и последние четыре цифры необязательны. Даже одинаково названные карты одного банка имеют разные истории и балансы. Полные номера, PIN, срок действия и код безопасности не запрашиваются как реквизиты этого учёта.

Данные принадлежат локальному пользователю. Для них достаточно сессии WealthLedger; подключение T-Bank не требуется. Банковские суммы не входят в брокерский портфель, пассивный доход или прогноз выплат, а смена подключения брокера не изменяет ручную историю.

Откуда берётся баланс

Начальный остаток означает деньги до всех внесённых операций начиная с даты начала учёта. Баланс равен этому остатку плюс пополнения, входящие переводы и возвраты, минус расходы и исходящие переводы. Он учитывает всю неудалённую историю, независимо от выбранного месяца, страницы журнала и архива.

Например, остаток 1 ₽ и расходы 0,10 ₽ и 0,20 ₽ дают ровно 0,70 ₽. Отрицательный результат допустим: он не блокирует реальную трату или перевод. Это баланс по внесённым операциям, а не подтверждение остатка в банковском приложении. Пропущенные движения могут создавать расхождения.

Деньги хранятся целыми копейками и рассчитываются без преобразования в JavaScript Number. Отдельный ввод ограничен signed64: начальный остаток — от −92 233 720 368 547 758,08 ₽ до 92 233 720 368 547 758,07 ₽; сумма операции строго положительна и не выше верхней границы. Допускается не больше двух десятичных знаков, лишняя точность отклоняется без округления. Итог сложения может превышать границу отдельного ввода. HTTP использует общий Money, frontend только форматирует финансовые итоги.

Операции и категории

Вид	Смысл и связи
Расход	Уменьшает баланс и относится к категории
Пополнение	Увеличивает баланс, не входит в расходы
Перевод	Одной записью уменьшает баланс источника и увеличивает баланс другой своей активной карты; не считается расходом
Возврат	Связан с исходным расходом той же карты и наследует его текущую категорию

Даты сохраняются как календарные дни без времени. Сегодня определяется в Europe/Moscow; операция допускается от начала учёта до сегодня включительно. Для перевода дата должна подходить обеим картам. Описание необязательно.

При первом добавлении карты создаются категории «Продукты», «Кафе», «Такси», «Транспорт», «Жильё», «Здоровье», «Покупки», «Развлечения», «Другое». Категории общие для всех карт одного пользователя. Их можно добавлять и переименовывать; уникальность названия не зависит от регистра и внешних пробелов. Переименование сохраняет идентичность, поэтому история показывает новое имя. «Другое» сохраняет роль категории по умолчанию даже после переименования. Подкатегории и удаление категорий в этой версии отсутствуют.

Возврат может относиться к покупке любого месяца. Несколько частичных возвратов допустимы, если вместе не превышают текущую сумму покупки; возврат не может быть датирован раньше неё. При исправлении возврата его старая сумма заменяется новой, а не учитывается второй раз. Доступный лимит для исправления рассчитывает сервер, поэтому полностью возвращённую покупку можно оставить без изменения суммы и исправить описание.

Месяц и сводка

Журнал и сводка карты относятся к одному выбранному месяцу. Журнал показывает операции по убыванию даты, затем времени создания и идентификатора; доступны следующие страницы. Баланс при выборе прошлого месяца остаётся текущим. Сводка учитывает все подходящие записи, включая не показанные на странице.

Сводка одной или всех карт отдельно показывает потраченное, возвращённое и разницу, в том числе по категориям. Возврат уменьшает расходы месяца своего получения: августовская покупка 1 000 ₽ и сентябрьский возврат 600 ₽ дают августовский итог 1 000 ₽ и сентябрьский −600 ₽ при отсутствии других трат. Начальный остаток, пополнения и переводы в эти показатели не входят. Сводка всех карт включает архивные карты независимо от фильтра списка.

Исправления и архив

Можно исправить сумму, дату, описание и применимые связи операции. Вид записи и исходная покупка возврата неизменны. Обычный расход или пополнение можно перенести на другую активную карту; изменение или удаление перевода затрагивает обе стороны целиком. Исправление категории покупки перегруппировывает её возвраты, в том числе в других месяцах.

Расход с возвратами нельзя удалить, перенести, уменьшить ниже уже возвращённого или датировать позже возврата. Сначала исправляются мешающие возвраты. Изменение начала учёта проверяет всю историю, включая входящие переводы; изменение начального остатка не создаёт отдельной операции и не меняет траты. Произвольной операции «исправить баланс» нет.

Архив сохраняет историю при любом балансе. До возвращения карты из архива недоступны финансовые изменения и изменение начала учёта; описательные реквизиты менять можно. Для исправления перевода должны быть активны и прежние, и новые стороны. Безвозвратное удаление карт не предусмотрено.

Сохранение и конфликты

Карты, операции и категории хранятся в SQLite и переживают повторный вход и перезапуск. Переводы и связанные изменения сохраняются транзакционно. Проверка владельца распространяется на каждую ссылку, включая категорию, обе карты перевода и покупку возврата.

Создание карты или операции получает постоянный идентификатор намерения. Повтор того же ввода после потерянного ответа возвращает текущую запись; изменённый ввод с тем же идентификатором получает конфликт. Проверка уже сохранённого намерения предшествует проверке нового лимита возврата или архива. Поэтому полный возврат не списывается повторно, а архивная карта не становится активной от запоздалого повтора создания.

Удалённая операция оставляет служебную отметку и fingerprint первоначального ввода: повтор не восстанавливает её. Это не полный журнал всех редакций. Исправления используют версию записи: устаревшее изменение отклоняется, а форма сохраняет черновик и позволяет получить актуальную запись. При ошибке сохранения неподтверждённые суммы не выдаются за новый баланс.

Безопасное восстановление сохраняет новую финансовую историю и при откате приложения. Устройство хранения описано в контейнерах. Согласованный контракт этой поставки находится в manual-bank-cards. Автоматическая загрузка банковских данных, кредитные карты, другие валюты, бюджеты и общий баланс банковских денег с инвестициями в эту версию не входят.