Balance/BalanceServer/docs/DATA_MODEL.md

Модель данных 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:

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 необходима метаинформация:

user
entity
record ID
deleted
updatedAt
sequence
payload

sequence используется как серверный порядок изменений, а updatedAt — как timestamp версии самой записи.

Tombstones

Удаление нельзя реализовывать только физическим DELETE, если клиентам нужно узнать о нём при следующем pull.

Используется логическое изменение:

{
  "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 без периода совместимости.