docs/domains/cards/overview.md

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

Банковская карта — самостоятельный ручной учёт дебетовой карты в рублях.
Пользователь задаёт название, дату начала и начальный остаток; банк и последние
четыре цифры и платёжная система (Мир, Visa или Mastercard) необязательны. Даже одинаково названные карты одного банка имеют
разные истории и балансы. Полные номера, 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](../../glossary.md#money), frontend только форматирует финансовые итоги.

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

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

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

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

В журнале расходов, списке категорий и сводке иконка подбирается по текущему
названию категории: исходные тематические категории, а также алкоголь, табак,
образование, путешествия, подписки, связь и интернет, страхование, ставки,
вклады, инвестиции и накопления, переводы, погашение кредита, снятие наличных,
хостинг и ИИ-сервисы и цифровые покупки имеют свои пиктограммы.
«Другое» и неизвестные названия используют общую иконку. Карточки операций
имеют лёгкий красный фон для списаний и зелёный для поступлений.
Цвета иконок зависят от категории, знак и цвет суммы показывают направление
движения денег. Регистр, внешние пробелы и различие «е»/«ё» не влияют
на подбор; после переименования иконка может измениться. Пополнения обозначаются
кошельком с плюсом, переводы и возвраты — соответствующими стрелками.

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

## Период и сводка

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

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

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

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

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

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

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

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

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

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

[Безопасное восстановление](../../architecture/containers.md#сохранение-и-восстановление-данных)
сохраняет новую финансовую историю и при откате приложения. Устройство хранения
описано в [контейнерах](../../architecture/containers.md#хранимые-данные-и-границы-доступа).
Согласованный контракт банковского учёта находится в
[manual-bank-cards](https://git.personal.ksv741.ru/WealthLedger/specs/src/commit/9e227a563dda67620f0ad78228aa8a4c18bf35a0/openspec/changes/add-manual-bank-cards/specs/manual-bank-cards/spec.md).
Автоматическая загрузка банковских данных, кредитные карты, другие валюты,
бюджеты и общий баланс банковских денег с инвестициями в эту версию не входят.