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
+
+## Роль сервера
+
+BalanceServer — backend для синхронизации личных финансов между устройствами.
+
+Поток данных:
+
+```text
+iOS/macOS/watchOS ─┐
+                   ├── HTTPS/JSON API ──> BalanceServer ──> Database
+Android ───────────┘
+```
+
+Сервер отвечает за:
+- регистрацию и авторизацию;
+- пользовательские сессии;
+- хранение финансовых изменений;
+- push/pull synchronization;
+- глобальную последовательность изменений;
+- удаление через tombstones;
+- выдачу изменений начиная с cursor.
+
+## Исходный код
+
+Текущая кодовая база содержит 9 Go-файлов.
+
+Пути:
+
+```text
+- internal/auth
+- internal/config
+- internal/database
+- internal/httpapi
+```
+
+Конкретные границы package/handler/service/repository нужно сохранять при рефакторинге: перенос кода между слоями не должен менять внешний API.
+
+## HTTP layer
+
+HTTP layer принимает JSON requests от мобильных клиентов.
+
+Каждый handler должен:
+1. проверить method/content type;
+2. аутентифицировать пользователя, если endpoint защищён;
+3. валидировать input;
+4. вызвать domain/storage logic;
+5. вернуть стабильный JSON response.
+
+## Domain / sync layer
+
+Sync layer является наиболее критичной частью backend.
+
+Он должен разделять:
+- изменения, созданные текущим клиентом;
+- изменения, которые нужно вернуть клиенту;
+- удалённые записи;
+- cursor/sequence.
+
+Ключевая модель:
+
+```text
+client cursor
+      │
+      ▼
+server change log
+      │
+      ├── sequence 101
+      ├── sequence 102
+      ├── sequence 103
+      └── ...
+```
+
+Клиент может запросить изменения после своего cursor и затем сохранить новый cursor.
+
+## Persistence
+
+Хранилище должно сохранять как минимум:
+- user/account identity;
+- credentials/session metadata;
+- financial records;
+- change metadata;
+- deletion/tombstone metadata;
+- monotonically increasing sequence, если оно является частью текущего sync protocol.
+
+Конкретные entities и schema документированы в `docs/DATA_MODEL.md`.
+
+## Security boundaries
+
+```text
+Internet
+   │
+   ▼
+HTTP server
+   │
+   ├── authentication
+   ├── authorization
+   ├── input validation
+   │
+   ▼
+domain/sync
+   │
+   ▼
+database
+```
+
+Нельзя позволять клиенту выбирать произвольный `user_id` для чужих records.
+
+## Совместимость клиентов
+
+Apple и Android реализации должны видеть одну и ту же семантику данных.
+
+Особенно важно, чтобы:
+- enum values были стабильными;
+- даты имели единый формат;
+- UUID/string IDs не менялись;
+- `deleted` semantics были одинаковыми;
+- cursor/sequence были монотонными;
+- conflict resolution совпадал с клиентской логикой.