Зафиксировать рабочий 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,186 @@
# BreathMonitor — автономный прибор + Java/SQLite сервер
**Комплект для развёртывания** · 24 октября 2026 года
Адрес API и сайта уже задан: **https://breathmonitor.shineup.me**
Это исходники готовой первой интеграционной версии, а не подтверждённая сборка для конкретной платы: Java-код и парсер рассчитаны на JDK 17, но `.ino` требуется собрать в Arduino IDE с исходными библиотеками и проверить на физическом ESP32-S3. Интернет в среде сборки отсутствовал, поэтому готовый исполняемый JAR с SQLite JDBC не вложен: `server/build.sh` соберёт его Gradle, скачав зависимости из Maven Central.
## Содержимое
```text
firmware/breathmonitor_lvgl.ino — изменённый скетч (исходный UI, измерения, RTC)
firmware/ISRG_Root_X1_reference.pem — копия публичного корневого сертификата (он уже встроен в .ino)
server/BreathServer.java — один Java-класс: API, SQLite, HTTPS через Caddy, веб-сайт
server/RecordFixtureTest.java — тест бинарного формата/CRC32 без JDBC
server/build.gradle — зависимости SQLite JDBC, SLF4J и сборка jar
server/build.sh — Gradle package
server/start.sh — запуск и админ-команды
server/web/ — независимая HTML/CSS/JavaScript статистика
deploy/Caddyfile.fragment — пример секции для Caddy
deploy/breathmonitor.service — пример службы systemd
```
## 1. Изменения прибора
- **Без постоянного Wi-Fi.** После загрузки радиомодуль выключен. Операция `TIME → SYNC NOW` подключает известную сеть, синхронизирует NTP+RTC, выключает Wi-Fi. `ONLINE → UPLOAD` делает то же самое для передачи журналов. `Wi-Fi → TEST` проверяет доступность сети и отключает модуль.
- До восьми сохранённых SSID и паролей перенесены из старой прошивки без изменения ключей `manual-wifi`.
- Если известные Wi-Fi недоступны, открывается список сетей; после выбора/ввода пароля ранее запрошенная операция продолжается автоматически.
- **Журнал по дням:** `/logs/20261024.bin` и т. п., записи по 32 байта, версия 1 + CRC32. Запись только в конец, существующие дневные файлы продолжаются после перезагрузки. `/logs/undated.bin` — события при недостоверном времени.
- `/events.bin` из исходной прошивки **не удаляется**. При первом запуске записи переносятся в дневные файлы, успешный перенос фиксируется `/migration.done`. При аварийном выключении перенос пробуется снова; старый исходный файл остаётся. Неверные CRC в старом файле пропускаются, но остаются в оригинале для диагностики.
- Автоформатирование FFat отключено (`FFat.begin(false)`). Если FFat не монтируется, прибор показывает на экране подтверждение `FORMAT FFat`; форматирование выполняется только после явного нажатия и удаляет локальные журналы.
- `ONLINE → ACCOUNT`: ввести логин и пароль учётной записи сайта, затем `PAIR` или сразу `UPLOAD`. Введённый пароль живёт в RAM до авторизации; хранится отдельный токен устройства в Preferences. После перезагрузки пароль не нужен.
- `ONLINE → REUPLOAD` очищает **только индекс отправленных размеров** `/sync.state`, не сами журналы. При следующем `UPLOAD` прибор повторно отправит все дневные файлы (сервер не дублирует циклы).
- Передача HTTPS в отдельной FreeRTOS-задаче; измерения и обновление LVGL продолжаются в основном цикле. Отправляется зафиксированный на момент начала передачи размер файла: новые записи попадут в следующую синхронизацию.
- Публичный ключ SSL не выключен: прошивка доверяет **ISRG Root X1**. Caddy должен получить совместимый сертификат Let's Encrypt. При смене удостоверяющего центра нужно обновить доверенный сертификат в прошивке.
**USB CDC:** доступны `LOG INFO`, `LOG LIST`, `LOG DOWNLOAD 20261024`, `LOG DOWNLOAD undated`, `LOG DOWNLOAD LEGACY`. `LOG DOWNLOAD` без указания даты больше не поддерживается. Бинарные данные передаются HEX-строками между `LOG BEGIN ...` и `LOG END`.
**Важно при прошивке:** используйте тот же раздел/Partition Scheme, который содержал исходный FFat, и не выбирайте `Erase All Flash`. Перепрошивка с изменением разметки может стереть старые журналы. До прошивки сделайте резервную копию `/events.bin` через исходную команду `LOG DOWNLOAD`.
## 2. Установка Java + SQLite (Ubuntu)
На сервере с Caddy и доступом в интернет:
```bash
sudo apt update
sudo apt install -y openjdk-17-jdk gradle
# Скопируйте папку server в /opt/breathmonitor/server
cd /opt/breathmonitor/server
chmod +x build.sh start.sh
./build.sh
```
Сборка создаёт `target/breathmonitor-1.0.0.jar`. Это самодостаточный shaded JAR, включающий SQLite JDBC и SLF4J. Другой процесс базы данных не нужен.
Для первого запуска от текущего пользователя:
```bash
cd /opt/breathmonitor/server
./start.sh create-user aidar
# Введите пароль длиной 1–63 символа
./start.sh create-user anna
./start.sh
```
Админ-команда сброса пароля:
```bash
./start.sh reset-password aidar
```
**Сброс пароля отзывает все веб-сессии и токены привязанных устройств**; пароль и привязку придётся ввести заново.
По умолчанию:
- Java-сервер слушает **только** `127.0.0.1:8090`, так что он не доступен напрямую из интернета.
- База данных находится в `server/data/statistics.db`, журналы в `server/data/logs/<login>/<device-id>/<login>_YYYYMMDD.bin`.
- Файлы фронтенда читаются из `server/web`.
- Значения настраиваются переменными `BREATH_PORT`, `BREATH_BIND`, `BREATH_DATA_DIR`, `BREATH_WEB_DIR`, `PUBLIC_ORIGIN`.
### Служба systemd
Для постоянного запуска рекомендуется отдельный системный пользователь и каталог данных:
```bash
sudo useradd --system --user-group --no-create-home --shell /usr/sbin/nologin breathmonitor || true
sudo mkdir -p /var/lib/breathmonitor
sudo chown -R breathmonitor:breathmonitor /var/lib/breathmonitor
sudo chown -R root:root /opt/breathmonitor/server
sudo cp /opt/breathmonitor/deploy/breathmonitor.service /etc/systemd/system/
sudo systemctl daemon-reload
# Сначала создайте пользователей, используя то же BREATH_DATA_DIR и от имени breathmonitor:
sudo -u breathmonitor env BREATH_DATA_DIR=/var/lib/breathmonitor bash -c 'cd /opt/breathmonitor/server && ./start.sh create-user aidar'
sudo systemctl enable --now breathmonitor
sudo journalctl -u breathmonitor -n 70 --no-pager
```
Не создавайте сначала пользователей в `server/data/`, а потом не переключайтесь на `/var/lib/breathmonitor`: это **разные** базы данных. При необходимости перенесите каталог данных до запуска службы.
## 3. Caddy / HTTPS / DNS
Настройте DNS-запись `A` (и при необходимости `AAAA`) для `breathmonitor.shineup.me` на адрес вашего сервера. В вашем существующем Caddyfile добавьте блок из `deploy/Caddyfile.fragment`, не перезаписывая остальные сайты. Прибор всегда использует `https://breathmonitor.shineup.me` — адрес уже в `.ino`.
```bash
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -i https://breathmonitor.shineup.me/api/health
```
Ответ должен быть HTTP 200 и `{"ok":true}`. Затем откройте сайт в браузере, войдите под созданным логином и паролем.
Текущая версия Caddy сама использует стандартный Let's Encrypt. Это важно, поскольку `ROOT_CA` прошивки содержит только ISRG Root X1; другой TLS-издатель может не пройти проверку. Если у вас уже есть отдельный wildcard-сертификат, сначала проверьте его цепочку доверия и при необходимости обновите `ROOT_CA`.
## 4. Первое подключение прибора
1. Установить обновлённую прошивку без стирания FFat/Preferences.
2. `SETTINGS → Wi-Fi → SCAN`: выбрать свою сеть, ввести пароль, дождаться успешной проверки. Сеть сохранится.
3. `SETTINGS → TIME → SYNC NOW`: получить точное время и выключить Wi-Fi. После NTP аппаратные часы продолжают работать автономно.
4. `SETTINGS → ONLINE → ACCOUNT → LOGIN`: ввести **тот же** логин, что создали командой `create-user`.
5. `PASSWORD`: ввести пароль аккаунта; `PAIR` — одноразово получить токен (или просто `ONLINE → UPLOAD`, и привязка выполнится при первой выгрузке).
6. Сделать несколько циклов дыхания и нажать `ONLINE → UPLOAD`. Увидеть сообщение `Done: ... uploaded`. Через браузер обновить страницу статистики.
7. Последующие загрузки выполняются одним нажатием `UPLOAD`; пароль повторно не вводится.
На приборах с заводским/сброшенным RTC перед защищённой отправкой автоматически выполняется NTP. Если отсутствует интернет/NTP, файлы продолжают сохраняться локально; при неудачной синхронизации не удаляются.
## 5. Формат API (для отладки)
| Метод и путь | Назначение | Авторизация |
|---|---|---|
| `GET /api/health` | проверка сервера | нет |
| `POST /api/device/login` | `login\npassword\nDEVICEID` → 64 шестнадцатеричных символа токена | пароль пользователя |
| `PUT /api/device/upload?date=20261024` | сырое тело `.bin`, заголовки `Authorization: Bearer TOKEN` и `X-Device-ID: <12 hex>` | токен устройства |
| `POST /api/login` | логин в браузере | пароль пользователя; cookie с Secure/HttpOnly |
| `GET /api/me` | профиль | cookie |
| `GET /api/stats` | личная статистика | cookie |
| `GET /api/leaderboard` | открытый рейтинг только согласившихся | нет |
| `POST /api/privacy` | тело `true` или `false`, включение публичного рейтинга | cookie + проверка Origin |
| `POST /api/logout` | выход | cookie + проверка Origin |
Сервер проверяет каждую 32-байтную запись и CRC32. Если файл уже существует, новая версия обязана **полностью содержать старый файл как начальный префикс**. Повторная отправка идентичной версии не добавляет циклы; изменение/уменьшение журнала отклоняется с HTTP 409. После проверки файл атомарно заменяется, а суточная статистика пересчитывается и записывается в SQLite через UPSERT. Для разных устройств одного пользователя файлы лежат в отдельных папках.
## 6. Конфиденциальность, администрирование, резервные копии
- По умолчанию **все аккаунты приватные**; другие люди не видят их результаты. Пользователь может включить публичный рейтинг в личном кабинете. В рейтинг попадают только агрегированные показатели, не подробные записи.
- Password storage: PBKDF2-HMAC-SHA256 с солью и 210 тыс. итераций. Веб-сессии и токены устройств в БД хранятся как SHA-256-хеши. Базовые ограничения на перебор логина — до 12 попыток с IP за минуту (для публичного большого проекта позже нужен усиленный anti-abuse перед Caddy).
- Важно делать резервные копии **и `statistics.db` (с учётом SQLite WAL), и `data/logs/`**. При работающем сервере лучше снимать транзакционный SQLite backup, а не просто копировать открытый файл базы без `-wal`.
- Долговременное сохранение FFat зависит от носителя и состояния питания. Базовую защиту обеспечивают append-only журналы, контроль CRC и серверные копии; для критичных данных нужен дополнительный журнал транзакций/резервирование.
- Сайт не утверждает, что измеряет здоровье или качество медитации. Он показывает только события, зафиксированные прибором.
## 7. Известные ограничения первой версии
1. `.ino` пока не прошёл аппаратную компиляцию, прошивку и испытания на вашей конкретной плате. Исходный LVGL UI, сенсор, IMU и аудио сохранены, но реальный тест кнопок, Wi-Fi и FFat обязателен.
2. Серверный Java-класс синтаксически компилируется; двоичный тест CRC и декодирования цикла пройден. Полный тест запуска SQLite/JDBC требует загрузки зависимостей Gradle из Maven Central.
3. Для простоты передаётся **целиком изменившийся суточный файл** (а не только его добавленный хвост); при типичном размере десятки КБ это нормально. Загрузка ограничена 16 МиБ на файл.
4. Если текущий дневной файл физически повреждён или содержит неполную запись, отправка этого файла отклоняется; прибор не удаляет файл автоматически. Нужна ручная диагностика через `LOG LIST`/USB.
5. При недостоверных часах события попадают в `undated.bin`. Автоматически приписывать им выдуманную дату нельзя: их можно учесть в общей сумме, но не привязать надёжно к календарному дню без дополнительной информации.
6. Суточная дата задаётся **фиксированным** UTC-смещением в настройках прибора (автоматический переход на летнее/зимнее время пока не предусмотрен).
7. Изменение времени/смещения суток не переименовывает уже записанные файлы. В случае некорректного времени возможен дневной файл с неправильной датой; хранящиеся в каждой записи UTC и флаг доверия дают возможность дальнейшей коррекции.
8. Устройства на одном аккаунте считаются вместе. Разные физические устройства должны иметь разные ID ESP32. В **первой версии прибор рассчитан на одного владельца**: после успешной привязки вход в другой аккаунт с того же прибора заблокирован, чтобы не загрузить личную историю прежнего владельца в чужой аккаунт. Для передачи устройства другому человеку нужно сначала экспортировать/архивировать журналы и безопасно сбросить локальное хранилище и Preferences (реализация безопасного сброса — отдельная задача).
9. Регистрация пользователей выполняется администратором через CLI; самостоятельная регистрация на сайте не реализована.
10. В `ONLINE → REUPLOAD` удаляется только локальный индекс выгрузок. Если сервер получил отличающуюся старую историю, он вернёт HTTP 409: безопаснее исследовать конфликт, чем автоматически переписать старые данные.
## 8. Проверки до ежедневного использования
- Питание OFF/ON посреди дня → количество 32-байтных записей в текущем файле увеличивается, записи не исчезают.
- Переход через полночь по настроенному времени → создаётся новый датированный файл.
- Сохранённая Wi-Fi сеть недоступна → устройство предлагает список сетей и затем продолжает именно TIME/UPLOAD.
- Отключение интернет-кабеля во время отправки → файл на приборе остаётся, повторная синхронизация работает.
- Повторный `UPLOAD` без новых циклов → нет дублей статистики.
- Появление новых циклов во время отправки → в следующей синхронизации сервер получает расширенный файл.
- Сброс часов RTC → новые события идут в `undated.bin` до синхронизации.
- Новый пользователь/новый токен → доступ только к своим файлам, публичный рейтинг по умолчанию пустой.
- Перед прошивкой заранее выгрузить старый `/events.bin` по USB и сравнить запись после миграции.
### Локальный тест Java без JDBC
```bash
cd server
javac --release 21 BreathServer.java RecordFixtureTest.java
java RecordFixtureTest
```
Ожидаемый ответ: `PASS: 32-byte little-endian event, duration and CRC32 validation`.
---
**После первого запуска** я рекомендую следующий этап: сделать диагностический экран «свободно FFat / не выгружено / ошибка последней передачи» и веб-функцию загрузки журнала вручную с компьютера. Это облегчит восстановление и сопровождение приборов, когда пользователей станет больше.