docs(18-02): complete admin timezone endpoints plan
This commit is contained in:
Lucas Berger
@@ -636,7 +636,7 @@ Plans:
|
||||
**Goal:** Make the household timezone an explicit, stored, user-changeable setting — auto-detected from the browser at first run, changeable from the role-gated /admin Settings — and route the server-side all-day "9 AM local" reminder computation through it (replacing the implicit `process.env.TZ` fallback), without touching the already-correct browser-local display/timed-write path.
|
||||
**Requirements**: TBD (decision contract D-01..D-07 from 18-CONTEXT.md)
|
||||
**Depends on:** Phase 10 (admin role + `/admin` Settings + `app_config`); Phase 11 (all-day reminder computation this rewires). Independent of Phase 17. Phase 12 (setup wizard) not required — seeding is self-contained.
|
||||
**Plans:** 1/4 plans executed
|
||||
**Plans:** 2/4 plans executed
|
||||
|
||||
Plans:
|
||||
**Wave 1**
|
||||
@@ -645,7 +645,7 @@ Plans:
|
||||
|
||||
**Wave 2** *(blocked on Wave 1 completion)*
|
||||
|
||||
- [ ] 18-02-PLAN.md — TDD: admin GET/PUT/seed timezone endpoints on adminRouter, requireAdmin + IANA validation + no-overwrite seed (D-01/D-02/D-03/D-04)
|
||||
- [x] 18-02-PLAN.md — TDD: admin GET/PUT/seed timezone endpoints on adminRouter, requireAdmin + IANA validation + no-overwrite seed (D-01/D-02/D-03/D-04)
|
||||
- [ ] 18-03-PLAN.md — TDD: route all-day reminder TZ at reminderScheduler:247 + outboxWorker:501,607 through the accessor (D-05/D-06/D-07)
|
||||
|
||||
**Wave 3** *(blocked on Wave 2 completion)*
|
||||
|
||||
+5
-4
@@ -4,13 +4,13 @@ milestone: v1.1
|
||||
milestone_name: Operability & Polish
|
||||
status: executing
|
||||
stopped_at: Phase 18 context gathered
|
||||
last_updated: "2026-06-15T02:08:26.245Z"
|
||||
last_updated: "2026-06-15T02:13:43.020Z"
|
||||
last_activity: 2026-06-15
|
||||
progress:
|
||||
total_phases: 23
|
||||
completed_phases: 9
|
||||
total_plans: 36
|
||||
completed_plans: 33
|
||||
completed_plans: 34
|
||||
percent: 39
|
||||
---
|
||||
|
||||
@@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-06-10)
|
||||
## Current Position
|
||||
|
||||
Phase: 18 (auto-timezone-detection-and-ability-to-change-timezone) — EXECUTING
|
||||
Plan: 2 of 4
|
||||
Plan: 3 of 4
|
||||
Status: Ready to execute
|
||||
Last activity: 2026-06-15
|
||||
|
||||
@@ -108,6 +108,7 @@ _Updated after each plan completion_
|
||||
| Phase 10-admin-role-settings P04 | 1315 | 3 tasks | 8 files |
|
||||
| Phase 11-per-event-reminders P11-04 | 60 | 3 tasks | 4 files |
|
||||
| Phase 18-auto-timezone-detection-and-ability-to-change-timezone P01 | 2 | 2 tasks | 2 files |
|
||||
| Phase 18 P02 | 3 | 2 tasks | 2 files |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@@ -253,7 +254,7 @@ Recent decisions affecting current work:
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-06-15T02:08:26.229Z
|
||||
Last session: 2026-06-15T02:13:43.000Z
|
||||
Stopped at: Phase 18 context gathered
|
||||
Resume file: None
|
||||
|
||||
|
||||
+123
@@ -0,0 +1,123 @@
|
||||
---
|
||||
phase: 18-auto-timezone-detection-and-ability-to-change-timezone
|
||||
plan: "02"
|
||||
subsystem: api
|
||||
tags: [timezone, iana, drizzle, vitest, tdd, admin, hono]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 18-01
|
||||
provides: isValidIanaTimezone + getHouseholdTimezone (consumed by timezoneSchema + GET handler)
|
||||
- phase: 10-admin-role-settings
|
||||
provides: adminRouter + requireAdmin + appConfig table
|
||||
|
||||
provides:
|
||||
- GET /api/admin/config/timezone — reads stored household timezone with isExplicitlySet flag
|
||||
- PUT /api/admin/config/timezone — validates IANA string + upserts household_timezone in app_config
|
||||
- POST /api/admin/config/timezone/seed — seeds only when unset (D-03 no-overwrite)
|
||||
|
||||
affects:
|
||||
- 18-03-PLAN (broker rewire — reminderScheduler + outboxWorker import getHouseholdTimezone)
|
||||
- 18-04-PLAN (PWA settings UI — consumes GET + PUT endpoints built here)
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- zValidator('json', schema) without noEchoHook for non-sensitive config (timezone is not a credential)
|
||||
- Drizzle onDuplicateKeyUpdate upsert for config PUT (appConfig PK = key)
|
||||
- SELECT-before-INSERT pattern for no-overwrite seed (D-03 — DO NOT use onDuplicateKeyUpdate for seed)
|
||||
- requireAdmin positional coverage: new routes appended after line-41 adminRouter.use('*', requireAdmin)
|
||||
|
||||
key-files:
|
||||
created: []
|
||||
modified:
|
||||
- apps/api/src/routes/admin.ts
|
||||
- apps/api/tests/routes/admin.test.ts
|
||||
|
||||
key-decisions:
|
||||
- "timezoneSchema uses isValidIanaTimezone (from 18-01) in Zod .refine() — no noEchoHook needed (T-18-06: timezone is non-sensitive)"
|
||||
- "GET /config/timezone reads row directly (not via getHouseholdTimezone) to compute isExplicitlySet from row?.value != null, then uses getHouseholdTimezone for the fallback value"
|
||||
- "seed endpoint uses SELECT-then-INSERT (not onDuplicateKeyUpdate) to ensure D-03 no-overwrite is an explicit code path, not a silent race"
|
||||
|
||||
requirements-completed: [D-01, D-02, D-03, D-04]
|
||||
|
||||
# Metrics
|
||||
duration: 3min
|
||||
completed: 2026-06-15
|
||||
---
|
||||
|
||||
# Phase 18 Plan 02: Admin Timezone API Endpoints Summary
|
||||
|
||||
**Three role-gated admin endpoints (GET + PUT + seed) added to adminRouter with server-side IANA validation via isValidIanaTimezone and D-03 no-overwrite seed semantics enforced by SELECT-before-INSERT**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 3 min
|
||||
- **Started:** 2026-06-15T02:09:38Z
|
||||
- **Completed:** 2026-06-15T02:12:39Z
|
||||
- **Tasks:** 2 (TDD RED + GREEN)
|
||||
- **Files modified:** 2
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Added `describe('admin timezone config')` to `admin.test.ts` with 8 test cases covering all boundary conditions
|
||||
- Implemented `GET /api/admin/config/timezone`, `PUT /api/admin/config/timezone`, and `POST /api/admin/config/timezone/seed` on the existing `adminRouter`
|
||||
- All routes inherit the line-41 `requireAdmin` guard (Pitfall 9 / T-18-03) — no per-route auth addition needed
|
||||
- `timezoneSchema` uses `isValidIanaTimezone` from Plan 18-01 in a Zod `.refine()` — no `noEchoHook` (T-18-06)
|
||||
- `PUT` uses `onDuplicateKeyUpdate` for a true upsert; `seed` uses SELECT-then-INSERT to enforce D-03 no-overwrite
|
||||
- 25/25 `admin.test.ts` tests pass; 366/366 full API suite green; `tsc --noEmit` clean
|
||||
|
||||
## Task Commits
|
||||
|
||||
1. **Task 1: RED — failing integration tests** - `f109b3c` (test)
|
||||
2. **Task 2: GREEN — implement GET/PUT/seed timezone endpoints** - `3bd6a5d` (feat)
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `apps/api/src/routes/admin.ts` — added appConfig + householdTimezone imports, timezoneSchema, and three new route handlers
|
||||
- `apps/api/tests/routes/admin.test.ts` — added appConfig import + `describe('admin timezone config')` with 8 test cases + per-test afterEach cleanup
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- `timezoneSchema` does NOT use `noEchoHook` because timezone strings are non-sensitive (not credentials/PII); standard `zValidator` error responses are safe (T-18-06 accepted disposition).
|
||||
- `GET /config/timezone` does a direct single-row read (not `getHouseholdTimezone`) so the handler can compute `isExplicitlySet` from `row?.value != null` before deciding whether to invoke the fallback chain — using `getHouseholdTimezone` would discard the "was it stored?" signal.
|
||||
- `POST /api/admin/config/timezone/seed` uses a SELECT-then-INSERT (not `onDuplicateKeyUpdate`) so that D-03 no-overwrite is an explicit code branch, not an implicit race. The test asserts the stored value after a second seed attempt remains unchanged.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None — plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- Running `pnpm --filter @familysync/api exec vitest run` requires `DB_ROOT_PASSWORD` from `.env` sourced into the shell (the global-setup provisions `familysync_test` using the root credential). This is the established pattern from quick 260613-ndv and documented in `familysync-dev-stack-setup.md`.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None — all three endpoints are fully wired to the database. No placeholder data.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
No new threat surface beyond the plan's threat model. All three endpoints are behind `requireAdmin` (T-18-03). IANA validation enforced by `isValidIanaTimezone` (T-18-04). No SQL injection surface — key is a hard-coded literal, value is IANA-validated, Drizzle parameterizes the insert/upsert (T-18-07).
|
||||
|
||||
## TDD Gate Compliance
|
||||
|
||||
- RED gate: `f109b3c` — `test(18-02): add failing integration tests for admin timezone endpoints`
|
||||
- GREEN gate: `3bd6a5d` — `feat(18-02): admin timezone GET/PUT/seed endpoints`
|
||||
- REFACTOR gate: N/A (implementation was clean on first pass)
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Plan 18-03 (broker rewire) can import `getHouseholdTimezone(db)` from `../lib/householdTimezone.js` to replace the bare `process.env.TZ ?? Intl…` lookups in `reminderScheduler.ts:247` and `outboxWorker.ts:501,607`.
|
||||
- Plan 18-04 (PWA settings UI) can wire to `GET /api/admin/config/timezone` and `PUT /api/admin/config/timezone`. The seed endpoint is also available for the Phase 12 wizard auto-detect flow.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- `apps/api/src/routes/admin.ts` — FOUND (modified)
|
||||
- `apps/api/tests/routes/admin.test.ts` — FOUND (modified)
|
||||
- Commit `f109b3c` — FOUND
|
||||
- Commit `3bd6a5d` — FOUND
|
||||
|
||||
---
|
||||
*Phase: 18-auto-timezone-detection-and-ability-to-change-timezone*
|
||||
*Completed: 2026-06-15*
|
||||
Reference in New Issue
Block a user