wt
da9e17f45f
Android CI / Build and Test (push) Failing after 13m25s
iOS CI / Build and Test SwiftUI App (push) Canceled after 0s
Build Unsigned iOS and macOS Apps / Build Unsigned iOS IPA (push) Canceled after 0s
Build Unsigned iOS and macOS Apps / Build macOS ZIP (push) Canceled after 0s
168 lines
10 KiB
Markdown
168 lines
10 KiB
Markdown
# AGENTS.md — корень монорепозитория Balance
|
||
|
||
Этот файл — точка входа для AI-агентов и разработчиков, работающих в
|
||
репозитории Balance. Он описывает, как устроены три подпроекта, как они
|
||
связаны друг с другом, и куда идти за подробностями. **Каждый подпроект
|
||
имеет собственный `AGENTS.md` с детальными правилами — читай его перед
|
||
любым изменением внутри соответствующей папки.**
|
||
|
||
## Что это за проект
|
||
|
||
Balance — приложение для учёта личных финансов, доступное на пяти
|
||
платформах, которые используют одну и ту же доменную модель и один и
|
||
тот же протокол синхронизации:
|
||
|
||
| Платформа | Папка | Стек |
|
||
| --- | --- | --- |
|
||
| iOS 17+ | `Balance/` | SwiftUI + SwiftData |
|
||
| macOS 14+ | `Balance/` (`BalanceMac/`) | SwiftUI + SwiftData |
|
||
| watchOS 10+ | `Balance/` (`BalanceWatch/`) | SwiftUI + SwiftData |
|
||
| Android 8.0+ | `BalanceAndroid/` | Kotlin + Jetpack Compose + Room |
|
||
| Web (встроен в сервер) | `BalanceServer/` | Go + embedded static client |
|
||
| Сервер синхронизации | `BalanceServer/` | Go + SQLite |
|
||
|
||
Все клиенты — iOS, macOS, watchOS, Android, web — синхронизируются через
|
||
один и тот же self-hosted сервер (`BalanceServer`) по единому HTTP(S)
|
||
API: регистрация, вход, refresh-токены, push/pull изменений с курсором,
|
||
tombstone-удаления, пользовательские категории и месячные бюджеты.
|
||
|
||
## Структура репозитория
|
||
|
||
```text
|
||
Balance/ # монорепозиторий
|
||
├── AGENTS.md # этот файл — общие правила для агентов
|
||
├── README.md # общий обзор и точки входа
|
||
├── docs/ # сводная документация по всему проекту
|
||
│ ├── ARCHITECTURE.md # как связаны клиенты и сервер
|
||
│ ├── SYNC_PROTOCOL.md # единый протокол синхронизации
|
||
│ ├── DATA_MODEL.md # сопоставление сущностей между платформами
|
||
│ ├── SECURITY.md # сквозные требования безопасности
|
||
│ └── DEVELOPMENT.md # как собрать и проверить все три проекта
|
||
│
|
||
├── Balance/ # Xcode-проект: iOS + macOS + watchOS
|
||
│ ├── AGENTS.md # правила для Apple-клиента
|
||
│ ├── README.md
|
||
│ └── docs/ # ARCHITECTURE, DATA_MODEL, SYNC, DEVELOPMENT, PRODUCT
|
||
│
|
||
├── BalanceAndroid/ # Android-проект (Gradle/Kotlin)
|
||
│ ├── AGENTS.md # правила для Android-клиента
|
||
│ ├── README.md
|
||
│ └── docs/ # ARCHITECTURE, DATA_MODEL, SYNC, DEVELOPMENT, PRODUCT
|
||
│
|
||
└── BalanceServer/ # Go-сервер синхронизации + web-клиент
|
||
├── AGENTS.md # правила для сервера
|
||
├── README.md
|
||
└── docs/ # ARCHITECTURE, API, DATA_MODEL, SYNC, SECURITY, DEVELOPMENT, DEPLOYMENT, PRODUCT
|
||
```
|
||
|
||
## Как работать в этом репозитории
|
||
|
||
### 1. Сначала пойми, в каком подпроекте изменение
|
||
|
||
Каждый подпроект — независимый билд с собственными зависимостями,
|
||
тестами и CI-шагами. Изменения в одной папке не должны требовать
|
||
правок в другой, **кроме** случаев, когда меняется общий контракт:
|
||
|
||
- HTTP API / формат sync-запросов и ответов (`BalanceServer`);
|
||
- набор синхронизируемых полей сущности (транзакция, категория, бюджет);
|
||
- правила финансовых расчётов (баланс, корректировки, аналитика).
|
||
|
||
Если меняется общий контракт — обнови все три подпроекта согласованно
|
||
и синхронизируй документацию (`docs/SYNC_PROTOCOL.md`, а также
|
||
`docs/SYNC.md`/`docs/API.md`/`docs/DATA_MODEL.md` внутри каждой папки).
|
||
|
||
### 2. Единая доменная модель
|
||
|
||
Три клиента независимо реализуют одну и ту же модель на своём стеке
|
||
(SwiftData / Room), но со семантически одинаковыми сущностями:
|
||
|
||
- **Транзакция** (доход/расход, сумма, дата, заметка, категория —
|
||
хранится snapshot'ом имени/иконки/цвета категории на момент операции);
|
||
- **Пользовательская категория** (имя, иконка/emoji, цвет);
|
||
- **Месячный бюджет** (категория, месяц, лимит);
|
||
- **Tombstone/deletion journal** для распространения удалений между
|
||
устройствами.
|
||
|
||
Общие правила расчётов (баланс = доходы − расходы; корректировки
|
||
баланса учитываются в общем балансе, но не в периодической аналитике;
|
||
расходы группируются по имени категории) продублированы в:
|
||
|
||
- `Balance/Balance/Utilities/FinanceCalculations.swift` (Apple);
|
||
- `BalanceAndroid/.../data/FinanceMath.kt` (Android).
|
||
|
||
При изменении этих правил на одной платформе — переноси изменение на
|
||
другую и обновляй оба набора тестов
|
||
(`BalanceTests/FinanceCalculationsTests.swift`, `FinanceMathTest`).
|
||
|
||
### 3. Синхронизация — общий контракт
|
||
|
||
Единый протокол описан в `docs/SYNC_PROTOCOL.md` (сводно) и подробно —
|
||
в `BalanceServer/docs/API.md` и `BalanceServer/docs/SYNC.md`. Клиентские
|
||
реализации:
|
||
|
||
- Apple: `Balance/Balance/Shared/ServerSync.swift`;
|
||
- Android: `BalanceAndroid/.../sync/SyncRepository.kt`.
|
||
|
||
Изменение cursor/sequence semantics, JSON-полей или auth-заголовков —
|
||
breaking change для всех клиентов сразу. Не меняй его в одном
|
||
подпроекте, не проверив остальные два.
|
||
|
||
### 4. Безопасность (сквозные требования)
|
||
|
||
- Секреты (пароли, access/refresh токены) никогда не хранятся в
|
||
открытом виде: Keychain (Apple), Android Keystore + AES/GCM
|
||
(Android), Argon2id-хеши + SHA-256 refresh-token хеши (сервер).
|
||
- HTTPS обязателен для удалённого сервера на всех клиентах; HTTP
|
||
разрешён только для `localhost`/`127.0.0.1`/`::1`.
|
||
- Не логируй пароли, токены или заголовок `Authorization` ни в одном
|
||
из подпроектов.
|
||
- Не коммить секреты, production-URL или credentials.
|
||
|
||
Подробности — `docs/SECURITY.md` и `BalanceServer/docs/SECURITY.md`.
|
||
|
||
### 5. Тестирование перед PR
|
||
|
||
Запусти проверки для всех подпроектов, которые ты менял:
|
||
|
||
```bash
|
||
# Apple (из Balance/)
|
||
xcodebuild -project Balance.xcodeproj -scheme Balance \
|
||
-destination 'platform=iOS Simulator,name=<available iPhone>' test
|
||
|
||
# Android (из BalanceAndroid/)
|
||
./gradlew clean test assembleDebug
|
||
|
||
# Server (из BalanceServer/)
|
||
go test ./...
|
||
go vet ./...
|
||
go build ./...
|
||
```
|
||
|
||
Если менялся общий контракт (API/sync/data model) — прогони проверки
|
||
во всех трёх, а не только в изменённой папке.
|
||
|
||
### 6. Документация
|
||
|
||
- Меняешь контракт синхронизации → обнови `docs/SYNC_PROTOCOL.md` в
|
||
корне **и** `BalanceServer/docs/SYNC.md`/`API.md`, а также
|
||
`docs/SYNC.md` в `Balance/` и `BalanceAndroid/`.
|
||
- Меняешь модель данных на любой платформе → обнови `docs/DATA_MODEL.md`
|
||
в корне и в затронутом подпроекте.
|
||
- Меняешь способ сборки/запуска → обнови `docs/DEVELOPMENT.md` в
|
||
корне и соответствующий `README.md`/`docs/DEVELOPMENT.md` подпроекта.
|
||
- Каждый подпроект содержит собственный подробный `AGENTS.md` — этот
|
||
файл не заменяет их, а даёт общую картину и правила координации между
|
||
платформами.
|
||
|
||
## PR checklist (для изменений, затрагивающих несколько платформ)
|
||
|
||
- [ ] Определены все подпроекты, которые затрагивает изменение.
|
||
- [ ] Общий контракт (API/sync/data model) обновлён согласованно во
|
||
всех платформах, а не только в одной.
|
||
- [ ] Финансовые расчёты остаются идентичными на Apple и Android.
|
||
- [ ] Обновлены `docs/SYNC_PROTOCOL.md`, `docs/DATA_MODEL.md` в корне,
|
||
если менялась схема/протокол.
|
||
- [ ] Секреты и токены не добавлены в репозиторий ни в одном подпроекте.
|
||
- [ ] Тесты пройдены в каждом изменённом подпроекте.
|
||
- [ ] Локальный `AGENTS.md` соответствующего подпроекта тоже соблюдён.
|