docs(idaa): update CLIENT doc for error handling and contact search status

- 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 <noreply@anthropic.com>
This commit is contained in:
Scott Idem
2026-05-19 15:02:09 -04:00
parent 76e21b08ff
commit 615af58a11
2 changed files with 41 additions and 25 deletions

View File

@@ -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-18Recovery 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-19Access 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

View File

@@ -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