Files
QuoteForge/bible-local/decisions/2026-09-24-configuration-feature-flags.md
T
Mikhail ChusavitinandClaude Opus 5.5 4e3b43dbd0 feat: фича-флаги конфигурации — клиент не сохраняет то, чего не понимает
Конфигурация хранит 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>
2026-09-24 12:10:58 +03:00

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 migration 034) and local_configurations.feature_flags (AutoMigrate) record which data features a configuration uses. Synced like any other column; carried in version snapshots.
  • internal/configfeatures is 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, UpdateServerCount first Check the flags as stored and refuse with *configfeatures.UnsupportedError if any is unknown, then set FeatureFlags = 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 touches line_no and writes the row back with its flags and notes intact.
  • Every HTTP handler reports errors via handlers.RespondError, which turns an UnsupportedError into 409 {"code":"unsupported_config_features","unsupported_features":[...],"error":"..."} regardless of the status the caller picked.
  • Reads expose unsupported_features (computed in LocalToConfiguration). 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 034 runs, the server write retries without feature_flags (withOptionalColumns in internal/repository/configuration.go, same fallback as line_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.known and to Detect in 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_flags and can still erase newer data — rollout must get every user onto a version with this check.
  • Order of rollout: apply server migration 034 before (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).