Конфигурация хранит feature_flags (JSON-массив, NULL = нет) — какие данные она использует. Флаги выводятся из содержимого при каждом сохранении (internal/configfeatures). Если у конфигурации есть флаг, неизвестный этой версии, клиент отказывается её изменять: все write-пути отдают 409 unsupported_config_features со списком флагов, конфигуратор показывает баннер «обновите приложение» и блокирует сохранение. Push на сервер тоже отказывается, если серверная версия несёт неизвестный флаг; такое изменение остаётся в очереди до обновления. Первый флаг: sale_row_markups. Серверная миграция 034 добавляет колонку; до её применения запись идёт без колонки (с warning). Формат имён и реестр флагов — bible-local/02-architecture.md, ADL 2026-09-24. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.8 KiB
3.8 KiB
Decision: per-configuration feature flags — clients refuse to write what they don't understand
Date: 2026-09-24 Status: active
Context
Configurations are synced last-write-wins, and every client rebuilds a configuration's
content from what it knows before saving. When a newer client adds data (e.g. the
per-row "Накидка" in Notes.pricing_ui.sale_row_markups, see
2026-09-15-sale-row-markup-and-minimal-csv.md),
an older client that opens and saves the same configuration silently drops it; the drop
is pushed to the server and the next pull spreads it to every other client. This
happened in the field (a markup pushed on 2026-09-22 came back null on the 09-23 pull).
A global minimum-app-version gate was considered and rejected: it would block all sync
for an outdated client, even for configurations that use no new feature.
Decision
qt_configurations.feature_flags(JSON array of strings, NULL = none; server migration034) andlocal_configurations.feature_flags(AutoMigrate) record which data features a configuration uses. Synced like any other column; carried in version snapshots.internal/configfeaturesis the single source of truth:known(flags this build understands),Detect(notes)(derive flags from content),Unknown,Check,UnsupportedError. Current flags:sale_row_markups(at least one non-zero row markup).- Flags are derived on every local write, never sent by the UI:
saveWithVersionAndPending,createWithVersionTx,rollbackToVersion,UpdateServerCountfirstCheckthe flags as stored and refuse with*configfeatures.UnsupportedErrorif any is unknown, then setFeatureFlags = Detect(notes). This covers update, rename, move, refresh prices, vendor-spec, rental, server count, deactivate/reactivate, rollback (current and target snapshot) and clone (the clone inherits the original's flags). Project line reorder is exempt: it only touchesline_noand writes the row back with its flags and notes intact. - Every HTTP handler reports errors via
handlers.RespondError, which turns anUnsupportedErrorinto409{"code":"unsupported_config_features","unsupported_features":[...],"error":"..."}regardless of the status the caller picked. - Reads expose
unsupported_features(computed inLocalToConfiguration). The configurator shows a red banner listing them, disables "Сохранить", skips the exit-save, and also locks itself when a save comes back with the 409. - Sync push (
pushConfigurationUpdate) reads the server row first and refuses if its flags are unknown — a newer client may have written it after our last pull. Such a refused change is kept in the queue (it is exempt from the max-attempts abandon) so the local edit is pushed once the app is updated. - Until migration
034runs, the server write retries withoutfeature_flags(withOptionalColumnsininternal/repository/configuration.go, same fallback asline_no) and logs a warning — sync keeps working, but flags are not stored on the server.
Consequences
- Rule: any new data feature that an older client would lose on save must add a
flag to
configfeatures.knownand toDetectin the same change. Features that old clients round-trip safely (e.g. data they carry verbatim) need no flag. - Flags only protect against clients that already contain this check. Clients older
than this change ignore
feature_flagsand can still erase newer data — rollout must get every user onto a version with this check. - Order of rollout: apply server migration
034before (or together with) releasing the client; otherwise flags silently stay local. - The UI shows raw flag ids (an old client, by definition, has no human names for them).