Balance/BalanceServer/AGENTS.md

AGENTS.md

Назначение

BalanceServer — серверная часть приложения Balance, используемая iOS/macOS/watchOS и Android-клиентами.

Этот файл является operational guide для AI-агентов и разработчиков. При изменениях сначала изучай существующий код и сохраняй текущий API-контракт клиентов.

Быстрая карта проекта

Проект написан на Go 1.25.0.

Основные Go-файлы:

- 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:

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 ./... проходит.
• Документация обновлена.