Эталонная структура Android-проекта

Это ориентир, а не требование складывать в каждый проект все каталоги. Выберите один основной runtime: Native Android или Capacitor. Смешанный вариант допустим только при явной архитектурной причине.

Native Android / Compose

sample-app/
├── AGENTS.md
├── README.md
├── settings.gradle.kts
├── build.gradle.kts
├── gradle/libs.versions.toml
├── gradlew
├── gradle/wrapper/
├── app/src/{main,test,androidTest}/
├── scripts/{doctor.sh,verify.sh}
└── docs/play/
    ├── privacy-policy.md
    ├── data-safety.md
    ├── content-rating.md
    └── release-evidence.md

Предпочтительная организация кода: UI → ViewModel/state holder → use cases только при реальной пользе → repositories → local/remote data sources. UI не должен напрямую обращаться к сети, БД или системным API. Для API-приложения явно проектируются loading, empty, error, offline, retry и expired-session.

Capacitor

sample-capacitor-app/
├── AGENTS.md
├── README.md
├── package.json
├── package-lock.json
├── capacitor.config.ts
├── src/
├── public/
├── android/
├── scripts/{doctor.sh,verify.sh}
└── docs/play/

Source of truth — web-исходники. Содержимое android/app/src/main/assets/public генерируется через web build и cap sync, а не редактируется вручную.

Общий контракт автоматизации

Команда	Назначение	Побочный эффект
scripts/doctor.sh	Проверить JDK, SDK, wrapper и нужные инструменты	Нет
scripts/verify.sh	Все локальные проверки проекта	Только build/cache
./gradlew assembleDebug	Собрать debug APK	Создаёт артефакт
./gradlew bundleRelease	Собрать release AAB без публикации	Создаёт артефакт

В Capacitor те же действия можно оркестрировать через npm run doctor и npm run verify. Команды должны быть неинтерактивными, падать при ошибке и одинаково работать локально и в CI.

Минимальная конфигурация

• Gradle Wrapper и зафиксированные версии зависимостей;
• неизменяемый после публикации applicationId;
• version catalog или другой единый источник версий;
• секреты и signing только вне Git;
• permissions только под реализованные функции;
• docs/play с фактическими декларациями и release evidence;
• отдельные product flavors лишь когда это реальное разделение продукта;
• CI не имеет production signing/Play credentials без необходимости.

Definition of Done

• основной пользовательский сценарий работает на поддерживаемом API;
• приложение честно обрабатывает отсутствие сети и ошибки сервера;
• Back, Home, background/resume, rotation/adaptive layout и process recreation проверены в объёме, подходящем приложению;
• lint, unit, instrumentation/UI и release build проходят;
• permissions, SDK inventory, privacy и Data Safety совпадают с кодом;
• upgrade с опубликованной версии не теряет совместимые данные;
• AAB принят internal track и Play-delivered build проверен перед production;
• откат означает остановку rollout и выпуск исправленной версии: уменьшить versionCode уже опубликованного Android-пакета нельзя.