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>
This commit is contained in:
1 parent
6b9652e3ac
commit
4e3b43dbd0
18 files changed
+579
-20
No files matched your search
@@ -0,0 +1,58 @@
|
||||
# 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](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).
|
||||
Reference in new issue
Block a user