254 lines
16 KiB
Markdown
254 lines
16 KiB
Markdown
# 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.
|