added AGENTS.md and docs for BalanceServer

BalanceServer/AGENTS.md

@@ -0,0 +1,125 @@
+# AGENTS.md
+
+## Назначение
+
+**BalanceServer** — серверная часть приложения Balance, используемая iOS/macOS/watchOS и Android-клиентами.
+
+Этот файл является operational guide для AI-агентов и разработчиков. При изменениях сначала изучай существующий код и сохраняй текущий API-контракт клиентов.
+
+## Быстрая карта проекта
+
+Проект написан на Go 1.25.0.
+
+Основные Go-файлы:
+
+```text
+- internal/database/database.go
+- internal/config/config.go
+- internal/auth/tokens.go
+- internal/auth/password.go
+- internal/httpapi/auth_handlers.go
+- internal/httpapi/server.go
+- internal/httpapi/sync_handler.go
+- internal/httpapi/web.go
+- internal/httpapi/server_test.go
+```
+
+Количество Go-файлов: **9**.
+
+Обнаруженные технологии/интеграции: SQLite, Docker.
+
+## Правила изменений
+
+### 1. Не ломать клиентский контракт
+
+Сервер обслуживает несколько клиентов:
+- Apple Balance;
+- Android Balance.
+
+Изменение JSON-полей, HTTP methods, endpoint paths, auth semantics или sync semantics считается breaking change, даже если сервер компилируется.
+
+Перед изменением API ищи использование endpoint/field в server code и документации клиентов.
+
+### 2. Sync — центральный контракт
+
+Синхронизация должна оставаться:
+- детерминированной;
+- идемпотентной при повторной доставке;
+- устойчивой к повторным запросам;
+- корректной при нескольких устройствах одного пользователя.
+
+Не меняй правила cursor/sequence/update timestamps без обновления `docs/SYNC.md`.
+
+### 3. Аутентификация
+
+Никогда не:
+- логируй пароль;
+- логируй access/refresh token;
+- возвращай секреты в ошибках;
+- храни plaintext passwords.
+
+При изменении auth обязательно проверь:
+- регистрацию;
+- login;
+- refresh;
+- logout;
+- истечение токенов;
+- авторизацию sync endpoint.
+
+### 4. База данных
+
+Любое изменение schema должно иметь:
+- migration strategy;
+- обратную совместимость там, где её требуют старые клиенты;
+- проверку индексов для user/entity/id/sequence/update timestamp.
+
+Не удаляй существующие поля только потому, что текущий клиент ими не пользуется.
+
+### 5. Конкурентность
+
+Go server должен быть безопасен при одновременных запросах от нескольких устройств.
+
+Особое внимание:
+- генерации sequence;
+- выдаче cursor;
+- записи изменений;
+- refresh-token rotation;
+- race между push и pull.
+
+### 6. Ошибки
+
+HTTP API должен возвращать стабильную структуру ошибок. Не отдавай stack traces, SQL errors или внутренние пути клиенту.
+
+Внутренние детали логируй только в безопасном виде.
+
+### 7. Тесты
+
+Перед PR:
+
+```bash
+go test ./...
+go vet ./...
+go build ./...
+```
+
+Если проект использует дополнительные проверки/линтеры, запускай их по Makefile/CI.
+
+### 8. Документация
+
+При изменении:
+- endpoint → обновить `docs/API.md`;
+- sync → `docs/SYNC.md`;
+- DB model → `docs/DATA_MODEL.md`;
+- deploy/config → `docs/DEPLOYMENT.md`;
+- архитектуры → `docs/ARCHITECTURE.md`.
+
+## Checklist
+
+- [ ] Не изменён API случайно.
+- [ ] Auth secrets не попадают в logs/errors.
+- [ ] Sync остаётся идемпотентным.
+- [ ] DB migration учтена.
+- [ ] Concurrent requests безопасны.
+- [ ] `go test ./...` проходит.
+- [ ] `go vet ./...` проходит.
+- [ ] Документация обновлена.