Balance/AGENTS.md

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-удаления, пользовательские категории и месячные бюджеты.

Структура репозитория

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

Запусти проверки для всех подпроектов, которые ты менял:

# 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 соответствующего подпроекта тоже соблюдён.