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) |
|
| Editors | CodeMirror 6 (primary), Edra/TipTap (secondary) |
|
||||||
| Native | Electron app for onsite launcher (`src/lib/electron/electron_relay.ts`) |
|
| Native | Electron app for onsite launcher (`src/lib/electron/electron_relay.ts`) |
|
||||||
| Backend | FastAPI + MariaDB, V3 API (`/v3/crud/`, `/v3/lookup/`) |
|
| 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`.
|
**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.
|
**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` |
|
| Electron / native launcher | `documentation/PROJECT__AE_Events_Launcher_Native_integration.md` |
|
||||||
| Store migration plan | `documentation/PROJECT__Stores_Svelte5_Migration.md` |
|
| Store migration plan | `documentation/PROJECT__Stores_Svelte5_Migration.md` |
|
||||||
| Exhibitor Leads module | `documentation/MODULE__AE_Events_Exhibitor_Leads.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` |
|
| Naming conventions | `documentation/AE__Naming_Conventions.md` |
|
||||||
|
|||||||
Reference in New Issue
Block a user