wtandClaude Opus 5.5
dfb4fe4e1a
- GET /v1/capabilities and the extended sync entity allowlist (§0, §1). - Shared ledgers (§7): ledgers, members and hashed one-time invite codes; X-Balance-Ledger selects the space on /v1/sync and /v1/attachments with its own records, change stream and cursor. Personal space keeps the v1 tables and behaviour; the migration only adds tables. - Attachments (§8): SHA-256, size and media type checks, blob files in BALANCE_ATTACHMENTS_DIR (default: attachments next to the database), garbage collection of unreferenced blobs with a grace period for fresh uploads, and ledger deletion removes its blobs. - Tests for every new endpoint and error code; API, sync, data model, security, deployment and README docs updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
124 lines
5.3 KiB
Markdown
124 lines
5.3 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`,
|
|
`ledgers.rs`, `attachments.rs` (контракт v2, `docs/CONTRACT_V2.md`).
|
|
Веб-клиент из `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.
|
|
- [ ] Документация обновлена.
|