From 615af58a11bfc496fe2f657f4b71111fd9d4b7a6 Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Tue, 19 May 2026 15:02:09 -0400 Subject: [PATCH] docs(idaa): update CLIENT doc for error handling and contact search status MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Access Gate: document new verify_error_type states (rate_limited/api_error), retry/reset UI buttons added in the previous session - Search Architecture: correct 'contacts not searchable' — default_qry_str already includes contact data; two bugs fixed 2026-05-19 (stale STORED GENERATED columns, frontend secondary filter dropping API-matched results). IDB fast-path gap remains. - TODO__Agents.md: update contact search task to reflect API path now working; narrow remaining work to IDB fast-path only Co-Authored-By: Claude Sonnet 4.6 --- .../CLIENT__IDAA_and_customized_mods.md | 40 +++++++++++++------ documentation/TODO__Agents.md | 26 ++++++------ 2 files changed, 41 insertions(+), 25 deletions(-) diff --git a/documentation/CLIENT__IDAA_and_customized_mods.md b/documentation/CLIENT__IDAA_and_customized_mods.md index 76920e58..b0a63da2 100644 --- a/documentation/CLIENT__IDAA_and_customized_mods.md +++ b/documentation/CLIENT__IDAA_and_customized_mods.md @@ -286,7 +286,12 @@ This ensures that OSIT staff with `super` or `manager` roles retain full access ### Access Gate (`(idaa)/+layout.svelte`) The inner layout blocks ALL rendering if the user is not authorized: -- `novi_verifying = true` → "Verifying identity..." spinner +- `novi_verifying = true` → "Verifying identity..." spinner (message updates during retry) +- `verify_error_type === 'rate_limited'` → yellow "Identity Verification Unavailable" panel with: + - **Try Again** — calls `handle_verify_retry()` (respects retry_count, waits 10 s before re-calling Novi) + - **Clear Cache & Reload** — clears IDB + localStorage + sessionStorage, then reloads + - **Full Reset** — same clear but also navigates to `/` with `invalidateAll` +- `verify_error_type === 'api_error'` → same yellow panel (API returned non-2xx, not a rate limit) - Verification failed or no UUID → "Access Denied" error page - Access check runs before any child routes render @@ -392,18 +397,29 @@ Search uses the standard Aether SWR pattern (IDB cache returned immediately, the ### Search Architecture — What Is and Isn't Searched -The fulltext search runs against the `default_qry_str` field (backend-computed, contains: -`id_random`, type, name, description, timezone, recurring pattern/text, location text). +The fulltext search runs against the `default_qry_str` field (backend-computed STORED GENERATED +column, contains: `id_random`, type, name, description, timezone, recurring pattern/text, +location text, **contact name and email**). -**Contact names and emails are NOT currently searchable.** The `contact_li_json` field is a -JSON longtext — MariaDB cannot efficiently substring-search it directly. The backend already -has a `contact_li_json_ext` (STORED GENERATED, indexed) column to work around this, but it -has not yet been added to the searchable fields whitelist in the API. +**Contact names and emails ARE searchable via the API path.** `default_qry_str` includes +contact data, so the API `lk_qry` LIKE search on that field covers contacts automatically. -**Pending fix (tracked in TODO__Agents.md, 2026-04-08):** -- Backend: add `contact_li_json_ext` to the event object searchable fields whitelist -- Frontend: add `contact_li_json_ext` as an OR condition in `search__event()`, and update - the local IDB fast-path filter to parse `contact_li_json` for instant cache results +**IDB fast-path gap:** The local cache (Dexie) fast-path returns all cached meetings without +text filtering — users see the unfiltered list immediately, then the API result (with contacts +filtered) replaces it after the background refresh completes. The IDB path does not parse +`contact_li_json` for instant local text matching. + +**Known history (2026-05-19):** Contact search appeared broken due to two issues now resolved: +1. The backend STORED GENERATED columns (`default_qry_str`, `contact_li_json_ext`) had stale + values; forced a rebuild via fake updates on each event record. +2. The recovery meetings page secondary filter was re-running text matching against response + fields — silently dropping results that matched only via `default_qry_str` (e.g. by contact + name, since that field may not appear in the response body). Fix: removed text re-filtering + from the secondary filter (type / physical / virtual OR-logic only). + +**Remaining enhancement (tracked in TODO__Agents.md):** +- Add `contact_li_json_ext` to the IDB fast-path filter in `search__event()` and the recovery + meetings page so contact matches appear instantly from cache, not only after API refresh. ### My Meetings (Favorites) @@ -821,4 +837,4 @@ ae_loc.idaa_loc = { novi_uuid: 'test-uuid-value', ... }; --- **Document Status:** ✅ Current -**Last Verified:** 2026-05-18 — Recovery Meetings: updated default limit to 100 and added 75 to limit stepper; added My Meetings / favorites (data_store-backed, star button on list + detail page), guided empty state for filtered zero-results, corrected filter/sort descriptions; updated `idaa_loc` and `idaa_sess` store schemas to match actual fields +**Last Verified:** 2026-05-19 — Access Gate: documented new `verify_error_type` error-handling states and retry/reset UI; Search Architecture: corrected contact-search status (now works via `default_qry_str` in API path — two root causes fixed 2026-05-18/19); noted IDB fast-path gap as remaining enhancement diff --git a/documentation/TODO__Agents.md b/documentation/TODO__Agents.md index 9c3008fe..da99e229 100644 --- a/documentation/TODO__Agents.md +++ b/documentation/TODO__Agents.md @@ -217,20 +217,20 @@ suddenly jumps to 0 errors, verify it's not because a bad `.d.ts` replaced a pac - `$effect` auth guards in IDAA page components are reactivity guards (prevent spurious SWR calls on coarse `$ae_loc` writes), NOT auth-bypass guards. SvelteKit layout hierarchy already prevents child components from mounting when `(idaa)/+layout.svelte` blocks rendering. - Doc: SvelteKit layout hierarchy security model captured in `GUIDE__SvelteKit2_Svelte5_DexieJS.md` and `BOOTSTRAP__AI_Agent_Quickstart.md` (Mistake #7). -- [ ] **[IDAA] Make `contact_li_json_ext` searchable — Recovery Meeting contact search (2026-04-08)** - Members cannot search for meetings by contact name or email. `contact_li_json` data is not - included in `default_qry_str` and MariaDB cannot substring-search a JSON longtext directly. - The `event` table already has `contact_li_json_ext` (STORED GENERATED, indexed) to work around this. +- [ ] **[IDAA] IDB fast-path contact search — Recovery Meetings (2026-04-08, updated 2026-05-19)** + **API path is now working** — `default_qry_str` already includes contact name/email. + Two bugs were fixed 2026-05-19: (1) STORED GENERATED columns had stale values; forced + rebuild via fake updates. (2) Frontend secondary filter was re-checking text against + response fields, silently dropping API results that matched only via `default_qry_str`. - **Backend (blocked on this first):** Add `contact_li_json_ext` to the searchable fields - whitelist for the `event` object type — likely a one-line change in `ae_obj_types_def.py` - or the event object definition. Message sent to backend agent 2026-04-08. - - **Frontend (after backend ships):** - - `src/lib/ae_events/ae_events__event.ts` → `search__event()`: add `contact_li_json_ext` - as an OR condition alongside `default_qry_str` when `qry_str` is present. - - `src/routes/idaa/(idaa)/recovery_meetings/+page.svelte` fast-path IDB filter: parse - `contact_li_json` and include contact names/emails in the local text match check. + **Remaining gap — IDB fast-path only:** The local cache fast-path returns all cached meetings + without text filtering; users see the unfiltered list first, then the API-filtered result + replaces it. To make contact matches appear instantly from cache: + - `src/lib/ae_events/ae_events__event.ts` → fast-path filter in `search__event()`: parse + `contact_li_json` and include contact names/emails in the local text match. + - `src/routes/idaa/(idaa)/recovery_meetings/+page.svelte` fast-path display: same filter. + Backend enhancement (`contact_li_json_ext` whitelist) is not required for this — the IDB + records already store `contact_li_json` raw JSON which can be parsed client-side. - [ ] **[IDAA] Optimize Recovery Meetings SQL VIEW and indexes.** The current search query can be taxing on the server. With ~150 active meetings, the view