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,119 @@
+# Модель данных BalanceServer
+
+Ниже описана серверная модель на основании исходного кода проекта. При изменении schema обновляйте этот документ.
+
+## Найденные определения моделей/schema
+
+- internal/database/database.go
+- internal/database/database.go
+- internal/database/database.go
+- internal/config/config.go
+- internal/auth/tokens.go
+- internal/auth/tokens.go
+- internal/httpapi/auth_handlers.go
+- internal/httpapi/auth_handlers.go
+- internal/httpapi/auth_handlers.go
+- internal/httpapi/server.go
+- internal/httpapi/server.go
+- internal/httpapi/server.go
+- internal/httpapi/sync_handler.go
+- internal/httpapi/sync_handler.go
+- internal/httpapi/sync_handler.go
+- internal/httpapi/web.go
+- internal/httpapi/server_test.go
+- internal/httpapi/server_test.go
+- internal/httpapi/server_test.go
+
+## Общие сущности
+
+Сервер должен различать как минимум следующие логические типы синхронизируемых данных, совместимые с клиентами Balance:
+
+```text
+transaction
+category
+budget
+```
+
+### Transaction
+
+Логически содержит:
+- стабильный ID;
+- amount;
+- date;
+- note;
+- category presentation data;
+- transaction kind;
+- balance-adjustment flag;
+- update timestamp;
+- принадлежность пользователю.
+
+### Category
+
+Логически содержит:
+- стабильный ID;
+- name;
+- icon/emoji;
+- color;
+- operation kind;
+- creation/update metadata;
+- принадлежность пользователю.
+
+### Budget
+
+Логически содержит:
+- стабильный ID;
+- category information;
+- monthly limit;
+- month start;
+- update timestamp;
+- принадлежность пользователю.
+
+## Change metadata
+
+Для sync необходима метаинформация:
+
+```text
+user
+entity
+record ID
+deleted
+updatedAt
+sequence
+payload
+```
+
+`sequence` используется как серверный порядок изменений, а `updatedAt` — как timestamp версии самой записи.
+
+## Tombstones
+
+Удаление нельзя реализовывать только физическим `DELETE`, если клиентам нужно узнать о нём при следующем pull.
+
+Используется логическое изменение:
+
+```json
+{
+  "entity": "transaction",
+  "id": "…",
+  "deleted": true,
+  "updatedAt": "…"
+}
+```
+
+После того как tombstone перестанет быть нужен для поддерживаемого sync history window, сервер может применять retention policy. Такая политика должна быть согласована с cursor semantics.
+
+## Invariants
+
+1. Record ID стабилен между sync.
+2. Record принадлежит одному пользователю.
+3. Клиент не может читать/изменять чужую запись.
+4. `sequence` не должен уменьшаться.
+5. Повторная доставка одного change не должна повреждать данные.
+6. Удаление должно быть видимо клиенту через sync.
+7. Timestamps должны храниться в UTC.
+8. Enum/string values должны быть совместимы с iOS и Android.
+
+## Миграции
+
+Schema changes должны быть backward-compatible с активными версиями клиентов либо сопровождаться versioned API/миграцией.
+
+Не переименовывайте JSON field без периода совместимости.