wtandClaude Opus 5.5
10272f3851
CI / Rust (fmt / clippy / test / build) (push) Successful in 1m41s
CI / HTTP/JSON reference + SQLite persistence (push) Successful in 1m16s
CI / Rust (fmt / clippy / test / build) (pull_request) Successful in 47s
CI / HTTP/JSON reference + SQLite persistence (pull_request) Successful in 1m34s
The Go implementation is preserved in the v1.0.0 tag. Its observable behaviour stays the API reference: responses recorded from the Go server live in tools/compatibility_expected.txt, and tools/compatibility.py now compares the Rust server against them (--update re-records after an intentional change). The Go SQLite schema is frozen in tests/fixtures/go_schema_v1.sql for the existing-database test. Move the web client from internal/httpapi/web to web/, drop the Go CI job and Go version pin, and update README, AGENTS.md and docs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
123 lines
5.2 KiB
Markdown
123 lines
5.2 KiB
Markdown
# AGENTS.md
|
|
|
|
## Назначение
|
|
|
|
**BalanceServer** — серверная часть приложения Balance, используемая iOS/macOS/watchOS и Android-клиентами.
|
|
|
|
Этот файл является operational guide для AI-агентов и разработчиков. При изменениях сначала изучай существующий код и сохраняй текущий API-контракт клиентов.
|
|
|
|
## Быстрая карта проекта
|
|
|
|
Сервер написан на Rust 1.90+. Исходная Go-реализация удалена после v1.0.0
|
|
(её исходники остались в теге `v1.0.0`), но её поведение остаётся эталоном API:
|
|
ответы Go записаны в `tools/compatibility_expected.txt`, а исходная SQLite-схема
|
|
Go — в `tests/fixtures/go_schema_v1.sql`. Оба файла не правь вручную.
|
|
|
|
Основные Rust-модули: `src/main.rs`, `runtime.rs`, `config.rs`,
|
|
`database.rs`, `auth.rs`, `server.rs`, `sync.rs`, `go_json.rs`.
|
|
Веб-клиент из `web/` встроен в Rust executable.
|
|
|
|
Обнаруженные технологии/интеграции: 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. Конкурентность
|
|
|
|
Сервер должен быть безопасен при одновременных запросах от нескольких устройств.
|
|
|
|
Особое внимание:
|
|
- генерации sequence;
|
|
- выдаче cursor;
|
|
- записи изменений;
|
|
- refresh-token rotation;
|
|
- race между push и pull.
|
|
|
|
### 6. Ошибки
|
|
|
|
HTTP API должен возвращать стабильную структуру ошибок. Не отдавай stack traces, SQL errors или внутренние пути клиенту.
|
|
|
|
Внутренние детали логируй только в безопасном виде.
|
|
|
|
### 7. Тесты
|
|
|
|
Перед PR:
|
|
|
|
```bash
|
|
cargo fmt --check
|
|
cargo test --locked
|
|
cargo clippy --locked --all-targets -- -D warnings
|
|
cargo build --locked --release
|
|
python3 tools/compatibility.py --binary target/release/balance-server
|
|
```
|
|
|
|
Если `tools/compatibility.py` нашёл расхождение, это изменение видно клиентам.
|
|
Перезаписывай эталон (`--update`) только для намеренного изменения API и
|
|
после обновления документации.
|
|
|
|
Если проект использует дополнительные проверки/линтеры, запускай их по 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 безопасны.
|
|
- [ ] Rust tests, fmt, clippy и release build проходят.
|
|
- [ ] `tools/compatibility.py` совпадает с записанным эталоном Go.
|
|
- [ ] Документация обновлена.
|