ios/README.md

# MusicBridge для iPhone

Нативный пульт на SwiftUI для MusicBridge.Agent на Windows. Звук играет на ПК.
Минимальная версия iOS — 17. Зависимостей Swift Package/CocoaPods нет.

## Первый вариант

- Сопряжение по HTTPS-адресу домашнего ПК, SHA-256 сертификата и коду.
- Импорт строки `musicbridge://pair?data=…` из QR агента; камера пока не реализована.
- Проверка закреплённого DER-сертификата до отправки кода и при следующих соединениях.
- Хранение адреса, отпечатка и токена в Keychain только на этом устройстве.
- Название, исполнитель, обложка, позиция, play/pause, следующий/предыдущий трек,
  перемотка ползунком, системная громкость и mute.
- WSS-состояние, переподключение с задержкой, остановка сети в фоне и восстановление
  при возврате. Команды автоматически не повторяются.

**Статус:** первый вариант собирается в GitHub Actions на macOS, Xcode 16.4,
Swift 6.1.2. Семь XCTest прошли на симуляторе iOS 18.5; проверка на физическом
iPhone и соединение с Windows-агентом ещё не выполнены.
[Успешный запуск](https://github.com/polskikh13/musicbridgeios/actions/runs/34444563869)
проверяет исходники коммита `a761431`.

## Сборка на Mac

1. Открыть `MusicBridge.xcodeproj` в Xcode 16 или новее.
2. Выбрать схему MusicBridge и симулятор iPhone. Run запускает приложение,
   Test выполняет `MusicBridgeTests`.
3. Для физического iPhone выбрать свою Team в Signing & Capabilities. Сертификаты
   и provisioning profiles не хранить в Git. Bundle ID при необходимости сменить
   в `tools/generate_project.py`, затем повторно сгенерировать проект.
4. На ПК запустить агент с `--tray --lan`, открыть сопряжение. В приложении
   ввести адрес, отпечаток и код с экрана ПК. Разрешить доступ к локальной сети.

Проект уже сгенерирован и включён в Git; Python для обычной сборки не требуется.
После добавления Swift-файлов выполнить `python3 tools/generate_project.py`.
Структурная проверка на Windows/macOS: `python tools/validate_project.py`.

## GitHub Actions

`.github/workflows/ios.yml` собирает приложение и выполняет XCTest на `macos-15`
при push в main, pull request или ручном запуске. Сохраняет лог, `.xcresult`
и ZIP приложения **для симулятора**, который нельзя установить на физический iPhone.
Apple ID и сертификаты для этой проверки не требуются. GitHub remote подключён:
`git@github.com:polskikh13/musicbridgeios.git`. GitHub CLI установлен и авторизован;
результаты доступны через `gh run list --repo polskikh13/musicbridgeios` и
`gh run view <run-id> --repo polskikh13/musicbridgeios --log-failed`.

Основной origin: `ssh://git@dev.yukinoki.ru:2222/musicbridge/ios.git`.
Отдельный remote `github` используется для Actions, основной origin сохранён.
Отправка: `git push origin main` и `git push github main`.
Код автоматически не зеркалируется между серверами. Локальная регрессионная
проверка выбора симулятора: `python tools/test_select_simulator.py`.

## Подключение через QR и поиск ПК

В версии 0.2.0 откройте окно сопряжения в Windows-агенте (`--tray --lan`),
на iPhone нажмите «Сканировать QR с ПК» и разрешите камеру. После сканирования
нажмите «Подключить компьютер». Ссылки `musicbridge://` также открываются
из стандартной камеры. Приглашение должно быть свежим.

В разделе «Найти ПК в сети» можно выбрать найденный адрес. Сверьте **весь**
предложенный отпечаток с экраном ПК и введите код. Если поиск не работает,
проверьте доступ к локальной сети в настройках MusicBridge; ручной ввод остаётся.
При смене адреса уже доверенного ПК приложение пробует объявления с тем же
отпечатком и сохраняет новый адрес только после успешной TLS-проверки и авторизации.

## Установка на iPhone через Sideloadly

Пользователь также подтвердил установку через iloader. Для повторной установки
с исправлениями устойчивости используйте версию **0.3.0 (build 4)**:
`build/iPhone-0.3.0/MusicBridge-iPhone.ipa`. Выберите этот файл в iloader и
подпишите тем же Apple Account, которым установлена первая версия.

В 0.3.0 обложка повторно загружается после временного сбоя, а после четырёх
неудачных попыток доступен ручной повтор. Отозванный доступ требует нового
сопряжения; автоматические попытки прекращаются. Если свернуть приложение во
время сопряжения, повторите его со свежим QR (удалив созданную запись на ПК,
если она уже успела появиться). При неизвестном результате команды проверьте
плеер перед повтором: приложение не повторяет команды автоматически.

Workflow также выполняет Release archive для `generic/platform=iOS` и создаёт
`MusicBridge-iPhone.ipa` в артефакте `MusicBridge-iPhone`. Это ARM64-сборка для
iOS 17+, без подписи. Подпись создаёт Sideloadly на вашем ПК с вашим Apple Account.
В Actions не передаются пароль Apple, сертификаты или provisioning profile.

1. Скачать артефакт MusicBridge-iPhone из успешного запуска Actions и распаковать
   ZIP артефакта, чтобы получить файл `.ipa`.
2. Подключить разблокированный iPhone к Windows кабелем; подтвердить доверие ПК.
3. Открыть Sideloadly, выбрать свой iPhone и файл `MusicBridge-iPhone.ipa`.
4. Войти в Apple Account непосредственно в Sideloadly, нажать Start, дождаться Done.
5. Если iPhone сообщает о недоверенном разработчике, открыть «Настройки → Основные
   → VPN и управление устройством», выбрать свой аккаунт и подтвердить доверие.
6. Для запуска включить «Настройки → Конфиденциальность и безопасность → Режим
   разработчика», затем выполнить предложенные iPhone перезагрузку и подтверждение.
7. Открыть MusicBridge, разрешить локальную сеть и выполнить сопряжение с ПК.

На бесплатном Apple Account подпись действует 7 дней; её нужно обновлять через
Sideloadly (в том числе его функцией автоматического обновления).
Файл MusicBridge-simulator.zip для установки на телефон не подходит.

[Sideloadly FAQ](https://sideloadly.io/faq) ·
[Apple: режим разработчика](https://developer.apple.com/documentation/Xcode/enabling-developer-mode-on-a-device)

## Источники

- [Apple: проверка доверия сервера](https://developer.apple.com/documentation/Foundation/performing-manual-server-trust-authentication)
- [Apple: доступ к локальной сети](https://developer.apple.com/documentation/technotes/tn3179-understanding-local-network-privacy)
- [GitHub: macOS runners](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)
- [GitHub: лимиты и оплата Actions](https://docs.github.com/en/billing/concepts/product-billing/github-actions)

План и ограничения — в `PLAN.md`. Копия протокола агента — в `PROTOCOL.md`.