freshyo/docs/consts-three-tables-part1-backend-admin.md
2026-10-08 19:48:14 +05:30

16 KiB
Raw Blame History

Plan — Part 1/2: Backend + Admin UIs (three-table consts model)

Part 1 of 2. Covers the DB model, KV, migration, backend, and the admin UIs (apps/admin-ui, apps/admin-web, apps/superadmin-ui). Part 2 covers apps/user-ui (see consts-three-tables-part2-user-ui.md). Supersedes three-table-consts-model.md.

0. Decisions

  • Scope Part 1: backend + admin-ui + admin-web + superadmin-ui.
  • allItemsOrder is region-scoped (one row per region in region_consts), grouped with popularItems.
  • Leftover keys stay in key_val_store: platformFeePercent, taxRate, tester, minOrderAmountForCoupon, maxCouponDiscount, flashDeliverySlotId, readableOrderId, tagsOrder.
  • region_cache_versions + region_bound_settings are dropped after data copy.
  • Precomputed flat JSON per bound in the KV gen namespace (§2) — consumed by user-ui (Part 2).
  • AGENTS.md: do NOT run migrations (user runs), do NOT run the test suite, do NOT use git. Append planned diffs + timestamp to change-log.txt before editing non-.md/.txt files.

1. Data model

New tables (packages/db_helper_sqlite/src/db/schema.ts):

global_consts        (key TEXT PRIMARY KEY, value TEXT)
region_consts        (region_id INTEGER FK->regions.id, key TEXT, value TEXT, PK(region_id,key))
region_bound_consts  (bound_id INTEGER FK->region_bounds.id, region_id INTEGER FK->regions.id,
                      key TEXT, value TEXT, PK(bound_id,key))
Table Keys
global_consts versionNum, playStoreUrl, appStoreUrl, internalAppVersion
region_consts products_version_num (was cache_version), availability_version_num, slots_version_num, popularItems, allItemsOrder, isFlashDeliveryEnabled, supportMobile, supportEmail, welcomeMessage
region_bound_consts minRegularOrderValue, freeDeliveryThreshold, deliveryCharge, flashFreeDeliveryThreshold, flashDeliveryCharge
key_val_store (kept) platformFeePercent, taxRate, tester, minOrderAmountForCoupon, maxCouponDiscount, flashDeliverySlotId, readableOrderId, tagsOrder
  • Region-level keys are one row per region (no bound precedence). Bound-level keys stay per bound.
  • Version counters (products_version_num/availability_version_num/slots_version_num) live in region_consts, auto-created default 1.
  • allItemsOrder: exactly one row per region; identical for every bound in that region.

2. KV model

  • Key essentialConsts_{boundId} in freshyo_gen/freshyo_gen_dev. Flat value = { ...global, ...region, ...bound, assetsDomain, apiCacheKey, regionId, boundId, webviewHtml, isWebviewClosable }.
  • Numbers/booleans coerced (Number() / boolean) at build time; other values raw strings.

3. Migration (author only — user runs)

packages/db_helper_sqlite/drizzle/0009_three_const_tables.sql + journal idx 9 (0009_three_const_tables). Steps: CREATE the 3 tables; copy global_consts (4 keys) from key_val_store; copy region_consts version counters from region_cache_versions and region business keys (incl. allItemsOrder) from each region's lowest-priority bound's region_bound_settings; copy the 5 bound keys into region_bound_consts; DELETE the migrated keys from key_val_store (keep the 8 leftovers); DROP region_bound_settings + region_cache_versions. (full SQL is in docs/consts-three-tables-changes.md §2.2 — reuse it verbatim.)

4. Backend

4.1 packages/db_helper_sqlite

  • src/db/schema.ts: add globalConsts, regionConsts, regionBoundConsts; remove regionCacheVersions + regionBoundSettings and their relations.
  • src/lib/const-keys.ts: add GLOBAL_CONST_KEYS, REGION_CONST_KEYS, BOUND_CONST_KEYS, LEGACY_CONST_KEYS; keep merged CONST_KEYS + labels/types/visibility/defaults; add products_version_num; add CONST_SCOPE (global|region|bound|legacy).
  • src/admin-apis/const.ts:
    • add getAllGlobalConsts(), upsertGlobalConsts(rows), getRegionConsts(regionId), upsertRegionConsts(regionId, rows), getBoundConsts(boundId), upsertBoundConsts(boundId, regionId, rows), getLegacyConsts(), upsertLegacyConsts(rows).
    • keep getAllConstants/upsertConstants working: getAllConstants() = merged global+legacy (+ CONST_DEFAULTS); upsertConstants(rows, regionId?) routes by CONST_SCOPE.
    • remove the dead global counters (get/incrementCacheVersion, availability, slots).
  • src/lib/region-cache-versions.ts: back it with region_consts (products_version_num/availability_version_num/slots_version_num), auto-create rows; public signatures/return type unchanged (cloud_cache.ts untouched).
  • src/superadmin-apis/regions.ts:
    • getBoundSettings(boundId) → region_bound_consts only (5 keys), Record<string,string|null>.
    • upsertBoundSettings(boundId, settings) → region_bound_consts (look up regionId from bound).
    • add getRegionConstants(regionId) / upsertRegionConstants(regionId, rows).
    • getEffectiveRegionSettings(regionId) → merged region + effective bound (shape unchanged).
    • add getEffectiveBoundId(regionId); getAllRegions() → add effectiveBoundId.
    • createRegionWithBounds/createRegionBound → seed default rows + version counters (1/1/1).
  • src/db/seed.ts + src/db/seed.sql: seed the 3 tables (incl. per-region allItemsOrder); leftovers keep going to key_val_store.
  • index.ts: export the new helpers; drop removed ones.

4.2 packages/shared

  • types/region.types.ts: RegionSummary.effectiveBoundId?: number | null.
  • types/const.types.ts: unchanged (Constant, ConstantUpdateResult); optional add GlobalConstKey/RegionConstKey/BoundConstKey union types if useful to the UIs.

4.3 apps/backend core

  • src/lib/const-keys.ts: mirror the four key groups (allItemsOrder in REGION_CONST_KEYS).
  • src/lib/const-store.ts: getGlobalConstValues(), getRegionConstValues(regionId), getBoundConstValues(boundId); getConstant(key) (tagsOrder) stays on key_val_store.
  • src/lib/gen-store.ts: GEN_KV_KEY='essentialConsts', genKvKeyForBound(boundId), refreshGenKv(boundId?), refreshGenKvForRegion(regionId), readEssentialConstsFromKv(boundId).
  • src/trpc/apis/common-apis/common-trpc-index.ts: scaffoldEssentialConsts(boundId); essentialConsts input { boundId }; listRegions returns effectiveBoundId; regionSettings merged.
  • src/lib/cloud_cache.ts: refreshGenKvForRegion(regionId); essential-consts CDN file uses the effective bound.
  • src/lib/flash-delivery-cron.ts: isFlashDeliveryEnabled now region-level → write region_consts for all regions, then refreshGenKv().
  • src/lib/seed.ts: new db seeds + refreshGenKv().
  • src/sqliteImporter.ts: re-export new helpers.

4.4 tRPC endpoint surface (new / repointed)

Keep old admin.const.getConstants/updateConstants as backward-compat aliases (tests at apps/backend/tests/helpers/consts.ts + any stragglers). Add clean, scoped endpoints:

Endpoint Kind Scope Notes
admin.const.getGlobalConstants / updateGlobalConstants query/mutation staff global_consts (4 keys)
admin.const.getLegacyConstants / updateLegacyConstants query/mutation staff key_val_store leftovers (tagsOrder, coupons, etc.)
admin.const.getConstants / updateConstants query/mutation staff alias: merged global+legacy; update routes by scope
admin.region.getRegionConstants / updateRegionConstants query/mutation staff region region_consts for ctx.staffUser.regionId
admin.region.getBoundSettings / updateBoundSettings query/mutation staff region region_bound_consts (5 keys); add refreshGenKvForRegion after write
superadmin.const.getGlobalConstants / updateGlobalConstants query/mutation superadmin NEW router (fixes the current admin.const guard mismatch)
superadmin.const.getLegacyConstants / updateLegacyConstants query/mutation superadmin leftovers
superadmin.regions.getRegionConstants / updateRegionConstants query/mutation superadmin { regionId } + constants
superadmin.regions.boundSettings / updateBoundSettings query/mutation superadmin repointed to region_bound_consts; refreshGenKvForRegion
  • update* handlers validate keys against their group (GLOBAL_CONST_KEYS / REGION_CONST_KEYS / BOUND_CONST_KEYS / LEGACY_CONST_KEYS) and refresh KV for the affected scope.
  • admin.region.updateRegionConstants and superadmin.regions.updateRegionConstants taking isFlashDeliveryEnabled/etc. must refreshGenKvForRegion(regionId).
  • Version-counter keys (products_version_num, etc.) are not editable via these endpoints (read-only in getRegionConstants, ignored on write).

4.5 apps/backend routers to edit

  • src/trpc/apis/admin-apis/apis/const.ts — new global/legacy procedures + alias.
  • src/trpc/apis/admin-apis/apis/region.ts — getRegionConstants/updateRegionConstants; getBoundSettings/updateBoundSettings → bound table + KV refresh.
  • src/trpc/apis/superadmin-apis/apis/regions.ts — bound settings repoint + region constants + refreshGenKvForRegion.
  • new src/trpc/apis/superadmin-apis/apis/const.ts (superadminConstRouter) + register in superadmin-apis/superadmin-trpc-index.ts.
  • src/trpc/apis/admin-apis/apis/admin-trpc-index.ts — const router still mounted; nothing new needed beyond procedure additions.

5. Admin UI — apps/admin-ui

All key maps are local in app/(drawer)/dashboard/customize-app/index.tsx (CONST_LABELS 11–33, CONST_VISIBILITY 35–58, BOUND_KEY_TYPES 61–75, REGIONAL_KEYS 77, parseBoundValue 80–102, serializeBoundValue 105–120, local ConstantInput 122–261).

5.1 customize-app/index.tsx

  • Replace the 2-way switch (mode: 'bounds' | 'global', line 265) with 3 tabs: Global / Region / Bound.
  • Global tab → admin.const.getGlobalConstants/updateGlobalConstants; rows = the 4 GLOBAL_CONST_KEYS (visibility-controlled) + a "Legacy" subsection for admin.const.getLegacyConstants (only if you want tagsOrder/coupon keys exposed; otherwise omit).
  • Region tab → admin.region.getRegionConstants/updateRegionConstants; rows = REGION_CONST_KEYS minus the 3 version counters (display-only). popularItems / allItemsOrder keep allowSectionNavigation links to their editors (§5.2).
  • Bound tab → keep the existing per-bound tabs + Formik, but REGIONAL_KEYS shrinks to the 5 BOUND_CONST_KEYS (minRegularOrderValue, freeDeliveryThreshold, deliveryCharge, flashFreeDeliveryThreshold, flashDeliveryCharge) via admin.region.getBoundSettings/updateBoundSettings. Remove the 6 region-level keys from BOUND_KEY_TYPES.
  • Rebuild CONST_LABELS/CONST_VISIBILITY/type maps from the key groups (or import a small shared keys module — see §5.5); keep the local ConstantInput (incl. allowSectionNavigation).
  • These are now region-scoped (region_consts): switch reads/writes from admin.const.* to admin.region.getRegionConstants/updateRegionConstants (same { key, value:number[] } payload; keep the array-or-CSV parse). Invalidate region.getRegionConstants.

5.3 product-tags/order.tsx

  • tagsOrder stays a global leftover in key_val_store → switch to admin.const.getLegacyConstants/updateLegacyConstants (payload unchanged; still triggers scheduleStoreInitialization() server-side).

5.4 components/OrderOptionsMenu.tsx

  • welcomeMessage is now in region_consts → read it from admin.region.getRegionConstants instead of admin.const.getConstants.

5.5 (optional) shared keys module

  • Consider extracting the key groups + labels into a small apps/admin-ui/src/constants/const-keys.ts to stop the label/visibility drift; not required.

6. Admin UI — apps/admin-web

Mirror of admin-ui (single file src/routes/dashboard.customize-app.tsx: CONST_LABELS 14–35, CONST_VISIBILITY 37–59, BOUND_KEY_TYPES 64–76, REGIONAL_KEYS 78, local ConstantInput 123–256).

  • dashboard.customize-app.tsx: 3 tabs (Global/Region/Bound) as §5.1; handleBoundSubmit (323–354) writes the 5 bound keys; handleGlobalSubmit (356–383) writes global (+ legacy).
  • dashboard.customize-app.popular.tsx (110–204) and .ordering.tsx (97–183): switch to admin.region.getRegionConstants/updateRegionConstants; invalidate that key.
  • dashboard.product-tags.order.tsx (90–174): switch to admin.const.getLegacyConstants/ updateLegacyConstants.
  • Keep the local ConstantInput + allowSectionNavigation.

7. Admin UI — apps/superadmin-ui

  • src/routes/constants.tsx: currently calls admin.const.* under a superadmin token, which is protectedProcedure → UNAUTHORIZED. Switch to the new superadmin.const.* (getGlobalConstants/updateGlobalConstants + getLegacyConstants/updateLegacyConstants). Split the single form into Global (+ Legacy) sections; drop the region/bound keys from this screen (they move to the Regions page).
  • src/routes/regions.tsx: SETTING_KEYS (18–30) currently mixes region keys + bound keys. Split into:
    • Region constants editor (new RegionConstantsEditor) using superadmin.regions.getRegionConstants/updateRegionConstants({ regionId }) for the region keys (popularItems, allItemsOrder, isFlashDeliveryEnabled, supportMobile, supportEmail, welcomeMessage).
    • Bound constants editor (BoundSettingsEditor, 383–436) uses SETTING_KEYS reduced to the 5 bound keys via superadmin.regions.boundSettings/updateBoundSettings.
  • Keep the EFFECTIVE badge logic (bounds sorted by priority; effective = first).

8. Out of scope (Part 1)

  • apps/user-ui — Part 2.
  • apps/web-ui storefront — still calls common.essentialConsts({ regionId }) and will fail input validation once the input becomes { boundId }. Not migrated here; flagged. (Optional follow-up: accept { regionId } and map via getEffectiveBoundId(regionId).)

9. Verification

  1. Append planned diffs + timestamp to change-log.txt first.
  2. Typecheck: npx tsc --noEmit --project packages/db_helper_sqlite/tsconfig.json, ... apps/backend/tsconfig.json, ... apps/admin-ui/tsconfig.json, ... apps/superadmin-ui/tsconfig.json, ... apps/admin-web/tsconfig.json (admin-web package has its own typecheck script).
  3. After migration 0009: verify the three tables populated, key_val_store keeps the 8 leftovers, exactly one allItemsOrder per region.
  4. Endpoints: admin.const.getGlobalConstants (4 keys), admin.region.getRegionConstants (9 keys, versions read-only), admin.region.getBoundSettings (5 keys); superadmin.const.* works with a superadmin token; writes refresh KV (essentialConsts_{boundId} in freshyo_gen).
  5. Admin smoke: Global/Region/Bound tabs save to the correct tables; popular/all-items edits hit region_consts; tagsOrder edit still triggers cache regeneration.

10. Checklist

  1. change-log.txt — append planned diffs.
  2. packages/db_helper_sqlite: schema, 0009 migration + journal, const-keys, admin-apis/const, region-cache-versions, superadmin-apis/regions, seed, index exports.
  3. packages/shared: region.types.ts (effectiveBoundId).
  4. apps/backend: const-keys, const-store, gen-store, common-trpc-index, cloud_cache, flash-delivery-cron, seed, sqliteImporter, admin const/region routers, superadmin regions router, new superadmin const router.
  5. apps/admin-ui: customize-app (3 tabs), popular-items, all-items-order, product-tags/order, OrderOptionsMenu.
  6. apps/admin-web: customize-app (3 tabs), popular, ordering, product-tags/order.
  7. apps/superadmin-ui: constants.tsx (superadmin.const.*), regions.tsx (region + bound editors).
  8. Typecheck all five projects; fix self-introduced errors.