90 lines
5.8 KiB
Markdown
90 lines
5.8 KiB
Markdown
# SettingsBackup
|
||
|
||
`SettingsBackup` сохраняет только подтверждённые конфигурации в JSON на
|
||
SD-карту. Ядро `Src/settings_backup.c` не включает STM32 HAL, FatFs, Modbus,
|
||
RTC или `AppStorage`: календарь и нормализованный снимок передаёт приложение,
|
||
а файловые операции задаются callbacks структуры `SettingsBackupPort`.
|
||
|
||
## Размещение
|
||
|
||
При достоверном RTC используется путь:
|
||
|
||
```text
|
||
niceOne/settings/YYYY-MM_EnglishMonth/settings_YYYY-MM-DD_HH-MM-SS.json
|
||
```
|
||
|
||
Например:
|
||
|
||
```text
|
||
niceOne/settings/2026-07_July/settings_2026-07-17_14-30-05.json
|
||
```
|
||
|
||
Названия месяцев фиксированы на английском и состоят только из FAT-безопасных
|
||
ASCII-символов. При недостоверном RTC файл помещается в `invalid_rtc` и получает
|
||
имя `settings_invalid_rtc_rev_N.json`; это имя не выдаётся за календарную дату.
|
||
Коллизии разрешаются суффиксами `_1`, `_2` и далее. Проверяются одновременно
|
||
итоговое имя и `.tmp`, поэтому незавершённая транзакция после перезапуска не
|
||
перезаписывается.
|
||
|
||
## Schema v1
|
||
|
||
Корневые поля: `schema`, `schema_version`, `snapshot_revision`,
|
||
`snapshot_crc32`, `rtc`, `storage`, `units`, `rooms`, `sensors` и
|
||
`restore_policy`. Все 32 комнаты содержат уставку и гистерезис в десятых долях
|
||
градуса, старт калибровки и время полного открытия в 100 мс, целевое и
|
||
подтверждённое положение в процентах. Датчик содержит полный 16-символьный HEX
|
||
ROM: family, шесть serial-байтов и Dallas CRC, а также номер комнаты.
|
||
|
||
В `RoomSettings` v1 во Flash фиксируется достигнутый безопасный checkpoint.
|
||
Поэтому `target_position_pct` резервной копии равен
|
||
`confirmed_position_pct`; ещё не подтверждённая цель Modbus/GUI принципиально
|
||
не попадает в файл.
|
||
|
||
## Когда создаётся копия
|
||
|
||
`settings_backup_app.c` сравнивает номер committed-записи. Только при его
|
||
изменении он физически перечитывает 512 байт через
|
||
`AppStorage_GetConfirmedSnapshot`, где кольцевой журнал повторно проверяет
|
||
version, длину, commit marker и CRC. На старте та же ревизия ищется во всех
|
||
месячных каталогах по content CRC; revision остаётся в файле для аудита, но
|
||
повторный commit тех же настроек не создаёт дубль. Десятиминутный температурный
|
||
журнал не является trigger backup.
|
||
|
||
Запись атомарна: уникальный `.tmp` создаётся с `FA_CREATE_NEW`, полностью
|
||
записывается, синхронизируется, закрывается и только затем переименовывается в
|
||
`.json`. Старые JSON не удаляются при ошибке open/write/sync/close/rename.
|
||
Ошибки absent/full/removal переводят автомат в диагностическое состояние и
|
||
назначают ограниченный retry без задержек и busy wait в main loop.
|
||
|
||
Retention задаётся `SETTINGS_BACKUP_MAXIMUM_COPIES` (по умолчанию 24). При
|
||
превышении лимита сначала удаляется самый старый подтверждённый duplicate hash,
|
||
затем самый старый уникальный файл; последняя корректная копия не удаляется.
|
||
|
||
## Восстановление
|
||
|
||
Автоматического восстановления нет. Наличие JSON никогда не вызывает запись в
|
||
`AppStorage`. Будущая отдельная команда должна прочитать выбранный файл только
|
||
для проверки, подтвердить schema/version, UTF-8/JSON, диапазоны 32 комнат,
|
||
полные ROM и Dallas CRC, content CRC, совместимость backend и получить явное
|
||
подтверждение оператора. Лишь после этого отдельная реализация может собрать
|
||
новый AppStorage image и выполнить обычный committed write с обратным чтением.
|
||
|
||
## Перенос на другую платформу
|
||
|
||
Скопируйте `Inc`, `Src` и конфигурацию. Реализуйте callbacks mount, global
|
||
dedupe scan, collision-safe path resolve, atomic write и retention. Каждая
|
||
callback-функция должна иметь ограниченный timeout и не выполняться из ISR.
|
||
FatFs-порт данного проекта находится в `Port/FatFs`; это единственный модуль
|
||
библиотеки, который включает `ff.h` и использует общий том SD logger.
|
||
|
||
Модельные тесты запускаются так:
|
||
|
||
```text
|
||
python -m unittest discover -s Libraries/SettingsBackup/Tests -p "test_*.py"
|
||
```
|
||
|
||
|
||
## Shared source
|
||
|
||
Canonical source: `templates/c/settings-backup`. Used by `home/climate`; its old paths are compatibility includes. Board-specific ports remain in the application. Change this library, not the forwarding files.
|