Зафиксировать рабочий BreathMonitor v1 и сервер

This commit is contained in:
AidarKC
2026-10-25 14:14:27 +03:00
parent 370f4ae94e
commit d5a37d3009
43 changed files with 2490 additions and 1522 deletions
@@ -0,0 +1,130 @@
# 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`.