131 lines
8.9 KiB
Markdown
131 lines
8.9 KiB
Markdown
# Phase 11: Per-Event Reminders - Context
|
||
|
||
**Gathered:** 2026-06-13
|
||
**Status:** Ready for planning
|
||
|
||
<domain>
|
||
## Phase Boundary
|
||
|
||
A per-event reminder lead picker on the event form, round-tripped to Fastmail as a
|
||
VALARM, with a variable-lead push scheduler that honors each event's choice. The
|
||
preset list, default-None, VALARM DURATION-trigger format, preserve-on-edit
|
||
mechanism, `uid:dtstartMs` dedup, variable scan window, dropping the `isShared`-only
|
||
reminder restriction, and the scheduler reading `reminder_lead_minutes` from the DB
|
||
as ground truth are all **locked by ROADMAP Phase 11 + research/PITFALLS.md** — this
|
||
discussion only resolved the product/UX gray areas on top of that.
|
||
|
||
</domain>
|
||
|
||
<decisions>
|
||
## Implementation Decisions
|
||
|
||
### Reminder picker — timed vs all-day presets
|
||
- **D-01:** Timed events keep the locked preset list: None / 5m / 10m / 15m / 30m / 1h / 2h / 1d / 2d, default **None**.
|
||
- **D-02:** All-day events get a **context-swapped, day-granularity** preset list: **None / Same day / 1 day before / 2 days before / 1 week before**, default **None**. The picker is NOT hidden or disabled for all-day events.
|
||
- **D-03:** The picker is shown for both event types — it swaps its option set based on the All-day toggle, rather than disappearing.
|
||
|
||
### All-day reminder semantics
|
||
- **D-04:** All-day reminders fire at **9 AM local** on the computed alert day (retains the roadmap's sensible-morning decision; "Same day" = 9 AM on the event's own date, "1 day before" = 9 AM the prior day, etc.).
|
||
- **D-05:** All-day leads are stored in the existing `reminder_lead_minutes` column as minutes: Same day = `0`, 1d = `1440`, 2d = `2880`, 1wk = `10080`. The scheduler applies the 9 AM-local rule whenever the event is all-day.
|
||
- **D-06:** **`reminder_lead_minutes` must distinguish "no reminder" from "same-day".** No reminder = `NULL` (no VALARM, no push). Same-day all-day = `0` (fire 9 AM on the event date). For timed events `0`/absent still means None. The scheduler and `outboxPayloadSchema` must treat NULL-vs-0 as semantically distinct.
|
||
|
||
### Existing / non-preset alarms on edit (preserve — CAL-14)
|
||
- **D-07:** **Show exact if single.** When an event already carries a reminder that isn't a preset: if it is a *single simple relative alarm*, render its real value in the picker (e.g. "45 min before") even though it's off-list. For *absolute-time triggers or multiple alarms*, show a read-only **"Custom (kept)"** entry.
|
||
- **D-08:** In both off-list cases the original VALARM(s) are **preserved verbatim** on save unless the user explicitly selects a preset or None — never silently rewritten or dropped (mirrors the WR-01 RRULE-preserve pattern; `outboxPayloadSchema` distinguishes "no change" from explicit "no reminder").
|
||
|
||
### Notification copy
|
||
- **D-09:** Reminder push body uses **humanized relative** phrasing, largest sensible unit: "Starts in 2 days" / "Starts in 1 hour" / "Starts in 30 min". Replaces the current hardcoded `Starts in ${minutes} min` which breaks for long leads. Title and deep-link `navigate` behavior are unchanged.
|
||
|
||
### Recurring events
|
||
- **D-10:** **Series-level only.** One VALARM on the master event; every occurrence inherits the same lead, and the scheduler fires per occurrence naturally. No per-occurrence (RECURRENCE-ID) reminder override in this phase — see Deferred.
|
||
|
||
### Claude's Discretion
|
||
- Picker placement within `EventForm.tsx` (reuse the existing labeled `<select>` pattern used for Recurrence).
|
||
- Exact humanized-unit thresholds/wording for D-09 (e.g. when to switch min→hour→day).
|
||
|
||
</decisions>
|
||
|
||
<roadmap_amendments>
|
||
## Roadmap / Requirement Amendments (planner MUST honor)
|
||
|
||
The all-day decision **reverses a locked roadmap criterion** — surfaced and authorized by the user during discussion:
|
||
|
||
- **ROADMAP Phase 11 success-criterion 5** and **research/PITFALLS.md Pitfall 3** lock *"the reminder selector is disabled/hidden for all-day events"*. This is **overridden**: the picker is shown for all-day events with the D-02 day-granularity presets. The "9 AM local" fire time (criterion 5 / NOTIF-06) is **retained** and now applies to the chosen day-lead.
|
||
- **`buildVeventString`'s `if (!allDay && reminderMinutes > 0)` guard** (Pitfall 3) must change to also emit a VALARM for all-day events with a day-based lead.
|
||
- **CAL-13** preset list is extended for the all-day case (day-granularity presets per D-02); timed presets unchanged.
|
||
- **NOTIF-06** stays satisfied (9 AM all-day fire) but now governs all-day day-leads, not a hidden/disabled selector.
|
||
|
||
</roadmap_amendments>
|
||
|
||
<open_questions>
|
||
## Open for Research
|
||
|
||
- **VALARM trigger encoding for all-day "N days before at 9 AM"** for other-client interop. An all-day VEVENT's DTSTART is a DATE (midnight); a bare relative DURATION trigger fires at midnight, not 9 AM. Research the best-effort trigger representation (relative DURATION offset vs absolute trigger) that other clients (Fastmail/Apple) honor reasonably. The **scheduler remains ground truth** for the actual push fire time (9 AM local via D-04/D-05), so interop fidelity here is best-effort, not exactly-once-critical.
|
||
- Confirm `eventFieldsSchema` / `outboxPayloadSchema` can carry the NULL-vs-0 distinction (D-06) end to end.
|
||
|
||
</open_questions>
|
||
|
||
<canonical_refs>
|
||
## Canonical References
|
||
|
||
**Downstream agents MUST read these before planning or implementing.**
|
||
|
||
### Phase scope & requirements
|
||
- `.planning/ROADMAP.md` §"Phase 11: Per-Event Reminders" — goal, success criteria, owned pitfalls (note criterion-5 amendment above).
|
||
- `.planning/REQUIREMENTS.md` — CAL-13, CAL-14 (lines 15–16); NOTIF-04, NOTIF-05, NOTIF-06 (lines 21–23).
|
||
- `.planning/research/PITFALLS.md` — Pitfalls 1 (preserve-on-edit), 2 (no TRIGGER VALUE=TEXT), 3 (all-day guard — amended), 4 (`uid:dtstartMs` dedup).
|
||
|
||
### Implementation surface (existing code this phase modifies)
|
||
- `apps/api/src/broker/vevent.ts` — `buildVeventString` (VALARM emission, allDay guard to amend).
|
||
- `apps/api/src/broker/write.ts` — write-back path; VALARM extraction/preserve from `rawVevent`.
|
||
- `apps/api/src/broker/outboxWorker.ts` + `outboxPayloadSchema` — "no change" vs explicit "no reminder" distinction.
|
||
- `apps/api/src/broker/reminderScheduler.ts` — variable per-event window, `uid:dtstartMs` dedup, drop `isShared`-only restriction, read `reminder_lead_minutes`, all-day 9 AM rule, humanized body (D-09).
|
||
- `apps/api/src/db/schema.ts` — `calendarEvents.reminder_lead_minutes` (NULL-vs-0 semantics, D-06).
|
||
- `apps/pwa/src/components/EventForm.tsx` — reminder `<select>` (reuse Recurrence-select pattern; allDay-aware preset swap).
|
||
|
||
</canonical_refs>
|
||
|
||
<code_context>
|
||
## Existing Code Insights
|
||
|
||
### Reusable Assets
|
||
- `EventForm.tsx` already renders a labeled `<select>` for Recurrence (~line 852) — the reminder picker reuses this exact pattern, including the allDay-conditional rendering already present for time fields (`{!allDay && (...)}`).
|
||
- `reminderScheduler.ts` already has the dispatch loop, per-event/per-sub error isolation, deep-link `navigate`, and the prune step — Phase 11 changes the *query window, dedup key, lead source, and body text*, not the dispatch plumbing.
|
||
- `dispatchPush` / `pushDispatcher.ts` push pipeline reused unchanged.
|
||
|
||
### Established Patterns
|
||
- **WR-01 RRULE-preserve** in the write path is the template for VALARM preserve-on-edit (D-08): extract sub-components from `rawVevent`, re-attach rather than rebuild.
|
||
- Phase 10 added `reminder_lead_minutes` as the scheduler's ground truth — the column already exists from the v1.1 migration (use generate+migrate if any column change is needed, **never** `drizzle-kit push`).
|
||
- `setInterval`-only scheduling (node-cron silently skips ticks in the long-lived process — do not reintroduce).
|
||
|
||
### Integration Points
|
||
- Event form → `outboxPayloadSchema` → outbox worker → `buildVeventString` → Fastmail PUT.
|
||
- DB `reminder_lead_minutes` → `reminderScheduler` → `dispatchPush` → browser push.
|
||
|
||
</code_context>
|
||
|
||
<specifics>
|
||
## Specific Ideas
|
||
|
||
- The current scheduler body is literally `Starts in ${minutes} min` (reminderScheduler.ts:157) — that is the string being replaced by D-09.
|
||
- All-day "Same day" reminder was explicitly requested by the user as a useful heads-up case ("why not").
|
||
|
||
</specifics>
|
||
|
||
<deferred>
|
||
## Deferred Ideas
|
||
|
||
- **Per-occurrence reminder override** (RECURRENCE-ID) — flexible but significantly more complex; its own phase if ever wanted (D-10 keeps this phase series-level).
|
||
- **Reminder snooze / notification-preferences UI** — already declared out of scope in REQUIREMENTS.md (over-build for a 2-member household).
|
||
|
||
### Reviewed Todos (not folded)
|
||
- `2026-06-13-pwa-phone-bottombar-overlap.md` — BottomTabBar overlaps the New Event FAB/legend. Belongs to **Phase 17 (UI Optimization & Polish)**, not reminders.
|
||
- `2026-06-10-gitea-ci-regression-and-docker-publish.md` — CI regression/Docker publish. Tooling/CI scope (Phase 8 / backlog), unrelated to reminders.
|
||
|
||
</deferred>
|
||
|
||
---
|
||
|
||
*Phase: 11-per-event-reminders*
|
||
*Context gathered: 2026-06-13*
|