126 lines
4.4 KiB
Markdown
126 lines
4.4 KiB
Markdown
# 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 ./...` проходит.
|
|
- [ ] Документация обновлена.
|