Сборка APK и цикл доработок

Этот маршрут объединяет создание приложения, сборку APK, проверку и исправления. Рабочий каталог — ~/projects/android; каждое приложение живёт в отдельной прямой подпапке. Названия my-app и ru.example.myapp ниже — пример, замените их своими до запуска.

Выберите исходную точку

Что уже есть	Следующий шаг
Идея нового Android-приложения	Заполнить паспорт, создать проект из Compose-шаблона.
Исходники работающей PWA	Проверить исходную web-сборку, затем подготовить отдельный Android-проект через Capacitor.
Существующий Android-проект	Сохранить его stack, прочитать локальные инструкции и запустить его проверку.
Только адрес сайта	Установить владельца исходников, права на контент, способ входа и работу без сети. Один URL ещё не является переносимым приложением.

Новый проект с нуля

Короткие команды из корня workspace:

Команда	Для чего
npm run android:doctor	Проверить установленную среду.
npm run apk:new -- --name my-app --package-id ru.example.myapp	Создать новый native-проект.
npm run apk:pwa-check -- my-pwa-app	Проверить подготовленную Capacitor-оболочку и web-команды без сборки.
npm run apk:iterate -- my-app --lane native	Выполнить полный локальный цикл проекта.
npm run apk:iterate -- my-app --lane native --quick	Быстро проверить изменение; перед передачей APK нужен полный цикл.

cd ~/projects/android
bash scripts/scaffold-native-compose.sh --name my-app --package-id ru.example.myapp
bash scripts/android-iterate.sh my-app --lane native

Генератор создаёт исходники, Gradle Wrapper, инструкции агента, проверки и заготовки документов публикации. Он не должен перезаписывать существующий каталог. Созданный стартовый экран — основа для реализации вашего сценария; прежние результаты проверки шаблона не доказывают работоспособность нового приложения.

После создания заполните README и docs/architecture.md, реализуйте первую пользовательскую задачу и дополните тесты. Package ID выбирается до публикации. Путь к свежему APK и результаты проверки сохраняйте в проектном документе проверки, а не в общей истории другого приложения.

Подготовка существующей PWA

1. Назовите точную папку исходников, Android target и package ID. Зафиксируйте, где останется источник web-кода и как изменения будут попадать в приложение.
2. Проверьте текущую web-сборку штатными командами и менеджером зависимостей проекта. Сохраните закреплённые версии и lock-файл. Не копируйте .env, рабочие данные, ключи или весь каталог сайта вместе с кешами.
3. Подготовьте отдельную подпапку Android workspace: согласованный web source или воспроизводимый импорт его сборки, package.json, lock-файл, capacitor.config.*, android/, AGENTS.md, README и docs/play/. Последовательность подключения описана в PWA через Capacitor.
4. В webDir укажите фактический каталог web-сборки с index.html. Проверьте маршрутизацию, относительные пути, загрузку изображений и шрифтов, вход и сетевые запросы внутри Android. Режим без сети проверяется отдельно.
5. Предоставьте исполняемые lint, test, build, локальный Capacitor CLI и Android Wrapper. Укажите точную версию npm/pnpm/yarn в packageManager и соответствующий lock-файл. Полный цикл закрепите в проектном scripts/verify.sh либо package script verify и README. Общий runner выполняет этот контракт; он не заменяет проверку его содержания.
6. Запустите общий цикл для подготовленного проекта:

bash scripts/android-iterate.sh my-pwa-app --lane capacitor

Отсутствующие проверки нужно реализовать или явно классифицировать как непройденный этап. Пустой test, возвращающий успех, не заменяет проверку. Не правьте вручную android/app/src/main/assets: меняйте web source, затем повторяйте build и sync. Не переносите project-local SDK/AVD/cache из Arcade в другое приложение.

Доработка одного сценария

Перед правкой запишите ожидаемое поведение, способ воспроизведения ошибки и минимальную проверку. Во время работы используйте целевой unit/UI test или проектную команду быстрой сборки. Завершайте итерацию полной проверкой на неизменённом дереве:

bash scripts/android-iterate.sh my-app --lane native

За одно изменение отвечает один исполнитель. Общие SDK, кеш сборки и устройство не используются одновременно несколькими задачами. После сбоя запишите точную команду, тип ошибки, изменённую гипотезу и следующий шаг; не очищайте SDK/AVD или данные приложения в качестве универсального исправления.

--quick у native запускает unit-тесты и debug APK, у Capacitor — web build, sync и debug APK. Этот режим не выполняет весь release gate. Опция --device <serial> только проверяет доступность выбранного устройства после сборки и выводит следующий шаг; она не устанавливает и не запускает приложение.

Проверка на устройстве

ADB должен видеть конкретное устройство или AVD в состоянии device. Выберите его явно; общий цикл без такого выбора не запускает установку или UI-проверку. Перед вызовом проектного device-smoke.sh прочитайте его: старые сценарии могут удалять приложение или данные. Для таких действий нужен отдельный точный scope.

На выбранной тестовой среде проверьте:

• запуск и основную пользовательскую задачу;
• Back, сворачивание/возврат и пересоздание процесса;
• разные размеры экрана, поворот, увеличенный шрифт;
• заявленное поведение без сети, ошибки сервера и отказ в разрешениях;
• обновление предыдущей версии с сохранением пользовательских данных.

Установка поверх предыдущей версии и чистая установка — разные проверки. При несовпадении подписи не удаляйте установленное приложение автоматически. Данные реального телефона не являются расходным тестовым материалом. В официальной документации ADB описаны явный выбор устройства и установка пакетов.

Перед передачей APK тестировщику

Полная локальная проверка, ручной сценарий и публикация имеют отдельные результаты. Зафиксируйте package, versionName/versionCode, путь, размер, SHA-256, тип подписи и известные ограничения. Не подменяйте файл уже опубликованной версии. Используйте стандартный реестр тестовых APK.

Debug APK подходит для разработки; требования к release-подписи отличаются. Это разделение описано в официальной инструкции сборки Android. Сборка, публикация тестового APK и готовность к Google Play не взаимозаменяемы.

Готовые задания агенту

Новый проект:

Используй $android-release. Создай <app> в ~/projects/android из native template.
Package ID: <id>. Пользовательский сценарий: <описание>. Реализуй сценарий,
проверь его и собери APK. Сохрани evidence и остаточные ограничения.
Не меняй соседние приложения; не добавляй SDK и permissions без необходимости.

PWA:

Используй $android-release. Подготовь Android-приложение <app> из PWA <source>.
Package ID: <id>. Сохрани исходный web stack и опиши воспроизводимый build/sync.
Проверь маршруты, вход и <требуемое поведение без сети>, собери APK.
Не копируй секреты или рабочие данные сайта. Публикацию выполняй только
в разрешённом для этого приложения канале.

Исправление:

Исправь в <app> поведение <шаги и ожидаемый результат>.
Сначала воспроизведи дефект, затем внеси минимальную правку и регрессионную
проверку. Выполни полный локальный verify, проверь на <точный serial>,
обнови проектное evidence. Не удаляй данные и не меняй package ID.