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

254 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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`).
### 5.2 `customize-app/popular-items.tsx` + `all-items-order.tsx`
- 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
0. Append planned diffs + timestamp to `change-log.txt` first.
1. 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).
2. After migration 0009: verify the three tables populated, `key_val_store` keeps the 8 leftovers,
exactly one `allItemsOrder` per region.
3. 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`).
4. 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.