# AGENTS — BreathMonitor v3 ## Назначение Эта папка содержит третью версию автономного ESP32-монитора дыхания и отдельный Java/SQLite-сервер. - `firmware/` — прошивка для Waveshare ESP32-S3-Touch-AMOLED-2.16. - `server/` — исходники Java-сервера, Gradle-сборка и веб-интерфейс. - `deploy/` — шаблон systemd-службы и отдельный фрагмент Caddy. ## Обязательные правила - Все изменения этого проекта относятся к репозиторию `SKETCH`, не смешивать их с коммитами `SHiNE-product`. - Основной язык документации и пояснений — русский. - Не удалять FFat при обновлении прошивки. Не использовать `Erase All Flash`, если нужно сохранить локальные журналы. - Если при старте появляется `STORAGE ERROR`, нажимать `FORMAT FFat` только после проверки/резервирования локальных журналов; без подтверждения прошивка форматирование не выполняет. - Перед прошивкой убедиться, что выбрана схема `app3M_fat9M_16MB`. - Не менять формат записей журналов и API без отдельного согласования: сервер проверяет 32-байтные записи, CRC32 и префиксную целостность загрузок. - Не хранить пароли, токены, SQLite-базу и реальные серверные секреты в git. ## Прошивка Плата и библиотеки такие же, как у `breathmonitor_v2 lvgl`. `firmware/burn.sh` использует библиотеки из: `SHiNE-product/ESP32/esp32/ESP32-S3-Touch-AMOLED-2.16/official-demo/examples/Arduino-v3.3.5/libraries` Сборка без загрузки: ```bash cd "SKETCH/breath_button_monitor/breathmonitor_v3 with server/firmware" NO_UPLOAD=1 ./burn.sh ``` Загрузка на подключённую плату: ```bash PORT=/dev/ttyACM0 ./burn.sh ``` Скрипт использует ESP32 core 3.3.5, FQBN с 16 MB Flash, PSRAM OPI и разделом `app3M_fat9M_16MB`. Перед загрузкой проверить порт командой `arduino-cli board list`. ## Серверная сборка Сервер всегда собирается локально. VPS не должен запускать Maven, Gradle или компилятор. ```bash cd "SKETCH/breath_button_monitor/breathmonitor_v3 with server/server" ./gradlew --no-daemon clean shadowJar ``` Требуется JDK 17. Результат: `server/build/libs/breathmonitor-1.0.0.jar` Проверить локально запуск и health можно так: ```bash BREATH_DATA_DIR="$PWD/.local-data" \ BREATH_WEB_DIR="$PWD/web" \ PUBLIC_ORIGIN="https://breathmonitor.shineup.me" \ java -jar build/libs/breathmonitor-1.0.0.jar ``` Для VPS передаётся только готовый JAR и при необходимости статические файлы `web/`. Не выполнять на VPS `build.sh`, `gradlew`, `mvn` или компиляцию. ## Деплой сервера Целевой адрес: `breathmonitor.shineup.me`, VPS: `178.208.90.249`. SSH-пользователь текущего тестового контура — `player`. Постоянные пути на VPS: - приложение: `/opt/breathmonitor/server` - JAR: `/opt/breathmonitor/server/build/libs/breathmonitor-1.0.0.jar` - данные SQLite и журналы: `/var/lib/breathmonitor` - systemd unit: `/etc/systemd/system/breathmonitor.service` - Caddy: `/etc/caddy/Caddyfile` - внутренний HTTP-порт: `127.0.0.1:8090` Безопасный порядок обновления: 1. Локально собрать и проверить JAR. 2. Передать только JAR во временный файл на VPS через `rsync`. 3. Сделать копию текущего JAR и проверить права. 4. Атомарно заменить JAR, не удаляя `/var/lib/breathmonitor`. 5. Перезапустить только `breathmonitor.service`. 6. Проверить `systemctl status breathmonitor` и `curl https://breathmonitor.shineup.me/api/health`. 7. Caddy не перезапускать при обычном обновлении JAR. Перезагрузка Caddy нужна только при изменении его конфигурации. Пример передачи готового артефакта: ```bash rsync -az server/build/libs/breathmonitor-1.0.0.jar \ player@178.208.90.249:/tmp/breathmonitor-1.0.0.jar ``` Дальнейшая замена требует SSH/sudo-доступа и выполняется отдельно от сборки. При недоступном VPS не повторять сборку удалённо и не трогать существующие сервисы. ## Первый запуск и аккаунт Сервис запускается от системного пользователя `breathmonitor` и использует `BREATH_DATA_DIR=/var/lib/breathmonitor`. Создание аккаунта выполняется один раз на VPS с тем же каталогом данных: ```bash sudo -u breathmonitor env BREATH_DATA_DIR=/var/lib/breathmonitor \ /opt/breathmonitor/server/start.sh create-user aidar ``` Текущая версия допускает пароль длиной от 1 до 63 символов. Короткие пароли допустимы только для закрытого тестового контура; для публичного использования нужен длинный пароль. ## Проверки после обновления ```bash curl -fsS https://breathmonitor.shineup.me/api/health sudo systemctl is-active breathmonitor sudo journalctl -u breathmonitor -n 70 --no-pager ``` После прошивки на приборе проверить Wi-Fi, синхронизацию времени, `ONLINE → ACCOUNT`, `PAIR`, затем `UPLOAD`. Журналы на устройстве не удалять при диагностике; использовать USB-команды `LOG INFO`, `LOG LIST` и `LOG DOWNLOAD <дата>`. ## Резервирование Резервировать нужно SQLite-базу с учётом WAL и каталог журналов: - `/var/lib/breathmonitor/statistics.db` - `/var/lib/breathmonitor/statistics.db-wal` - `/var/lib/breathmonitor/statistics.db-shm` - `/var/lib/breathmonitor/logs/` Не заменять каталог данных при обновлении приложения и не выполнять `rsync --delete` по `/var/lib/breathmonitor`.