docs: fix bootstrap — remove JWT Bearer claim; add mistakes 16-17; add pres_mgmt reading entry
- Auth row in stack table wrongly said "JWT Bearer is auto-injected" — this project uses custom headers only (x-aether-api-key + x-account-id, NOT Bearer tokens) - Mistake #16: $ sigil on plain prop value → store_invalid_shape at runtime - Mistake #17: *_json / *_kv_json columns start as null — require ?. and ?? {} guards - Renumbered old #16 (service worker) to #18 - Reading order: added Pres Mgmt module doc pointer Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -29,7 +29,7 @@ running in Docker. The frontend talks to it exclusively via the V3 REST API.
|
||||
| Editors | CodeMirror 6 (primary), Edra/TipTap (secondary) |
|
||||
| Native | Electron app for onsite launcher (`src/lib/electron/electron_relay.ts`) |
|
||||
| Backend | FastAPI + MariaDB, V3 API (`/v3/crud/`, `/v3/lookup/`) |
|
||||
| Auth | Custom headers: `x-aether-api-key` + `x-account-id`; JWT Bearer is auto-injected when a session exists |
|
||||
| Auth | Custom headers only: `x-aether-api-key` + `x-account-id` — **NOT** Bearer tokens |
|
||||
|
||||
---
|
||||
|
||||
@@ -474,7 +474,39 @@ These are real incidents — know them before you start.
|
||||
|
||||
**Exception — legacy `ae_events__event.ts` encoding:** `ae_events__event.ts` (and `ae_events__event_session.ts`) do NOT use `build_tmp_sort`. They use `priority ? 1 : 0` (priority=true→`'1'`), which requires **descending** sort to put priority items first. `ae_events__event_presentation.ts` DOES use `build_tmp_sort` (it overrides the generic encoding in its `specific_processor`). Do not apply the ascending rule to raw event or session sorts until those modules are migrated to `build_tmp_sort`.
|
||||
|
||||
16. **Service worker without `skipWaiting()` + `clients.claim()` silently serves stale code to long-lived tabs** — The default SvelteKit service worker template does NOT include these calls. Without them, a new SW installs in the background but waits in a **"waiting"** state until every tab running the old version is closed before it activates. Users who leave a page open all day (especially IDAA members in the Novi iframe on idaa.org) run old buggy JS indefinitely after a fix is deployed.
|
||||
16. **`$` sigil on a plain prop value → `store_invalid_shape` at runtime** — when a parent passes
|
||||
`prop={resolved_value}`, the child receives a plain JS value. Using `$prop` inside the child
|
||||
tries to subscribe to it as a Svelte store and throws `store_invalid_shape: X is not a store
|
||||
with a subscribe method`. This often happens in files migrated from Svelte 4 where `$lq__*`
|
||||
usage was correct for the old store-subscription pattern. In Svelte 5, props are plain values:
|
||||
```svelte
|
||||
<!-- ❌ Wrong — treats prop as a Svelte store -->
|
||||
{$lq__event_session_obj?.name}
|
||||
|
||||
<!-- ✅ Correct — prop is already the resolved value -->
|
||||
{lq__event_session_obj?.name}
|
||||
```
|
||||
Also note: `PersistedState` stores (events module) use `.current` access, never the `$` sigil.
|
||||
|
||||
17. **`*_json` / `*_kv_json` DB columns start as `null`** — JSON blob columns (`cfg_json`,
|
||||
`data_json`, `poc_kv_json`, etc.) are `null` in the database until first written. Two failure
|
||||
modes:
|
||||
- **Read crash:** `obj.poc_kv_json[poc_type]` throws `TypeError: can't access property "X",
|
||||
poc_kv_json is null`. Fix: always use optional chaining: `obj.poc_kv_json?.[poc_type]`.
|
||||
- **Write crash:** spreading `null` — `{ ...obj.poc_kv_json }` throws. Fix: initialize with
|
||||
`{ ...(obj.poc_kv_json ?? {}) }` before writing any nested keys.
|
||||
```ts
|
||||
// ✅ Safe read
|
||||
const bio_updated = obj.poc_kv_json?.[poc_type]?.biography_updated_on;
|
||||
|
||||
// ✅ Safe write
|
||||
const kv = { ...(obj.poc_kv_json ?? {}) };
|
||||
if (!kv[poc_type]) kv[poc_type] = {};
|
||||
kv[poc_type]['biography'] = new_value;
|
||||
await update_obj({ data_kv: { poc_kv_json: kv } });
|
||||
```
|
||||
|
||||
18. **Service worker without `skipWaiting()` + `clients.claim()` silently serves stale code to long-lived tabs** — The default SvelteKit service worker template does NOT include these calls. Without them, a new SW installs in the background but waits in a **"waiting"** state until every tab running the old version is closed before it activates. Users who leave a page open all day (especially IDAA members in the Novi iframe on idaa.org) run old buggy JS indefinitely after a fix is deployed.
|
||||
|
||||
**Symptom that should trigger this check:** Bug reports from users that developers cannot reproduce. Developers constantly refresh and open/close tabs — the new SW activates immediately for them. End users with persistent tabs never get it.
|
||||
|
||||
@@ -536,4 +568,5 @@ Start here, then go deeper as needed:
|
||||
| Electron / native launcher | `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` |
|
||||
| Store migration plan | `documentation/PROJECT__Stores_Svelte5_Migration.md` |
|
||||
| Exhibitor Leads module | `documentation/MODULE__AE_Events_Exhibitor_Leads.md` |
|
||||
| Presentation Management module | `documentation/PROJECT__AE_Events_PressMgmt_Config_Cleanup.md` |
|
||||
| Naming conventions | `documentation/AE__Naming_Conventions.md` |
|
||||
|
||||
Reference in New Issue
Block a user