added AGENTS.md and docs for BalanceServer

2026-09-08 13:11:53 +07:00
parent 684ac58b73
commit 2f891c9503
10 changed files with 1022 additions and 0 deletions
@@ -0,0 +1,62 @@
+# Функциональная документация BalanceServer
+
+## Назначение
+
+BalanceServer является backend для приложения Balance — персонального финансового учёта.
+
+Он не реализует пользовательский UI. Его задача — безопасно хранить и синхронизировать данные между устройствами.
+
+## Пользовательские данные
+
+Синхронизируются:
+
+- финансовые операции;
+- пользовательские категории;
+- месячные бюджеты;
+- удаления этих сущностей.
+
+## Multi-device
+
+Один пользователь может работать с несколькими устройствами.
+
+Пример:
+
+```text
+iPhone добавил расход
+        ↓
+     Server
+        ↓
+Android получил расход
+        ↓
+Mac получил расход
+```
+
+## Offline-first
+
+Мобильные приложения сохраняют изменения локально и затем отправляют их серверу.
+
+Поэтому сервер должен корректно принимать изменения спустя некоторое время после их создания.
+
+## Delete
+
+Удаление является syncable operation, а не только локальным DB delete.
+
+Другие устройства должны получить tombstone и удалить локальную запись.
+
+## Privacy
+
+Сервер хранит персональные финансовые данные. Поэтому production deployment должен обеспечивать:
+- TLS;
+- authentication;
+- authorization;
+- encrypted backups;
+- controlled database access;
+- минимальное логирование финансовых payloads.
+
+## Клиентская совместимость
+
+Backend должен рассматриваться как общий контракт для:
+- Apple Balance;
+- Android Balance.
+
+Любое изменение протокола требует проверки обеих реализаций.